j-templates 8.1.2 → 9.0.0

package/Store/Diff/diffTree.js

@@ -1,458 +1,170 @@
-import { ArraysEqual } from "../../Utils/array";
-import { JsonDeepClone, JsonDiff, JsonMerge, JsonType } from "../../Utils/json";
-import { PROJECTION_PREFIX } from "./diffTree.types";
+import { JsonDiffInto, JsonMerge, JsonType } from '../../Utils/json';
+import { Snapshot } from '../Tree/snapshot';
+import { ApplyValueToPath, SpliceValueAtPath } from './utils/homes';
+import { JoinPaths, PROJECTION_PREFIX, ROOT_ROUTE, SplitRouteAndPath } from './utils/paths';
+import { Projections } from './utils/projections';
+import { RouteInstances } from './utils/routes';
+import { DeleteRouteState, KeyUnchanged, ReadPath, ReadSnapshot } from './utils/state';
 /**
- * Flattens nested objects/arrays, extracting keyed objects to root.
- * @param root - Root object to store flattened values
- * @param value - Value to flatten
- * @param keyFunc - Function to extract key from objects
- * @returns The root object with flattened values
+ * A tree of JSON state in routes, with projections, that tracks its changes as diffs. The work is
+ * split across `utils/`:
+ * - `homes`: writes, which keep every keyed value at its home
+ * - `state`: reading and writing route state, and snapshots of it
+ * - `routes`: route instances, created from the route definitions
+ * - `projections`: running each route instance's projections
+ * - `paths`: path strings
  */
