j-templates 8.0.10 → 8.0.13

package/Store/Diff/diffAsync.d.ts

@@ -1,4 +1,4 @@
-import { DiffSpliceResult, IDiffTree } from "./diffTree";
+import { DiffSpliceResult, DiffTreeProjectionMap, IDiffTree } from "./diffTree";
 import { JsonDiffResult } from "../../Utils/json";
 /**
  * Async version of IDiffTree interface with all methods returning promises.
@@ -18,10 +18,13 @@ export declare class DiffAsync implements IDiffTreeAsync {
     /**
      * Creates a DiffAsync instance and initializes the worker.
      * @param keyFunc - Optional function to extract a key from objects
+     * @param projections - Optional map of derived-value projections, keyed by id. Each
+     *   projection's function is serialized with `.toString()` and `eval`'d back into a
+     *   function in the worker, the same mechanic used for `keyFunc`.
      */
     constructor(keyFunc?: {
         (val: any): string;
-    });
+    }, projections?: DiffTreeProjectionMap);
     /**
      * Computes the diff between a new value and the current value at a path asynchronously.
      * @param path - Dot-separated path to the value

package/Store/Diff/diffAsync.js

@@ -3,6 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiffAsync = void 0;
 const workerQueue_1 = require("./workerQueue");
 const diffWorker_1 = require("./diffWorker");
+/**
+ * Serializes a `DiffTreeProjectionMap` for the worker boundary: `reads` survives structured
+ * clone as-is, and each `projection` function is serialized with `.toString()`, the same
+ * mechanic used below for `keyFunc`.
+ */
+function SerializeProjections(projections) {
+    const serialized = {};
+    const ids = Object.keys(projections);
+    for (let x = 0; x < ids.length; x++) {
+        const id = ids[x];
+        serialized[id] = {
+            reads: projections[id].reads,
+            projection: projections[id].projection.toString(),
+        };
+    }
+    return serialized;
+}
 /**
  * Asynchronous diff implementation using web workers.
  * Offloads diff computation to a worker to prevent blocking the main thread.
@@ -14,12 +31,18 @@ class DiffAsync {
     /**
      * Creates a DiffAsync instance and initializes the worker.
      * @param keyFunc - Optional function to extract a key from objects
+     * @param projections - Optional map of derived-value projections, keyed by id. Each
+     *   projection's function is serialized with `.toString()` and `eval`'d back into a
+     *   function in the worker, the same mechanic used for `keyFunc`.
      */
-    constructor(keyFunc) {
+    constructor(keyFunc, projections) {
         this.workerQueue = new workerQueue_1.WorkerQueue(diffWorker_1.DiffWorker.Create());
         this.workerQueue.Push({
             method: "create",
-            arguments: keyFunc ? [keyFunc.toString()] : [],
+            arguments: [
+                keyFunc ? keyFunc.toString() : undefined,
+                projections ? SerializeProjections(projections) : undefined,
+            ],
         });
     }
     /**

package/Store/Diff/diffSync.d.ts

@@ -1,4 +1,4 @@
-import { DiffSpliceResult, IDiffTree } from "./diffTree";
+import { DiffSpliceResult, DiffTreeProjectionMap, IDiffTree } from "./diffTree";
 /**
  * Synchronous diff implementation.
  * Computes diffs immediately without queuing or workers.
@@ -11,10 +11,11 @@ export declare class DiffSync implements IDiffTree {
     /**
      * Creates a DiffSync instance.
      * @param keyFunc - Optional function to extract a key from objects
+     * @param projections - Optional map of derived-value projections, keyed by id
      */
     constructor(keyFunc?: {
         (val: any): string;
-    });
+    }, projections?: DiffTreeProjectionMap);
     /**
      * Computes the diff between a new value and the current value at a path.
      * @param path - Dot-separated path to the value

package/Store/Diff/diffSync.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiffSync = void 0;
+const array_1 = require("../../Utils/array");
 const json_1 = require("../../Utils/json");
 const diffTree_1 = require("./diffTree");
-const diffCnstr = (0, diffTree_1.DiffTreeFactory)(json_1.JsonDiffFactory);
+const diffCnstr = (0, diffTree_1.DiffTreeFactory)(json_1.JsonDiffFactory, array_1.ArraysEqual);
 /**
  * Synchronous diff implementation.
  * Computes diffs immediately without queuing or workers.
@@ -15,9 +16,10 @@ class DiffSync {
     /**
      * Creates a DiffSync instance.
      * @param keyFunc - Optional function to extract a key from objects
+     * @param projections - Optional map of derived-value projections, keyed by id
      */
