@cratis/arc 18.0.0

package/queries/ObservableQueryFor.ts

@@ -0,0 +1,230 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IObservableQueryFor, OnNextResult } from './IObservableQueryFor';
+import { ObservableQueryConnection } from './ObservableQueryConnection';
+import { ObservableQuerySubscription } from './ObservableQuerySubscription';
+import { ValidateRequestArguments } from './ValidateRequestArguments';
+import { IObservableQueryConnection } from './IObservableQueryConnection';
+import { NullObservableQueryConnection } from './NullObservableQueryConnection';
+import { Constructor } from '@cratis/fundamentals';
+import { JsonSerializer } from '@cratis/fundamentals';
+import { QueryResult } from './QueryResult';
+import { Sorting } from './Sorting';
+import { Paging } from './Paging';
+import { SortDirection } from './SortDirection';
+import { Globals } from '../Globals';
+import { joinPaths } from '../joinPaths';
+import { UrlHelpers } from '../UrlHelpers';
+import { GetHttpHeaders } from '../GetHttpHeaders';
+import { ParameterDescriptor } from '../reflection/ParameterDescriptor';
+import { ParametersHelper } from '../reflection/ParametersHelper';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Represents an implementation of {@link IQueryFor}.
+ * @template TDataType Type of data returned by the query.
+ */
+export abstract class ObservableQueryFor<TDataType, TParameters = object> implements IObservableQueryFor<TDataType, TParameters> {
+    private _microservice: string;
+    private _apiBasePath: string;
+    private _origin: string;
+    private _connection?: IObservableQueryConnection<TDataType>;
+    private _httpHeadersCallback: GetHttpHeaders;
+
+    abstract readonly route: string;
+    abstract readonly defaultValue: TDataType;
+    abstract readonly parameterDescriptors: ParameterDescriptor[];
+    abstract get requiredRequestParameters(): string[];
+    sorting: Sorting;
+    paging: Paging;
+
+    /**
+     * Initializes a new instance of the {@link ObservableQueryFor<,>}} class.
+     * @param modelType Type of model, if an enumerable, this is the instance type.
+     * @param enumerable Whether or not it is an enumerable.
+     */
+    constructor(readonly modelType: Constructor, readonly enumerable: boolean) {
+        this.sorting = Sorting.none;
+        this.paging = Paging.noPaging;
+        this._microservice = Globals.microservice ?? '';
+        this._apiBasePath = '';
+        this._origin = '';
+        this._httpHeadersCallback = () => ({});
+    }
+
+    /**
+     * Disposes the query.
+     */
+    dispose() {
+        this._connection?.disconnect();
+    }
+
+    /** @inheritdoc */
+    setMicroservice(microservice: string) {
+        this._microservice = microservice;
+    }
+
+    /** @inheritdoc */
+    setApiBasePath(apiBasePath: string): void {
+        this._apiBasePath = apiBasePath;
+    }
+
+    /** @inheritdoc */
+    setOrigin(origin: string): void {
+        this._origin = origin;
+    }
+
+    /** @inheritdoc */
+    setHttpHeadersCallback(callback: GetHttpHeaders): void {
+        this._httpHeadersCallback = callback;
+    }
+
+    /** @inheritdoc */
+    subscribe(callback: OnNextResult<QueryResult<TDataType>>, args?: TParameters): ObservableQuerySubscription<TDataType> {
+        const connectionQueryArguments: any = this.buildQueryArguments();
+
+        if (this._connection) {
+            this._connection.disconnect();
+        }
+
+        if (!this.validateArguments(args)) {
+            this._connection = new NullObservableQueryConnection(this.defaultValue);
+        } else {
+            const actualRoute = this.buildRoute(args);
+            const url = UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);
+            this._connection = new ObservableQueryConnection<TDataType>(url, this._microservice);
+        }
+
+        const subscriber = new ObservableQuerySubscription(this._connection);
+        this._connection.connect(data => {
+            const result: any = data;
+            try {
+                this.deserializeResult(result);
+                callback(result);
+            } catch (ex) {
+                console.log(ex);
+            }
+        }, connectionQueryArguments);
+        return subscriber;
+    }
+
+    /** @inheritdoc */
+    async perform(args?: TParameters): Promise<QueryResult<TDataType>> {
+        const noSuccess = { ...QueryResult.noSuccess, ...{ data: this.defaultValue } } as QueryResult<TDataType>;
+
+        if (!this.validateArguments(args)) {
+            return new Promise<QueryResult<TDataType>>((resolve) => {
+                resolve(noSuccess);
+            });
+        }
+
+        const { route, unusedParameters } = UrlHelpers.replaceRouteParameters(this.route, args as object);
+        let actualRoute = joinPaths(this._apiBasePath, route);
+        
+        const additionalParams: Record<string, string | number> = {};
+        if (this.paging.hasPaging) {
+            additionalParams.page = this.paging.page;
+            additionalParams.pageSize = this.paging.pageSize;
+        }
+
+        if (this.sorting.hasSorting) {
+            additionalParams.sortBy = this.sorting.field;
+            additionalParams.sortDirection = (this.sorting.direction === SortDirection.descending) ? 'desc' : 'asc';
+        }
+
+        // Collect parameter values from parameterDescriptors that are set
+        const parameterValues = ParametersHelper.collectParameterValues(this);
+
+        const queryParams = UrlHelpers.buildQueryParams({ ...unusedParameters, ...parameterValues }, additionalParams);
+        const queryString = queryParams.toString();
+        if (queryString) {
+            actualRoute += (actualRoute.includes('?') ? '&' : '?') + queryString;
+        }
+
+        const url = UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);
+
+        const headers = {
+            ...(this._httpHeadersCallback?.() || {}),
+            'Accept': 'application/json',
+            'Content-Type': 'application/json'
+        };
+
+        if (this._microservice?.length > 0) {
+            headers[Globals.microserviceHttpHeader] = this._microservice;
+        }
+
+        const response = await fetch(url, {
+            method: 'GET',
+            headers
+        });
+
+        try {
+            const result = await response.json();
+            return new QueryResult(result, this.modelType, this.enumerable);
+        } catch {
+            return noSuccess;
+        }
+    }
+
+    private validateArguments(args?: TParameters): boolean {
+        return ValidateRequestArguments(this.constructor.name, this.requiredRequestParameters, args as object);
+    }
+
+    private buildRoute(args?: TParameters): string {
+        const { route } = UrlHelpers.replaceRouteParameters(this.route, args as object);
+        const actualRoute = joinPaths(this._apiBasePath, route);
+        return actualRoute;
+    }
+
+    private buildQueryArguments(): any {
+        const queryArguments: any = {};
+
+        if (this.paging && this.paging.pageSize > 0) {
+            queryArguments.pageSize = this.paging.pageSize;
+            queryArguments.page = this.paging.page;
+        }
+
+        if (this.sorting.hasSorting) {
+            queryArguments.sortBy = this.sorting.field;
+            queryArguments.sortDirection = (this.sorting.direction === SortDirection.descending) ? 'desc' : 'asc';
+        }
+
+        return queryArguments;
+    }
+
+    private addPagingAndSortingToRoute(route: string): string {
+        const additionalParams: Record<string, string | number> = {};
+        
+        if (this.paging.hasPaging) {
+            additionalParams.page = this.paging.page;
+            additionalParams.pageSize = this.paging.pageSize;
+        }
+
+        if (this.sorting.hasSorting) {
+            additionalParams.sortBy = this.sorting.field;
+            additionalParams.sortDirection = (this.sorting.direction === SortDirection.descending) ? 'desc' : 'asc';
+        }
+
+        const queryParams = UrlHelpers.buildQueryParams({}, additionalParams);
+        const queryString = queryParams.toString();
+        if (queryString) {
+            route += '?' + queryString;
+        }
+        
+        return route;
+    }
+
+    private deserializeResult(result: any): void {
+        if (this.enumerable) {
+            if (Array.isArray(result.data)) {
+                result.data = JsonSerializer.deserializeArrayFromInstance(this.modelType, result.data);
+            } else {
+                result.data = [];
+            }
+        } else {
+            result.data = JsonSerializer.deserializeFromInstance(this.modelType, result.data);
+        }
+    }
+}

