j-templates 8.1.1 → 8.2.0

package/Store/Diff/diffTree.js

@@ -1,448 +1,569 @@
-import { ArraysEqual } from "../../Utils/array";
-import { JsonDeepClone, JsonDiff, JsonMerge, JsonType } from "../../Utils/json";
-import { PROJECTION_PREFIX } from "./diffTree.types";
-/**
- * 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
- */
-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);
+import { JsonDiff, JsonMerge, JsonType } from '../../Utils/json';
+import { Snapshot } from '../Tree/snapshot';
+import { ApplyDiff, ApplyValueToPath, CreateKeyResolver, DeleteRouteState, ExpandWildcardPath, IsWildcardPath, JoinPaths, PROJECTION_PREFIX, ReadPath, ReadPathFound, ROOT_ROUTE, RouteMatches, SplitRouteAndPath, ToSnapshotPath, ValidateWildcardPath, WritePath } from './utils/diffTree.utils';
+export class DiffTree {
+    constructor(keyFunc, routeDefinitions = {}) {
+        this.keyFunc = keyFunc;
+        this.routeDefinitions = routeDefinitions;
+        this.rootState = {};
+        this.commitedSnapshot = {};
+        // Definitions are fixed and instances are never removed, so a route path always finds the same instance
+        this.routeCache = new Map();
+        this.routeKeyFunc = (routePath) => this.GetRouteInstance(routePath).keyFunc;
+        this.resolver = CreateKeyResolver(this.rootState, this.routeKeyFunc);
+        this.snapshot = Snapshot.Create(this.resolver);
+        // Changes whenever the order is reset, so a wildcard read can tell its matches may have changed
+        this.routeVersion = 0;
+        if (!Object.hasOwn(this.routeDefinitions, ROOT_ROUTE))
+            this.routeDefinitions = { ...this.routeDefinitions, [ROOT_ROUTE]: { projections: {} } };
+        this.rootRoute = CreateRoute([], ROOT_ROUTE, this.routeDefinitions[ROOT_ROUTE], this.keyFunc);
+        // Every other pattern in the map is a child of the root route
+        this.rootRoute.routeDefinitions = this.routeDefinitions;
+        this.rootRoute.childPartCounts = PartCounts(this.routeDefinitions);
+        // Both spellings of the root route, so the first lookup of either isn't taken for a new instance
+        this.routeCache.set("", this.rootRoute);
+        this.routeCache.set(ROOT_ROUTE, this.rootRoute);
     }
-    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++;
+    WritePath(path, value) {
+        const [routePath, propertyPath] = SplitRouteAndPath(path);
+        if (propertyPath.startsWith(PROJECTION_PREFIX))
+            throw new Error(`${PROJECTION_PREFIX} keys are read-only.`);
+        this.GetRouteInstance(routePath);
+        // Keyed entities are local to the route written to; a key starting with "/" is a route path from the root
+        ApplyValueToPath(this.snapshot, this.rootState, this.routeKeyFunc, routePath, path, value);
+    }
+    PatchPath(path, patch) {
+        const value = this.Snapshot(path);
+        const merged = JsonMerge(value, patch);
+        this.WritePath(path, merged);
+    }
+    PushPath(path, items) {
+        const [routePath, valuePath] = SplitRouteAndPath(path);
+        if (valuePath.startsWith(PROJECTION_PREFIX))
+            throw new Error(`${PROJECTION_PREFIX} keys are read-only.`);
+        const combinedRoutePath = JoinPaths("", routePath);
+        const routeRoot = ReadPath(this.rootState, combinedRoutePath);
+        const value = ReadPath(this.Snapshot(combinedRoutePath), valuePath);
+        if (!value)
+            throw new Error(`Array not found at path: ${path}`);
+        if (!Array.isArray(value))
+            throw new Error(`Value at path ${path} is not an array`);
+        if (items.length === 0)
+            return;
+        const diff = [];
+        for (let x = 0; x < items.length; x++)
+            diff.push({
+                type: "write",
+                path: `${valuePath}.${value.length + x}`.split('.'),
+                value: items[x]
+            });
+        diff.push({
+            type: "write",
+            path: `${valuePath}.length`.split('.'),
+            value: value.length + items.length
+        });
+        ApplyDiff(this.snapshot, this.rootState, this.routeKeyFunc, combinedRoutePath, routeRoot, diff);
+        /* const keyedValues = ApplyDiffToData(this.snapshot, this.rootState, this.routeKeyFunc, combinedRoutePath, routeRoot, diff);
+        ApplyPathValues(this.snapshot, this.rootState, keyedValues); */
+    }
+    SplicePath(path, start, deleteCount, items) {
+        const [routePath, valuePath] = SplitRouteAndPath(path);
+        if (valuePath.startsWith(PROJECTION_PREFIX))
+            throw new Error(`${PROJECTION_PREFIX} keys are read-only.`);
+        const combinedRoutePath = JoinPaths("", routePath);
+        const routeRoot = this.ReadPath(combinedRoutePath);
+        const routeRootSnapshot = this.Snapshot(combinedRoutePath);
+        const value = ReadPath(routeRootSnapshot, valuePath);
+        if (!value)
+            throw new Error(`Array not found at path: ${path}`);
+        if (!Array.isArray(value))
+            throw new Error(`Value at path ${path} is not an array`);
+        const moveStartIndex = start + deleteCount;
+        const moveEndIndex = start + items.length;
+        const diff = [];
+        const basePath = valuePath.split('.');
+        for (let x = moveStartIndex; x < value.length; x++)
+            diff.push({
+                type: "move",
+                path: basePath,
+                sourceProp: x,
+                targetProp: moveEndIndex + (x - moveStartIndex)
+            });
+        for (let x = 0; x < items.length; x++)
+            diff.push({
+                type: "write",
+                path: basePath.concat(start + x),
+                value: items[x]
+            });
+        const actualDelete = start + deleteCount > value.length ? value.length - start : deleteCount;
+        diff.push({
+            type: "write",
+            path: basePath.concat("length"),
+            value: value.length - actualDelete + items.length
+        });
+        ApplyDiff(this.snapshot, this.rootState, this.routeKeyFunc, combinedRoutePath, routeRoot, diff);
+    }
+    /**
+     * 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`
+     */
+    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);
+        RemoveRouteInstances(this.rootRoute, fullRoute);
+        for (const cachedPath of this.routeCache.keys())
+            if (cachedPath.startsWith(fullRoute))
+                this.routeCache.delete(cachedPath);
+        this.projectionOrder = undefined;
+        this.routeVersion++;
+    }
+    /**
+     * 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
+     */
+    ReadPath(path) {
+        return ReadPath(this.rootState, path);
+    }
+    /**
+     * Runs every projection of every route instance, dependencies first. A projection is skipped
+     * when no route it reads through changed since its last run, when a read's parent is missing,
+     * or when every read value is the same as its last run. Outputs are written as-is to
+     * `$projection_<key>` in their route, without a diff.
+     * @throws When projections depend on each other in a cycle
+     */
+    RunProjections() {
+        const order = this.projectionOrder ??= OrderProjections(this.rootRoute);
+        for (let x = 0; x < order.length; x++) {
+            const projection = order[x];
+            if (this.SourcesUnchanged(projection.sources))
+                continue;
+            const previous = projection.sources;
+            const values = this.ReadValues(projection.reads, projection.sources = new Array(projection.reads.length), previous);
+            if (!values || SameValues(projection.reads, values, projection.values))
+                continue;
+            let output;
+            if (projection.keyed) {
+                output = RunKeyed(projection, projection.keyed, values[0]);
+                // Every entry kept its output, so the record it wrote last run still holds
+                if (output === UNCHANGED) {
+                    projection.values = values;
+                    continue;
+                }
+            }
+            else
+                output = projection.projection(...values);
+            WritePath(this.snapshot, this.rootState, projection.output, output, false);
+            Snapshot.Register(this.snapshot, output);
+            if (projection.readsOutput)
+                // Its own output is one of its reads, so the output it just wrote isn't a change
+                projection.values = this.ReadValues(projection.reads, projection.sources = new Array(projection.reads.length), projection.sources);
+            else {
+                projection.values = values;
+                this.RefreshSources(projection.sources, SplitRouteAndPath(projection.output)[0]);
+            }
+        }
+    }
+    Commit() {
+        const nextSnapshot = Snapshot.Get(this.snapshot, this.rootState, this.resolver);
+        const currentKeys = new Set(Object.keys(this.commitedSnapshot));
+        const nextKeys = Object.keys(nextSnapshot);
+        let diff = [];
+        for (let x = 0; x < nextKeys.length; x++) {
+            currentKeys.delete(nextKeys[x]);
+            diff = JsonDiff(nextSnapshot[nextKeys[x]], this.commitedSnapshot[nextKeys[x]], nextKeys[x], diff);
+        }
+        for (let key of currentKeys)
+            diff.push({
+                type: "write",
+                path: [key],
+                value: undefined
+            });
+        this.commitedSnapshot = nextSnapshot;
+        return diff;
+    }
+    Snapshot(path) {
+        const [routePath, propertyPath] = SplitRouteAndPath(path);
+        const routeState = ReadPath(this.rootState, routePath);
+        const routeSnapshot = Snapshot.Get(this.snapshot, routeState, undefined, ToSnapshotPath(routePath));
+        const snapshot = ReadPath(routeSnapshot, propertyPath);
+        return snapshot;
+    }
+    /**
+     * Finds the route instance for a route path (the portion of a path before the last `/`), creating it (and any missing
+     * parent instances) from the matching definition on first use.
+     * @returns The deepest route instance matched by a definition, or the root route when none matches
+     */
+    GetRouteInstance(routePath) {
+        let route = this.routeCache.get(routePath);
+        if (route)
+            return route;
+        this.projectionOrder = undefined;
+        this.routeVersion++;
+        const segments = RouteSegments(routePath);
+        route = segments.length === 0 ? this.rootRoute : FindRoute(this.rootRoute, segments, 0, this.keyFunc) ?? this.rootRoute;
+        this.routeCache.set(routePath, route);
+        return route;
+    }
+    /**
+     * Whether every route a projection's reads resolved through on its last full read still has
+     * the snapshot it read: a write anywhere under a route clears its cached snapshot, so then no
+     * read can have changed. A wildcard read also needs the same route instances to exist.
+     */
+    SourcesUnchanged(sources) {
+        if (!sources)
+            return false;
+        for (let x = 0; x < sources.length; x++) {
+            const source = sources[x];
+            if (!source)
+                return false;
+            if ("matches" in source) {
+                if (source.version !== this.routeVersion)
+                    return false;
+                for (let y = 0; y < source.matches.length; y++)
+                    if (Snapshot.Peek(this.snapshot, source.matches[y].state) !== source.matches[y].snapshot)
+                        return false;
+            }
+            else if (Snapshot.Peek(this.snapshot, source.state) !== source.snapshot)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Takes a new snapshot of every source in the route a projection just wrote its output to. The
+     * write cleared that route's snapshot, but nothing the projection read changed between its read
+     * and the write, so without this the next run would read everything again for nothing.
+     */
+    RefreshSources(sources, outputRoute) {
+        for (let x = 0; x < sources.length; x++) {
+            const source = sources[x];
+            const routes = source && ("matches" in source ? source.matches : [source]);
+            for (let y = 0; routes && y < routes.length; y++)
+                if (routes[y].route === outputRoute)
+                    routes[y].snapshot = Snapshot.Get(this.snapshot, routes[y].state, this.resolver, ToSnapshotPath(outputRoute));
+        }
+    }
+    /**
+     * Snapshots of the values at each path, read through the route's root object so keyed
+     * values resolve through their own copy.
+     * @param sources Filled with what each read resolved through; a read after a missing one is left undefined
+     * @param previous The sources of the last full read, so a wildcard read reuses its unchanged matches
+     * @returns The values, or undefined when any of them is missing
+     */
+    ReadValues(paths, sources, previous) {
+        const values = new Array(paths.length);
+        for (let x = 0; x < paths.length; x++) {
+            if (IsWildcardPath(paths[x])) {
+                const source = this.ReadWildcard(paths[x], previous?.[x]);
+                values[x] = WildcardValue(source);
+                sources[x] = source;
+                continue;
+            }
+            const [value, found, source] = this.ReadValue(paths[x]);
+            sources[x] = source;
+            if (!found)
+                return undefined;
+            values[x] = value;
+        }
+        return values;
+    }
+    /** The value at a path, whether it was found, and the route it was read through, when there is one */
+    ReadValue(path) {
+        const [route, property] = SplitRouteAndPath(path);
+        const [routeState, found] = ReadPathFound(this.rootState, route);
+        if (!found || !routeState)
+            return [undefined, false, undefined];
+        const routeSnapshot = Snapshot.Get(this.snapshot, routeState, this.resolver, ToSnapshotPath(route));
+        const [value, valueFound] = ReadPathFound(routeSnapshot, property);
+        return [value, valueFound, { route, state: routeState, snapshot: routeSnapshot }];
+    }
+    /**
+     * Reads every route a wildcard path matches. While no route instance was added or removed since
+     * the last read, the matches are the same, and a match whose route has the same snapshot keeps
+     * the value it read.
+     */
+    ReadWildcard(path, previous) {
+        if (previous && previous.version === this.routeVersion) {
+            const matches = previous.matches.map(match => Snapshot.Peek(this.snapshot, match.state) === match.snapshot ? match : this.ReadMatch(match.segment, match.path));
+            return { version: this.routeVersion, matches };
+        }
+        const paths = ExpandWildcardPath(this.rootState, path);
+        const matches = [];
+        for (const segment in paths)
+            matches.push(this.ReadMatch(segment, paths[segment]));
+        return { version: this.routeVersion, matches };
+    }
+    ReadMatch(segment, path) {
+        const [value, found, source] = this.ReadValue(path);
+        // An expanded path's route exists, so a source is always found
+        return { ...source, segment, path, value, found };
     }
-    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
+ * The value of a wildcard read: each match's value keyed by its segment. A match missing the
+ * value is left out, so no match reads as an empty object.
  */
-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);
+function WildcardValue(source) {
+    const values = {};
+    for (let x = 0; x < source.matches.length; x++)
+        if (source.matches[x].found)
+            values[source.matches[x].segment] = source.matches[x].value;
+    return values;
 }
-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);
+/** Whether every read value is the same as its last run; a wildcard read compares each matched value */
+function SameValues(paths, values, lastValues) {
+    if (!lastValues)
+        return false;
+    for (let x = 0; x < values.length; x++)
+        if (values[x] !== lastValues[x] && !(IsWildcardPath(paths[x]) && SameEntries(values[x], lastValues[x])))
+            return false;
+    return true;
+}
+function SameEntries(values, lastValues) {
+    const keys = Object.keys(values);
+    if (keys.length !== Object.keys(lastValues).length)
+        return false;
+    for (let x = 0; x < keys.length; x++)
+        if (!Object.hasOwn(lastValues, keys[x]) || values[keys[x]] !== lastValues[keys[x]])
+            return false;
+    return true;
 }
 /**
- * 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`.
+ * Whether a read and a projection output overlap: the read's route matches the output's (see
+ * `RouteMatches` for wildcards), and one dot path contains the other. A read of the route's root
+ * object (`/channel/1/`) overlaps every output in that route, but not those of its child routes,
+ * which a snapshot of the route doesn't include.
  */
