j-templates 8.1.1 → 8.2.0

package/Store/Tree/snapshot.js

@@ -0,0 +1,141 @@
+import { JsonType } from "../../Utils/json";
+function CreateSnapshotLink(state, child, parent) {
+    let parents = state.hierarchy.get(child);
+    if (!parents)
+        state.hierarchy.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.
+ */
+function InvalidateValue(state, value) {
+    state.rawToSnapshotCache.delete(value);
+    const parents = state.hierarchy.get(value);
+    if (parents === undefined)
+        return;
+    state.hierarchy.delete(value);
+    for (const parent of parents)
+        if (state.rawToSnapshotCache.has(parent))
+            InvalidateValue(state, parent);
+}
+/**
+ * An immutable snapshot of a raw value (arrays and plain objects; other values are
+ * returned as they are). A snapshot is cached per raw value and returned as-is until a
+ * write invalidates it. 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(state, resolve, value, path) {
+    if (JsonType(value) === "value")
+        return value;
+    const cached = state.rawToSnapshotCache.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(state, resolve, value, x, path);
+    }
+    else {
+        snapshot = {};
+        const keys = Object.keys(value);
+        for (let x = 0; x < keys.length; x++)
+            snapshot[keys[x]] = ChildSnapshot(state, resolve, value, keys[x], path);
+    }
+    state.rawToSnapshotCache.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, 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(state, resolve, parent, key, path) {
+    const child = parent[key];
+    if (JsonType(child) === "value")
+        return child;
+    CreateSnapshotLink(state, child, parent);
+    path.push(key);
+    try {
+        const resolved = resolve?.(child, path);
+        if (resolved !== undefined && resolved.value !== child) {
+            CreateSnapshotLink(state, resolved.value, parent);
+            return CreateSnapshot(state, resolve, resolved.value, resolved.path);
+        }
+        return CreateSnapshot(state, resolve, child, path);
+    }
+    finally {
+        path.pop();
+    }
+}
+function RegisterSnapshot(state, snapshot) {
+    if (JsonType(snapshot) !== 'value')
+        state.rawToSnapshotCache.set(snapshot, snapshot);
+}
+export var Snapshot;
+(function (Snapshot) {
+    /**
+     * Creates a new, empty snapshot cache.
+     * @param resolve Optional default resolver for keyed children.
+     * @returns A new snapshot state.
+     */
+    function Create(resolve) {
+        return {
+            rawToSnapshotCache: new WeakMap(),
+            hierarchy: new WeakMap(),
+            resolve,
+        };
+    }
+    Snapshot.Create = Create;
+    /**
+     * Returns an immutable, cached snapshot of a raw value. The same snapshot is returned
+     * until a write invalidates it, and unchanged nested parts are shared between snapshots,
+     * so `===` holds for any part that hasn't changed.
+     * @param state The snapshot cache to read from and populate.
+     * @param value The raw value to snapshot.
+     * @param resolve Resolver for keyed children; defaults to the state's resolver.
+     * @param path The value's own path. Snapshots are cached per raw value, so a value must
+     * always be seeded with the same path or a resolver may see a different one.
+     * @returns The snapshot.
+     */
+    function Get(state, value, resolve = state.resolve, path = []) {
+        return CreateSnapshot(state, resolve, value, path.slice());
+    }
+    Snapshot.Get = Get;
+    /**
+     * Invalidates the cached snapshot of a raw value that was just written to, along with
+     * every cached ancestor that embedded it.
+     * @param state The snapshot cache to invalidate.
+     * @param value The raw value that was written to.
+     */
+    function Invalidate(state, value) {
+        InvalidateValue(state, value);
+    }
+    Snapshot.Invalidate = Invalidate;
+    /**
+     * The cached snapshot of a raw value, without building one. A write to the value, or to
+     * anything its snapshot embeds, clears the cache, so a reader that kept the snapshot it got
+     * can tell nothing under the value changed when this returns that same snapshot.
+     * @param state The snapshot cache.
+     * @param value The raw value.
+     * @returns The cached snapshot, or undefined when there's none.
+     */
+    function Peek(state, value) {
+        return state.rawToSnapshotCache.get(value);
+    }
+    Snapshot.Peek = Peek;
+    /**
+     * Registers a value as its own snapshot. Use in a case where an immutable value can
+     * represent itself as a valid snapshot without cloning.
+     * @param state The snapshot cache.
+     * @param value The raw value that is its own snapshot.
+     */
+    function Register(state, value) {
+        RegisterSnapshot(state, value);
+    }
+    Snapshot.Register = Register;
+})(Snapshot || (Snapshot = {}));