package/queries/ObservableQuerySubscription.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IObservableQueryConnection } from './IObservableQueryConnection';
+
+/**
+ * Represents a subscription for an observable query.
+ */
+export class ObservableQuerySubscription<TDataType> {
+
+    /**
+     * Initializes a new instance of the {@link ObservableQuerySubscription} class.
+     * @param {ObservableQueryConnection<TDataType> _connection The connection to use.
+     */
+    constructor(private _connection: IObservableQueryConnection<TDataType>) {
+    }
+
+    /**
+     * Unsubscribe subscription.
+     */
+    unsubscribe() {
+        if (this._connection) {
+            this._connection.disconnect();
+            this._connection = undefined!;
+        }
+    }
+}

package/queries/Paging.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the paging information for a query.
+ */
+export class Paging {
+
+    /**
+     * No paging.
+     */
+    static noPaging: Paging = new Paging(0, 0);
+
+    /**
+     * Initializes a new instance of {@link Paging}.
+     */
+    constructor(page?: number, pageSize?: number) {
+        this.page = page ?? 0;
+        this.pageSize = pageSize ?? 0;
+    }
+
+    /**
+     * Page  of paging
+     */
+    page: number;
+
+    /**
+     * Page size of paging
+     */
+    pageSize: number;
+
+    /**
+     * Gets whether or not there is paging.
+     */
+    get hasPaging(): boolean {
+        return this.page > 0 || this.pageSize > 0;
+    }
+}