-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 PathsOverlap(read, output) {
+    const [readRoute, readProperty] = SplitRouteAndPath(read);
+    const [outputRoute, outputProperty] = SplitRouteAndPath(output);
+    return RouteMatches(readRoute, outputRoute) && PropertiesOverlap(readProperty, outputProperty);
 }
+/** What `RunKeyed` returns when no entry's output changed and none was added or removed */
+const UNCHANGED = Symbol("UNCHANGED");
 /**
- * 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.
+ * A keyed projection's output for a record: each entry's output, from its last run when its value
+ * is the same, and without the entries it returns undefined for. A value that isn't an object or
+ * array reads as an empty record.
+ * @returns The output, or `UNCHANGED` when it would hold the same entries as the last one written
  */
-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]]);
+function RunKeyed(projection, state, record) {
+    const entries = new Map();
+    const output = {};
+    let changed = projection.values === undefined;
+    const keys = JsonType(record) === "value" ? [] : Object.keys(record);
+    for (let x = 0; x < keys.length; x++) {
+        const key = keys[x];
+        if (state.routeState && key.startsWith(PROJECTION_PREFIX))
+            continue;
+        const value = record[key];
+        const last = state.entries.get(key);
+        const entry = last && last.value === value ? last : { value, output: projection.projection(value, key) };
+        entries.set(key, entry);
+        changed ||= entry !== last && entry.output !== last?.output;
+        if (entry.output !== undefined)
+            SetOwnKey(output, key, entry.output);
     }
-    valueSnapshotCache.set(value, snapshot);
-    return snapshot;
+    // A key that's gone changes the output unless it was left out of it
+    for (const [key, last] of state.entries)
+        if (!entries.has(key) && last.output !== undefined)
+            changed = true;
+    state.entries = entries;
+    return changed ? output : UNCHANGED;
 }
