j-templates 8.0.25 → 8.0.27

package/Node/vNode.js

@@ -212,7 +212,7 @@ function ToArray(result) {
 function MapNode(vnode) {
     switch (vnode.type) {
         case FRAGMENT_NODE:
-            return vnode.children?.flatMap(MapNode);
+            return vnode.children?.flatMap(MapNode) ?? null;
         default:
             return vnode.node;
     }

package/Store/Diff/diffSync.d.ts

@@ -1,10 +1,11 @@
+import { JsonDiffResult } from "../../Utils/json";
 import { DiffSpliceResult, DiffTreeProjectionMap, IDiffTree } from "./diffTree";
 /**
  * Synchronous diff implementation.
  * Computes diffs immediately without queuing or workers.
  *
  * @see StoreSync
- * @see DiffAsync
+ * @see StoreAsync
  */
 export declare class DiffSync implements IDiffTree {
     private diffTree;
@@ -22,15 +23,14 @@ export declare class DiffSync implements IDiffTree {
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path: string, value: any, flatten?: boolean): import("../../Utils/json").JsonDiffResult;
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data: Array<{
-        path: string;
-        value: any;
-    }>): import("../../Utils/json").JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[], flatten?: boolean): DiffSpliceResult;
+    DiffPath(path: string, value: any): {
+        path: (string | number)[];
+        value: unknown;
+    }[];
+    PatchPath(path: string, patch: any): {
+        path: (string | number)[];
+        value: unknown;
+    }[];
+    PushPath(path: string, items: any[]): JsonDiffResult;
+    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[]): DiffSpliceResult;
 }

package/Store/Diff/diffSync.js

@@ -4,7 +4,7 @@ import { DiffTree } from "./diffTree";
  * Computes diffs immediately without queuing or workers.
  *
  * @see StoreSync
