@cratis/arc 20.6.0 → 20.7.1

package/package.json

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

package/queries/ChangeSet.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the set of changes in an observable query result, describing
+ * which items were added, replaced, or removed since the previous update.
+ * @template T The item type in the observable collection.
+ */
+export interface ChangeSet<T> {
+    /**
+     * Items that were added since the last update.
+     */
+    readonly added: T[];
+
+    /**
+     * Items that were replaced (same identity, updated content) since the last update.
+     */
+    readonly replaced: T[];
+
+    /**
+     * Items that were removed since the last update.
+     */
+    readonly removed: T[];
+}

package/queries/IChangeStreamFor.ts

@@ -0,0 +1,14 @@
+// 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';
+
+/**
+ * Defines a change-stream-capable observable query. Any {@link IObservableQueryFor} returning
+ * an enumerable ({@code TDataType[]}) satisfies this interface automatically, enabling it to
+ * be used with the {@code useChangeStream} React hook which delivers per-update deltas
+ * (added / replaced / removed) instead of the full collection.
+ * @template TDataType The element type of the observable collection (not the array itself).
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface IChangeStreamFor<TDataType> extends IObservableQueryFor<TDataType[]> {}

package/queries/IQueryResult.ts

@@ -3,6 +3,7 @@
 
 import { ValidationResult } from '../validation/ValidationResult';
 import { PagingInfo } from './PagingInfo';
+import { ChangeSet } from './ChangeSet';
 
 /**
  * Defines the result from executing a query.
@@ -53,6 +54,13 @@ export interface IQueryResult<TDataType> {
      */
     readonly exceptionStackTrace: string;
 
+    /**
+     * Gets the optional change set describing what changed since the previous update.
+     * When present (server-side delta mode), clients apply the delta to local state instead
+     * of replacing the full dataset.
+     */
+    readonly changeSet?: ChangeSet<unknown>;
+
     /**
      * Gets whether or not the query has data.
      */

package/queries/ObservableQueryMultiplexer.ts

@@ -107,6 +107,9 @@ export class ObservableQueryMultiplexer {
     private buildSubscriptionRequest(queryName: string, args?: object): SubscriptionRequest {
         const request: SubscriptionRequest = { queryName };
 
+        // Always include the transfer mode so the server knows which emission strategy to use.
+        request.transferMode = Globals.observableQueryTransferMode;
+
         if (!args) return request;
 
         const a = args as Record<string, any>;

package/queries/QueryResult.ts

@@ -5,6 +5,7 @@ import { Constructor, JsonSerializer } from '@cratis/fundamentals';
 import { ValidationResult } from '../validation/ValidationResult';
 import { IQueryResult } from './IQueryResult';
 import { PagingInfo } from './PagingInfo';
+import { ChangeSet } from './ChangeSet';
 
 type ServerQueryResult = {
     /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -18,6 +19,16 @@ type ServerQueryResult = {
     exceptionMessages: string[];
     exceptionStackTrace: string;
     paging: ServerPagingInfo;
+    changeSet?: ServerChangeSet;
+}
+
+type ServerChangeSet = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    added: any[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    replaced: any[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    removed: any[];
 }
 
 type ServerValidationResult = {
@@ -132,6 +143,14 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
         } else {
             this.data = (enumerable ? [] : null) as TDataType;
         }
+
+        if (enumerable && result.changeSet) {
+            this.changeSet = {
+                added: JsonSerializer.deserializeArrayFromInstance(instanceType, result.changeSet.added ?? []),
+                replaced: JsonSerializer.deserializeArrayFromInstance(instanceType, result.changeSet.replaced ?? []),
+                removed: JsonSerializer.deserializeArrayFromInstance(instanceType, result.changeSet.removed ?? []),
+            } as ChangeSet<unknown>;
+        }
     }
 
     /** @inheritdoc */
@@ -161,6 +180,14 @@ export class QueryResult<TDataType = object> implements IQueryResult<TDataType>
     /** @inheritdoc */
     readonly exceptionStackTrace: string;
 
+    /**
+     * Gets the optional change set describing what changed since the previous update.
+     * Set by the server when the delta transfer mode is active.
+     * When present, clients can apply the delta to their local state rather than replacing
+     * the full dataset.
+     */
+    readonly changeSet?: ChangeSet<unknown>;
+
     /**
      * Gets whether or not the query has data.
      */

package/queries/QueryResultWithState.ts

@@ -5,6 +5,7 @@ import { ValidationResult } from '../validation/ValidationResult';
 import { IQueryResult } from './IQueryResult';
 import { PagingInfo } from './PagingInfo';
 import { QueryResult } from './QueryResult';
+import { ChangeSet } from './ChangeSet';
 
 /**
  * Represents a specialized {@link QueryResult<TDataType>} that holds state for its execution
@@ -51,6 +52,7 @@ export class QueryResultWithState<TDataType> implements IQueryResult<TDataType>
      * @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.
+     * @param {ChangeSet<unknown> | undefined} changeSet Optional change set from the server describing the delta since the last update.
      */
     constructor(
         readonly data: TDataType,
@@ -62,7 +64,8 @@ export class QueryResultWithState<TDataType> implements IQueryResult<TDataType>
         readonly hasExceptions: boolean,
         readonly exceptionMessages: string[],
         readonly exceptionStackTrace: string,
-        readonly isPerforming: boolean) {
+        readonly isPerforming: boolean,
+        readonly changeSet?: ChangeSet<unknown>) {
     }
 
     /** @inheritdoc */
@@ -90,6 +93,7 @@ export class QueryResultWithState<TDataType> implements IQueryResult<TDataType>
             queryResult.hasExceptions,
             queryResult.exceptionMessages,
             queryResult.exceptionStackTrace,
-            isPerforming);
+            isPerforming,
+            queryResult.changeSet);
     }
 }

package/queries/WebSocketHubConnection.ts

@@ -45,6 +45,7 @@ export interface SubscriptionRequest {
     pageSize?: number;
     sortBy?: string;
     sortDirection?: string;
+    transferMode?: string;
 }
 
 interface ActiveSubscription {

package/queries/index.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+export * from './ChangeSet';
+export * from './IChangeStreamFor';
 export * from './IQuery';
 export * from './IQueryFor';
 export * from './Paging';