package/queries/PagingInfo.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the paging information for a query.
+ */
+export class PagingInfo {
+
+    /**
+     * No paging paging info.
+     */
+    static readonly noPaging = new PagingInfo();
+
+    /**
+     * Initializes a new instance of the {@link PagingInfo} class.
+     */
+    constructor() {
+        this.page = 0;
+        this.size = 0;
+        this.totalItems = 0;
+        this.totalPages = 0;
+    }
+
+    /**
+     * Current page.
+     */
+    page: number;
+
+    /**
+     * Page size.
+     */
+    size: number;
+
+    /**
+     * Total number items.
+     */
+    totalItems: number;
+
+    /**
+     * Total number of pages.
+     */
+    totalPages: number;
+}

package/queries/QueryFor.ts

@@ -0,0 +1,138 @@
+// 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 { QueryResult } from "./QueryResult";
+import { ValidateRequestArguments } from './ValidateRequestArguments';
+import { Constructor } from '@cratis/fundamentals';
+import { Paging } from './Paging';
+import { Globals } from '../Globals';
+import { Sorting } from './Sorting';
+import { SortDirection } from './SortDirection';
+import { joinPaths } from '../joinPaths';
+import { UrlHelpers } from '../UrlHelpers';
+import { GetHttpHeaders } from '../GetHttpHeaders';
+import { ParameterDescriptor } from '../reflection/ParameterDescriptor';
+import { ParametersHelper } from '../reflection/ParametersHelper';
+
+/**
+ * Represents an implementation of {@link IQueryFor}.
+ * @template TDataType Type of data returned by the query.
+ */
+export abstract class QueryFor<TDataType, TParameters = object> implements IQueryFor<TDataType, TParameters> {
+    private _microservice: string;
+    private _apiBasePath: string;
+    private _origin: string;
+    private _httpHeadersCallback: GetHttpHeaders;
+    abstract readonly route: string;
+    abstract readonly parameterDescriptors: ParameterDescriptor[];
+    abstract get requiredRequestParameters(): string[];
+    abstract defaultValue: TDataType;
+    abortController?: AbortController;
+    sorting: Sorting;
+    paging: Paging;
+    parameters: TParameters | undefined;
+
+    /**
+     * Initializes a new instance of the {@link ObservableQueryFor<,>}} class.
+     * @param modelType Type of model, if an enumerable, this is the instance type.
+     * @param enumerable Whether or not it is an enumerable.
+     */
+    constructor(readonly modelType: Constructor, readonly enumerable: boolean) {
+        this.sorting = Sorting.none;
+        this.paging = Paging.noPaging;
+        this._microservice = Globals.microservice ?? '';
+        this._apiBasePath = '';
+        this._origin = '';
+        this._httpHeadersCallback = () => ({});
+    }
+
+    /** @inheritdoc */
+    setMicroservice(microservice: string) {
+        this._microservice = microservice;
+    }
+
+    /** @inheritdoc */
+    setApiBasePath(apiBasePath: string): void {
+        this._apiBasePath = apiBasePath;
+    }
+
+    /** @inheritdoc */
+    setOrigin(origin: string): void {
+        this._origin = origin;
+    }
+
+    /** @inheritdoc */
+    setHttpHeadersCallback(callback: GetHttpHeaders): void {
+        this._httpHeadersCallback = callback;
+    }
+
+    /** @inheritdoc */
+    async perform(args?: TParameters): Promise<QueryResult<TDataType>> {
+        const noSuccess = { ...QueryResult.noSuccess, ...{ data: this.defaultValue } } as QueryResult<TDataType>;
+
+        args = args || this.parameters;
+
+        if (!ValidateRequestArguments(this.constructor.name, this.requiredRequestParameters, args as object)) {
+            return new Promise<QueryResult<TDataType>>((resolve) => {
+                resolve(noSuccess);
+            });
+        }
+
+        if (this.abortController) {
+            this.abortController.abort();
+        }
+
+        this.abortController = new AbortController();
+
+        const { route, unusedParameters } = UrlHelpers.replaceRouteParameters(this.route, args as object);
+        let actualRoute = joinPaths(this._apiBasePath, route);
+        
+        const additionalParams: Record<string, string | number> = {};
+        if (this.paging.hasPaging) {
+            additionalParams.page = this.paging.page;
+            additionalParams.pageSize = this.paging.pageSize;
+        }
+
+        if (this.sorting.hasSorting) {
+            additionalParams.sortBy = this.sorting.field;
+            additionalParams.sortDirection = (this.sorting.direction === SortDirection.descending) ? 'desc' : 'asc';
+        }
+
+        // Collect parameter values from parameterDescriptors that are set
+        const parameterValues = ParametersHelper.collectParameterValues(this);
+
+        const queryParams = UrlHelpers.buildQueryParams({ ...unusedParameters, ...parameterValues }, additionalParams);
+        const queryString = queryParams.toString();
+        if (queryString) {
+            actualRoute += (actualRoute.includes('?') ? '&' : '?') + queryString;
+        }
+        
+        const url = UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);
+
+        const headers = {
+            ... this._httpHeadersCallback?.(), ...
+            {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json'
+            }
+        };
+
+        if (this._microservice?.length > 0) {
+            headers[Globals.microserviceHttpHeader] = this._microservice;
+        }
+
+        const response = await fetch(url, {
+            method: 'GET',
+            headers,
+            signal: this.abortController.signal
+        });
+
+        try {
+            const result = await response.json();
+            return new QueryResult(result, this.modelType, this.enumerable);
+        } catch {
+            return noSuccess;
+        }
+    }
+}

