@cratis/arc 18.0.0

package/queries/QueryResultWithState.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ValidationResult } from '../validation/ValidationResult';
+import { IQueryResult } from './IQueryResult';
+import { PagingInfo } from './PagingInfo';
+import { QueryResult } from './QueryResult';
+
+/**
+ * Represents a specialized {@link QueryResult<TDataType>} that holds state for its execution
+ */
+export class QueryResultWithState<TDataType> implements IQueryResult<TDataType> {
+
+    static empty<TDataType>(defaultValue: TDataType): QueryResultWithState<TDataType> {
+        return new QueryResultWithState(
+            defaultValue,
+            PagingInfo.noPaging,
+            true,
+            true,
+            true,
+            [],
+            false,
+            [],
+            '',
+            false);
+    }
+
+    static initial<TDataType>(defaultValue: TDataType): QueryResultWithState<TDataType> {
+        return new QueryResultWithState(
+            defaultValue,
+            PagingInfo.noPaging,
+            true,
+            true,
+            true,
+            [],
+            false,
+            [],
+            '',
+            true);
+    }
+
+    /**
+     * Initializes an instance of {@link QueryResultWithState<TDataType>}.
+     * @param {TDataType} data The items returned, if any - can be empty.
+     * @param {PagingInfo} paging The paging info.
+     * @param {boolean} isSuccess Whether or not the query was successful.
+     * @param {boolean} isAuthorized Whether or not the query was authorized.
+     * @param {boolean} isValid Whether or not it is valid.
+     * @param {ValidationResult[]} validationResults Any validation errors.
+     * @param {boolean} hasExceptions Whether or not it has exceptions.
+     * @param {string[]} exceptionMessages Any exception messages.
+     * @param {string} exceptionStackTrace Exception stack trace, if any.
+     * @param {boolean} isPerforming Whether or not the query is being performed. True if its performing, false if it is done.
+     */
+    constructor(
+        readonly data: TDataType,
+        readonly paging: PagingInfo,
+        readonly isSuccess: boolean,
+        readonly isAuthorized: boolean,
+        readonly isValid: boolean,
+        readonly validationResults: ValidationResult[],
+        readonly hasExceptions: boolean,
+        readonly exceptionMessages: string[],
+        readonly exceptionStackTrace: string,
+        readonly isPerforming: boolean) {
+    }
+
+    /** @inheritdoc */
+    get hasData(): boolean {
+        if (Array.isArray(this.data)) {
+            return this.data.length > 0;
+        }
+        return !!this.data;
+    }
+
+    /**
+     * Create a new {@link QueryResultWithState<TDataType>} from {@link QueryResult<TDataType>}.
+     * @param queryResult The original query result.
+     * @param isPerforming Whether or not the query is performing.
+     * @returns A new {@link QueryResultWithState<TDataType>}
+     */
+    static fromQueryResult<TDataType>(queryResult: QueryResult<TDataType>, isPerforming: boolean) {
+        return new QueryResultWithState<TDataType>(
+            queryResult.data,
+            queryResult.paging,
+            queryResult.isSuccess,
+            queryResult.isAuthorized,
+            queryResult.isValid,
+            queryResult.validationResults,
+            queryResult.hasExceptions,
+            queryResult.exceptionMessages,
+            queryResult.exceptionStackTrace,
+            isPerforming);
+    }
+}

package/queries/SortDirection.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines the direction of sorting.
+ */
+export enum SortDirection {
+    /**
+     * Unspecified sort direction.
+     */
+    unspecified = 0,
+
+    /**
+     * Sort in ascending order.
+     */
+    ascending = 1,
+
+    /**
+     * Sort in descending order.
+     */
+    descending = 2,
+}

