@cratis/arc 22.0.2 → 22.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/arc",
-    "version": "22.0.2",
+    "version": "22.1.0",
     "description": "",
     "author": "Cratis",
     "license": "MIT",

package/queries/IQueryResult.ts

@@ -24,6 +24,16 @@ export interface IQueryResult<TDataType> {
      */
     readonly isSuccess: boolean;
 
+    /**
+     * Gets whether the query has produced a result.
+     * A false value is a transient observable-query state, not a failure.
+     *
+     * Optional for source compatibility with older servers and third-party structural results that
+     * predate readiness. Arc normalizes transport results that omit it to true, while SDK-produced
+     * result classes always expose a concrete boolean.
+     */
+    readonly isReady?: boolean;
+
     /**
      * Gets whether or not the query was authorized to execute.
      */

package/queries/ObservableQueryFor.ts

@@ -28,7 +28,10 @@ import { executeQueryHttpRequest } from './QueryHttpRequest';
  * 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> {
+export abstract class ObservableQueryFor<
+    TDataType,
+    TParameters = object,
+> implements IObservableQueryFor<TDataType, TParameters> {
     private _microservice: string;
     private _apiBasePath: string;
     private _origin: string;
@@ -52,7 +55,10 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
      * @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) {
+    constructor(
+        readonly modelType: Constructor,
+        readonly enumerable: boolean,
+    ) {
         this.sorting = Sorting.none;
         this.paging = Paging.noPaging;
         this._microservice = Globals.microservice ?? '';
@@ -94,18 +100,23 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
     }
 
     /** @inheritdoc */
-    subscribe(callback: OnNextResult<QueryResult<TDataType>>, args?: TParameters): ObservableQuerySubscription<TDataType> {
+    subscribe(
+        callback: OnNextResult<QueryResult<TDataType>>,
+        args?: TParameters,
+    ): ObservableQuerySubscription<TDataType> {
         if (this._connection) {
             this._connection.disconnect();
         }
 
-        const clientValidationErrors = this.validation?.validate(args as object || {}) || [];
+        const clientValidationErrors =
+            this.validation?.validate((args as object) || {}) || [];
         if (clientValidationErrors.length > 0) {
             // Serve the failure through the connection rather than throwing, so a subscriber sees an invalid result
             // on its normal callback path instead of the empty result an unestablished connection would emit.
             this._connection = new NullObservableQueryConnection(
                 this.defaultValue,
-                QueryResult.validationFailed(clientValidationErrors, this));
+                QueryResult.validationFailed(clientValidationErrors, this),
+            );
         } else if (this.validateArguments(args)) {
             this._connection = createObservableQueryConnection({
                 route: this.route,
@@ -128,17 +139,25 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
         // In multiplexed mode ALL arguments — including route-derived ones — must be included
         // in the subscribe payload so the server can execute the query correctly.
         const parameterValues = ParametersHelper.collectParameterValues(this);
-        const { unusedParameters } = UrlHelpers.replaceRouteParameters(this.route, args as object);
+        const { unusedParameters } = UrlHelpers.replaceRouteParameters(
+            this.route,
+            args as object,
+        );
         const connectionQueryArguments: any = {
             ...parameterValues,
             ...(Globals.queryDirectMode ? unusedParameters : (args as object) || {}),
-            ...this.buildQueryArguments()
+            ...this.buildQueryArguments(),
         };
 
         const subscriber = new ObservableQuerySubscription(this._connection);
-        this._connection.connect(data => {
+        this._connection.connect((data) => {
             const result: any = data;
             try {
+                // Observable transports deliver structural query-result envelopes directly instead of
+                // constructing QueryResult. Servers predating readiness therefore omit the member;
+                // those results are complete by definition and must be normalized before subscribers
+                // observe them. Preserve an explicit false transient state from newer servers.
+                result.isReady ??= true;
                 this.deserializeResult(result);
                 callback(result);
             } catch (ex) {
@@ -150,9 +169,13 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
 
     /** @inheritdoc */
     async perform(args?: TParameters): Promise<QueryResult<TDataType>> {
-        const noSuccess = { ...QueryResult.noSuccess, ...{ data: this.defaultValue } } as QueryResult<TDataType>;
+        const noSuccess = {
+            ...QueryResult.noSuccess,
+            ...{ data: this.defaultValue },
+        } as QueryResult<TDataType>;
 
-        const clientValidationErrors = this.validation?.validate(args as object || {}) || [];
+        const clientValidationErrors =
+            this.validation?.validate((args as object) || {}) || [];
         if (clientValidationErrors.length > 0) {
             return QueryResult.validationFailed(clientValidationErrors, this);
         }
@@ -168,8 +191,8 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
 
         const headers = {
             ...(this._httpHeadersCallback?.() || {}),
-            'Accept': 'application/json',
-            'Content-Type': 'application/json'
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
         };
 
         if (this._microservice?.length > 0) {
@@ -184,7 +207,7 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
             parameterValues,
             paging: this.paging,
             sorting: this.sorting,
-            headers
+            headers,
         });
 
         try {
@@ -197,8 +220,12 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
 
     private validateArguments(args?: TParameters): boolean {
         const parameterValues = ParametersHelper.collectParameterValues(this);
-        const combinedArgs = { ...(args as object || {}), ...parameterValues };
-        return ValidateRequestArguments(this.constructor.name, this.requiredRequestParameters, combinedArgs as object);
+        const combinedArgs = { ...((args as object) || {}), ...parameterValues };
+        return ValidateRequestArguments(
+            this.constructor.name,
+            this.requiredRequestParameters,
+            combinedArgs as object,
+        );
     }
 
     private buildQueryArguments(): any {
@@ -211,7 +238,8 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
 
         if (this.sorting.hasSorting) {
             queryArguments.sortBy = this.sorting.field;
-            queryArguments.sortDirection = (this.sorting.direction === SortDirection.descending) ? 'desc' : 'asc';
+            queryArguments.sortDirection =
+                this.sorting.direction === SortDirection.descending ? 'desc' : 'asc';
         }
 
         return queryArguments;

package/queries/QueryInstanceCache.ts

@@ -2,7 +2,10 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { QueryResultWithState } from './QueryResultWithState';
-import { CacheDiagnostics, CacheEntryDiagnostics } from './ObservableQueryDiagnosticsSnapshot';
+import type {
+    CacheDiagnostics,
+    CacheEntryDiagnostics,
+} from './ObservableQueryDiagnosticsSnapshot';
 import { reconcileQueryData } from './reconcileQueryData';
 
 /**
@@ -13,7 +16,9 @@ export type QueryCacheKey = string;
 /**
  * Callback invoked when the cached result for an entry changes.
  */
-export type QueryCacheListener<TDataType> = (result: QueryResultWithState<TDataType>) => void;
+export type QueryCacheListener<TDataType> = (
+    result: QueryResultWithState<TDataType>,
+) => void;
 
 /**
  * Represents a single entry in the {@link QueryInstanceCache}.
@@ -78,12 +83,11 @@ export class QueryInstanceCache {
      *   value lets users navigate away and back without losing cached data.  Defaults to
      *   30 000 ms.  Pass 0 for immediate eviction.
      */
-    constructor(private readonly _retentionMs: number = 30_000) {
-    }
+    constructor(private readonly _retentionMs: number = 30_000) {}
 
     /**
      * Builds the cache key for a query.
-     * @param queryTypeName The stable type name for the query. Use the instance's {@link queryName}
+     * @param queryTypeName The stable type name for the query. Use the instance's `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.
@@ -114,7 +118,7 @@ export class QueryInstanceCache {
      */
     getOrCreate<TInstance>(
         key: QueryCacheKey,
-        factory: () => TInstance
+        factory: () => TInstance,
     ): { instance: TInstance; isNew: boolean } {
         if (!this._entries.has(key)) {
             const entry: QueryCacheEntry<unknown> = {
@@ -159,8 +163,12 @@ export class QueryInstanceCache {
      * @param key The cache key produced by {@link buildKey}.
      * @returns The last {@link QueryResultWithState}, or `undefined`.
      */
-    getLastResult<TDataType>(key: QueryCacheKey): QueryResultWithState<TDataType> | undefined {
-        return this._entries.get(key)?.lastResult as QueryResultWithState<TDataType> | undefined;
+    getLastResult<TDataType>(
+        key: QueryCacheKey,
+    ): QueryResultWithState<TDataType> | undefined {
+        return this._entries.get(key)?.lastResult as
+            | QueryResultWithState<TDataType>
+            | undefined;
     }
 
     /**
@@ -169,31 +177,38 @@ export class QueryInstanceCache {
      * @param key The cache key produced by {@link buildKey}.
      * @param result The result to store.
      */
-    setLastResult<TDataType>(key: QueryCacheKey, result: QueryResultWithState<TDataType>): void {
+    setLastResult<TDataType>(
+        key: QueryCacheKey,
+        result: QueryResultWithState<TDataType>,
+    ): void {
         const entry = this._entries.get(key);
 
         if (!entry) {
             return;
         }
 
-        const previousResult = entry.lastResult as QueryResultWithState<TDataType> | undefined;
+        const previousResult = entry.lastResult as
+            | QueryResultWithState<TDataType>
+            | undefined;
 
         // Reconcile the incoming payload against the one already held so items that did not actually
         // change keep their previous references. A full snapshot — which is what the server re-sends
         // whenever a subscription is re-established — otherwise arrives as all-new references and
         // makes every consumer treat every item as changed.
-        const reconciled = previousResult !== undefined
-            ? this.withReconciledData(previousResult, result)
-            : result;
+        const reconciled =
+            previousResult === undefined
+                ? result
+                : this.withReconciledData(previousResult, result);
 
         entry.lastResult = reconciled as QueryResultWithState<unknown>;
 
         // Reconciliation returns the previous data reference when nothing changed, so identity is
-        // enough to detect it. Only `data` and `isSuccess` matter here — the other fields (e.g.
-        // changeSet) are ephemeral and do not affect what the user sees.
+        // enough to detect it. Data, success, and readiness affect what the user sees; changeSet is
+        // ephemeral and does not independently require a notification.
         if (
             previousResult !== undefined &&
             previousResult.isSuccess === reconciled.isSuccess &&
+            previousResult.isReady === reconciled.isReady &&
             previousResult.data === reconciled.data
         ) {
             return;
@@ -214,7 +229,7 @@ export class QueryInstanceCache {
      */
     private withReconciledData<TDataType>(
         previous: QueryResultWithState<TDataType>,
-        next: QueryResultWithState<TDataType>
+        next: QueryResultWithState<TDataType>,
     ): QueryResultWithState<TDataType> {
         const reconciledData = reconcileQueryData(previous.data, next.data);
 
@@ -233,7 +248,9 @@ export class QueryInstanceCache {
             next.exceptionMessages,
             next.exceptionStackTrace,
             next.isPerforming,
-            next.changeSet);
+            next.changeSet,
+            next.isReady,
+        );
     }
 
     /**
@@ -242,7 +259,10 @@ export class QueryInstanceCache {
      * @param key The cache key produced by {@link buildKey}.
      * @param listener The callback to register.
      */
-    addListener<TDataType>(key: QueryCacheKey, listener: QueryCacheListener<TDataType>): void {
+    addListener<TDataType>(
+        key: QueryCacheKey,
+        listener: QueryCacheListener<TDataType>,
+    ): void {
         const entry = this._entries.get(key);
 
         if (entry) {
@@ -256,7 +276,10 @@ export class QueryInstanceCache {
      * @param key The cache key produced by {@link buildKey}.
      * @param listener The callback to remove.
      */
-    removeListener<TDataType>(key: QueryCacheKey, listener: QueryCacheListener<TDataType>): void {
+    removeListener<TDataType>(
+        key: QueryCacheKey,
+        listener: QueryCacheListener<TDataType>,
+    ): void {
         const entry = this._entries.get(key);
 
         if (entry) {

package/queries/QueryResult.ts

@@ -13,6 +13,7 @@ type ServerQueryResult = {
     data: any;
     /* eslint-enable @typescript-eslint/no-explicit-any */
     isSuccess: boolean;
+    isReady?: boolean;
     isAuthorized: boolean;
     isValid: boolean;
     hasExceptions: boolean;
@@ -21,7 +22,7 @@ type ServerQueryResult = {
     exceptionStackTrace: string;
     paging: ServerPagingInfo;
     changeSet?: ServerChangeSet;
-}
+};
 
 type ServerChangeSet = {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -30,7 +31,7 @@ type ServerChangeSet = {
     replaced: any[];
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     removed: any[];
-}
+};
 
 type ServerValidationResult = {
     severity: number;
@@ -39,39 +40,47 @@ type ServerValidationResult = {
     state: object;
     reason?: string;
     reasonDetail?: string;
-}
+};
 
 type ServerPagingInfo = {
     page: number;
-    size: 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> {
-
+    /**
+     * Creates a settled empty result. It is ready because no server result is pending.
+     * @param defaultValue The query's empty data value.
+     * @returns A ready empty result.
+     */
     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);
+        return new QueryResult(
+            {
+                data: defaultValue as object,
+                isSuccess: true,
+                isReady: true,
+                isAuthorized: true,
+                isValid: true,
+                hasExceptions: false,
+                validationResults: [],
+                exceptionMessages: [],
+                exceptionStackTrace: '',
+                paging: {
+                    totalItems: 0,
+                    totalPages: 0,
+                    page: 0,
+                    size: 0,
+                },
+            },
+            Object,
+            false,
+        );
     }
 
     /**
@@ -79,42 +88,86 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
      * {@link CommandResult.validationFailed} so a caller reads a failed query the same way it reads a failed command.
      * @param {ValidationResult[]} validationResults The validation results that caused the failure.
      * @param {object} query The query being rejected, which describes how to shape its own result.
-     * @returns {QueryResult<TDataType>} A result that is neither successful nor valid.
+     * @returns {QueryResult<TDataType>} A ready result that is neither successful nor valid.
      */
     static validationFailed<TDataType>(
         validationResults: ValidationResult[],
-        query: { readonly defaultValue: TDataType; readonly modelType: Constructor; readonly enumerable: boolean }): QueryResult<TDataType> {
+        query: {
+            readonly defaultValue: TDataType;
+            readonly modelType: Constructor;
+            readonly enumerable: boolean;
+        },
+    ): QueryResult<TDataType> {
         const { defaultValue, modelType, enumerable } = query;
-        return new QueryResult({
-            data: defaultValue as object,
-            isSuccess: false,
-            isAuthorized: true,
-            isValid: false,
-            hasExceptions: false,
-            validationResults: validationResults.map(_ => ({
-                severity: _.severity,
-                message: _.message,
-                members: _.members,
-                state: _.state,
-                reason: _.reason,
-                reasonDetail: _.reasonDetail
-            })),
-            exceptionMessages: [],
-            exceptionStackTrace: '',
-            paging: {
-                totalItems: 0,
-                totalPages: 0,
-                page: 0,
-                size: 0
-            }
-        }, modelType, enumerable) as QueryResult<TDataType>;
+        return new QueryResult(
+            {
+                data: defaultValue as object,
+                isSuccess: false,
+                isReady: true,
+                isAuthorized: true,
+                isValid: false,
+                hasExceptions: false,
+                validationResults: validationResults.map((_) => ({
+                    severity: _.severity,
+                    message: _.message,
+                    members: _.members,
+                    state: _.state,
+                    reason: _.reason,
+                    reasonDetail: _.reasonDetail,
+                })),
+                exceptionMessages: [],
+                exceptionStackTrace: '',
+                paging: {
+                    totalItems: 0,
+                    totalPages: 0,
+                    page: 0,
+                    size: 0,
+                },
+            },
+            modelType,
+            enumerable,
+        ) as QueryResult<TDataType>;
     }
 
+    /**
+     * Creates a settled unauthorized result. Authorization rejection is terminal, so the result is ready.
+     * @returns A ready unauthorized result.
+     */
     static unauthorized<TDataType>(): QueryResult<TDataType> {
-        return new QueryResult({
-            data: null as unknown as object,
+        return new QueryResult(
+            {
+                // SAFETY: An unauthorized result intentionally has no data, while the wire envelope uses object.
+                data: null as unknown as object,
+                isSuccess: false,
+                isReady: true,
+                isAuthorized: false,
+                isValid: true,
+                hasExceptions: false,
+                validationResults: [],
+                exceptionMessages: [],
+                exceptionStackTrace: '',
+                paging: {
+                    totalItems: 0,
+                    totalPages: 0,
+                    page: 0,
+                    size: 0,
+                },
+            },
+            Object,
+            false,
+        );
+    }
+
+    /**
+     * A settled unsuccessful result used for client-side and transport failures. These failures are ready because
+     * the client has completed the attempt; they are not the server's transient not-ready state.
+     */
+    static noSuccess: QueryResult = new QueryResult(
+        {
+            data: {},
             isSuccess: false,
-            isAuthorized: false,
+            isReady: true,
+            isAuthorized: true,
             isValid: true,
             hasExceptions: false,
             validationResults: [],
@@ -124,27 +177,12 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
                 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);
+                size: 0,
+            },
+        },
+        Object,
+        false,
+    );
 
     /**
      * Creates an instance of query result.
@@ -152,12 +190,29 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
      * @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) {
+    constructor(
+        result: ServerQueryResult,
+        instanceType: Constructor,
+        enumerable: boolean,
+    ) {
         this.isSuccess = result.isSuccess;
+        // Older servers and hand-built envelopes do not carry readiness. Those results predate
+        // the transient not-ready state and are therefore complete from the client's perspective.
+        this.isReady = result.isReady ?? true;
         this.isAuthorized = result.isAuthorized;
         this.isValid = result.isValid;
         this.hasExceptions = result.hasExceptions;
-        this.validationResults = result.validationResults.map(_ => new ValidationResult(_.severity, _.message, _.members, _.state, _.reason, _.reasonDetail));
+        this.validationResults = result.validationResults.map(
+            (_) =>
+                new ValidationResult(
+                    _.severity,
+                    _.message,
+                    _.members,
+                    _.state,
+                    _.reason,
+                    _.reasonDetail,
+                ),
+        );
         this.exceptionMessages = result.exceptionMessages;
         this.exceptionStackTrace = result.exceptionStackTrace;
         this.paging = new PagingInfo();
@@ -167,9 +222,11 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
         this.paging.totalPages = result.paging.totalPages;
 
         if (result.data) {
-            this.data = (enumerable
-                ? deserializeQueryModels(instanceType, result.data)
-                : deserializeQueryModel(instanceType, result.data)) as TDataType;
+            this.data = (
+                enumerable
+                    ? deserializeQueryModels(instanceType, result.data)
+                    : deserializeQueryModel(instanceType, result.data)
+            ) as TDataType;
         } else {
             this.data = (enumerable ? [] : null) as TDataType;
         }
@@ -177,8 +234,14 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
         if (enumerable && result.changeSet) {
             this.changeSet = {
                 added: deserializeQueryModels(instanceType, result.changeSet.added ?? []),
-                replaced: deserializeQueryModels(instanceType, result.changeSet.replaced ?? []),
-                removed: deserializeQueryModels(instanceType, result.changeSet.removed ?? []),
+                replaced: deserializeQueryModels(
+                    instanceType,
+                    result.changeSet.replaced ?? [],
+                ),
+                removed: deserializeQueryModels(
+                    instanceType,
+                    result.changeSet.removed ?? [],
+                ),
             } as ChangeSet<unknown>;
         }
     }
@@ -192,6 +255,9 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
     /** @inheritdoc */
     readonly isSuccess: boolean;
 
+    /** @inheritdoc */
+    readonly isReady: boolean;
+
     /** @inheritdoc */
     readonly isAuthorized: boolean;