package/queries/QueryProvider.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 { Constructor } from '@cratis/fundamentals';
+import { IQueryProvider } from './IQueryProvider';
+import { IQuery } from './IQuery';
+import { GetHttpHeaders } from '../GetHttpHeaders';
+
+/**
+ * Represents an implementation of {@link IQueryProvider}
+ */
+export class QueryProvider implements IQueryProvider {
+
+    /**
+     * Initializes a new instance of {@link QueryProvider}
+     * @param _microservice Name of the microservice to provide queries for.
+     * @param _apiBasePath Base path for the API to use for the query.
+     * @param _origin Origin to use for the query.
+     * @param _httpHeadersCallback Callback to get HTTP headers for the query.
+     */
+    constructor(
+        private readonly _microservice: string,
+        private readonly _apiBasePath: string,
+        private readonly _origin: string,
+        private readonly _httpHeadersCallback: GetHttpHeaders) { }
+
+    /** @inheritdoc */
+    get<T extends IQuery>(queryType: Constructor<T>): T {
+        const query = new queryType();
+        query.setMicroservice(this._microservice);
+        query.setApiBasePath(this._apiBasePath);
+        query.setOrigin(this._origin);
+        query.setHttpHeadersCallback(this._httpHeadersCallback);
+        return query;
+    }
+}

