j-templates 8.0.25 → 8.0.27

package/Store/Store/storeAsync.js

@@ -1,6 +1,5 @@
 import { AsyncQueue } from "../../Utils/asyncQueue";
-import { JsonDeepClone, JsonMerge } from "../../Utils/json";
-import { DiffAsync } from "../Diff/diffAsync";
+import { WorkerQueue } from "../Diff/workerQueue";
 import { Store } from "./store";
 /**
  * StoreAsync class extends the base Store class to provide asynchronous data management operations.
@@ -23,138 +22,160 @@ 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 class StoreAsync extends Store {
     /**
      * 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, keyFunc) {
         super(keyFunc, false);
-        /**
-         * The async queue instance used to manage asynchronous operations in a non-blocking manner.
-         * @private
-         */
-        this.queue = new AsyncQueue();
-        this.nextWritePromise = null;
-        this.nextWriteBatch = null;
-        this.diff = new DiffAsync(diffWorker);
+        this.writeKeySet = new Set();
+        this.currentBatch = [];
+        this.currentBatchPromise = Promise.resolve([]);
+        this.workerQueue = new WorkerQueue(diffWorker);
+        this.asyncQueue = new AsyncQueue(true);
     }
-    /**
-     * Returns a promise that resolve once all current queued writes have completed
-     */
-    async Flush() {
-        return this.queue.Flush();
+    async Schedule(method) {
+        if (this.currentBatch.length === 0) {
+            const batch = this.currentBatch;
+            this.currentBatchPromise = this.asyncQueue.Next(async () => {
+                await Promise.resolve();
+                if (batch === this.currentBatch)
+                    this.currentBatch = [];
+                const results = await this.workerQueue.Push(batch);
+                for (let x = 0; x < results.length; x++) {
+                    const result = results[x];
+                    switch (result.type) {
+                        case "diff": {
+                            this.UpdateRootMap(result.result);
+                            break;
+                        }
+                        case "splice": {
+                            const spliceResult = result.result;
+                            this.UpdateRootMap(spliceResult.diffResult);
+                            this.SpliceRootObject(spliceResult.path[0], spliceResult.start, spliceResult.deleteCount, spliceResult.items);
+                            break;
+                        }
+                    }
+                }
+                return results;
+            });
+        }
+        const batchIndex = this.currentBatch.length;
+        this.currentBatch.push(method);
+        const batchResult = await this.currentBatchPromise;
+        return batchResult[batchIndex].result;
     }
     /**
      * 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.
      */
     async Write(data, key) {
-        const nextWriteBatch = this.nextWriteBatch ??= [];
-        const init = nextWriteBatch.length === 0;
-        nextWriteBatch.push({
-            path: key || this.keyFunc?.(data),
-            value: data
+        key = key || this.keyFunc?.(data);
+        if (!key)
+            throw new Error("No key provided for data");
+        this.writeKeySet.add(key);
+        await this.Schedule({
+            method: "diffpath",
+            arguments: [key, data]
         });
-        if (init) {
-            this.nextWritePromise = this.queue.Next(async () => {
-                await Promise.resolve();
-                this.nextWriteBatch = null;
-                const diffResult = await this.diff.DiffBatch(nextWriteBatch);
-                this.UpdateRootMap(diffResult);
-            });
-        }
-        return this.nextWritePromise;
+        this.writeKeySet.delete(key);
     }
     /**
      * 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.
      */
     async Patch(key, patch) {
-        await this.queue.Next(async () => {
-            if (!this.Has(key))
-                throw "Key not found in store";
-            const value = this.Get(key);
-            if (value === undefined)
-                throw "Unable to patch undefined value";
-            const json = value.toJSON();
-            const mergedJson = JsonMerge(json, patch);
-            const diffResult = await this.diff.DiffPath(key, mergedJson, false);
-            this.UpdateRootMap(diffResult);
+        if (!this.Has(key) && !this.writeKeySet.has(key))
+            throw "Key not found in store";
+        await this.Schedule({
+            method: "patchpath",
+            arguments: [key, patch]
         });
     }
     /**
      * 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.
      */
     async Push(key, ...data) {
-        await this.queue.Next(async () => {
-            if (!this.Has(key))
-                throw "Key not found in store";
-            const arr = this.Get(key);
-            const batch = data.map(function (d, i) {
-                return {
-                    path: `${key}.${arr.length + i}`,
-                    value: d,
-                };
-            });
-            const diffResult = await this.diff.DiffBatch(batch);
-            this.UpdateRootMap(diffResult);
+        if (!this.Has(key) && !this.writeKeySet.has(key))
+            throw "Key not found in store";
+        await this.Schedule({
+            method: "pushpath",
+            arguments: [key, data]
         });
     }
     /**
      * 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.
      */
     async Splice(key, start, deleteCount, ...items) {
-        items = JsonDeepClone(items);
-        return await this.queue.Next(async () => {
-            if (!this.Has(key))
-                throw "Key not found in store";
-            const spliceResult = await this.diff.SplicePath(key, start, deleteCount, items);
-            this.UpdateRootMap(spliceResult.diffResult);
-            this.SpliceRootObject(spliceResult.path[0], spliceResult.start, spliceResult.deleteCount, items);
-            return spliceResult.spliceResult;
+        if (!this.Has(key) && !this.writeKeySet.has(key))
+            throw "Key not found in store";
+        const spliceResult = await this.Schedule({
+            method: "splicepath",
+            arguments: [key, start, deleteCount, items]
         });
+        return spliceResult.spliceResult;
+    }
+    /**
+     * 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.
+     */
+    async Flush() {
+        this.currentBatch = [];
+        return this.asyncQueue.Flush();
     }
     /**
      * 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.
      */
     Destroy() {
-        this.queue.Stop();
-        this.diff.Destroy();
+        this.asyncQueue.Stop();
+        this.workerQueue.Destroy();
     }
 }

package/Store/Store/storeSync.js

@@ -1,6 +1,5 @@
-import { JsonMerge, JsonDeepClone } from "../../Utils/json";
+import { JsonDeepClone } from "../../Utils/json";
 import { DiffSync } from "../Diff/diffSync";
-import { ObservableNode } from "../Tree/observableNode";
 import { Store } from "./store";
 /**
  * StoreSync class extends the base Store class to provide synchronous data management operations.
@@ -51,7 +50,6 @@ export class StoreSync extends Store {
         key = key || this.keyFunc?.(data);
         if (!key)
             throw "No key provided for data";
-        data = ObservableNode.Unwrap(data);
         const diffResult = this.diff.DiffPath(key, data);
         this.UpdateRootMap(diffResult);
     }
@@ -64,12 +62,7 @@ export class StoreSync extends Store {
     Patch(key, patch) {
         if (!this.Has(key))
             throw "Key not found in store";
-        const value = this.Get(key);
-        if (value === undefined)
-            throw "Unable to patch undefined value";
-        const json = ObservableNode.Unwrap(value);
-        const mergedJson = JsonMerge(json, patch);
-        const diffResult = this.diff.DiffPath(key, mergedJson, false);
+        const diffResult = this.diff.PatchPath(key, patch);
         this.UpdateRootMap(diffResult);
     }
     /**
@@ -80,14 +73,7 @@ export class StoreSync extends Store {
     Push(key, ...data) {
         if (!this.Has(key))
             throw "Key not found in store";
-        const arr = this.Get(key);
-        const batch = data.map(function (d, i) {
-            return {
-                path: `${key}.${arr.length + i}`,
-                value: d,
-            };
-        });
-        const diffResult = this.diff.DiffBatch(batch);
+        const diffResult = this.diff.PushPath(key, data);
         this.UpdateRootMap(diffResult);
     }
     /**

package/Utils/asyncQueue.d.ts

@@ -2,8 +2,11 @@
  * A queue that executes async callbacks sequentially, one at a time.
  */
 export declare class AsyncQueue {
+    private maintainError;
     private running;
+    private error;
     private queue;
+    constructor(maintainError?: boolean);
     Flush(): Promise<void>;
     /**
      * Adds a callback to the queue and returns a promise that resolves when it executes.

package/Utils/asyncQueue.js

@@ -3,13 +3,23 @@ import { List } from "./list";
  * A queue that executes async callbacks sequentially, one at a time.
  */
 export class AsyncQueue {
-    constructor() {
+    constructor(maintainError = false) {
+        this.maintainError = maintainError;
         this.running = false;
+        this.error = null;
         this.queue = List.Create();
     }
     Flush() {
-        const ret = new Promise(resolve => {
-            List.Add(this.queue, resolve);
+        if (this.maintainError && this.error)
+            return Promise.reject(this.error);
+        const ret = new Promise((resolve, reject) => {
+            List.Add(this.queue, () => {
+                if (this.maintainError && this.error) {
+                    reject(this.error);
+                    return;
+                }
+                resolve();
+            });
         });
         this.Start();
         return ret;
@@ -21,13 +31,21 @@ export class AsyncQueue {
      * @returns Promise that resolves with the callback's result when executed
      */
     Next(callback) {
+        if (this.maintainError && this.error)
+            return Promise.reject(this.error);
         const ret = new Promise((resolve, reject) => {
-            List.Add(this.queue, async function () {
+            List.Add(this.queue, async () => {
+                if (this.maintainError && this.error) {
+                    reject(this.error);
+                    return;
+                }
                 try {
                     const ret = await callback();
                     resolve(ret);
                 }
                 catch (e) {
+                    if (this.maintainError)
+                        this.error = e;
                     reject(e);
                 }
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "j-templates",
-  "version": "8.0.25",
+  "version": "8.0.27",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",

package/Store/Diff/diffAsync.d.ts

@@ -1,47 +0,0 @@
-import { DiffSpliceResult, IDiffTree } from "./diffTree";
-import { JsonDiffResult } from "../../Utils/json";
-/**
- * Async version of IDiffTree interface with all methods returning promises.
- */
-type IDiffTreeAsync = {
-    [property in keyof IDiffTree]: (...args: Parameters<IDiffTree[property]>) => Promise<ReturnType<IDiffTree[property]>>;
-};
-/**
- * Asynchronous diff implementation using web workers.
- * Offloads diff computation to a worker to prevent blocking the main thread.
- *
- * @see StoreAsync
- * @see DiffSync
- */
-export declare class DiffAsync implements IDiffTreeAsync {
-    private workerQueue;
-    /**
-     * Creates a DiffAsync instance around an already-running worker.
-     * @param diffWorker - A `Worker` running a `DiffTree` connected via
-     *   `ConnectWorkerToDiffTree` (e.g. a bundled `defaultDiffTreeWorker` entry, or a custom
-     *   entry file for a non-default `keyFunc`/`projections` baked into the worker thread).
-     */
-    constructor(diffWorker: Worker);
-    /**
-     * Computes the diff between a new value and the current value at a path asynchronously.
-     * @param path - Dot-separated path to the value
-     * @param value - The new value to compare
-     * @returns Promise that resolves to diff results showing changes
-     */
-    DiffPath(path: string, value: any, flatten?: boolean): Promise<JsonDiffResult>;
-    /**
-     * Computes diffs for a batch of path/value pairs asynchronously.
-     * @param data - Array of objects with path and value properties
-     * @returns Promise that resolves to combined diff results
-     */
-    DiffBatch(data: Array<{
-        path: string;
-        value: any;
-    }>): Promise<JsonDiffResult>;
-    SplicePath(path: string, start: number, deleteCount: number, items: any[], flatten?: boolean): Promise<DiffSpliceResult<unknown>>;
-    /**
-     * Destroys the DiffAsync instance and terminates the worker.
-     */
-    Destroy(): void;
-}
-export {};

package/Store/Diff/diffAsync.js

@@ -1,54 +0,0 @@
-import { WorkerQueue } from "./workerQueue";
-/**
- * Asynchronous diff implementation using web workers.
- * Offloads diff computation to a worker to prevent blocking the main thread.
- *
- * @see StoreAsync
- * @see DiffSync
- */
-export class DiffAsync {
-    /**
-     * Creates a DiffAsync instance around an already-running worker.
-     * @param diffWorker - A `Worker` running a `DiffTree` connected via
-     *   `ConnectWorkerToDiffTree` (e.g. a bundled `defaultDiffTreeWorker` entry, or a custom
-     *   entry file for a non-default `keyFunc`/`projections` baked into the worker thread).
-     */
-    constructor(diffWorker) {
-        this.workerQueue = new WorkerQueue(diffWorker);
-    }
-    /**
-     * Computes the diff between a new value and the current value at a path asynchronously.
-     * @param path - Dot-separated path to the value
-     * @param value - The new value to compare
-     * @returns Promise that resolves to diff results showing changes
-     */
-    async DiffPath(path, value, flatten = true) {
-        return await this.workerQueue.Push({
-            method: "diffpath",
-            arguments: [path, value, flatten],
-        });
-    }
-    /**
-     * Computes diffs for a batch of path/value pairs asynchronously.
-     * @param data - Array of objects with path and value properties
-     * @returns Promise that resolves to combined diff results
-     */
-    async DiffBatch(data) {
-        return await this.workerQueue.Push({
-            method: "diffbatch",
-            arguments: [data],
-        });
-    }
-    async SplicePath(path, start, deleteCount, items, flatten) {
-        return await this.workerQueue.Push({
-            method: "splicepath",
-            arguments: [path, start, deleteCount, items, flatten]
-        });
-    }
-    /**
-     * Destroys the DiffAsync instance and terminates the worker.
-     */
-    Destroy() {
-        this.workerQueue.Destroy();
-    }
-}

package/Store/Diff/diffTree_v2.d.ts

@@ -1,135 +0,0 @@
-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;
-}
-/**
- * Constructor interface for IDiffTree.
- */
-export interface IDiffTreeConstructor {
-    /**
-     * Creates a new IDiffTree instance.
-     * @param keyFunc - Optional function to extract a key from a value
-     * @param projections - Optional map of derived-value projections, keyed by id
-     */
-    new (keyFunc?: {
-        (val: any): string;
-    }, projections?: DiffTreeProjectionMap): IDiffTree;
-}
-/**
- * A pure function computing a derived value from the current values at `reads`. Called with
- * the resolved read paths (`keys`) first, then each value positionally in the same order as
- * `reads`, so each value parameter can be typed at the call site instead of cast out of a
- * generic read. A trailing wildcard read expands to one key/value pair per matched root key,
- * so `keys` lets the function tell which root each trailing value came from.
- */
-export type DiffTreeProjectionFunc = (keys: string[], ...values: any[]) => any;
-/**
- * A projection's declaration: the dot-separated paths it reads (a plain tree path, an
- * entity's key, or another projection's `$projection_<id>` key for chaining) and the
- * function computing its result from their current values, positionally. Declaring `reads`
- * up front lets the tree topologically sort projections and reject a dependency cycle at
- * construction instead of on first write.
- *
- * The final entry in `reads` may instead be a wildcard root key (e.g. `"user_*"`, no dot
- * nesting) matching every root key with that prefix; each match is read and passed to the
- * projection as its own trailing key/value pair. A wildcard read can't be chained off a
- * projection's `$projection_<id>` key and can't appear anywhere but last.
- */
-export type DiffTreeProjectionDefinition = {
-    reads: string[];
-    projection: DiffTreeProjectionFunc;
-};
-/** A map of projection id to its declaration, keyed by the id used in `$projection_<id>`. */
-export type DiffTreeProjectionMap = {
-    [id: string]: DiffTreeProjectionDefinition;
-};
-/** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
-export declare const PROJECTION_PREFIX = "$projection_";
-export type DiffSpliceResult<T = unknown> = {
-    /** Array path segments (strings for object keys, numbers for array indices) */
-    path: (string | number)[];
-    /** Required by the splice operation **/
-    start: number;
-    deleteCount: number;
-    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
- * 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).
- */
-export declare class DiffTree {
-    private keyFunc?;
-    private rootState;
-    private projectionOrder;
-    private projectionMemo;
-    /**
-     * Creates a DiffTree instance.
-     * @param keyFunc - Optional function to extract a key from objects
-     * @param projections - Optional map of derived-value projections, keyed by id. Cycles
-     *   and reads of an unregistered projection id are rejected here, at construction.
-     */
-    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;
-    }[];
-    /**
-     * 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;
-    PatchPath(path: string, patch: any): JsonDiffResult;
-    PushPath(path: string, data: unknown[]): {
-        path: (string | number)[];
-        value: unknown;
-    }[];
-    SplicePath(path: string, start: number, deleteCount: number, items: any[], flatten?: boolean): DiffSpliceResult<unknown>;
-    /**
-     * Retrieves the current value at a path.
-     * @param path - Dot-separated path to the value
-     * @returns The value at the specified path
-     */
-    GetPath(path: string): any;
-    /**
-     * Returns an immutable, cached snapshot of the value at a path (empty string for the
-     * whole tree). Not part of `IDiffTree`; internal, for a future feature.
-     * @param path - Dot-separated path to the value
-     */
-    Snapshot(path: string): any;
-}