package/queries/Sorting.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SortDirection } from './SortDirection';
+
+/**
+ * Represents sorting for a query.
+ */
+export class Sorting {
+
+    /**
+     * No sorting.
+     */
+    static none: Sorting = new Sorting('', SortDirection.ascending);
+
+    /**
+     * Initializes a new instance of the {@link Sorting} class.
+     * @param {string} field The field to sort by.
+     * @param {SortDirection} direction The {@link SortDirection} to sort by.
+     */
+    constructor(readonly field: string, readonly direction: SortDirection) {
+    }
+
+    /**
+     * Gets whether sorting is enabled.
+     */
+    get hasSorting(): boolean {
+        return this.field !== '';
+    }
+}

package/queries/SortingActions.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SortDirection } from './SortDirection';
+import { Sorting } from './Sorting';
+
+/**
+ * Represents sorting for a query.
+ */
+export class SortingActions {
+    private readonly _ascending: Sorting;
+    private readonly _descending: Sorting;
+
+    /**
+     * Initializes a new instance of {@link SortingActions}.
+     * @param {string} field The field that the sorting represents.
+     */
+    constructor(readonly field: string) { 
+        this._ascending = new Sorting(this.field, SortDirection.ascending);
+        this._descending = new Sorting(this.field, SortDirection.descending);
+    }
+
+    /**
+      * Returns ascending sort for the field.
+      */
+    get ascending(): Sorting {
+        return this._ascending;
+    }
+
+    /**
+      * Returns ascending sort for the field.
+      */
+    get descending(): Sorting {
+        return this._descending;
+    }
+}

package/queries/SortingActionsForObservableQuery.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IObservableQueryFor } from './IObservableQueryFor';
+import { SortDirection } from './SortDirection';
+import { Sorting } from './Sorting';
+
+/**
+ * Represents sorting for an observable query.
+ */
+export class SortingActionsForObservableQuery<TDataType, TArguments = object> {
+
+    /**
+     * Initializes a new instance of {@link SortingActionsForQuery}.
+     * @param {string} field The field that the sorting represents.
+     * @param {IQueryFor<TDataType, TArguments>} query The query that holds the field.
+     */
+    constructor(readonly field: string, readonly query: IObservableQueryFor<TDataType, TArguments>) {
+    }
+
+    /**
+      * Instructs query to sort ascending for the field.
+      */
+    ascending(): Sorting {
+        this.query.sorting = new Sorting(this.field, SortDirection.ascending);
+        return this.query.sorting;
+    }
+
+    /**
+      * Instructs query to sort ascending for the field.
+      */
+    descending(): Sorting {
+        this.query.sorting = new Sorting(this.field, SortDirection.descending);
+        return this.query.sorting;
+    }
+}

package/queries/SortingActionsForQuery.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IQueryFor } from './IQueryFor';
+import { SortDirection } from './SortDirection';
+import { Sorting } from './Sorting';
+
+/**
+ * Represents sorting for a query.
+ */
+export class SortingActionsForQuery<TDataType, TArguments = object> {
+
+    /**
+     * Initializes a new instance of {@link SortingActionsForQuery}.
+     * @param {string} field The field that the sorting represents.
+     * @param {IQueryFor<TDataType, TArguments>} query The query that holds the field.
+     */
+    constructor(readonly field: string, readonly query: IQueryFor<TDataType, TArguments>) { 
+    }
+
+    /**
+      * Instructs query to sort ascending for the field.
+      */
+    ascending(): Sorting {
+        this.query.sorting = new Sorting(this.field, SortDirection.ascending);
+        return this.query.sorting;
+    }
+
+    /**
+      * Instructs query to sort ascending for the field.
+      */
+    descending(): Sorting {
+        this.query.sorting = new Sorting(this.field, SortDirection.descending);
+        return this.query.sorting;
+    }
+}