-/**
- * 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);
-            }
-        }
+/** Sets a key as an own property, even `__proto__`, which plain assignment would make the prototype */
+function SetOwnKey(target, key, value) {
+    if (key === "__proto__")
+        Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+    else
+        target[key] = value;
+}
+/** Whether a read's property path and an output's in a matching route overlap; see `PathsOverlap` */
+function PropertiesOverlap(readProperty, outputProperty) {
+    return readProperty === "" ||
+        readProperty === outputProperty ||
+        readProperty.startsWith(`${outputProperty}.`) ||
+        outputProperty.startsWith(`${readProperty}.`);
+}
+function CollectProjections(route, byRoute) {
+    for (let x = 0; x < route.projections.length; x++) {
+        const [outputRoute] = SplitRouteAndPath(route.projections[x].output);
+        let projections = byRoute.get(outputRoute);
+        projections || byRoute.set(outputRoute, projections = []);
+        projections.push(route.projections[x]);
     }
-    return CreateSnapshot(source, keyFunc, child);
+    for (const child of route.childRoutes.values())
+        CollectProjections(child, byRoute);
 }
 /**
- * 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.
+ * Topologically sorts every projection under a route: a projection depends on every other
+ * projection whose output overlaps one of its reads, so that projection is sorted earlier.
+ * @throws When projections depend on each other in a cycle
  */