-function FlattenValue(root, value, keyFunc) {
-    const type = JsonType(value);
-    switch (type) {
-        case "array":
-            const typedArray = value;
-            for (let x = 0; x < typedArray.length; x++)
-                FlattenValue(root, typedArray[x], keyFunc);
-            break;
-        case "object":
-            const typedObject = value;
-            const key = keyFunc(typedObject);
-            if (key)
-                root[key] = typedObject;
-            const keys = Object.keys(typedObject);
-            for (let x = 0; x < keys.length; x++)
-                FlattenValue(root, typedObject[keys[x]], keyFunc);
-    }
-    return root;
-}
-/**
- * Retrieves a value from a source object using a dot-separated path.
- * @param source - The source object
- * @param path - Dot-separated path to the value (empty string returns source)
- * @returns The value at the specified path
- */
-function GetPathValue(source, path, keyFunc) {
-    if (path === "")
-        return [source, true];
-    const parts = path.split(".");
-    let curr = source;
-    let x = 0;
-    for (; curr && x < parts.length - 1; x++)
-        curr = ResolveKeyed(source, curr[parts[x]], keyFunc);
-    if (curr && Object.hasOwn(curr, parts[x])) {
-        curr = ResolveKeyed(source, curr[parts[x]], keyFunc);
-        x++;
-    }
-    else
-        curr = undefined;
-    return [curr, x === parts.length];
-}
-/**
- * Sets a value in a source object at the specified path.
- * @param source - The source object
- * @param path - Array of path segments (strings for keys, numbers for indices)
- * @param value - The value to set
- */
-function SetPathValue(source, path, value) {
-    if (path.length === 0)
-        return;
-    let curr = source;
-    let x = 0;
-    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.
- * Also validates each projection's wildcard reads here, at construction: a wildcard must be
- * the final read, must not have dot nesting, and can't target a projection's
- * `$projection_<id>` key.
- */
-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 read = def.reads[x];
-            const root = read.split(".", 1)[0];
-            if (root.endsWith("*") && x !== def.reads.length - 1)
-                throw `Wildcard reads only supported as the final read: ${root}`;
-            if (root.endsWith("*") && root.includes("."))
-                throw `Wildcard reads do not support dot nesting: ${root}`;
-            if (root.startsWith(PROJECTION_PREFIX) && read.endsWith("*"))
-                throw `Projection keys do not support wildcard reads: ${root}`;
-            if (root.startsWith(PROJECTION_PREFIX))
-                Visit(root.slice(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.
- *
- * A trailing wildcard read is expanded against the current root keys before the projection
- * runs: every root key matching the prefix is read and appended as its own key/value pair,
- * so the projection is called with `(keys, ...values)` where `keys` is every resolved read
- * path (fixed reads first, then each matched wildcard key) positional with `values`.
- *
- * @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) {
-    let diffResult = [];
-    for (let x = 0; x < projections.length; x++) {
-        const { id, reads, projection } = projections[x];
-        const values = [];
-        const keys = [];
-        let allPathsExist = true;
-        let y = 0;
-        for (; allPathsExist && y < reads.length && !reads[y].endsWith("*"); y++) {
-            const read = reads[y];
-            const [value, found] = GetPathValue(source, read, keyFunc);
-            allPathsExist = found;
-            keys.push(read);
-            values.push((found && CreateSnapshot(source, keyFunc, value)) || value);
-        }
-        if (y < reads.length && reads[y].endsWith("*")) {
-            const prefix = reads[y].slice(0, reads[y].length - 1);
-            const matchedKeys = Object.keys(source).filter(key => key.startsWith(prefix));
-            for (let z = 0; z < matchedKeys.length; z++) {
-                // No keyFunc passed because dot paths are not supported for wildcard paths
-                const [value, found] = GetPathValue(source, matchedKeys[z]);
-                allPathsExist = allPathsExist && found;
-                keys.push(matchedKeys[z]);
-                values.push((found && CreateSnapshot(source, keyFunc, value)) || value);
-            }
-        }
-        if (allPathsExist) {
-            const priorValues = memo.get(id);
-            if (!ArraysEqual(priorValues, values)) {
-                const result = projection(keys, ...values);
-                memo.set(id, values);
-                const diff = UpdateSource(source, PROJECTION_PREFIX + id, result, keyFunc);
-                diffResult = diffResult.concat(diff);
-                // 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 returns.
-                /* diffResult.push(
-                  ...UpdateSource(
-                    source,
-                    PROJECTION_PREFIX + id,
-                    result,
-                    keyFunc,
-                  ),
-                ); */
-            }
-        }
-    }
-    return diffResult;
-}
-function ResolveKeyed(source, value, keyFunc) {
-    if (keyFunc === undefined || JsonType(value) === 'value')
-        return value;
-    const key = keyFunc(value);
-    return (key && source[key]) ?? value;
-}
-/**
- * Resolves a path to its keyed root object if applicable.
- * Searches up the path to find an object with a key from keyFunc.
- * @param source - The source object
- * @param path - Dot-separated path
- * @param keyFunc - Function to extract key from objects
- * @returns The resolved path (possibly shortened to root key)
- */
-function ResolveKeyPath(source, path, keyFunc) {
-    const parts = path.split(".");
-    const pathValues = new Array(parts.length - 1);
-    let curr = source;
-    for (let x = 0; x < parts.length - 1; x++) {
-        curr = curr[parts[x]];
-        pathValues[x] = curr;
-    }
-    let y = pathValues.length - 1;
-    for (; y >= 0 && !(JsonType(pathValues[y]) === "object" && keyFunc(pathValues[y])); y--) { }
-    if (y >= 0) {
-        const key = keyFunc(pathValues[y]);
-        parts.splice(0, y + 1, key);
-        return parts.join(".");
-    }
-    return path;
-}
-/**
- * Updates the source with a new value at the specified path and computes diffs.
- * Also updates any keyed objects that were nested in the value.
- * @param source - The source object to update
- * @param path - Dot-separated path to update
- * @param value - The new value
- * @param keyFunc - Optional function to extract keys from objects
- * @returns Diff results showing all changes made
- */
-function UpdateSource(source, path, value, keyFunc) {
-    let diffResult = [];
-    if (keyFunc) {
-        const keyPath = ResolveKeyPath(source, path, keyFunc);
-        if (keyPath !== path) {
-            const keyDiffResult = UpdateSource(source, keyPath, value, keyFunc);
-            diffResult = diffResult.concat(keyDiffResult);
-            // diffResult.push(...keyDiffResult);
-        }
-    }
-    const [sourceValue] = GetPathValue(source, path);
-    JsonDiff(value, sourceValue, path, diffResult);
-    if (keyFunc) {
-        let flattened = {};
-        flattened = FlattenValue(flattened, value, keyFunc);
-        flattened = JsonDeepClone(flattened);
-        const keys = Object.keys(flattened);
-        for (let x = 0; x < keys.length; x++)
-            JsonDiff(flattened[keys[x]], source[keys[x]], keys[x], diffResult);
+export class DiffTree {
+    constructor(keyFunc, routeDefinitions = {}) {
+        this.rootState = {};
+        this.snapshot = Snapshot.Create();
+        /** Each root key's snapshot as of the last commit */
+        this.commitedSnapshot = new Map();
+        this.routes = new RouteInstances(keyFunc, routeDefinitions);
+        this.projections = new Projections(this.snapshot, this.rootState, this.routes);
+        this.writeContext = {
+            snapshot: this.snapshot,
+            root: this.rootState,
+            routeKeyFunc: (routePath) => this.routes.Get(routePath).keyFunc
+        };
     }
-    const filteredDiffResult = diffResult.filter((diff) => diff.value !== undefined);
-    for (let x = 0; x < filteredDiffResult.length; x++) {
-        SetPathValue(source, filteredDiffResult[x].path, filteredDiffResult[x].value);
+    WritePath(path, value) {
+        AssertWritable(SplitRouteAndPath(path)[1]);
+        // Keyed entities are local to the route written to; a key starting with "/" is a route path from the root
+        ApplyValueToPath(this.writeContext, path, value);
     }
-    return diffResult;
-}
-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);
+    PatchPath(path, patch) {
+        const value = this.Snapshot(path);
+        const merged = JsonMerge(value, patch);
+        this.WritePath(path, merged);
     }
-    const filteredDiffResult = results.filter((diff) => diff.value !== undefined);
-    for (let x = 0; x < filteredDiffResult.length; x++) {
-        SetPathValue(source, filteredDiffResult[x].path, filteredDiffResult[x].value);
+    PushPath(path, items) {
+        // A start past the end appends
+        this.Splice(path, Infinity, 0, items);
     }
-    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}`;
-    if (!Array.isArray(sourceValue))
-        throw `Value found at path ${path} is not an array`;
-    deleteCount ??= sourceValue.length - start;
-    const spliceResult = {
-        path: path.split("."),
-        start,
-        items,
-        deleteCount,
-        spliceResult: null,
-        diffResult: [],
-    };
-    spliceResult.spliceResult = sourceValue.splice(start, deleteCount, ...items);
-    InvalidateSnapshotForValue(sourceValue);
-    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.
-        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], spliceResult.diffResult);
+    SplicePath(path, start, deleteCount, items) {
+        this.Splice(path, start, deleteCount, items);
     }
-    const filteredDiffResult = spliceResult.diffResult.filter((diff) => diff.value !== undefined);
-    for (let x = 0; x < filteredDiffResult.length; x++) {
-        SetPathValue(source, filteredDiffResult[x].path, filteredDiffResult[x].value);
+    // Shared by PushPath and SplicePath, which a DiffTreeWriter guards separately
+    Splice(path, start, deleteCount, items) {
+        AssertWritable(SplitRouteAndPath(path)[1]);
+        SpliceValueAtPath(this.writeContext, path, start, deleteCount, items);
     }
-    return spliceResult;
-}
-/**
- * Diff tree implementation. Maintains root state and computes diffs for path/value updates.
- * 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).
- */
-export class DiffTree {
     /**
-     * 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.
+     * Deletes a route: its state, its child routes and projection outputs, and its route
+     * instances. The projection order is rebuilt on the next `RunProjections`, so deleting
+     * several routes in a row sorts once.
+     * @param routePath The route to delete, e.g. `/channel/1/`
+     * @throws When the path is the root route or has a property path, e.g. `/channel/1/name`
      */
-    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);
+    DeleteRoute(routePath) {
+        const [route, propertyPath] = SplitRouteAndPath(routePath);
+        const fullRoute = JoinPaths("", route);
+        if (propertyPath || fullRoute === ROOT_ROUTE)
+            throw new Error(`Unable to delete ${routePath}: only a non-root route path, e.g. /channel/1/, can be deleted.`);
+        DeleteRouteState(this.snapshot, this.rootState, fullRoute);
+        this.routes.Delete(fullRoute);
     }
     /**
-     * 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
+     * Reads the raw value at a path, root (`value.prop`) or routed (`/channel/1/value.prop`).
+     * @returns The value, or undefined when any segment of the path doesn't exist
      */
-    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);
+    ReadPath(path) {
+        return ReadPath(this.rootState, path);
     }
-    SplicePath(path, start, deleteCount, items) {
-        return SpliceSource(this.rootState, path, start, deleteCount, items, this.keyFunc);
+    /** Runs every projection of every route instance; see `Projections.Run` */
+    RunProjections() {
+        this.projections.Run();
     }
     /**
-     * Retrieves the current value at a path.
-     * @param path - Dot-separated path to the value
-     * @returns The value at the specified path
+     * The changes since the last commit. The root is a flat record of keys, so each key's snapshot
+     * is taken and compared on its own, without building a snapshot of the whole root: a key no
+     * write touched has the same cached snapshot as the last commit, and is skipped.
      */
-    GetPath(path) {
-        const [value] = GetPathValue(this.rootState, path, this.keyFunc);
-        return value;
+    Commit() {
+        const committed = this.commitedSnapshot;
+        const keys = Object.keys(this.rootState);
+        // Diffed key by key into one result
+        const diff = [];
+        const rootKeyFunc = this.routes.root.keyFunc;
+        const strategy = CommitStrategy(rootKeyFunc);
+        const identity = CommitIdentity(rootKeyFunc);
+        // How many of the committed keys are still in the root, to tell whether any are gone
+        let kept = 0;
+        for (let x = 0; x < keys.length; x++) {
+            const key = keys[x];
+            const had = committed.has(key);
+            had && kept++;
+            const last = committed.get(key);
+            if (had && KeyUnchanged(this.snapshot, this.rootState, key, last))
+                continue;
+            const next = Snapshot.Child(this.snapshot, this.rootState, key);
+            if (had && next === last)
+                continue;
+            JsonDiffInto(next, last, [key], diff, strategy, identity);
+            committed.set(key, next);
+        }
+        if (kept < committed.size)
+            for (const key of committed.keys())
+                if (!Object.hasOwn(this.rootState, key)) {
+                    committed.delete(key);
+                    diff.push({
+                        type: "delete",
+                        path: [key]
+                    });
+                }
+        return diff;
     }
     /**
-     * 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
+     * The snapshot of the value at a path. Only the path's first property is snapshotted, not
+     * its whole route.
+     * @returns The snapshot, or undefined when any segment of the path doesn't exist
      */
     Snapshot(path) {
-        const [value, found] = GetPathValue(this.rootState, path, this.keyFunc);
-        if (!found)
-            throw `Unable to get snapshot for path ${path}`;
-        return CreateSnapshot(this.rootState, this.keyFunc, value);
+        return ReadSnapshot(this.snapshot, this.rootState, path)[0];
     }
 }
+/**
+ * How `Commit` diffs the root's snapshots for a Store with the same keyFunc:
+ * - An array whose first element is keyed is spliced, its elements matched by CommitIdentity.
+ * - A keyed value below a root key, with the same key as before, is skipped when the Store reads it
+ *   through its root key (any key not starting with `/`): that root key's own diff carries the
+ *   change. The Store doesn't read a route key through its key, so that one is diffed.
+ * - A keyed value with a different key is written.
+ * Each root key's own value is diffed, keyed or not: it's the entity's home.
+ */
+function CommitStrategy(keyFunc) {
+    return keyFunc && function (newValue, oldValue, path) {
+        if (Array.isArray(newValue))
+            return newValue.length > 0 && JsonType(newValue[0]) !== "value" && keyFunc(newValue[0]) !== undefined ? "splice" : undefined;
+        if (path.length <= 1)
+            return undefined;
+        const key = keyFunc(newValue);
+        if (key === undefined)
+            return undefined;
+        if (key !== (JsonType(oldValue) === "value" ? undefined : keyFunc(oldValue)))
+            return "write";
+        return key.startsWith(ROOT_ROUTE) ? undefined : "skip";
+    };
+}
+/**
+ * What `Commit` matches a spliced array's elements by:
+ * - An entity the Store reads by its root key (any key not starting with `/`) is matched by that
+ *   key. Editing it leaves the array unchanged, and its root key's own diff carries the change. An
+ *   entity whose key changed doesn't match, so it's deleted and the new one inserted.
+ * - Anything else, route-key entities included, is matched by ===: the Store doesn't read a route
+ *   key through its key, so a changed one must be replaced.
+ */
+function CommitIdentity(keyFunc) {
+    return keyFunc && function (value) {
+        if (JsonType(value) === "value")
+            return value;
+        const key = keyFunc(value);
+        return key === undefined || key.startsWith(ROOT_ROUTE) ? value : key;
+    };
+}
+/** Projection outputs are written only by RunProjections */
+function AssertWritable(propertyPath) {
+    if (propertyPath.startsWith(PROJECTION_PREFIX))
+        throw new Error(`${PROJECTION_PREFIX} keys are read-only.`);
+}