- * @see DiffAsync
+ * @see StoreAsync
  */
 export class DiffSync {
     /**
@@ -21,18 +21,21 @@ export class DiffSync {
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path, value, flatten = true) {
-        return this.diffTree.DiffPath(path, value, flatten);
+    DiffPath(path, value) {
+        const diff = this.diffTree.DiffPath(path, value);
+        return diff.concat(this.diffTree.RunProjections());
     }
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data) {
-        return this.diffTree.DiffBatch(data);
+    PatchPath(path, patch) {
+        const diff = this.diffTree.PatchPath(path, patch);
+        return diff.concat(this.diffTree.RunProjections());
+    }
+    PushPath(path, items) {
+        const diff = this.diffTree.PushPath(path, items);
+        return diff.concat(this.diffTree.RunProjections());
     }
-    SplicePath(path, start, deleteCount, items, flatten) {
-        return this.diffTree.SplicePath(path, start, deleteCount, items, flatten);
+    SplicePath(path, start, deleteCount, items) {
+        const spliceResult = this.diffTree.SplicePath(path, start, deleteCount, items);
+        spliceResult.diffResult.push(...this.diffTree.RunProjections());
+        return spliceResult;
     }
 }

package/Store/Diff/diffTree.d.ts

@@ -3,23 +3,16 @@ import { type JsonDiffResult } from "../../Utils/json";
  * Interface for diff tree operations.
  */
 export interface IDiffTree {
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data: Array<{
-        path: string;
-        value: any;
-    }>): JsonDiffResult;
     /**
      * Computes the diff between a new value and the current value at a path.
      * @param path - Dot-separated path to the value
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path: string, value: any, flatten?: boolean): JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[], flatten?: boolean): DiffSpliceResult;
+    DiffPath(path: string, value: any): JsonDiffResult;
+    PatchPath(path: string, patch: any): JsonDiffResult;
+    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[]): DiffSpliceResult;
+    PushPath(path: string, items: any[]): JsonDiffResult;
 }
 /**
  * Constructor interface for IDiffTree.
@@ -70,12 +63,13 @@ export type DiffSpliceResult<T = unknown> = {
     /** Required by the splice operation **/
     start: number;
     deleteCount: number;
+    items: any[];
     spliceResult: any[];
     diffResult: JsonDiffResult;
 };
 /**
  * Diff tree implementation. Maintains root state and computes diffs for path/value updates.
- * Used directly by `DiffSync`, and is the building block for a `DiffAsync` worker entry
+ * Used directly by `DiffSync`, and is the building block for a `StoreAsync` worker entry
  * file: construct one with the desired `keyFunc`/`projections` and connect it to the worker
  * thread with `ConnectWorkerToDiffTree` (see `defaultDiffTreeWorker.ts` for the no-argument
  * case, or a custom entry file when either is needed).
@@ -94,27 +88,17 @@ export declare class DiffTree {
     constructor(keyFunc?: {
         (val: any): string;
     }, projections?: DiffTreeProjectionMap);
-    private RunProjections;
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data: Array<{
-        path: string;
-        value: any;
-    }>): {
-        path: (string | number)[];
-        value: unknown;
-    }[];
+    RunProjections(): JsonDiffResult;
     /**
      * Computes the diff between a new value and the current value at a path.
      * @param path - Dot-separated path to the value
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path: string, value: any, flatten?: boolean): JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number, items: any[], flatten?: boolean): DiffSpliceResult<unknown>;
+    DiffPath(path: string, value: any): JsonDiffResult;
+    PatchPath(path: string, patch: any): JsonDiffResult;
+    PushPath(path: string, items: unknown[]): JsonDiffResult;
+    SplicePath(path: string, start: number, deleteCount: number, items: any[]): DiffSpliceResult<unknown>;
     /**
      * Retrieves the current value at a path.
      * @param path - Dot-separated path to the value

package/Store/Diff/diffTree.js

@@ -1,5 +1,5 @@
 import { ArraysEqual } from "../../Utils/array";
-import { JsonDeepClone, JsonDiff, JsonType } from "../../Utils/json";
+import { JsonDeepClone, JsonDiff, JsonMerge, JsonType } from "../../Utils/json";
 /** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
 export const PROJECTION_PREFIX = "$projection_";
 /**
@@ -247,8 +247,8 @@ function RunProjections(source, keyFunc, projections, memo) {
                 memo.set(id, values);
                 // The same diff-and-apply UpdateSource uses for any other write, so a keyed entity
                 // embedded in a projection's result is flattened to its own root like any other write,
-                // and the diff reported here is unfiltered, the same as DiffPath/DiffBatch return.
-                diffResult.push(...UpdateSource(source, PROJECTION_PREFIX + id, result, true, keyFunc));
+                // and the diff reported here is unfiltered, the same as DiffPath returns.
+                diffResult.push(...UpdateSource(source, PROJECTION_PREFIX + id, result, keyFunc));
             }
         }
     }
@@ -294,18 +294,18 @@ function ResolveKeyPath(source, path, keyFunc) {
  * @param keyFunc - Optional function to extract keys from objects
  * @returns Diff results showing all changes made
  */