-function BuildProjectionOrder(projections) {
+function OrderProjections(rootRoute) {
+    const byRoute = new Map();
+    CollectProjections(rootRoute, byRoute);
     const order = [];
     const state = new Map();
-    function Visit(id, stack) {
-        if (state.get(id) === "done")
+    // The projections of every route a wildcard read's route matches, found once per read route
+    const wildcardCandidates = new Map();
+    const CandidatesOf = (readRoute) => {
+        let candidates = wildcardCandidates.get(readRoute);
+        if (!candidates) {
+            candidates = [];
+            for (const [outputRoute, projections] of byRoute)
+                if (RouteMatches(readRoute, outputRoute))
+                    candidates.push(projections);
+            wildcardCandidates.set(readRoute, candidates);
+        }
+        return candidates;
+    };
+    function Visit(projection, stack) {
+        if (state.get(projection) === "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));
+        if (state.get(projection) === "visiting")
+            throw new Error(`DiffTree projection cycle detected: ${stack.concat(projection.output).join(" -> ")}`);
+        state.set(projection, "visiting");
+        const next = stack.concat(projection.output);
+        // A keyed projection of its route's own state reads none of the route's projection outputs
+        for (let x = 0; !projection.keyed?.routeState && x < projection.reads.length; x++) {
+            const [readRoute, readProperty] = SplitRouteAndPath(projection.reads[x]);
+            // A wildcard read can match outputs in any number of routes; the others only in their own
+            const routeCandidates = IsWildcardPath(projection.reads[x]) ? CandidatesOf(readRoute) : [byRoute.get(readRoute) ?? []];
+            for (const candidates of routeCandidates)
+                for (let y = 0; y < candidates.length; y++)
+                    if (candidates[y] !== projection && PropertiesOverlap(readProperty, SplitRouteAndPath(candidates[y].output)[1]))
+                        Visit(candidates[y], next);
         }
-        state.set(id, "done");
-        order.push({ id, ...def });
+        state.set(projection, "done");
+        order.push(projection);
     }
-    const ids = Object.keys(projections);
-    for (let x = 0; x < ids.length; x++)
-        Visit(ids[x], []);
+    for (const projections of byRoute.values())
+        for (let x = 0; x < projections.length; x++)
+            Visit(projections[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) {
-    const 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);
-                // 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));
-            }
-        }
+function FindRoute(parent, segments, index, defaultKeyFunc) {
+    let route = FindChildRoute(parent, segments, index);
+    if (!route) {
+        const match = MatchRouteDefinition(parent.routeDefinitions, segments, index);
+        if (!match)
+            return undefined;
+        const end = index + match.length;
+        const parts = segments.slice(index, end);
+        route = CreateRoute(parts, `/${segments.slice(0, end).join("/")}/`, match.definition, defaultKeyFunc);
+        // Kept even when a deeper segment matches no definition, so a write below an undefined
+        // child route still creates the parent routes whose projections may read it
+        parent.childRoutes.set(parts.join("/"), route);
     }
-    return diffResult;
-}
-function ResolveKeyed(source, value, keyFunc) {
-    if (keyFunc === undefined || JsonType(value) === 'value')
-        return value;
-    const key = keyFunc(value);
-    return (key && source[key]) ?? value;
+    const nextIndex = index + route.parts.length;
+    // Segments below the deepest defined route belong to it
+    return nextIndex === segments.length ? route : FindRoute(route, segments, nextIndex, defaultKeyFunc) ?? route;
 }
 /**
- * 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)
+ * The existing child instance the segments from `index` name, looked up by key for each number
+ * of segments a child pattern spans, so finding one doesn't scan its siblings.
  */
-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;
+function FindChildRoute(parent, segments, index) {
+    for (let x = 0; x < parent.childPartCounts.length; x++) {
+        const count = parent.childPartCounts[x];
+        if (index + count > segments.length)
+            continue;
+        const route = parent.childRoutes.get(segments.slice(index, index + count).join("/"));
+        if (route)
+            return route;
     }
-    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;
+    return undefined;
 }
-/**
- * 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) {
-    const diffResult = [];
-    if (keyFunc) {
-        const keyPath = ResolveKeyPath(source, path, keyFunc);
-        if (keyPath !== path) {
-            const keyDiffResult = UpdateSource(source, keyPath, value, keyFunc);
-            diffResult.push(...keyDiffResult);
-        }
+/** Removes every route instance at or below a route path from the instances under `route` */
+function RemoveRouteInstances(route, routePath) {
+    for (const [key, child] of route.childRoutes) {
+        if (child.path.startsWith(routePath))
+            route.childRoutes.delete(key);
+        else if (routePath.startsWith(child.path))
+            RemoveRouteInstances(child, routePath);
     }
-    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);
-    }
-    const filteredDiffResult = diffResult.filter((diff) => diff.value !== undefined);
-    for (let x = 0; x < filteredDiffResult.length; x++) {
-        SetPathValue(source, filteredDiffResult[x].path, filteredDiffResult[x].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);
-    }
-    const filteredDiffResult = results.filter((diff) => diff.value !== undefined);
-    for (let x = 0; x < filteredDiffResult.length; x++) {
-        SetPathValue(source, filteredDiffResult[x].path, filteredDiffResult[x].value);
+/** The distinct numbers of segments the patterns in a definition map span, in definition order */
+function PartCounts(definitions) {
+    const counts = [];
+    for (const pattern in definitions) {
+        const count = RouteSegments(pattern).length;
+        // The root pattern has no segments and is never a child
+        if (count > 0 && !counts.includes(count))
+            counts.push(count);
     }
-    return results;
+    return counts;
 }
-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);
-    }
-    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);
+function MatchRouteDefinition(definitions, segments, index) {
+    if (!definitions)
+        return undefined;
+    for (const pattern in definitions) {
+        const patternParts = RouteSegments(pattern);
+        // The root pattern has no segments and would match anything
+        if (patternParts.length === 0 || patternParts.length > segments.length - index)
+            continue;
+        let x = 0;
+        for (; x < patternParts.length && (IsParam(patternParts[x]) || patternParts[x] === segments[index + x]); x++)
+            ;
+        if (x === patternParts.length)
+            return { definition: definitions[pattern], length: patternParts.length };
     }
-    return spliceResult;
+    return undefined;
 }
 /**
- * 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).
+ * @param routePath The instance's full route from the tree root, e.g. `/Root/1234/`. Each projection
+ * read is resolved against it, so `name` becomes `/Root/1234/name`; a read starting with `/` is kept as-is.
+ * @param defaultKeyFunc The tree's keyFunc, used when the definition doesn't define one
  */