-    constructor(keyFunc) {
-        this.diffTree = new diffCnstr(keyFunc);
+    constructor(keyFunc, projections) {
+        this.diffTree = new diffCnstr(keyFunc, projections);
     }
     /**
      * Computes the diff between a new value and the current value at a path.

package/Store/Diff/diffTree.d.ts

@@ -8,6 +8,40 @@ export interface IDiffMethod {
     /** Arguments for the method call */
     arguments: Array<any>;
 }
+/**
+ * A pure function computing a derived value from the current values at `reads`, passed
+ * positionally in the same order, so each parameter can be typed at the call site instead of
+ * cast out of a generic read.
+ */
+export type DiffTreeProjectionFunc = (...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.
+ */
+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;
+};
+/**
+ * The wire form of a `DiffTreeProjectionMap` sent to the diff worker: `reads` survives
+ * structured clone as-is, and `projection` is serialized with `.toString()`, the same
+ * mechanic `DiffAsync` already uses to send `keyFunc` across the worker boundary.
+ */
+export type DiffTreeSerializedProjectionMap = {
+    [id: string]: {
+        reads: string[];
+        projection: string;
+    };
+};
+/** 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)[];
@@ -46,10 +80,11 @@ 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;
-    }): IDiffTree;
+    }, projections?: DiffTreeProjectionMap): IDiffTree;
 }
 /**
  * Factory function that creates a DiffTree class.
@@ -58,4 +93,4 @@ export interface IDiffTreeConstructor {
  * @param worker - If true, sets up worker message handling
  * @returns DiffTree constructor
  */
-export declare function DiffTreeFactory(jsonDiffFactory?: () => JsonDiffFactoryResult, worker?: boolean): IDiffTreeConstructor;
+export declare function DiffTreeFactory(jsonDiffFactory: () => JsonDiffFactoryResult, arraysEqual: (left: any[], right: any[]) => boolean, worker?: boolean): IDiffTreeConstructor;

package/Store/Diff/diffTree.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECTION_PREFIX = void 0;
 exports.DiffTreeFactory = DiffTreeFactory;
+/** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
+exports.PROJECTION_PREFIX = "$projection_";
 /**
  * Factory function that creates a DiffTree class.
  * Can operate in worker mode for async operations.
@@ -8,8 +11,24 @@ exports.DiffTreeFactory = DiffTreeFactory;
  * @param worker - If true, sets up worker message handling
  * @returns DiffTree constructor
  */