package/queries/ValidateRequestArguments.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Validate request arguments.
+ * @param {string} requestName Name of request.
+ * @param {string[]} expectedRequestArguments Array of all expected arguments.
+ * @param {*} actualArguments Object containing the arguments.
+ * @returns True if valid, false if not.
+*/
+export function ValidateRequestArguments(requestName: string, expectedRequestArguments: string[], actualArguments?: object): boolean {
+    if (expectedRequestArguments.length > 0) {
+        const missing: string[] = [];
+
+        if (!actualArguments) {
+            expectedRequestArguments.forEach(_ => missing.push(_));
+        } else {
+            for (const argument of expectedRequestArguments) {
+                if (!actualArguments.hasOwnProperty(argument) ||
+                    actualArguments[argument] == undefined ||
+                    actualArguments[argument] == null ||
+                    actualArguments[argument] == '') {
+                    missing.push(argument);
+                }
+            }
+        }
+
+        if (missing.length > 0) {
+            const missingArgumentsString = missing.join(', ');
+            console.log(`Warning: Missing (${missingArgumentsString}) arguments for request (${requestName}). Will not perform.`);
+            return false;
+        }
+    }
+
+    return true;
+}

package/queries/for_ObservableQueryFor/given/TestQueries.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ObservableQueryFor } from '../../ObservableQueryFor';
+import { Constructor } from '@cratis/fundamentals';
+import { ParameterDescriptor } from '../../../reflection/ParameterDescriptor';
+
+export class TestObservableQuery extends ObservableQueryFor<string, { id: string }> {
+    readonly route = '/api/test/{id}';
+    readonly defaultValue = '';
+    readonly parameterDescriptors: ParameterDescriptor[] = [
+        new ParameterDescriptor('id', String as Constructor)
+    ];
+
+    get requiredRequestParameters(): string[] {
+        return ['id'];
+    }
+
+    constructor() {
+        super(String as Constructor, false);
+    }
+}
+
+export class TestEnumerableQuery extends ObservableQueryFor<string[], { category: string }> {
+    readonly route = '/api/items/{category}';
+    readonly defaultValue: string[] = [];
+    readonly parameterDescriptors: ParameterDescriptor[] = [
+        new ParameterDescriptor('category', String as Constructor)
+    ];
+
+    get requiredRequestParameters(): string[] {
+        return ['category'];
+    }
+
+    constructor() {
+        super(String as Constructor, true);
+    }
+}
+
+export class TestObservableQueryWithParameterDescriptorValues extends ObservableQueryFor<string, object> {
+    readonly route = '/api/search';
+    readonly defaultValue = '';
+    readonly parameterDescriptors: ParameterDescriptor[] = [
+        new ParameterDescriptor('filter', String as Constructor),
+        new ParameterDescriptor('limit', Number as Constructor)
+    ];
+
+    filter?: string;
+    limit?: number;
+
+    get requiredRequestParameters(): string[] {
+        return [];
+    }
+
+    constructor() {
+        super(String as Constructor, false);
+    }
+}

package/queries/for_ObservableQueryFor/given/an_observable_query_for.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { TestObservableQuery, TestEnumerableQuery, TestObservableQueryWithParameterDescriptorValues } from './TestQueries';
+
+export class an_observable_query_for {
+    query: TestObservableQuery;
+    enumerableQuery: TestEnumerableQuery;
+    queryWithParameterDescriptorValues: TestObservableQueryWithParameterDescriptorValues;
+
+    constructor() {
+        this.query = new TestObservableQuery();
+        this.enumerableQuery = new TestEnumerableQuery();
+        this.queryWithParameterDescriptorValues = new TestObservableQueryWithParameterDescriptorValues();
+    }
+}

package/queries/for_ObservableQueryFor/when_constructing.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_for } from './given/an_observable_query_for';
+import { given } from '../../given';
+import { Sorting } from '../Sorting';
+import { Paging } from '../Paging';
+import { Globals } from '../../Globals';
+
+
+describe('when constructing', given(an_observable_query_for, context => {
+    let originalMicroservice: string | undefined;
+
+    beforeEach(() => {
+        originalMicroservice = Globals.microservice;
+        Globals.microservice = 'test-microservice';
+    });
+
+    afterEach(() => {
+        if (originalMicroservice !== undefined) {
+            Globals.microservice = originalMicroservice;
+        }
+    });
+
+    it('should set sorting to none', () => context.query.sorting.should.equal(Sorting.none));
+    it('should set paging to no paging', () => context.query.paging.should.equal(Paging.noPaging));
+    it('should set model type to String', () => context.query.modelType.should.equal(String));
+    it('should set enumerable to false', () => context.query.enumerable.should.be.false);
+    it('should have default required request parameters', () => context.query.requiredRequestParameters.should.deep.equal(['id']));
+    it('should have default route', () => context.query.route.should.equal('/api/test/{id}'));
+    it('should have default value as empty string', () => context.query.defaultValue.should.equal(''));
+}));

