@cratis/arc 20.54.5 → 20.54.7

package/dist/cjs/queries/Paging.js

@@ -1,14 +1,28 @@
 'use strict';
 
-class Paging {
-    static noPaging = new Paging(0, 0);
-    constructor(page, pageSize) {
+// 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.
+ */ class Paging {
+    /**
+     * No paging.
+     */ static noPaging = new Paging(0, 0);
+    /**
+     * Initializes a new instance of {@link Paging}.
+     */ constructor(page, pageSize){
         this.page = page ?? 0;
         this.pageSize = pageSize ?? 0;
     }
-    page;
-    pageSize;
-    get hasPaging() {
+    /**
+     * Page  of paging
+     */ page;
+    /**
+     * Page size of paging
+     */ pageSize;
+    /**
+     * Gets whether or not there is paging.
+     */ get hasPaging() {
         return this.page > 0 || this.pageSize > 0;
     }
 }

package/dist/cjs/queries/Paging.js.map

@@ -1 +1 @@
-{"version":3,"file":"Paging.js","sources":["../../../queries/Paging.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * Represents the paging information for a query.\n */\nexport class Paging {\n\n    /**\n     * No paging.\n     */\n    static noPaging: Paging = new Paging(0, 0);\n\n    /**\n     * Initializes a new instance of {@link Paging}.\n     */\n    constructor(page?: number, pageSize?: number) {\n        this.page = page ?? 0;\n        this.pageSize = pageSize ?? 0;\n    }\n\n    /**\n     * Page  of paging\n     */\n    page: number;\n\n    /**\n     * Page size of paging\n     */\n    pageSize: number;\n\n    /**\n     * Gets whether or not there is paging.\n     */\n    get hasPaging(): boolean {\n        return this.page > 0 || this.pageSize > 0;\n    }\n}"],"names":[],"mappings":";;MAMa,MAAM,CAAA;IAKf,OAAO,QAAQ,GAAW,IAAI,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAK1C,WAAA,CAAY,IAAa,EAAE,QAAiB,EAAA;AACxC,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC;AACrB,QAAA,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,CAAC;IACjC;AAKA,IAAA,IAAI;AAKJ,IAAA,QAAQ;AAKR,IAAA,IAAI,SAAS,GAAA;QACT,OAAO,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC;IAC7C;;;;;"}
+{"version":3,"file":"Paging.js","sources":["../../../queries/Paging.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * Represents the paging information for a query.\n */\nexport class Paging {\n\n    /**\n     * No paging.\n     */\n    static noPaging: Paging = new Paging(0, 0);\n\n    /**\n     * Initializes a new instance of {@link Paging}.\n     */\n    constructor(page?: number, pageSize?: number) {\n        this.page = page ?? 0;\n        this.pageSize = pageSize ?? 0;\n    }\n\n    /**\n     * Page  of paging\n     */\n    page: number;\n\n    /**\n     * Page size of paging\n     */\n    pageSize: number;\n\n    /**\n     * Gets whether or not there is paging.\n     */\n    get hasPaging(): boolean {\n        return this.page > 0 || this.pageSize > 0;\n    }\n}"],"names":["Paging","noPaging","page","pageSize","hasPaging"],"mappings":";;AAAA;AACA;AAEA;;AAEC,IACM,MAAMA,MAAAA,CAAAA;AAET;;AAEC,QACD,OAAOC,QAAAA,GAAmB,IAAID,MAAAA,CAAO,GAAG,CAAA,CAAA;AAExC;;AAEC,QACD,WAAA,CAAYE,IAAa,EAAEC,QAAiB,CAAE;QAC1C,IAAI,CAACD,IAAI,GAAGA,IAAAA,IAAQ,CAAA;QACpB,IAAI,CAACC,QAAQ,GAAGA,QAAAA,IAAY,CAAA;AAChC,IAAA;AAEA;;AAEC,QACDD,IAAAA;AAEA;;AAEC,QACDC,QAAAA;AAEA;;AAEC,QACD,IAAIC,SAAAA,GAAqB;QACrB,OAAO,IAAI,CAACF,IAAI,GAAG,KAAK,IAAI,CAACC,QAAQ,GAAG,CAAA;AAC5C,IAAA;AACJ;;;;"}

package/dist/cjs/queries/PagingInfo.js

@@ -1,17 +1,33 @@
 'use strict';
 
-class PagingInfo {
-    static noPaging = new PagingInfo();
-    constructor() {
+// 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.
+ */ class PagingInfo {
+    /**
+     * No paging paging info.
+     */ static 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;
     }
-    page;
-    size;
-    totalItems;
-    totalPages;
+    /**
+     * Current page.
+     */ page;
+    /**
+     * Page size.
+     */ size;
+    /**
+     * Total number items.
+     */ totalItems;
+    /**
+     * Total number of pages.
+     */ totalPages;
 }
 
 exports.PagingInfo = PagingInfo;

package/dist/cjs/queries/PagingInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"PagingInfo.js","sources":["../../../queries/PagingInfo.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * Represents the paging information for a query.\n */\nexport class PagingInfo {\n\n    /**\n     * No paging paging info.\n     */\n    static readonly noPaging = new PagingInfo();\n\n    /**\n     * Initializes a new instance of the {@link PagingInfo} class.\n     */\n    constructor() {\n        this.page = 0;\n        this.size = 0;\n        this.totalItems = 0;\n        this.totalPages = 0;\n    }\n\n    /**\n     * Current page.\n     */\n    page: number;\n\n    /**\n     * Page size.\n     */\n    size: number;\n\n    /**\n     * Total number items.\n     */\n    totalItems: number;\n\n    /**\n     * Total number of pages.\n     */\n    totalPages: number;\n}\n"],"names":[],"mappings":";;MAMa,UAAU,CAAA;AAKnB,IAAA,OAAgB,QAAQ,GAAG,IAAI,UAAU,EAAE;AAK3C,IAAA,WAAA,GAAA;AACI,QAAA,IAAI,CAAC,IAAI,GAAG,CAAC;AACb,QAAA,IAAI,CAAC,IAAI,GAAG,CAAC;AACb,QAAA,IAAI,CAAC,UAAU,GAAG,CAAC;AACnB,QAAA,IAAI,CAAC,UAAU,GAAG,CAAC;IACvB;AAKA,IAAA,IAAI;AAKJ,IAAA,IAAI;AAKJ,IAAA,UAAU;AAKV,IAAA,UAAU;;;;;"}
+{"version":3,"file":"PagingInfo.js","sources":["../../../queries/PagingInfo.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * Represents the paging information for a query.\n */\nexport class PagingInfo {\n\n    /**\n     * No paging paging info.\n     */\n    static readonly noPaging = new PagingInfo();\n\n    /**\n     * Initializes a new instance of the {@link PagingInfo} class.\n     */\n    constructor() {\n        this.page = 0;\n        this.size = 0;\n        this.totalItems = 0;\n        this.totalPages = 0;\n    }\n\n    /**\n     * Current page.\n     */\n    page: number;\n\n    /**\n     * Page size.\n     */\n    size: number;\n\n    /**\n     * Total number items.\n     */\n    totalItems: number;\n\n    /**\n     * Total number of pages.\n     */\n    totalPages: number;\n}\n"],"names":["PagingInfo","noPaging","page","size","totalItems","totalPages"],"mappings":";;AAAA;AACA;AAEA;;AAEC,IACM,MAAMA,UAAAA,CAAAA;AAET;;QAGA,OAAgBC,QAAAA,GAAW,IAAID,UAAAA,EAAAA;AAE/B;;AAEC,QACD,WAAA,EAAc;QACV,IAAI,CAACE,IAAI,GAAG,CAAA;QACZ,IAAI,CAACC,IAAI,GAAG,CAAA;QACZ,IAAI,CAACC,UAAU,GAAG,CAAA;QAClB,IAAI,CAACC,UAAU,GAAG,CAAA;AACtB,IAAA;AAEA;;AAEC,QACDH,IAAAA;AAEA;;AAEC,QACDC,IAAAA;AAEA;;AAEC,QACDC,UAAAA;AAEA;;AAEC,QACDC,UAAAA;AACJ;;;;"}

package/dist/cjs/queries/QueryFor.js

@@ -10,21 +10,30 @@ var joinPaths = require('../joinPaths.js');
 var UrlHelpers = require('../UrlHelpers.js');
 var ParametersHelper = require('../reflection/ParametersHelper.js');
 
-class QueryFor {
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Represents an implementation of {@link IQueryFor}.
+ * @template TDataType Type of data returned by the query.
+ */ class QueryFor {
     modelType;
     enumerable;
     _microservice;
     _apiBasePath;
     _origin;
     _httpHeadersCallback;
-    queryName;
-    validation;
-    roles = [];
+    /** Backend fully-qualified query name used as cache key. Overridden in generated proxies. */ queryName;
+    /* eslint-disable @typescript-eslint/no-explicit-any */ validation;
+    /* eslint-enable @typescript-eslint/no-explicit-any */ roles = [];
     abortController;
     sorting;
     paging;
     parameters;
-    constructor(modelType, enumerable) {
+    /**
+     * 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(modelType, enumerable){
         this.modelType = modelType;
         this.enumerable = enumerable;
         this.sorting = Sorting.Sorting.none;
@@ -32,22 +41,27 @@ class QueryFor {
         this._microservice = Globals.Globals.microservice ?? '';
         this._apiBasePath = Globals.Globals.apiBasePath ?? '';
         this._origin = Globals.Globals.origin ?? '';
-        this._httpHeadersCallback = () => ({});
+        this._httpHeadersCallback = ()=>({});
     }
-    setMicroservice(microservice) {
+    /** @inheritdoc */ setMicroservice(microservice) {
         this._microservice = microservice;
     }
-    setApiBasePath(apiBasePath) {
+    /** @inheritdoc */ setApiBasePath(apiBasePath) {
         this._apiBasePath = apiBasePath;
     }
-    setOrigin(origin) {
+    /** @inheritdoc */ setOrigin(origin) {
         this._origin = origin;
     }
-    setHttpHeadersCallback(callback) {
+    /** @inheritdoc */ setHttpHeadersCallback(callback) {
         this._httpHeadersCallback = callback;
     }
-    async perform(args) {
-        const noSuccess = { ...QueryResult.QueryResult.noSuccess, ...{ data: this.defaultValue } };
+    /** @inheritdoc */ async perform(args) {
+        const noSuccess = {
+            ...QueryResult.QueryResult.noSuccess,
+            ...{
+                data: this.defaultValue
+            }
+        };
         args = args || this.parameters;
         const clientValidationErrors = this.validation?.validate(args || {}) || [];
         if (clientValidationErrors.length > 0) {
@@ -57,12 +71,12 @@ class QueryFor {
                 isAuthorized: true,
                 isValid: false,
                 hasExceptions: false,
-                validationResults: clientValidationErrors.map(_ => ({
-                    severity: _.severity,
-                    message: _.message,
-                    members: _.members,
-                    state: _.state
-                })),
+                validationResults: clientValidationErrors.map((_)=>({
+                        severity: _.severity,
+                        message: _.message,
+                        members: _.members,
+                        state: _.state
+                    })),
                 exceptionMessages: [],
                 exceptionStackTrace: '',
                 paging: {
@@ -74,7 +88,7 @@ class QueryFor {
             }, this.modelType, this.enumerable);
         }
         if (!ValidateRequestArguments.ValidateRequestArguments(this.constructor.name, this.requiredRequestParameters, args)) {
-            return new Promise((resolve) => {
+            return new Promise((resolve)=>{
                 resolve(noSuccess);
             });
         }
@@ -91,17 +105,22 @@ class QueryFor {
         }
         if (this.sorting.hasSorting) {
             additionalParams.sortBy = this.sorting.field;
-            additionalParams.sortDirection = (this.sorting.direction === SortDirection.SortDirection.descending) ? 'desc' : 'asc';
+            additionalParams.sortDirection = this.sorting.direction === SortDirection.SortDirection.descending ? 'desc' : 'asc';
         }
+        // Collect parameter values from parameterDescriptors that are set
         const parameterValues = ParametersHelper.ParametersHelper.collectParameterValues(this);
-        const queryParams = UrlHelpers.UrlHelpers.buildQueryParams({ ...unusedParameters, ...parameterValues }, additionalParams);
+        const queryParams = UrlHelpers.UrlHelpers.buildQueryParams({
+            ...unusedParameters,
+            ...parameterValues
+        }, additionalParams);
         const queryString = queryParams.toString();
         if (queryString) {
             actualRoute += (actualRoute.includes('?') ? '&' : '?') + queryString;
         }
         const url = UrlHelpers.UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);
         const headers = {
-            ...this._httpHeadersCallback?.(), ...{
+            ...this._httpHeadersCallback?.(),
+            ...{
                 'Accept': 'application/json',
                 'Content-Type': 'application/json'
             }
@@ -117,8 +136,7 @@ class QueryFor {
         try {
             const result = await response.json();
             return new QueryResult.QueryResult(result, this.modelType, this.enumerable);
-        }
-        catch {
+        } catch  {
             return noSuccess;
         }
     }

package/dist/cjs/queries/QueryFor.js.map

@@ -1 +1 @@
-{"version":3,"file":"QueryFor.js","sources":["../../../queries/QueryFor.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { IQueryFor } from './IQueryFor';\nimport { QueryResult } from \"./QueryResult\";\nimport { QueryValidator } from './QueryValidator';\nimport { ValidateRequestArguments } from './ValidateRequestArguments';\nimport { Constructor } from '@cratis/fundamentals';\nimport { Paging } from './Paging';\nimport { Globals } from '../Globals';\nimport { Sorting } from './Sorting';\nimport { SortDirection } from './SortDirection';\nimport { joinPaths } from '../joinPaths';\nimport { UrlHelpers } from '../UrlHelpers';\nimport { GetHttpHeaders } from '../GetHttpHeaders';\nimport { ParameterDescriptor } from '../reflection/ParameterDescriptor';\nimport { ParametersHelper } from '../reflection/ParametersHelper';\n\n/**\n * Represents an implementation of {@link IQueryFor}.\n * @template TDataType Type of data returned by the query.\n */\nexport abstract class QueryFor<TDataType, TParameters = object> implements IQueryFor<TDataType, TParameters> {\n    private _microservice: string;\n    private _apiBasePath: string;\n    private _origin: string;\n    private _httpHeadersCallback: GetHttpHeaders;\n    abstract readonly route: string;\n    /** Backend fully-qualified query name used as cache key. Overridden in generated proxies. */\n    readonly queryName?: string;\n    /* eslint-disable @typescript-eslint/no-explicit-any */\n    readonly validation?: QueryValidator<any>;\n    /* eslint-enable @typescript-eslint/no-explicit-any */\n    readonly roles: string[] = [];\n    abstract readonly parameterDescriptors: ParameterDescriptor[];\n    abstract get requiredRequestParameters(): string[];\n    abstract defaultValue: TDataType;\n    abortController?: AbortController;\n    sorting: Sorting;\n    paging: Paging;\n    parameters: TParameters | undefined;\n\n    /**\n     * Initializes a new instance of the {@link ObservableQueryFor<,>}} class.\n     * @param modelType Type of model, if an enumerable, this is the instance type.\n     * @param enumerable Whether or not it is an enumerable.\n     */\n    constructor(readonly modelType: Constructor, readonly enumerable: boolean) {\n        this.sorting = Sorting.none;\n        this.paging = Paging.noPaging;\n        this._microservice = Globals.microservice ?? '';\n        this._apiBasePath = Globals.apiBasePath ?? '';\n        this._origin = Globals.origin ?? '';\n        this._httpHeadersCallback = () => ({});\n    }\n\n    /** @inheritdoc */\n    setMicroservice(microservice: string) {\n        this._microservice = microservice;\n    }\n\n    /** @inheritdoc */\n    setApiBasePath(apiBasePath: string): void {\n        this._apiBasePath = apiBasePath;\n    }\n\n    /** @inheritdoc */\n    setOrigin(origin: string): void {\n        this._origin = origin;\n    }\n\n    /** @inheritdoc */\n    setHttpHeadersCallback(callback: GetHttpHeaders): void {\n        this._httpHeadersCallback = callback;\n    }\n\n    /** @inheritdoc */\n    async perform(args?: TParameters): Promise<QueryResult<TDataType>> {\n        const noSuccess = { ...QueryResult.noSuccess, ...{ data: this.defaultValue } } as QueryResult<TDataType>;\n\n        args = args || this.parameters;\n\n        const clientValidationErrors = this.validation?.validate(args as object || {}) || [];\n        if (clientValidationErrors.length > 0) {\n            return new QueryResult({\n                data: this.defaultValue as object,\n                isSuccess: false,\n                isAuthorized: true,\n                isValid: false,\n                hasExceptions: false,\n                validationResults: clientValidationErrors.map(_ => ({\n                    severity: _.severity,\n                    message: _.message,\n                    members: _.members,\n                    state: _.state\n                })),\n                exceptionMessages: [],\n                exceptionStackTrace: '',\n                paging: {\n                    totalItems: 0,\n                    totalPages: 0,\n                    page: 0,\n                    size: 0\n                }\n            }, this.modelType, this.enumerable) as QueryResult<TDataType>;\n        }\n\n        if (!ValidateRequestArguments(this.constructor.name, this.requiredRequestParameters, args as object)) {\n            return new Promise<QueryResult<TDataType>>((resolve) => {\n                resolve(noSuccess);\n            });\n        }\n\n        if (this.abortController) {\n            this.abortController.abort();\n        }\n\n        this.abortController = new AbortController();\n\n        const { route, unusedParameters } = UrlHelpers.replaceRouteParameters(this.route, args as object);\n        let actualRoute = joinPaths(this._apiBasePath, route);\n        \n        const additionalParams: Record<string, string | number> = {};\n        if (this.paging.hasPaging) {\n            additionalParams.page = this.paging.page;\n            additionalParams.pageSize = this.paging.pageSize;\n        }\n\n        if (this.sorting.hasSorting) {\n            additionalParams.sortBy = this.sorting.field;\n            additionalParams.sortDirection = (this.sorting.direction === SortDirection.descending) ? 'desc' : 'asc';\n        }\n\n        // Collect parameter values from parameterDescriptors that are set\n        const parameterValues = ParametersHelper.collectParameterValues(this);\n\n        const queryParams = UrlHelpers.buildQueryParams({ ...unusedParameters, ...parameterValues }, additionalParams);\n        const queryString = queryParams.toString();\n        if (queryString) {\n            actualRoute += (actualRoute.includes('?') ? '&' : '?') + queryString;\n        }\n        \n        const url = UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);\n\n        const headers = {\n            ... this._httpHeadersCallback?.(), ...\n            {\n                'Accept': 'application/json',\n                'Content-Type': 'application/json'\n            }\n        };\n\n        if (this._microservice?.length > 0) {\n            headers[Globals.microserviceHttpHeader] = this._microservice;\n        }\n\n        const response = await fetch(url, {\n            method: 'GET',\n            headers,\n            signal: this.abortController.signal\n        });\n\n        try {\n            const result = await response.json();\n            return new QueryResult(result, this.modelType, this.enumerable);\n        } catch {\n            return noSuccess;\n        }\n    }\n}\n"],"names":["Sorting","Paging","Globals","QueryResult","ValidateRequestArguments","UrlHelpers","joinPaths","SortDirection","ParametersHelper"],"mappings":"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"}
+{"version":3,"file":"QueryFor.js","sources":["../../../queries/QueryFor.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { IQueryFor } from './IQueryFor';\nimport { QueryResult } from \"./QueryResult\";\nimport { QueryValidator } from './QueryValidator';\nimport { ValidateRequestArguments } from './ValidateRequestArguments';\nimport { Constructor } from '@cratis/fundamentals';\nimport { Paging } from './Paging';\nimport { Globals } from '../Globals';\nimport { Sorting } from './Sorting';\nimport { SortDirection } from './SortDirection';\nimport { joinPaths } from '../joinPaths';\nimport { UrlHelpers } from '../UrlHelpers';\nimport { GetHttpHeaders } from '../GetHttpHeaders';\nimport { ParameterDescriptor } from '../reflection/ParameterDescriptor';\nimport { ParametersHelper } from '../reflection/ParametersHelper';\n\n/**\n * Represents an implementation of {@link IQueryFor}.\n * @template TDataType Type of data returned by the query.\n */\nexport abstract class QueryFor<TDataType, TParameters = object> implements IQueryFor<TDataType, TParameters> {\n    private _microservice: string;\n    private _apiBasePath: string;\n    private _origin: string;\n    private _httpHeadersCallback: GetHttpHeaders;\n    abstract readonly route: string;\n    /** Backend fully-qualified query name used as cache key. Overridden in generated proxies. */\n    readonly queryName?: string;\n    /* eslint-disable @typescript-eslint/no-explicit-any */\n    readonly validation?: QueryValidator<any>;\n    /* eslint-enable @typescript-eslint/no-explicit-any */\n    readonly roles: string[] = [];\n    abstract readonly parameterDescriptors: ParameterDescriptor[];\n    abstract get requiredRequestParameters(): string[];\n    abstract defaultValue: TDataType;\n    abortController?: AbortController;\n    sorting: Sorting;\n    paging: Paging;\n    parameters: TParameters | undefined;\n\n    /**\n     * Initializes a new instance of the {@link ObservableQueryFor<,>}} class.\n     * @param modelType Type of model, if an enumerable, this is the instance type.\n     * @param enumerable Whether or not it is an enumerable.\n     */\n    constructor(readonly modelType: Constructor, readonly enumerable: boolean) {\n        this.sorting = Sorting.none;\n        this.paging = Paging.noPaging;\n        this._microservice = Globals.microservice ?? '';\n        this._apiBasePath = Globals.apiBasePath ?? '';\n        this._origin = Globals.origin ?? '';\n        this._httpHeadersCallback = () => ({});\n    }\n\n    /** @inheritdoc */\n    setMicroservice(microservice: string) {\n        this._microservice = microservice;\n    }\n\n    /** @inheritdoc */\n    setApiBasePath(apiBasePath: string): void {\n        this._apiBasePath = apiBasePath;\n    }\n\n    /** @inheritdoc */\n    setOrigin(origin: string): void {\n        this._origin = origin;\n    }\n\n    /** @inheritdoc */\n    setHttpHeadersCallback(callback: GetHttpHeaders): void {\n        this._httpHeadersCallback = callback;\n    }\n\n    /** @inheritdoc */\n    async perform(args?: TParameters): Promise<QueryResult<TDataType>> {\n        const noSuccess = { ...QueryResult.noSuccess, ...{ data: this.defaultValue } } as QueryResult<TDataType>;\n\n        args = args || this.parameters;\n\n        const clientValidationErrors = this.validation?.validate(args as object || {}) || [];\n        if (clientValidationErrors.length > 0) {\n            return new QueryResult({\n                data: this.defaultValue as object,\n                isSuccess: false,\n                isAuthorized: true,\n                isValid: false,\n                hasExceptions: false,\n                validationResults: clientValidationErrors.map(_ => ({\n                    severity: _.severity,\n                    message: _.message,\n                    members: _.members,\n                    state: _.state\n                })),\n                exceptionMessages: [],\n                exceptionStackTrace: '',\n                paging: {\n                    totalItems: 0,\n                    totalPages: 0,\n                    page: 0,\n                    size: 0\n                }\n            }, this.modelType, this.enumerable) as QueryResult<TDataType>;\n        }\n\n        if (!ValidateRequestArguments(this.constructor.name, this.requiredRequestParameters, args as object)) {\n            return new Promise<QueryResult<TDataType>>((resolve) => {\n                resolve(noSuccess);\n            });\n        }\n\n        if (this.abortController) {\n            this.abortController.abort();\n        }\n\n        this.abortController = new AbortController();\n\n        const { route, unusedParameters } = UrlHelpers.replaceRouteParameters(this.route, args as object);\n        let actualRoute = joinPaths(this._apiBasePath, route);\n        \n        const additionalParams: Record<string, string | number> = {};\n        if (this.paging.hasPaging) {\n            additionalParams.page = this.paging.page;\n            additionalParams.pageSize = this.paging.pageSize;\n        }\n\n        if (this.sorting.hasSorting) {\n            additionalParams.sortBy = this.sorting.field;\n            additionalParams.sortDirection = (this.sorting.direction === SortDirection.descending) ? 'desc' : 'asc';\n        }\n\n        // Collect parameter values from parameterDescriptors that are set\n        const parameterValues = ParametersHelper.collectParameterValues(this);\n\n        const queryParams = UrlHelpers.buildQueryParams({ ...unusedParameters, ...parameterValues }, additionalParams);\n        const queryString = queryParams.toString();\n        if (queryString) {\n            actualRoute += (actualRoute.includes('?') ? '&' : '?') + queryString;\n        }\n        \n        const url = UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);\n\n        const headers = {\n            ... this._httpHeadersCallback?.(), ...\n            {\n                'Accept': 'application/json',\n                'Content-Type': 'application/json'\n            }\n        };\n\n        if (this._microservice?.length > 0) {\n            headers[Globals.microserviceHttpHeader] = this._microservice;\n        }\n\n        const response = await fetch(url, {\n            method: 'GET',\n            headers,\n            signal: this.abortController.signal\n        });\n\n        try {\n            const result = await response.json();\n            return new QueryResult(result, this.modelType, this.enumerable);\n        } catch {\n            return noSuccess;\n        }\n    }\n}\n"],"names":["QueryFor","_microservice","_apiBasePath","_origin","_httpHeadersCallback","queryName","validation","roles","abortController","sorting","paging","parameters","enumerable","modelType","Sorting","none","Paging","noPaging","Globals","microservice","apiBasePath","origin","setMicroservice","setApiBasePath","setOrigin","setHttpHeadersCallback","callback","perform","args","noSuccess","QueryResult","data","defaultValue","clientValidationErrors","validate","length","isSuccess","isAuthorized","isValid","hasExceptions","validationResults","map","_","severity","message","members","state","exceptionMessages","exceptionStackTrace","totalItems","totalPages","page","size","ValidateRequestArguments","name","requiredRequestParameters","Promise","resolve","abort","AbortController","route","unusedParameters","UrlHelpers","replaceRouteParameters","actualRoute","joinPaths","additionalParams","hasPaging","pageSize","hasSorting","sortBy","field","sortDirection","direction","SortDirection","descending","parameterValues","ParametersHelper","collectParameterValues","queryParams","buildQueryParams","queryString","toString","includes","url","createUrlFrom","headers","microserviceHttpHeader","response","fetch","method","signal","result","json"],"mappings":"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"}

package/dist/cjs/queries/QueryInstanceCache.js

@@ -1,40 +1,79 @@
 'use strict';
 
-class QueryInstanceCache {
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Provides a cache for query instances, keyed by query type and serialized arguments.
+ *
+ * Two callers requesting the same query type with identical arguments receive the same
+ * cached instance and immediately see the last known result — without an additional
+ * round trip to the server. When the last subscriber releases its reference the entry
+ * is evicted.
+ */ class QueryInstanceCache {
     _retentionMs;
     _entries = new Map();
     _pendingDispose;
-    constructor(_retentionMs = 30_000) {
+    /**
+     * Initializes a new instance of {@link QueryInstanceCache}.
+     * @param retentionMs How long in milliseconds to keep a cache entry alive after the last
+     *   subscriber releases it before evicting the subscription and cached data.  A non-zero
+     *   value lets users navigate away and back without losing cached data.  Defaults to
+     *   30 000 ms.  Pass 0 for immediate eviction.
+     */ constructor(_retentionMs = 30_000){
         this._retentionMs = _retentionMs;
     }
-    buildKey(queryTypeName, args) {
+    /**
+     * Builds the cache key for a query.
+     * @param queryTypeName The stable type name for the query. Use the instance's {@link queryName}
+     *   (a hardcoded fully-qualified string in generated proxies) rather than {@link Function.name},
+     *   which is unstable under minification.
+     * @param args Optional arguments supplied to the query.
+     * @returns A stable string key.
+     */ buildKey(queryTypeName, args) {
         if (!args || Object.keys(args).length === 0) {
             return `${queryTypeName}::`;
         }
-        const sorted = Object.keys(args)
-            .sort()
-            .reduce((accumulator, key) => {
+        const sorted = Object.keys(args).sort().reduce((accumulator, key)=>{
             accumulator[key] = args[key];
             return accumulator;
         }, {});
         return `${queryTypeName}::${JSON.stringify(sorted)}`;
     }
-    getOrCreate(key, factory) {
+    /**
+     * Returns a cached instance for the given key, or creates a new one using the provided factory.
+     * The subscriber count of the entry is incremented.
+     * @template TInstance The type of the query instance.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param factory A zero-argument factory that creates a fresh query instance when one is not yet cached.
+     * @returns The cached (or newly created) instance and whether it was newly created.
+     */ getOrCreate(key, factory) {
         if (!this._entries.has(key)) {
             const entry = {
                 instance: factory(),
                 lastResult: undefined,
                 subscriberCount: 0,
                 listeners: new Set(),
-                subscribed: false,
+                subscribed: false
             };
             this._entries.set(key, entry);
-            return { instance: entry.instance, isNew: true };
+            return {
+                instance: entry.instance,
+                isNew: true
+            };
         }
         const entry = this._entries.get(key);
-        return { instance: entry.instance, isNew: false };
+        return {
+            instance: entry.instance,
+            isNew: false
+        };
     }
-    acquire(key) {
+    /**
+     * Increments the active subscriber count for the given key.
+     * If a deferred cleanup was pending (from a recent {@link release}),
+     * it is cancelled so the existing subscription is reused.
+     * Call from `useEffect` setup to pair with {@link release} in the cleanup.
+     * @param key The cache key produced by {@link buildKey}.
+     */ acquire(key) {
         const entry = this._entries.get(key);
         if (entry) {
             if (entry.pendingCleanup !== undefined) {
@@ -44,52 +83,92 @@ class QueryInstanceCache {
             entry.subscriberCount++;
         }
     }
-    getLastResult(key) {
+    /**
+     * Returns the last cached result for the given key, or `undefined` if no result has been stored yet.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @returns The last {@link QueryResultWithState}, or `undefined`.
+     */ getLastResult(key) {
         return this._entries.get(key)?.lastResult;
     }
-    setLastResult(key, result) {
+    /**
+     * Stores the most recent result for the given key and notifies all registered listeners.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param result The result to store.
+     */ setLastResult(key, result) {
         const entry = this._entries.get(key);
         if (entry) {
             const previousResult = entry.lastResult;
             entry.lastResult = result;
-            if (previousResult !== undefined &&
-                previousResult.isSuccess === result.isSuccess &&
-                JSON.stringify(previousResult.data) === JSON.stringify(result.data)) {
+            // Suppress re-renders when the server re-sends identical data after a reconnect.
+            // We only compare `data` and `isSuccess` — other fields (e.g. changeSet) are
+            // ephemeral and do not affect what the user sees.
+            if (previousResult !== undefined && previousResult.isSuccess === result.isSuccess && JSON.stringify(previousResult.data) === JSON.stringify(result.data)) {
                 return;
             }
-            for (const listener of entry.listeners) {
+            for (const listener of entry.listeners){
                 listener(result);
             }
         }
     }
-    addListener(key, listener) {
+    /**
+     * Registers a listener that is invoked whenever the cached result for the given key changes.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param listener The callback to register.
+     */ addListener(key, listener) {
         const entry = this._entries.get(key);
         if (entry) {
             entry.listeners.add(listener);
         }
     }
-    removeListener(key, listener) {
+    /**
+     * Removes a previously registered listener.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param listener The callback to remove.
+     */ removeListener(key, listener) {
         const entry = this._entries.get(key);
         if (entry) {
             entry.listeners.delete(listener);
         }
     }
-    setTeardown(key, teardown) {
+    /**
+     * Stores a teardown function for the given key and marks the entry as subscribed.
+     * Called automatically when the last subscriber releases the entry.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param teardown Cleanup function that disconnects the underlying query subscription.
+     */ setTeardown(key, teardown) {
         const entry = this._entries.get(key);
         if (entry) {
             entry.teardown = teardown;
             entry.subscribed = true;
         }
     }
-    isSubscribed(key) {
+    /**
+     * Returns whether an active subscription exists for the given key.
+     * @param key The cache key to check.
+     * @returns `true` if a subscription has been established; `false` otherwise.
+     */ isSubscribed(key) {
         return this._entries.get(key)?.subscribed ?? false;
     }
-    release(key) {
+    /**
+     * Decrements the subscriber count for the given key. When the count reaches zero, both teardown
+     * and eviction are deferred by one microtask so that React StrictMode re-mounts — in any build
+     * environment — can re-acquire the entry and cancel the cleanup before the timeout fires. This
+     * prevents an unnecessary disconnect/reconnect cycle during the synthetic unmount/remount that
+     * StrictMode performs.
+     * @param key The cache key produced by {@link buildKey}.
+     */ release(key) {
         const entry = this._entries.get(key);
         if (entry) {
             entry.subscriberCount--;
             if (entry.subscriberCount <= 0) {
-                entry.pendingCleanup = setTimeout(() => {
+                // Defer both teardown and eviction.  React StrictMode re-mounts can cancel by
+                // calling acquire() before the timeout fires.  A non-zero _retentionMs keeps the
+                // entry alive so users navigating back quickly see cached data immediately.
+                entry.pendingCleanup = setTimeout(()=>{
                     const current = this._entries.get(key);
                     if (current && current.subscriberCount <= 0) {
                         current.subscribed = false;
@@ -102,11 +181,24 @@ class QueryInstanceCache {
             }
         }
     }
-    has(key) {
+    /**
+     * Returns whether an entry exists for the given key.
+     * @param key The cache key to check.
+     * @returns `true` if an entry exists; `false` otherwise.
+     */ has(key) {
         return this._entries.has(key);
     }
-    teardownAllSubscriptions() {
-        for (const [, entry] of this._entries) {
+    /**
+     * Tears down all active subscriptions and marks every entry as not subscribed,
+     * but preserves entries, subscriber counts, and listeners. This allows
+     * hooks whose effects re-run afterward to detect that the entry is no longer
+     * subscribed and re-establish a fresh connection.
+     *
+     * Use this when the underlying transport must be replaced (e.g. after an
+     * authentication change that requires new WebSocket connections with updated
+     * credentials).
+     */ teardownAllSubscriptions() {
+        for (const [, entry] of this._entries){
             if (entry.pendingCleanup !== undefined) {
                 clearTimeout(entry.pendingCleanup);
                 entry.pendingCleanup = undefined;
@@ -116,8 +208,12 @@ class QueryInstanceCache {
             entry.teardown = undefined;
         }
     }
-    dispose() {
-        for (const [, entry] of this._entries) {
+    /**
+     * Immediately tears down all subscriptions, cancels any pending deferred cleanups,
+     * and evicts all entries. Call when the owning component (e.g. the {@link Arc} provider)
+     * unmounts permanently so that all query connections are closed synchronously.
+     */ dispose() {
+        for (const [, entry] of this._entries){
             if (entry.pendingCleanup !== undefined) {
                 clearTimeout(entry.pendingCleanup);
                 entry.pendingCleanup = undefined;
@@ -128,26 +224,42 @@ class QueryInstanceCache {
         }
         this._entries.clear();
     }
-    deferDispose() {
+    /**
+     * Schedules a deferred {@link dispose} using {@code setTimeout(0)}.
+     *
+     * This allows React StrictMode re-mounts to call {@link cancelPendingDispose}
+     * before the dispose fires, avoiding the destruction of cache entries that child
+     * effects are about to re-acquire.
+     *
+     * If a deferred dispose is already pending, it is replaced.
+     */ deferDispose() {
         if (this._pendingDispose !== undefined) {
             clearTimeout(this._pendingDispose);
         }
-        this._pendingDispose = setTimeout(() => {
+        this._pendingDispose = setTimeout(()=>{
             this._pendingDispose = undefined;
             this.dispose();
         }, 0);
     }
-    cancelPendingDispose() {
+    /**
+     * Cancels a pending deferred dispose scheduled by {@link deferDispose}.
+     *
+     * Call from the {@code useEffect} setup phase so that a StrictMode re-mount
+     * prevents the synthetic unmount's deferred dispose from firing.
+     */ cancelPendingDispose() {
         if (this._pendingDispose !== undefined) {
             clearTimeout(this._pendingDispose);
             this._pendingDispose = undefined;
         }
     }
-    getDiagnosticsSnapshot() {
+    /**
+     * Returns a diagnostics snapshot of the current cache state.
+     * @returns A {@link CacheDiagnostics} describing all entries.
+     */ getDiagnosticsSnapshot() {
         const entries = [];
         let totalBytes = 0;
         let unhealthyCount = 0;
-        for (const [key, entry] of this._entries) {
+        for (const [key, entry] of this._entries){
             const colonIndex = key.indexOf('::');
             const queryName = colonIndex >= 0 ? key.substring(0, colonIndex) : key;
             let estimatedBytes = 0;
@@ -155,8 +267,8 @@ class QueryInstanceCache {
                 if (entry.lastResult !== undefined) {
                     estimatedBytes = JSON.stringify(entry.lastResult).length;
                 }
-            }
-            catch {
+            } catch  {
+            // Ignore serialization errors
             }
             if (entry.subscriberCount > 0 && !entry.subscribed) {
                 unhealthyCount++;
@@ -169,14 +281,14 @@ class QueryInstanceCache {
                 listenerCount: entry.listeners.size,
                 subscribed: entry.subscribed,
                 hasResult: entry.lastResult !== undefined,
-                estimatedBytes,
+                estimatedBytes
             });
         }
         return {
             healthy: unhealthyCount === 0,
             entryCount: this._entries.size,
             estimatedBytes: totalBytes,
-            entries,
+            entries
         };
     }
 }