-function DiffTreeFactory(jsonDiffFactory, worker) {
+function DiffTreeFactory(jsonDiffFactory, arraysEqual, worker) {
     const { JsonDiff, JsonType, JsonDeepClone } = jsonDiffFactory();
+    /**
+     * Reconstructs a `DiffTreeProjectionMap` from its wire form: each projection's function
+     * source, `eval`'d back into a function, the same mechanic used to deserialize `keyFunc`.
+     */
+    function DeserializeProjections(serialized) {
+        const projections = {};
+        const ids = Object.keys(serialized);
+        for (let x = 0; x < ids.length; x++) {
+            const id = ids[x];
+            projections[id] = {
+                reads: serialized[id].reads,
+                projection: eval(serialized[id].projection),
+            };
+        }
+        return projections;
+    }
     const ctx = this;
     if (worker && ctx) {
         let diffTree = null;
@@ -20,7 +39,10 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
                     const keyFunc = data.arguments[0]
                         ? eval(data.arguments[0])
                         : undefined;
-                    diffTree = new DiffTree(keyFunc);
+                    const projections = data.arguments[1]
+                        ? DeserializeProjections(data.arguments[1])
+                        : undefined;
+                    diffTree = new DiffTree(keyFunc, projections);
                     ctx.postMessage(null);
                     break;
                 }
@@ -81,12 +103,19 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
      */
     function GetPathValue(source, path) {
         if (path === "")
-            return source;
+            return [source, true];
         const parts = path.split(".");
         let curr = source;
-        for (let x = 0; x < parts.length; x++)
+        let x = 0;
+        for (; curr && x < parts.length - 1; x++)
             curr = curr[parts[x]];
-        return curr;
+        if (curr && Object.hasOwn(curr, parts[x])) {
+            curr = curr[parts[x]];
+            x++;
+        }
+        else
+            curr = undefined;
+        return [curr, x === parts.length];
     }
     /**
      * Sets a value in a source object at the specified path.
@@ -102,6 +131,165 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
         for (; x < path.length - 1; x++)
             curr = curr[path[x]];
         curr[path[x]] = value;
+        InvalidateSnapshotForValue(curr);
+    }
+    const valueSnapshotCache = new WeakMap();
+    const valueSnapshotHierarchy = new WeakMap();
+    function CreateSnapshotLink(child, parent) {
+        let parents = valueSnapshotHierarchy.get(child);
+        if (!parents)
+            valueSnapshotHierarchy.set(child, (parents = new Set()));
+        parents.add(parent);
+    }
+    /**
+     * Clears the cached snapshot for a raw value that was just written to, and climbs to
+     * every parent whose own cached snapshot embedded it, so a write to a deeply nested value
+     * invalidates every cached ancestor that still holds a snapshot. Mirrors ObservableNode's
+     * `InvalidateSnapshotForValue`.
+     */
+    function InvalidateSnapshotForValue(value) {
+        valueSnapshotCache.delete(value);
+        const parents = valueSnapshotHierarchy.get(value);
+        if (parents === undefined)
+            return;
+        valueSnapshotHierarchy.delete(value);
+        for (const parent of parents)
+            if (valueSnapshotCache.has(parent))
+                InvalidateSnapshotForValue(parent);
+    }
+    /**
+     * An immutable snapshot of a raw tree value (arrays and plain objects; other values are
+     * returned as-is), cached per raw value and reused until a write invalidates it. Mirrors
+     * ObservableNode's `CreateSnapshot`: a rebuild makes new containers but reuses the cached
+     * snapshots of unchanged children. A keyed child is read through the root entity `keyFunc`
+     * resolves it to, the parallel of ObservableNode's `alias`, so every reference to the same
+     * entity shares one snapshot and a write to the entity invalidates every holder.
+     */
+    function CreateSnapshot(source, keyFunc, value) {
+        if (JsonType(value) === "value")
+            return value;
+        const cached = valueSnapshotCache.get(value);
+        if (cached !== undefined)
+            return cached;
+        let snapshot;
+        if (Array.isArray(value)) {
+            snapshot = new Array(value.length);
+            for (let x = 0; x < value.length; x++)
+                snapshot[x] = ChildSnapshot(source, keyFunc, value, value[x]);
+        }
+        else {
+            snapshot = {};
+            const keys = Object.keys(value);
+            for (let x = 0; x < keys.length; x++)
+                snapshot[keys[x]] = ChildSnapshot(source, keyFunc, value, value[keys[x]]);
+        }
+        valueSnapshotCache.set(value, snapshot);
+        return snapshot;
+    }
+    /**
+     * A child's snapshot, linking the child to its parent so a write to the child invalidates
+     * the parent. A keyed child's snapshot comes from its root entity (`source[key]`), so the
+     * root is linked too; the parent's own embedded copy stays linked because a positional
+     * write (one that changes which entity a slot holds) mutates that copy in place.
+     */
+    function ChildSnapshot(source, keyFunc, parent, child) {
+        if (JsonType(child) === "value")
+            return child;
+        CreateSnapshotLink(child, parent);
+        if (keyFunc) {
+            const key = keyFunc(child);
+            if (key) {
+                const root = source[key];
+                if (root !== undefined && root !== child) {
+                    CreateSnapshotLink(root, parent);
+                    return CreateSnapshot(source, keyFunc, root);
+                }
+            }
+        }
+        return CreateSnapshot(source, keyFunc, child);
+    }
+    /**
+     * Topologically sorts projections by their declared `reads` into a single array, run
+     * sequentially: a read of another projection's `$projection_<id>` output is a dependency
+     * edge, so that projection is sorted earlier. Runs once, at construction, so a cycle (or a
+     * read of an id that isn't registered) is rejected immediately instead of on first write.
+     */
+    function BuildProjectionOrder(projections) {
+        const order = [];
+        const state = new Map();
+        function Visit(id, stack) {
+            if (state.get(id) === "done")
+                return;
+            if (state.get(id) === "visiting")
+                throw new Error(`DiffTree projection cycle detected: ${stack.concat(id).join(" -> ")}`);
+            const def = projections[id];
+            if (!def)
+                throw new Error(`DiffTree projection "${id}" is not defined`);
+            state.set(id, "visiting");
+            for (let x = 0; x < def.reads.length; x++) {
+                const root = def.reads[x].split(".", 1)[0];
+                if (root.startsWith(exports.PROJECTION_PREFIX))
+                    Visit(root.slice(exports.PROJECTION_PREFIX.length), stack.concat(id));
+            }
+            state.set(id, "done");
+            order.push({ id, ...def });
+        }
+        const ids = Object.keys(projections);
+        for (let x = 0; x < ids.length; x++)
+            Visit(ids[x], []);
+        return order;
+    }
+    /**
+     * Runs every registered projection, sequentially in the dependency order
+     * `BuildProjectionOrder` computed, skipping ones whose declared `reads` all still resolve
+     * to the same cached snapshot as last time (so nothing they read has changed), and returns
+     * the diff of every projection whose result changed. A projection's result is stored at
+     * `$projection_<id>` the same way a `DiffPath` write is: diffed against what was there
+     * before and applied path by path, so a change to one field of a projection's result
+     * produces one small diff entry rather than replacing the whole thing.
+     *
+     * Because `order` runs dependencies before dependents, a projection that reads another's
+     * `$projection_<id>` output (chaining) always sees that projection's up-to-date result
+     * within the same pass.
+     *
+     * A projection whose `reads` names a root key that doesn't exist yet (a plain path never
+     * written, an entity never seen, or another projection that hasn't produced a result) is
+     * not run at all, so a projection's author never has to guard every parameter against
+     * missing data. It's tried again on every later write until every read exists. This also
+     * makes a blocked dependency propagate for free: a projection that never runs never writes
+     * `$projection_<id>`, so anything chaining off it stays blocked in turn.
+     *
+     * @param source - The root tree object
+     * @param keyFunc - Optional function to extract a key from objects, for reading through roots
+     * @param projections - Dependency-sorted projection entries, from `BuildProjectionOrder`
+     * @param memo - Per-tree, cross-call memo of each projection's last-read values, by id,
+     *   positional with its `reads`
+     * @returns Diff entries for every projection whose result changed
+     */
+    function RunProjections(source, keyFunc, projections, memo) {
+        const diffResult = [];
+        for (let x = 0; x < projections.length; x++) {
+            const { id, reads, projection } = projections[x];
+            const values = new Array(reads.length);
+            let allPathsExist = true;
+            for (let y = 0; allPathsExist && y < reads.length; y++) {
+                const [value, found] = GetPathValue(source, reads[y]);
+                allPathsExist = found;
+                values[y] = found && CreateSnapshot(source, keyFunc, value) || value;
+            }
+            if (allPathsExist) {
+                const priorValues = memo.get(id);
+                if (!arraysEqual(priorValues, values)) {
+                    const result = projection(...values);
+                    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, exports.PROJECTION_PREFIX + id, result, true, keyFunc));
+                }
+            }
+        }
+        return diffResult;
     }
     /**
      * Resolves a path to its keyed root object if applicable.
@@ -147,7 +335,7 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
                 diffResult.push(...keyDiffResult);
             }
         }
-        const sourceValue = GetPathValue(source, path);
+        const [sourceValue] = GetPathValue(source, path);
         JsonDiff(value, sourceValue, path, diffResult);
         if (flatten && keyFunc) {
             let flattened = {};
@@ -164,7 +352,9 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
         return diffResult;
     }
     function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc) {
-        const sourceValue = GetPathValue(source, path);
+        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`;
         deleteCount ??= sourceValue.length - start;
@@ -176,6 +366,7 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
             diffResult: []
         };
         spliceResult.spliceResult = sourceValue.splice(start, deleteCount, ...items);
+        InvalidateSnapshotForValue(sourceValue);
         if (flatten && 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)
@@ -200,10 +391,19 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
         /**
          * 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) {
+        constructor(keyFunc, projections) {
             this.keyFunc = keyFunc;
             this.rootState = {};
+            this.projectionMemo = new Map();
+            this.projectionOrder = projections ? BuildProjectionOrder(projections) : [];
+        }
+        RunProjections() {
+            if (this.projectionOrder.length === 0)
+                return [];
+            return RunProjections(this.rootState, this.keyFunc, this.projectionOrder, this.projectionMemo);
         }
         /**
          * Computes diffs for a batch of path/value pairs.
@@ -212,8 +412,9 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
          */
         DiffBatch(data) {
             const results = data
-                .map(({ path, value }) => this.DiffPath(path, value))
+                .map(({ path, value }) => UpdateSource(this.rootState, path, value, true, this.keyFunc))
                 .flat(1);
+            results.push(...this.RunProjections());
             return results;
         }
         /**
@@ -223,10 +424,14 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
          * @returns Diff results showing changes
          */
         DiffPath(path, value, flatten = true) {
-            return UpdateSource(this.rootState, path, value, flatten, this.keyFunc);
+            const results = UpdateSource(this.rootState, path, value, flatten, this.keyFunc);
+            results.push(...this.RunProjections());
+            return results;
         }
         SplicePath(path, start, deleteCount, items, flatten = true) {
-            return SpliceSource(this.rootState, path, start, deleteCount, items, flatten, this.keyFunc);
+            const spliceResult = SpliceSource(this.rootState, path, start, deleteCount, items, flatten, this.keyFunc);
+            spliceResult.diffResult.push(...this.RunProjections());
+            return spliceResult;
         }
         /**
          * Retrieves the current value at a path.
@@ -234,7 +439,19 @@ function DiffTreeFactory(jsonDiffFactory, worker) {
          * @returns The value at the specified path
          */
         GetPath(path) {
-            return GetPathValue(this.rootState, path);
+            const [value] = GetPathValue(this.rootState, path);
+            return value;
+        }
+        /**
+         * 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) {
+            const [value, found] = GetPathValue(this.rootState, path);
+            if (!found)
+                throw `Unable to get snapshot for path ${path}`;
+            return CreateSnapshot(this.rootState, this.keyFunc, value);
         }
     }
     return DiffTree;

package/Store/Diff/diffWorker.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiffWorker = void 0;
+const array_1 = require("../../Utils/array");
 const json_1 = require("../../Utils/json");
 const diffTree_1 = require("./diffTree");
 var DiffWorker;
@@ -9,7 +10,7 @@ var DiffWorker;
     let workerParameter = null;
     if (typeof Worker !== "undefined") {
         workerConstructor = Worker;
-        workerParameter = URL.createObjectURL(new Blob([`(${diffTree_1.DiffTreeFactory}).call(this, (${json_1.JsonDiffFactory}), true)`]));
+        workerParameter = URL.createObjectURL(new Blob([`(${diffTree_1.DiffTreeFactory}).call(this, (${json_1.JsonDiffFactory}), (${array_1.ArraysEqual}), true)`]));
     }
     function Create() {
         if (!workerConstructor)

package/Store/Store/storeAsync.d.ts

@@ -1,3 +1,4 @@
+import { DiffTreeProjectionMap } from "../Diff/diffTree";
 import { Store } from "./store";
 /**
  * StoreAsync class extends the base Store class to provide asynchronous data management operations.
@@ -45,8 +46,13 @@ export declare class StoreAsync extends Store {
     /**
      * Creates an instance of StoreAsync.
      * @param keyFunc Optional function to generate a key for a given data value.
+     * @param projections Optional map of derived-value projections, keyed by id. A
+     * projection's result is readable through `Get` at `$projection_<id>`. Each projection's
+     * function is serialized with `.toString()` and `eval`'d back into a function in the
+     * worker, the same mechanic used for `keyFunc`, so it must not close over state that
+     * doesn't survive that round trip.
      */