package/queries/for_ObservableQueryFor/when_constructing_enumerable.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_for } from './given/an_observable_query_for';
+import { given } from '../../given';
+import { Sorting } from '../Sorting';
+import { Paging } from '../Paging';
+
+
+describe('when constructing enumerable query', given(an_observable_query_for, context => {
+    it('should set sorting to none', () => context.enumerableQuery.sorting.should.equal(Sorting.none));
+    it('should set paging to no paging', () => context.enumerableQuery.paging.should.equal(Paging.noPaging));
+    it('should set model type to String', () => context.enumerableQuery.modelType.should.equal(String));
+    it('should set enumerable to true', () => context.enumerableQuery.enumerable.should.be.true);
+    it('should have default required request parameters', () => context.enumerableQuery.requiredRequestParameters.should.deep.equal(['category']));
+    it('should have default route', () => context.enumerableQuery.route.should.equal('/api/items/{category}'));
+    it('should have default value as empty array', () => context.enumerableQuery.defaultValue.should.deep.equal([]));
+}));

package/queries/for_ObservableQueryFor/when_disposing.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_for } from './given/an_observable_query_for';
+import { given } from '../../given';
+
+import * as sinon from 'sinon';
+
+describe('when disposing', given(an_observable_query_for, context => {
+    let callback: sinon.SinonStub;
+
+    beforeEach(() => {
+        context.query.setOrigin('https://example.com'); // Set origin to avoid document access
+        callback = sinon.stub();
+        
+        // Create a subscription first
+        context.query.subscribe(callback, { id: 'test-id' });
+    });
+
+    it('should not throw when disposing', () => {
+        (() => context.query.dispose()).should.not.throw();
+    });
+
+    it('should be safe to dispose multiple times', () => {
+        context.query.dispose();
+        (() => context.query.dispose()).should.not.throw();
+    });
+}));

package/queries/for_ObservableQueryFor/when_performing/with_enumerable_query.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_for } from '../given/an_observable_query_for';
+import { given } from '../../../given';
+import * as sinon from 'sinon';
+import { QueryResult } from '../../QueryResult';
+
+describe('when performing with enumerable query', given(an_observable_query_for, context => {
+    let result: QueryResult<string[]>;
+    let fetchStub: sinon.SinonStub;
+    const mockResponse = {
+        data: ['item1', 'item2', 'item3'],
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        paging: {
+            totalItems: 3,
+            totalPages: 1,
+            page: 0,
+            size: 10
+        }
+    };
+
+    beforeEach(async () => {
+        fetchStub = sinon.stub(global, 'fetch');
+        fetchStub.resolves({
+            json: sinon.stub().resolves(mockResponse),
+            ok: true,
+            status: 200
+        } as unknown as Response);
+
+        context.enumerableQuery.setOrigin('https://api.example.com');
+        context.enumerableQuery.setApiBasePath('/api/v1');
+
+        result = await context.enumerableQuery.perform({ category: 'test-category' });
+    });
+
+    afterEach(() => {
+        fetchStub.restore();
+    });
+
+    it('should return successful result', () => {
+        result.isSuccess.should.be.true;
+    });
+
+    it('should return array data', () => {
+        result.data.should.be.an('array');
+        result.data.should.have.lengthOf(3);
+    });
+
+    it('should contain correct items', () => {
+        result.data[0].should.equal('item1');
+        result.data[1].should.equal('item2');
+        result.data[2].should.equal('item3');
+    });
+}));