-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.
-     */
-    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 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) {
-        return UpdateSource(this.rootState, path, value, this.keyFunc);
-    }
-    PatchPath(path, patch) {
-        const value = this.Snapshot(path);
-        const merged = JsonMerge(value, patch);
-        return UpdateSource(this.rootState, path, merged, this.keyFunc);
-    }
-    PushPath(path, items) {
-        return PushSource(this.rootState, path, items, this.keyFunc);
-    }
-    SplicePath(path, start, deleteCount, items) {
-        return SpliceSource(this.rootState, path, start, deleteCount, items, this.keyFunc);
-    }
-    /**
-     * Retrieves the current value at a path.
-     * @param path - Dot-separated path to the value
-     * @returns The value at the specified path
-     */
-    GetPath(path) {
-        const [value] = GetPathValue(this.rootState, path, this.keyFunc);
-        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, this.keyFunc);
-        if (!found)
-            throw `Unable to get snapshot for path ${path}`;
-        return CreateSnapshot(this.rootState, this.keyFunc, value);
+function CreateRoute(parts, routePath, definition, defaultKeyFunc) {
+    const projections = [];
+    for (const key in definition.projections) {
+        const projectionDefinition = definition.projections[key];
+        const output = JoinPaths(routePath, `${PROJECTION_PREFIX}${key}`);
+        if (IsKeyedDefinition(projectionDefinition)) {
+            const { read, projection } = projectionDefinition;
+            if (read !== undefined && IsWildcardPath(read))
+                throw new Error(`Invalid keyed projection read ${read}: a keyed projection reads one record, without a wildcard.`);
+            // Its route's own state, without the outputs, so its own output isn't one of its reads
+            const routeRead = JoinPaths(routePath, read ?? "");
+            projections.push({
+                key,
+                reads: [routeRead],
+                projection,
+                output,
+                readsOutput: read !== undefined && PathsOverlap(routeRead, output),
+                keyed: { entries: new Map(), routeState: read === undefined }
+            });
+            continue;
+        }
+        const { reads, projection } = projectionDefinition;
+        reads.forEach(ValidateWildcardPath);
+        const routeReads = reads.map(read => JoinPaths(routePath, read));
+        projections.push({ key, reads: routeReads, projection, output, readsOutput: routeReads.some(read => PathsOverlap(read, output)) });
     }
+    return {
+        path: routePath,
+        parts,
+        projections,
+        childRoutes: new Map(),
+        childPartCounts: PartCounts(definition.routes),
+        keyFunc: definition.keyFunc ?? defaultKeyFunc,
+        routeDefinitions: definition.routes
+    };
+}
+/** Whether a projection definition is a keyed projection: it has no `reads` */
+function IsKeyedDefinition(definition) {
+    return definition.reads === undefined;
+}
+function IsParam(part) {
+    return part.startsWith("{") && part.endsWith("}");
+}
+function RouteSegments(route) {
+    return route.split("/").filter(part => part !== "");
 }