-    constructor(keyFunc?: (value: any) => string | undefined);
+    constructor(keyFunc?: (value: any) => string | undefined, projections?: DiffTreeProjectionMap);
     /**
      * Returns a promise that resolve once all current queued writes have completed
      */

package/Store/Store/storeAsync.js

@@ -41,15 +41,20 @@ class StoreAsync extends store_1.Store {
     /**
      * Creates an instance of StoreAsync.
      * @param keyFunc Optional function to generate a key for a given data value.
+     * @param projections Optional map of derived-value projections, keyed by id. A
+     * projection's result is readable through `Get` at `$projection_<id>`. Each projection's
+     * function is serialized with `.toString()` and `eval`'d back into a function in the
+     * worker, the same mechanic used for `keyFunc`, so it must not close over state that
+     * doesn't survive that round trip.
      */
-    constructor(keyFunc) {
+    constructor(keyFunc, projections) {
         super(keyFunc, false);
         /**
          * The async queue instance used to manage asynchronous operations in a non-blocking manner.
          * @private
          */
         this.queue = new asyncQueue_1.AsyncQueue();
-        this.diff = new diffAsync_1.DiffAsync(keyFunc);
+        this.diff = new diffAsync_1.DiffAsync(keyFunc, projections);
     }
     /**
      * Returns a promise that resolve once all current queued writes have completed

package/Store/Store/storeSync.d.ts

@@ -1,3 +1,4 @@
+import { DiffTreeProjectionMap } from "../Diff/diffTree";
 import { Store } from "./store";
 /**
  * StoreSync class extends the base Store class to provide synchronous data management operations.
@@ -36,8 +37,10 @@ export declare class StoreSync extends Store {
     /**
      * Creates an instance of StoreSync.
      * @param keyFunc Optional function to generate a key for a given data value.
+     * @param projections Optional map of derived-value projections, keyed by id. A
+     * projection's result is readable through `Get` at `$projection_<id>`.
      */
-    constructor(keyFunc?: (value: any) => string | undefined);
+    constructor(keyFunc?: (value: any) => string | undefined, projections?: DiffTreeProjectionMap);
     /**
      * Writes data to the store synchronously.
      * @param data The data to be written. Can be of any type.

package/Store/Store/storeSync.js

@@ -37,10 +37,12 @@ class StoreSync extends store_1.Store {
     /**
      * Creates an instance of StoreSync.
      * @param keyFunc Optional function to generate a key for a given data value.
+     * @param projections Optional map of derived-value projections, keyed by id. A
+     * projection's result is readable through `Get` at `$projection_<id>`.
      */
-    constructor(keyFunc) {
+    constructor(keyFunc, projections) {
         super(keyFunc);
-        this.diff = new diffSync_1.DiffSync(keyFunc);
+        this.diff = new diffSync_1.DiffSync(keyFunc, projections);
     }
     /**
      * Writes data to the store synchronously.

package/Store/Tree/observableNode.d.ts

@@ -39,6 +39,7 @@ export declare namespace ObservableNode {
      * @returns A proxied version of the value that emits change events.
      */
     function Create<T>(value: T): T;
+    function Snapshot<T>(proxy: T): T | undefined;
     /**
      * Marks an observable node or its property as changed, triggering reactive updates.
      * Used internally to notify dependencies that a value has been modified.

package/Store/Tree/observableNode.js

@@ -6,6 +6,7 @@ const json_2 = require("../../Utils/json");
 const observableScope_1 = require("./observableScope");
 const NODE_VALUE = Symbol("NODE_VALUE");
 const NODE_PROXY = Symbol("NODE_PROXY");
+const NODE_SNAPSHOT = Symbol("NODE_SNAPSHOT");
 const toJSON = "toJSON";
 const IS_NODE = Symbol("IS_NODE");
 const OBJECT_SCOPE = Symbol("OBJECT_SCOPE");
@@ -17,6 +18,24 @@ function Property(value, prop) {
     return value[prop];
 }
 const wrapperCache = new WeakMap();
+const valueSnapshotCache = new WeakMap();
+const valueSnapshotHierarchy = new WeakMap();
+function CreateSnapshotLink(child, parent) {
+    let parents = valueSnapshotHierarchy.get(child);
+    if (!parents)
+        valueSnapshotHierarchy.set(child, (parents = new Set()));
+    parents.add(parent);
+}
+function InvalidateSnapshotForValue(value) {
+    valueSnapshotCache.delete(value);
+    const parents = valueSnapshotHierarchy.get(value);
+    if (parents === undefined)
+        return;
+    valueSnapshotHierarchy.delete(value);
+    for (const parent of parents)
+        if (valueSnapshotCache.has(parent))
+            InvalidateSnapshotForValue(parent);
+}
 function getOwnPropertyDescriptor(target, prop) {
     const descriptor = Object.getOwnPropertyDescriptor(target[NODE_VALUE], prop);
     return {
@@ -93,45 +112,67 @@ function CloneProxy(value, type = (0, json_2.JsonType)(value)) {
 function GetPropertyScope(object, prop) {
     return object[prop] ??= observableScope_1.ObservableScope.Basic(Property.bind(null, object[NODE_VALUE], prop));
 }
+function SetObjectValue(object, prop, value) {
+    const propExists = Object.hasOwn(object[NODE_VALUE], prop);
+    object[NODE_VALUE][prop] = value;
+    InvalidateSnapshotForValue(object[NODE_VALUE]);
+    observableScope_1.ObservableScope.Update(object[prop]);
+    !propExists && observableScope_1.ObservableScope.Update(object[ITERATOR_SCOPE]);
+}
+function SetArrayValue(object, prop, value) {
+    object[NODE_VALUE][prop] = value;
+    InvalidateSnapshotForValue(object[NODE_VALUE]);
+    observableScope_1.ObservableScope.Update(object[OBJECT_SCOPE]);
+}
 function CreateProxyFactory(alias) {
-    function ToJsonCopy(value) {
-        const type = (0, json_2.JsonType)(value);
-        switch (type) {
-            case "array": {
-                const typedValue = value;
-                const arrayValue = alias(typedValue, false) ?? typedValue;
-                return arrayValue.map(ToJsonCopy);
-            }
-            case "object": {
-                const typedValue = alias(value) ?? value;
-                const objectValue = alias(typedValue, false) ?? typedValue;
-                const keys = Object.keys(objectValue);
-                const copy = {};
-                for (let x = 0; x < keys.length; x++)
-                    copy[keys[x]] = ToJsonCopy(typedValue[keys[x]]);
-                return copy;
-            }
-            default:
-                return value;
+    /**
+     * An immutable snapshot of a raw node value (arrays and plain objects; other values are
+     * returned as they are). A snapshot is cached per raw value in valueSnapshotCache and
+     * returned as-is until a write invalidates it: every write path calls Invalidate, which
+     * clears the written value and every cached ancestor, found through the parent links
+     * recorded here. A rebuild makes new containers but reuses the cached snapshots of
+     * unchanged children, so a snapshot handed out never changes and unchanged parts are
+     * shared between snapshots. Keyed children are read through their root.
+     */
+    function CreateSnapshot(value) {
+        if ((0, json_2.JsonType)(value) === "value")
+            return value;
+        const cached = valueSnapshotCache.get(value);
+        if (cached !== undefined)
+            return cached;
+        let snapshot;
+        if (Array.isArray(value)) {
+            snapshot = new Array(value.length);
+            for (let x = 0; x < value.length; x++)
+                snapshot[x] = ChildSnapshot(value, value[x]);
         }
+        else {
+            snapshot = {};
+            const keys = Object.keys(value);
+            for (let x = 0; x < keys.length; x++)
+                snapshot[keys[x]] = ChildSnapshot(value, value[keys[x]]);
+        }
+        valueSnapshotCache.set(value, snapshot);
+        return snapshot;
     }
-    function ToJsonDefault(value) {
-        return (0, json_1.JsonDeepClone)(value);
+    /**
+     * A child's snapshot, linking the child to its parent so a write to the child
+     * invalidates the parent. A keyed child's snapshot comes from its root, so the root is
+     * linked too; the parent's own embedded copy stays linked because a positional write
+     * (one that changes which entity a slot holds) mutates that copy in place.
+     */
+    function ChildSnapshot(parent, child) {
+        if ((0, json_2.JsonType)(child) === "value")
+            return child;
+        CreateSnapshotLink(child, parent);
+        const resolved = alias?.(child, false);
+        if (resolved !== undefined && resolved !== child) {
+            CreateSnapshotLink(resolved, parent);
+            return CreateSnapshot(resolved);
+        }
+        return CreateSnapshot(child);
     }
-    const ToJson = alias !== undefined ? ToJsonCopy : ToJsonDefault;
     const readOnly = alias !== undefined;
-    function SetObjectValue(object, prop, value) {
-        object[NODE_VALUE][prop] = value;
-        observableScope_1.ObservableScope.Update(object[prop]);
-    }
-    function SetArrayValue(object, prop, value) {
-        object[NODE_VALUE][prop] = value;
-        observableScope_1.ObservableScope.Update(object[OBJECT_SCOPE]);
-    }
-    function CreateProxy(value) {
-        value = UnwrapProxy(value);
-        return CreateProxyFromValue(value);
-    }
     function CreateArrayProxy(value) {
         const wrapper = Object.assign([], {
             [NODE_VALUE]: value,
@@ -172,10 +213,12 @@ function CreateProxyFactory(alias) {
                 return true;
             case toJSON:
                 return function () {
-                    return ToJson(object[NODE_VALUE]);
+                    return CreateSnapshot(object[NODE_VALUE]);
                 };
             case NODE_VALUE:
                 return object[NODE_VALUE];
+            case NODE_SNAPSHOT:
+                return CreateSnapshot(object[NODE_VALUE]);
             default: {
                 const scope = object[OBJECT_SCOPE];
                 const array = observableScope_1.ObservableScope.Value(scope);
@@ -199,6 +242,7 @@ function CreateProxyFactory(alias) {
                                 array.length = proxyArray.length;
                                 for (let x = 0; x < proxyArray.length; x++)
                                     array[x] = UnwrapProxy(proxyArray[x]);
+                                InvalidateSnapshotForValue(object[NODE_VALUE]);
                                 observableScope_1.ObservableScope.Update(scope);
                                 break;
                         }
@@ -237,9 +281,11 @@ function CreateProxyFactory(alias) {
         switch (prop) {
             case IS_NODE:
                 return true;
+            case NODE_SNAPSHOT:
+                return CreateSnapshot(object[NODE_VALUE]);
             case toJSON:
                 return function () {
-                    return ToJson(object[NODE_VALUE]);
+                    return CreateSnapshot(object[NODE_VALUE]);
                 };
             case NODE_VALUE:
                 return object[NODE_VALUE];
@@ -334,6 +380,12 @@ var ObservableNode;
         return DefaultCreateProxy(value);
     }
     ObservableNode.Create = Create;
+    function Snapshot(proxy) {
+        if (proxy[IS_NODE])
+            return proxy[NODE_SNAPSHOT];
+        return undefined;
+    }
+    ObservableNode.Snapshot = Snapshot;
     /**
      * Marks an observable node or its property as changed, triggering reactive updates.
      * Used internally to notify dependencies that a value has been modified.
@@ -349,23 +401,18 @@ var ObservableNode;
     }
     ObservableNode.Update = Update;
     function Assign(value, prop, propValue) {
-        const propExists = Object.hasOwn(value, prop);
-        value[prop] = propValue;
+        // const propExists = Object.hasOwn(value as Object, prop);
+        // value[prop] = propValue;
         const wrapper = wrapperCache.get(value);
         if (wrapper) {
             if (Array.isArray(wrapper))
-                observableScope_1.ObservableScope.Update(wrapper[OBJECT_SCOPE]);
-            else {
-                const scope = wrapper[prop];
-                if (scope) {
-                    // A prop was just added to the object, fire the iterator scope
-                    if (!propExists)
-                        observableScope_1.ObservableScope.Update(wrapper[ITERATOR_SCOPE]);
-                    observableScope_1.ObservableScope.Update(scope);
-                }
-                else
-                    observableScope_1.ObservableScope.Update(wrapper[ITERATOR_SCOPE]);
-            }
+                SetArrayValue(wrapper, prop, propValue);
+            else
+                SetObjectValue(wrapper, prop, propValue);
+        }
+        else {
+            InvalidateSnapshotForValue(value);
+            value[prop] = propValue;
         }
     }
     ObservableNode.Assign = Assign;
@@ -411,6 +458,7 @@ var ObservableNode;
     ObservableNode.Apply = Apply;
     function ApplySplice(rootNode, start, deleteCount, items, cloneData = true) {
         const root = rootNode[NODE_VALUE];
+        InvalidateSnapshotForValue(rootNode[NODE_VALUE]);
         const addItems = cloneData ? (0, json_1.JsonDeepClone)(items) : items;
         root.splice(start, deleteCount, ...addItems);
         ObservableNode.Update(root);
@@ -426,6 +474,7 @@ var ObservableNode;
         const root = rootNode[NODE_VALUE];
         if (diffResult.length === 1 && diffResult[0].path.length === 0) {
             // Replacing rootNode
+            InvalidateSnapshotForValue(root);
             const rootPatch = cloneData ? (0, json_1.JsonDeepClone)(diffResult[0].value) : diffResult[0].value;
             const rootType = (0, json_2.JsonType)(root);
             const rootPatchType = (0, json_2.JsonType)(rootPatch);

package/Store/Tree/observableScope.js

@@ -191,7 +191,7 @@ function RegisterScope(scope) {
  */
 function GetScopeValue(scope) {
     if (scope.type === "basic")
-        return scope.getFunction();
+        return ExecuteBasicScope(scope);
     if (scope.type === "static" || !scope.dirty || scope.destroyed)
         return scope.value;
     ExecuteScope(scope);
@@ -274,6 +274,13 @@ function ExecuteScope(scope) {
         scope.onUpdated && emitter_1.Emitter.Emit(scope.onUpdated, lastValue, scope);
     }
 }
+function ExecuteBasicScope(scope) {
+    const parent = watchState;
+    watchState = null;
+    const result = scope.getFunction();
+    watchState = parent;
+    return result;
+}
 /**
  * Creates a scope from a function, choosing between static and dynamic based on dependencies.
  * @template T The type of value returned by the callback.

package/Utils/array.d.ts

@@ -16,3 +16,4 @@
  * ```
  */
 export declare function RemoveNulls(array: (unknown | null)[], startIndex?: number): void;
+export declare function ArraysEqual(left: any[], right: any[]): boolean;

package/Utils/array.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RemoveNulls = RemoveNulls;
+exports.ArraysEqual = ArraysEqual;
 /**
  * Removes all null values from an array starting from a specified index.
  * This function modifies the array in-place by shifting non-null elements
@@ -32,3 +33,9 @@ function RemoveNulls(array, startIndex = 0) {
     if (nullIndex < array.length)
         array.splice(nullIndex);
 }
+function ArraysEqual(left, right) {
+    let equal = left === right || left?.length === right?.length;
+    for (let x = 0; equal && x < left.length; x++)
+        equal = left[x] === right[x];
+    return equal;
+}

package/package.json

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