package/queries/for_ObservableQueryFor/when_performing/with_invalid_arguments.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_for } from '../given/an_observable_query_for';
+import { given } from '../../../given';
+import { QueryResult } from '../../QueryResult';
+
+describe('when performing with invalid arguments', given(an_observable_query_for, context => {
+    let result: QueryResult<string>;
+
+    beforeEach(async () => {
+        result = await context.query.perform({} as { id: string });
+    });
+
+    it('should return unsuccessful result', () => {
+        result.isSuccess.should.be.false;
+    });
+
+    it('should return default value', () => {
+        result.data.should.equal('');
+    });
+}));

package/queries/for_ObservableQueryFor/when_performing/with_paging.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_for } from '../given/an_observable_query_for';
+import { given } from '../../../given';
+import * as sinon from 'sinon';
+import { Paging } from '../../Paging';
+
+describe('when performing with paging', given(an_observable_query_for, context => {
+    let fetchStub: sinon.SinonStub;
+    const mockResponse = {
+        data: 'test-result',
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        paging: {
+            totalItems: 100,
+            totalPages: 10,
+            page: 2,
+            size: 10
+        }
+    };
+
+    beforeEach(async () => {
+        fetchStub = sinon.stub(global, 'fetch');
+        fetchStub.resolves({
+            json: sinon.stub().resolves(mockResponse),
+            ok: true,
+            status: 200
+        } as unknown as Response);
+
+        context.query.setOrigin('https://api.example.com');
+        context.query.paging = new Paging(2, 10);
+
+        await context.query.perform({ id: 'test-id' });
+    });
+
+    afterEach(() => {
+        fetchStub.restore();
+    });
+
+    it('should include page parameter in URL', () => {
+        const call = fetchStub.getCall(0);
+        call.args[0].href.should.contain('page=2');
+    });
+
+    it('should include pageSize parameter in URL', () => {
+        const call = fetchStub.getCall(0);
+        call.args[0].href.should.contain('pageSize=10');
+    });
+}));

package/queries/for_ObservableQueryFor/when_performing/with_parameter_descriptor_values.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_for } from '../given/an_observable_query_for';
+import { given } from '../../../given';
+import * as sinon from 'sinon';
+import { QueryResult } from '../../QueryResult';
+
+describe('with parameter descriptor values', given(an_observable_query_for, context => {
+    let result: QueryResult<string>;
+    let fetchStub: sinon.SinonStub;
+    const mockResponse = {
+        data: 'test-result',
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        paging: {
+            totalItems: 0,
+            totalPages: 0,
+            page: 0,
+            size: 0
+        }
+    };
+
+    beforeEach(async () => {
+        fetchStub = sinon.stub(global, 'fetch');
+        fetchStub.resolves({
+            json: sinon.stub().resolves(mockResponse),
+            ok: true,
+            status: 200
+        } as unknown as Response);
+
+        context.queryWithParameterDescriptorValues.setOrigin('https://api.example.com');
+        context.queryWithParameterDescriptorValues.setApiBasePath('/api/v1');
+
+        // Set values on the query instance
+        context.queryWithParameterDescriptorValues.filter = 'active';
+        context.queryWithParameterDescriptorValues.limit = 10;
+
+        result = await context.queryWithParameterDescriptorValues.perform();
+    });
+
+    afterEach(() => {
+        fetchStub.restore();
+    });
+
+    it('should return successful result', () => {
+        result.isSuccess.should.be.true;
+    });
+
+    it('should include parameter descriptor values in URL as query string', () => {
+        fetchStub.should.have.been.calledOnce;
+        const call = fetchStub.getCall(0);
+        const url = call.args[0].href;
+        url.should.include('filter=active');
+        url.should.include('limit=10');
+    });
+
+    it('should have query string separator in URL', () => {
+        const call = fetchStub.getCall(0);
+        const url = call.args[0].href;
+        url.should.include('?');
+    });
+}));