package/queries/QueryResult.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor, JsonSerializer } from '@cratis/fundamentals';
+import { ValidationResult } from '../validation/ValidationResult';
+import { IQueryResult } from './IQueryResult';
+import { PagingInfo } from './PagingInfo';
+
+type ServerQueryResult = {
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    data: any;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+    isSuccess: boolean;
+    isAuthorized: boolean;
+    isValid: boolean;
+    hasExceptions: boolean;
+    validationResults: ServerValidationResult[];
+    exceptionMessages: string[];
+    exceptionStackTrace: string;
+    paging: ServerPagingInfo;
+}
+
+type ServerValidationResult = {
+    severity: number;
+    message: string;
+    members: string[];
+    state: object;
+}
+
+type ServerPagingInfo = {
+    page: number;
+    size: number; 
+    totalItems: number;
+    totalPages: number;
+}
+
+/**
+ * Represents the result from executing a {@link IQueryFor}.
+ * @template TDataType The data type.
+ */
+export class QueryResult<TDataType = object> implements IQueryResult<TDataType> {
+
+    static empty<TDataType>(defaultValue: TDataType): QueryResult<TDataType> {
+        return new QueryResult({
+            data: defaultValue as object,
+            isSuccess: true,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: false,
+            validationResults: [],
+            exceptionMessages: [],
+            exceptionStackTrace: '',
+            paging: {
+                totalItems: 0,
+                totalPages: 0,
+                page: 0,
+                size: 0
+            }
+
+        }, Object, false);
+    }
+
+    static noSuccess: QueryResult = new QueryResult({
+        data: {},
+        isSuccess: false,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        paging: {
+            totalItems: 0,
+            totalPages: 0,
+            page: 0,
+            size: 0
+        }
+    }, Object, false);
+
+    /**
+     * Creates an instance of query result.
+     * @param {*} result The raw result from the backend.
+     * @param {Constructor} instanceType The type of instance to deserialize.
+     * @param {boolean} enumerable Whether or not the result is supposed be an enumerable or not.
+     */
+    constructor(result: ServerQueryResult, instanceType: Constructor, enumerable: boolean) {
+        this.isSuccess = result.isSuccess;
+        this.isAuthorized = result.isAuthorized;
+        this.isValid = result.isValid;
+        this.hasExceptions = result.hasExceptions;
+        this.validationResults = result.validationResults.map(_ => new ValidationResult(_.severity, _.message, _.members, _.state));
+        this.exceptionMessages = result.exceptionMessages;
+        this.exceptionStackTrace = result.exceptionStackTrace;
+        this.paging = new PagingInfo();
+        this.paging.page = result.paging.page;
+        this.paging.size = result.paging.size;
+        this.paging.totalItems = result.paging.totalItems;
+        this.paging.totalPages = result.paging.totalPages;
+
+        if (result.data) {
+            let data: object = result.data;
+            if (enumerable) {
+                if (Array.isArray(result.data)) {
+                    data = JsonSerializer.deserializeArrayFromInstance(instanceType, data);
+                } else {
+                    data = [];
+                }
+            } else {
+                data = JsonSerializer.deserializeFromInstance(instanceType, data);
+            }
+
+            this.data = data as TDataType;
+        } else {
+            this.data = null as TDataType;
+        }
+    }
+
+    /** @inheritdoc */
+    readonly data: TDataType;
+
+    /** @inheritdoc */
+    readonly paging: PagingInfo;
+
+    /** @inheritdoc */
+    readonly isSuccess: boolean;
+
+    /** @inheritdoc */
+    readonly isAuthorized: boolean;
+
+    /** @inheritdoc */
+    readonly isValid: boolean;
+
+    /** @inheritdoc */
+    readonly hasExceptions: boolean;
+
+    /** @inheritdoc */
+    readonly validationResults: ValidationResult[];
+
+    /** @inheritdoc */
+    readonly exceptionMessages: string[];
+
+    /** @inheritdoc */
+    readonly exceptionStackTrace: string;
+
+    /**
+     * Gets whether or not the query has data.
+     */
+    get hasData(): boolean {
+        if (this.data) {
+            if (Array.isArray(this.data)) {
+                return this.data.length > 0;
+            }
+            return true;
+        }
+        return false;
+    }
+}