package/Utils/json.d.ts

@@ -1,13 +1,19 @@
+export type JsonWrite = {
+    type: "write";
+    path: (string | number)[];
+    value: unknown;
+};
+export type JsonMove = {
+    type: "move";
+    path: (string | number)[];
+    sourceProp: string | number;
+    targetProp: string | number;
+};
 /**
  * Result of a JSON diff operation, containing paths and values that changed.
  * @template T - The type of the JSON value being diffed
  */
-export type JsonDiffResult<T = unknown> = {
-    /** Array path segments (strings for object keys, numbers for array indices) */
-    path: (string | number)[];
-    /** The new value at this path */
-    value: unknown;
-}[];
+export type JsonDiffResult<T = unknown> = (JsonMove | JsonWrite)[];
 /**
  * Determines the JSON type of a value.
  * @param value - The value to check
@@ -31,9 +37,33 @@ export declare function JsonMerge(source: unknown, patch: unknown): unknown;
  * @returns A deep clone of the value
  */
 export declare function JsonDeepClone<T>(value: T, type?: string): T;
+/**
+ * Applies a diff result to a root value in place: moves first, then writes.
+ * @param resolve - Returns the object to walk into for `parent[prop]`; the walk stores it back at
+ *   `parent[prop]` when it's a different object
+ * @param assign - Assigns a written value (already cloned) to its parent
+ * @param move - Assigns a moved value to its new slot. A move relocates a value that's already in
+ *   the root, so it's kept separate from `assign`, which handles new values.
+ */
+export declare function JsonApplyDiff(root: any, diff: JsonDiffResult, assign?: (parent: any, prop: string | number, value: any) => void): void;
+/**
+ * Applies a diff result to a root value in place. A diff doesn't own its values (see JsonDiff),
+ * so each value is deep-cloned before it's written: the root never shares an object with the
+ * diff, the value it was computed from, or another record.
+ * - A single record with an empty path replaces the root's contents, keeping its identity
+ * - Otherwise each record's value is assigned at its path
+ * @param root - The value to update; must be an object or array
+ * @param diff - The diff result to apply
+ * @param callback - Called with the object written to, the property written ("" when an array
+ *   root is replaced), and whether that property is new to the object
+ * @throws If a root replacement would change the root's JSON type, or the root is a primitive
+ */
+export declare function JsonApplyWrites(root: any, diff: JsonWrite[], assign?: (parent: any, prop: string | number, value: any) => void): void;
 /**
  * Computes the differences between two JSON values.
- * Returns an array of paths and values that changed from oldValue to newValue.
+ * Returns an array of paths and values that changed from oldValue to newValue. A record doesn't
+ * own its value: it references `newValue`'s objects, so two records can share one, and
+ * JsonApplyDiff clones each value as it's applied.
  * @template T - The type of the JSON values being compared
  * @param newValue - The new value
  * @param oldValue - The old value to compare against

package/Utils/json.js

@@ -1,3 +1,4 @@
+import { ArraysEqual } from "./array";
 const jsonProto = Object.getPrototypeOf({});
 const arrayProto = Object.getPrototypeOf([]);
 const strProto = Object.getPrototypeOf("");
@@ -94,9 +95,124 @@ export function JsonDeepClone(value, type = JsonType(value)) {
             return value;
     }
 }
+/**
+ * Applies a diff result to a root value in place: moves first, then writes.
+ * @param resolve - Returns the object to walk into for `parent[prop]`; the walk stores it back at
+ *   `parent[prop]` when it's a different object
+ * @param assign - Assigns a written value (already cloned) to its parent
+ * @param move - Assigns a moved value to its new slot. A move relocates a value that's already in
+ *   the root, so it's kept separate from `assign`, which handles new values.
+ */
+export function JsonApplyDiff(root, diff, 
+/* resolve?: (parent: any, prop: string | number) => any, */
+assign) {
+    const moves = diff.filter(function (diff) {
+        return diff.type === "move";
+    });
+    JsonApplyMoves(root, moves, assign);
+    const writes = diff.filter(function (diff) {
+        return diff.type === "write";
+    });
+    JsonApplyWrites(root, writes, assign);
+}
+function DefaultAssign(parent, prop, value) {
+    parent[prop] = value;
+}
+/**
+ * Applies a diff result to a root value in place. A diff doesn't own its values (see JsonDiff),
+ * so each value is deep-cloned before it's written: the root never shares an object with the
+ * diff, the value it was computed from, or another record.
+ * - A single record with an empty path replaces the root's contents, keeping its identity
+ * - Otherwise each record's value is assigned at its path
+ * @param root - The value to update; must be an object or array
+ * @param diff - The diff result to apply
+ * @param callback - Called with the object written to, the property written ("" when an array
+ *   root is replaced), and whether that property is new to the object
+ * @throws If a root replacement would change the root's JSON type, or the root is a primitive
+ */
+export function JsonApplyWrites(root, diff, assign = DefaultAssign) {
+    const pathTuples = [["", root]];
+    if (diff.length === 1 && diff[0].path.length === 0) {
+        const diffRow = diff[0];
+        const diffPatch = JsonDeepClone(diffRow.value);
+        const type = JsonType(root);
+        const patchType = JsonType(diffPatch);
+        if (type !== patchType)
+            throw new Error("Unable to change type of root value");
+        switch (type) {
+            case "array": {
+                root.splice(0, root.length, ...diffPatch);
+                break;
+            }
+            case "object": {
+                const keys = Object.keys(root);
+                const patchKeys = Object.keys(diffPatch);
+                for (let x = 0; x < keys.length; x++)
+                    if (!patchKeys.includes(keys[x]))
+                        delete root[keys[x]];
+                Object.assign(root, diffPatch);
+                break;
+            }
+            case "value":
+                throw new Error("Unable to replace root value type: " + root);
+        }
+        return;
+    }
+    for (let x = 0; x < diff.length; x++) {
+        const { path, value } = diff[x];
+        let y = 0;
+        for (; y < path.length - 1; y++) {
+            const property = path[y];
+            const tupleIndex = y + 1;
+            if (tupleIndex >= pathTuples.length || pathTuples[tupleIndex][0] !== property) {
+                const parent = pathTuples[y][1];
+                const child = parent[property];
+                if (tupleIndex < pathTuples.length) {
+                    pathTuples[tupleIndex] = [property, child];
+                    const next = tupleIndex + 1;
+                    if (next < pathTuples.length)
+                        pathTuples[next][0] = null;
+                }
+                else
+                    pathTuples.push([property, child]);
+            }
+        }
+        if (y >= path.length - 1) {
+            const assignValue = pathTuples[y][1];
+            const assignData = JsonDeepClone(value);
+            assign(assignValue, path[y], assignData);
+        }
+    }
+}
+function ReadPath(value, path) {
+    let curr = value;
+    let x = 0;
+    for (; curr && x < path.length; x++)
+        curr = curr[path[x]];
+    return curr;
+}
+function JsonApplyMoves(root, diff, move = DefaultAssign) {
+    if (diff.length === 0)
+        return;
+    let moveRoot = null;
+    let basePath = null;
+    let copy = null;
+    for (let x = diff.length - 1; x >= 0; x--) {
+        if (!ArraysEqual(diff[x].path, basePath)) {
+            basePath = diff[x].path;
+            moveRoot = ReadPath(root, diff[x].path); //, resolve);
+            const type = JsonType(moveRoot);
+            copy = type === "array" ? moveRoot.slice() : type === "object" ? Object.assign({}, moveRoot) : root;
+        }
+        const sourceValue = copy[diff[x].sourceProp];
+        move(moveRoot, diff[x].targetProp, sourceValue);
+    }
+}
 /**
  * Computes the differences between two JSON values.
- * Returns an array of paths and values that changed from oldValue to newValue.
+ * Returns an array of paths and values that changed from oldValue to newValue. A record doesn't
+ * own its value: it references `newValue`'s objects, so two records can share one, and
+ * JsonApplyDiff clones each value as it's applied.
  * @template T - The type of the JSON values being compared
  * @param newValue - The new value
  * @param oldValue - The old value to compare against
@@ -108,6 +224,11 @@ export function JsonDiff(newValue, oldValue, rootPath, initResult) {
     const result = initResult ?? [];
     const startPath = rootPath ? rootPath.split(".") : [];
     JsonDiffRecursive(startPath, newValue, oldValue, result);
+    result.sort(function (a, b) {
+        const aNum = a.type === "write" ? 1 : 0;
+        const bNum = b.type === "write" ? 1 : 0;
+        return aNum - bNum;
+    });
     return result;
 }
 /**
@@ -140,6 +261,7 @@ function JsonDiffRecursive(path, newValue, oldValue, resp) {
     if (allChildrenChanged) {
         resp.length > changedPathLength && resp.splice(changedPathLength);
         resp.push({
+            type: "write",
             path,
             value: newValue,
         });
@@ -147,6 +269,7 @@ function JsonDiffRecursive(path, newValue, oldValue, resp) {
     }
     return false;
 }
+const MOVE_SYMBOL = Symbol("MOVE_SYMBOL");
 /**
  * Compares two arrays and records differences.
  * @internal
@@ -160,24 +283,38 @@ function JsonDiffArrays(path, newValue, oldValue, resp) {
     if (oldValue.length === 0 || newValue.length === 0) {
         return oldValue.length !== newValue.length;
     }
-    let allChildrenChanged = true;
-    if (newValue.length > 0 || oldValue.length > 0) {
-        for (let y = 0; y < newValue.length; y++) {
-            const arrayPath = path.concat(y);
-            const oldValueElem = oldValue[y];
-            allChildrenChanged =
-                JsonDiffRecursive(arrayPath, newValue[y], oldValueElem, resp) &&
-                    allChildrenChanged;
+    let startIndex = 0;
+    for (; startIndex < newValue.length && startIndex < oldValue.length && newValue[startIndex] === oldValue[startIndex]; startIndex++) { }
+    // Arrays are equal, no diffing required
+    if (startIndex === newValue.length && startIndex === oldValue.length)
+        return false;
+    const newArraySlice = newValue.slice();
+    const oldArraySlice = oldValue.slice();
+    for (let x = startIndex; x < oldValue.length; x++) {
+        const newIndex = newValue.indexOf(oldValue[x], startIndex);
+        if (newIndex >= 0 && newIndex !== x) {
+            oldArraySlice[x] = MOVE_SYMBOL;
+            newArraySlice[newIndex] = MOVE_SYMBOL;
+            resp.push({
+                type: "move",
+                path: path,
+                sourceProp: x,
+                targetProp: newIndex
+            });
         }
     }
-    else
-        allChildrenChanged = false;
-    if (newValue.length !== oldValue.length)
+    for (let x = startIndex; x < newValue.length; x++) {
+        const arrayPath = path.concat(x);
+        if (newArraySlice[x] !== MOVE_SYMBOL)
+            JsonDiffRecursive(arrayPath, newArraySlice[x], oldArraySlice[x], resp);
+    }
+    if (oldValue.length !== newValue.length)
         resp.push({
+            type: "write",
             path: path.concat("length"),
             value: newValue.length,
         });
-    return allChildrenChanged;
+    return false;
 }
 /**
  * Compares two objects and records differences.
@@ -207,6 +344,7 @@ function JsonDiffObjects(path, newValue, oldValue, resp) {
         }
         else if (newValue[newKeys[newKeyIndex]] !== undefined) {
             resp.push({
+                type: "write",
                 path: childPath,
                 value: newValue[newKeys[newKeyIndex]],
             });

package/package.json

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

package/Store/Diff/diffSync.d.ts

@@ -1,36 +0,0 @@
-import { JsonDiffResult } from "../../Utils/json";
-import { DiffSpliceResult, DiffTreeProjectionMap, IDiffTree } from "./diffTree.types";
-/**
- * Synchronous diff implementation.
- * Computes diffs immediately without queuing or workers.
- *
- * @see StoreSync
- * @see StoreAsync
- */
-export declare class DiffSync implements IDiffTree {
-    private diffTree;
-    /**
-     * 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
-     * @param value - The new value to compare
-     * @returns Diff results showing changes
-     */
-    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

@@ -1,41 +0,0 @@
-import { DiffTree } from "./diffTree";
-/**
- * Synchronous diff implementation.
- * Computes diffs immediately without queuing or workers.
- *
- * @see StoreSync
- * @see StoreAsync
- */
-export 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, projections) {
-        this.diffTree = new DiffTree(keyFunc, projections);
-    }
-    /**
-     * 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) {
-        const diff = this.diffTree.DiffPath(path, value);
-        return diff.concat(this.diffTree.RunProjections());
-    }
-    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) {
-        const spliceResult = this.diffTree.SplicePath(path, start, deleteCount, items);
-        spliceResult.diffResult.push(...this.diffTree.RunProjections());
-        return spliceResult;
-    }
-}