-function UpdateSource(source, path, value, flatten, keyFunc) {
+function UpdateSource(source, path, value, keyFunc) {
     const diffResult = [];
     if (keyFunc) {
         const keyPath = ResolveKeyPath(source, path, keyFunc);
         if (keyPath !== path) {
-            const keyDiffResult = UpdateSource(source, keyPath, value, flatten, keyFunc);
+            const keyDiffResult = UpdateSource(source, keyPath, value, keyFunc);
             diffResult.push(...keyDiffResult);
         }
     }
     const [sourceValue] = GetPathValue(source, path);
     JsonDiff(value, sourceValue, path, diffResult);
-    if (flatten && keyFunc) {
+    if (keyFunc) {
         let flattened = {};
         flattened = FlattenValue(flattened, value, keyFunc);
         flattened = JsonDeepClone(flattened);
@@ -319,7 +319,37 @@ function UpdateSource(source, path, value, flatten, keyFunc) {
     }
     return diffResult;
 }
-function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc) {
+function PushSource(source, path, items, keyFunc) {
+    const [sourceValue, found] = GetPathValue(source, path);
+    if (!found)
+        throw `Value not found at path ${path}`;
+    if (!Array.isArray(sourceValue))
+        throw `Value found at path ${path} is not an array`;
+    const results = items.map(function (value, index) {
+        return {
+            path: `${path}.${sourceValue.length + index}`.split('.'),
+            value
+        };
+    });
+    sourceValue.push(...items);
+    if (items.length > 0)
+        results.push({
+            path: `${path}.length`.split('.'),
+            value: sourceValue.length
+        });
+    if (keyFunc) {
+        const flattened = JsonDeepClone(FlattenValue({}, items, keyFunc));
+        const keys = Object.keys(flattened);
+        for (let x = 0; x < keys.length; x++)
+            JsonDiff(flattened[keys[x]], source[keys[x]], keys[x], results);
+    }
+    const filteredDiffResult = results.filter((diff) => diff.value !== undefined);
+    for (let x = 0; x < filteredDiffResult.length; x++) {
+        SetPathValue(source, filteredDiffResult[x].path, filteredDiffResult[x].value);
+    }
+    return results;
+}
+function SpliceSource(source, path, start, deleteCount, items, keyFunc) {
     const [sourceValue, found] = GetPathValue(source, path);
     if (!found)
         throw `Value not found at path ${path}`;
@@ -329,13 +359,14 @@ function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc)
     const spliceResult = {
         path: path.split("."),
         start,
+        items,
         deleteCount,
         spliceResult: null,
         diffResult: [],
     };
     spliceResult.spliceResult = sourceValue.splice(start, deleteCount, ...items);
     InvalidateSnapshotForValue(sourceValue);
-    if (flatten && keyFunc) {
+    if (keyFunc) {
         // Register the keyed entities the new items carry, diffed against the roots
         // already held: a new entity is added whole, one re-inserted unchanged (an undo)
         // produces no diff, so its readers aren't woken.
@@ -352,7 +383,7 @@ function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc)
 }
 /**
  * Diff tree implementation. Maintains root state and computes diffs for path/value updates.
- * Used directly by `DiffSync`, and is the building block for a `DiffAsync` worker entry
+ * Used directly by `DiffSync`, and is the building block for a `StoreAsync` worker entry
  * file: construct one with the desired `keyFunc`/`projections` and connect it to the worker
  * thread with `ConnectWorkerToDiffTree` (see `defaultDiffTreeWorker.ts` for the no-argument
  * case, or a custom entry file when either is needed).
@@ -375,33 +406,25 @@ export class DiffTree {
             return [];
         return RunProjections(this.rootState, this.keyFunc, this.projectionOrder, this.projectionMemo);
     }
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data) {
-        const results = data
-            .map(({ path, value }) => UpdateSource(this.rootState, path, value, true, this.keyFunc))
-            .flat(1);
-        results.push(...this.RunProjections());
-        return results;
-    }
     /**
      * Computes the diff between a new value and the current value at a path.
      * @param path - Dot-separated path to the value
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path, value, flatten = true) {
-        const results = UpdateSource(this.rootState, path, value, flatten, this.keyFunc);
-        results.push(...this.RunProjections());
-        return results;
+    DiffPath(path, value) {
+        return UpdateSource(this.rootState, path, value, this.keyFunc);
+    }
+    PatchPath(path, patch) {
+        const value = this.Snapshot(path);
+        const merged = JsonMerge(value, patch);
+        return UpdateSource(this.rootState, path, merged, this.keyFunc);
+    }
+    PushPath(path, items) {
+        return PushSource(this.rootState, path, items, this.keyFunc);
     }
-    SplicePath(path, start, deleteCount, items, flatten = true) {
-        const spliceResult = SpliceSource(this.rootState, path, start, deleteCount, items, flatten, this.keyFunc);
-        spliceResult.diffResult.push(...this.RunProjections());
-        return spliceResult;
+    SplicePath(path, start, deleteCount, items) {
+        return SpliceSource(this.rootState, path, start, deleteCount, items, this.keyFunc);
     }
     /**
      * Retrieves the current value at a path.

package/Store/Diff/diffTreeWorker.d.ts

@@ -1,7 +1,16 @@
-import { DiffTree } from "./diffTree";
+import { JsonDiffResult } from "../../Utils/json";
+import { DiffSpliceResult, DiffTree } from "./diffTree";
+export type IDiffMethodBatch = IDiffMethod[];
+export type IDiffMethodBatchResult = ({
+    type: "diff";
+    result: JsonDiffResult;
+} | {
+    type: "splice";
+    result: DiffSpliceResult;
+})[];
 export interface IDiffMethod {
     /** The method to call */
-    method: "create" | "diffpath" | "splicepath" | "diffbatch" | "updatepath" | "getpath";
+    method: "diffpath" | "splicepath" | "pushpath" | "patchpath";
     /** Arguments for the method call */
     arguments: Array<any>;
 }

package/Store/Diff/diffTreeWorker.js

@@ -1,27 +1,44 @@
 export function ConnectWorkerToDiffTree(diffTree, worker) {
     worker.onmessage = function (event) {
         const data = event.data;
-        switch (data.method) {
-            case "diffpath": {
-                const diff = diffTree.DiffPath(data.arguments[0], data.arguments[1], data.arguments[2]);
-                worker.postMessage(diff);
-                break;
-            }
-            case "splicepath": {
-                const diff = diffTree.SplicePath(data.arguments[0], data.arguments[1], data.arguments[2], data.arguments[3], data.arguments[4]);
-                worker.postMessage(diff);
-                break;
-            }
-            case "diffbatch": {
-                const diff = diffTree.DiffBatch(data.arguments[0]);
-                worker.postMessage(diff);
-                break;
-            }
-            case "getpath": {
-                const ret = diffTree.GetPath(data.arguments[0]);
-                worker.postMessage(ret);
-                break;
+        const result = new Array(data.length + 1);
+        for (let x = 0; x < data.length; x++) {
+            const call = data[x];
+            switch (call.method) {
+                case "diffpath": {
+                    result[x] = {
+                        type: "diff",
+                        result: diffTree.DiffPath(call.arguments[0], call.arguments[1])
+                    };
+                    break;
+                }
+                case "splicepath": {
+                    result[x] = {
+                        type: "splice",
+                        result: diffTree.SplicePath(call.arguments[0], call.arguments[1], call.arguments[2], call.arguments[3])
+                    };
+                    break;
+                }
+                case "pushpath": {
+                    result[x] = {
+                        type: "diff",
+                        result: diffTree.PushPath(call.arguments[0], call.arguments[1])
+                    };
+                    break;
+                }
+                case "patchpath": {
+                    result[x] = {
+                        type: "diff",
+                        result: diffTree.PatchPath(call.arguments[0], call.arguments[1])
+                    };
+                    break;
+                }
             }
         }
+        result[result.length - 1] = {
+            type: "diff",
+            result: diffTree.RunProjections()
+        };
+        worker.postMessage(result);
     };
 }

package/Store/Store/storeAsync.d.ts

@@ -20,80 +20,87 @@ import { Store } from "./store";
  * await store.Patch("user", { age: 31 });
  *
  * // Pushing data into an array asynchronously
- * await store.Push("user.array", { id: 1 }, { id: 2 });
+ * await store.Write([], "users");
+ * await store.Push("users", { id: 1 }, { id: 2 });
  *
  * // Splicing an array asynchronously
- * const deletedItems = await store.Splice("user.array", 0, 1, { id: 3 });
+ * const deletedItems = await store.Splice("users", 0, 1, { id: 3 });
  *
  * // Cleaning up resources
  * store.Destroy();
  *
  * @see Store
  * @see StoreSync
- * @see DiffAsync
  */
 export declare class StoreAsync extends Store {
-    /**
-     * The diff instance used to compute differences between current and new data states asynchronously.
-     * @private
-     */
-    private diff;
-    /**
-     * The async queue instance used to manage asynchronous operations in a non-blocking manner.
-     * @private
-     */
-    private queue;
+    private writeKeySet;
+    private workerQueue;
+    private asyncQueue;
+    private currentBatch;
+    private currentBatchPromise;
     /**
      * Creates an instance of StoreAsync.
-     * @param diffWorker A `Worker` running a `DiffTree` connected via
-     *   `ConnectWorkerToDiffTree` (e.g. a bundled `defaultDiffTreeWorker` entry). Any
-     *   `keyFunc`/projections the diff needs must be baked into that worker's own entry file,
-     *   since the worker now runs standard bundled code rather than a serialized function.
-     * @param keyFunc Optional function to generate a key for a given data value, used locally
-     *   by this store to resolve root objects. Pass the same key logic the worker's `DiffTree`
-     *   was constructed with, if any.
+     * @param diffWorker A `Worker` running a `DiffTree` connected via `ConnectWorkerToDiffTree`
+     *   (e.g. a bundled `defaultDiffTreeWorker` entry). Any `keyFunc`/projections the diff needs
+     *   must be baked into that worker's own entry file.
+     * @param keyFunc Optional function to generate a key for a given data value, used locally by
+     *   this store to resolve root objects. Pass the same key logic the worker's `DiffTree` was
+     *   constructed with, if any.
      */
     constructor(diffWorker: Worker, keyFunc?: (value: any) => string | undefined);
-    /**
-     * Returns a promise that resolve once all current queued writes have completed
-     */
-    Flush(): Promise<void>;
-    private nextWritePromise;
-    private nextWriteBatch;
+    private Schedule;
     /**
      * Writes data to the store asynchronously.
-     * This method ensures that write operations are queued and executed in a non-blocking manner.
+     * Changes made in the same tick are sent to the worker together as one batch and applied in
+     * the order they were made. A change to this key may be made before the returned promise
+     * resolves; it's applied after this write.
      * @param data The data to be written. Can be of any type.
      * @param key Optional key for the data. If not provided, the keyFunc will be used to generate a key.
-     * @throws Will throw an error if no key is provided for the data.
+     * @returns A promise that resolves once the write has been applied to the store.
+     * @throws Will throw an error if no key is provided for the data, or reject with the original
+     *   error if an earlier change failed.
      */
     Write(data: unknown, key?: string): Promise<void>;
     /**
      * Patches an existing value in the store with new data asynchronously.
-     * This method ensures that patch operations are queued and executed in a non-blocking manner.
+     * The patch is merged with the current value in the worker, so it applies on top of any
+     * change made before it, including ones not yet applied to the store.
      * @param key The key of the value to be patched.
      * @param patch The patch data to be merged with the existing value.
-     * @throws Will throw an error if the value to be patched is undefined.
+     * @returns A promise that resolves once the patch has been applied to the store.
+     * @throws Will throw if the key isn't in the store and has no pending Write, or reject with
+     *   the original error if an earlier change failed.
      */
     Patch(key: string, patch: unknown): Promise<void>;
     /**
      * Pushes data into an array stored at the specified key asynchronously.
-     * This method ensures that push operations are queued and executed in a non-blocking manner.
      * @param key The key of the array where data will be pushed.
      * @param data The data items to be pushed into the array.
+     * @returns A promise that resolves once the items have been applied to the store.
+     * @throws Will throw if the key isn't in the store and has no pending Write, or reject with
+     *   the original error if an earlier change failed.
      */
     Push(key: string, ...data: unknown[]): Promise<void>;
     /**
      * Splices an array stored at the specified key with new data asynchronously.
-     * This method ensures that splice operations are queued and executed in a non-blocking manner.
-     * It modifies the array by deleting elements and inserting new ones at the specified position.
+     * This method modifies the array by deleting elements and inserting new ones at the specified position.
      * @param key The key of the array to be spliced.
      * @param start The position at which to start changing the array.
      * @param deleteCount Optional number of elements to delete. If not provided, all elements from start to end will be deleted.
      * @param items Optional elements to insert into the array.
-     * @returns The array of deleted elements.
+     * @returns A promise that resolves to the array of deleted elements once the splice has been
+     *   applied to the store.
+     * @throws Will throw if the key isn't in the store and has no pending Write, or reject with
+     *   the original error if an earlier change failed.
      */
     Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): Promise<any[]>;
+    /**
+     * Returns a promise that resolves once every change made before this call has been applied
+     * to the store. Changes made after this call are sent in a later batch, so they aren't
+     * waited for and haven't been applied when the promise resolves.
+     * @throws Rejects with the original error if a change made before this call failed.
+     */
+    Flush(): Promise<void>;
     /**
      * Destroys the StoreAsync instance, stopping the async queue and cleaning up the diff instance.
      * This method should be called when the instance is no longer needed to free up resources.