j-templates 8.2.0 → 9.0.1

package/Store/Diff/utils/projections.js

@@ -0,0 +1,290 @@
+import { JsonMaintainUnchanged, JsonType, SetOwnProperty } from "../../../Utils/json";
+import { Snapshot } from "../../Tree/snapshot";
+import { IsWildcardPath, PROJECTION_PREFIX, PropertiesOverlap, RouteMatches, SplitRouteAndPath } from "./paths";
+import { ExpandWildcardPath, KeyUnchanged, ReadPath, ReadSnapshot, WritePath } from "./state";
+/** Runs the projections of a DiffTree's route instances against its state */
+export class Projections {
+    constructor(snapshot, rootState, routes) {
+        this.snapshot = snapshot;
+        this.rootState = rootState;
+        this.routes = routes;
+        this.orderVersion = -1;
+    }
+    /**
+     * 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 to
+     * `$projection_<key>` in their route without a diff, and are their own snapshots, so they're
+     * never changed in place. Instead, each part of an output with no changes from the last one
+     * written is replaced by the last one's object (JsonMaintainUnchanged): unchanged parts keep
+     * their identity, so the projections and readers using them are skipped and `Commit` passes
+     * over them. An output with no changes at all isn't written.
+     * @throws When projections depend on each other in a cycle
+     */
+    Run() {
+        // Rebuilt once after any number of instances were created or deleted
+        if (this.order === undefined || this.orderVersion !== this.routes.version) {
+            this.order = OrderProjections(this.routes.root);
+            this.orderVersion = this.routes.version;
+        }
+        const order = this.order;
+        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 {
+                const last = ReadPath(this.rootState, projection.output);
+                // The last output is its own snapshot, so it's never changed and its parts can be shared
+                output = JsonMaintainUnchanged(projection.projection(...values), last);
+                // An output with no changes leaves the last one in place, so the projections reading it
+                // see the same objects and are skipped
+                if (projection.values !== undefined && output === last) {
+                    projection.values = values;
+                    continue;
+                }
+            }
+            WritePath(this.snapshot, this.rootState, projection.output, output);
+            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
+                const read = projection.sources;
+                projection.values = this.ReadValues(projection.reads, projection.sources = new Array(projection.reads.length), read);
+            }
+            else {
+                projection.values = values;
+                this.RefreshSources(projection.sources, SplitRouteAndPath(projection.output)[0]);
+            }
+        }
+    }
+    /**
+     * Whether every source a projection's reads resolved through on its last full read still has
+     * the snapshot it read: a write anywhere under a value 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.routes.version)
+                    return false;
+                for (let y = 0; y < source.matches.length; y++)
+                    if (!this.SourceUnchanged(source.matches[y]))
+                        return false;
+            }
+            else if (!this.SourceUnchanged(source))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Whether a source still has the snapshot it was read with. A key's value is read from the
+     * state again, so a key written with a new value is a change too (see KeyUnchanged).
+     */
+    SourceUnchanged(source) {
+        if (source.key === undefined)
+            return Snapshot.Peek(this.snapshot, source.state) === source.snapshot;
+        return KeyUnchanged(this.snapshot, source.state, source.key, source.snapshot);
+    }
+    /**
+     * Takes a new snapshot of every source in the route a projection just wrote its output to that
+     * the write cleared. Nothing the projection read changed between its read and the write, so
+     * without this the next run would read everything again for nothing. A source of one key keeps
+     * its snapshot unless the output is under that key.
+     */
+    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++) {
+                const route = routes[y];
+                if (route.route !== outputRoute || this.SourceUnchanged(route))
+                    continue;
+                route.snapshot = route.key === undefined ?
+                    Snapshot.Get(this.snapshot, route.state) :
+                    Snapshot.Child(this.snapshot, route.state, route.key);
+            }
+        }
+    }
+    /**
+     * Snapshots of the values at each path.
+     * @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] = ReadSnapshot(this.snapshot, this.rootState, paths[x]);
+            sources[x] = source;
+            if (!found)
+                return undefined;
+            values[x] = value;
+        }
+        return values;
+    }
+    /**
+     * 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) {
+        const version = this.routes.version;
+        if (previous && previous.version === version) {
+            const matches = previous.matches.map(match => this.SourceUnchanged(match) ? match : this.ReadMatch(match.segment, match.path));
+            return { version, matches };
+        }
+        const paths = ExpandWildcardPath(this.rootState, path);
+        const matches = [];
+        for (const segment in paths)
+            matches.push(this.ReadMatch(segment, paths[segment]));
+        return { version, matches };
+    }
+    ReadMatch(segment, path) {
+        const [value, found, source] = ReadSnapshot(this.snapshot, this.rootState, path);
+        // An expanded path's route exists, so a source is always found
+        return { ...source, segment, path, value, found };
+    }
+}
+/**
+ * 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 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;
+}
+/** 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;
+}
+/** What `RunKeyed` returns when no entry's output changed and none was added or removed */
+const UNCHANGED = Symbol("UNCHANGED");
+/**
+ * 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 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);
+        // A new output keeps every part of the last one with no changes (see Run)
+        const entry = last && last.value === value ? last : { value, output: JsonMaintainUnchanged(projection.projection(value, key), last?.output) };
+        entries.set(key, entry);
+        changed ||= entry !== last && entry.output !== last?.output;
+        if (entry.output !== undefined)
+            SetOwnProperty(output, key, entry.output);
+    }
+    // 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;
+}
+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]);
+    }
+    for (const child of route.childRoutes.values())
+        CollectProjections(child, byRoute);
+}
+/**
+ * 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 OrderProjections(rootRoute) {
+    const byRoute = new Map();
+    CollectProjections(rootRoute, byRoute);
+    const order = [];
+    const state = new Map();
+    // 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(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(projection, "done");
+        order.push(projection);
+    }
+    for (const projections of byRoute.values())
+        for (let x = 0; x < projections.length; x++)
+            Visit(projections[x], []);
+    return order;
+}

package/Store/Diff/utils/routes.d.ts

@@ -0,0 +1,27 @@
+import { IKeyFunc, IRoute, IRouteDefinitions } from "./diffTree.types";
+/**
+ * A DiffTree's route instances: one per route path a definition matches, created from the
+ * definition on first use, each with its own projections and keyFunc.
+ */
+export declare class RouteInstances {
+    private keyFunc;
+    readonly root: IRoute;
+    /**
+     * Changes whenever an instance may have been created or removed, so the projection order can
+     * tell it needs rebuilding and a wildcard read that its matches may have changed
+     */
+    version: number;
+    private cache;
+    constructor(keyFunc: IKeyFunc | undefined, definitions: IRouteDefinitions);
+    /**
+     * 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
+     */
+    Get(routePath: string): IRoute;
+    /**
+     * Removes every instance at or below a route.
+     * @param route A full, non-root route path, e.g. `/channel/1/`
+     */
+    Delete(route: string): void;
+}

package/Store/Diff/utils/routes.js

@@ -0,0 +1,168 @@
+import { IsWildcardPath, JoinPaths, PathsOverlap, PROJECTION_PREFIX, ROOT_ROUTE, RouteSegments, ValidateWildcardPath } from "./paths";
+/**
+ * A DiffTree's route instances: one per route path a definition matches, created from the
+ * definition on first use, each with its own projections and keyFunc.
+ */
+export class RouteInstances {
+    constructor(keyFunc, definitions) {
+        this.keyFunc = keyFunc;
+        /**
+         * Changes whenever an instance may have been created or removed, so the projection order can
+         * tell it needs rebuilding and a wildcard read that its matches may have changed
+         */
+        this.version = 0;
+        // Each route path looked up, by the instance it found; cleared below a deleted route
+        this.cache = new Map();
+        if (!Object.hasOwn(definitions, ROOT_ROUTE))
+            definitions = { ...definitions, [ROOT_ROUTE]: { projections: {} } };
+        this.root = CreateRoute([], ROOT_ROUTE, definitions[ROOT_ROUTE], keyFunc);
+        // Every other pattern in the map is a child of the root route
+        this.root.routeDefinitions = definitions;
+        this.root.childPartCounts = PartCounts(definitions);
+        // Both spellings of the root route, so the first lookup of either isn't taken for a new instance
+        this.cache.set("", this.root);
+        this.cache.set(ROOT_ROUTE, this.root);
+    }
+    /**
+     * 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
+     */
+    Get(routePath) {
+        let route = this.cache.get(routePath);
+        if (route)
+            return route;
+        this.version++;
+        const segments = RouteSegments(routePath);
+        route = segments.length === 0 ? this.root : FindRoute(this.root, segments, 0, this.keyFunc) ?? this.root;
+        this.cache.set(routePath, route);
+        return route;
+    }
+    /**
+     * Removes every instance at or below a route.
+     * @param route A full, non-root route path, e.g. `/channel/1/`
+     */
+    Delete(route) {
+        RemoveRouteInstances(this.root, route);
+        for (const cachedPath of this.cache.keys())
+            if (cachedPath.startsWith(route))
+                this.cache.delete(cachedPath);
+        this.version++;
+    }
+}
+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);
+    }
+    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;
+}
+/**
+ * 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 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;
+    }
+    return undefined;
+}
+/** 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);
+    }
+}
+/** 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 counts;
+}
+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 undefined;
+}
+/**
+ * @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
+ */
+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("}");
+}

package/Store/Diff/utils/state.d.ts

@@ -0,0 +1,56 @@
+import { ISnapshotState } from "../../Tree/snapshot";
+import { IRouteSource } from "./diffTree.types";
+/**
+ * The raw state of a DiffTree's routes. A route's state hangs off its parent route's state under
+ * `ROUTE_STATE`, keyed by segment, so `Object.keys` of a route's state lists only its own values.
+ */
+export declare const ROUTE_STATE: unique symbol;
+/**
+ * A route's state object, e.g. `/channel/1/`'s; `""` and `/` are the root.
+ * @param create Creates the route's state, and its parents', when missing
+ * @returns The state, or undefined when it's missing and `create` isn't set
+ */
+export declare function RouteState(root: any, route: string, create?: boolean): any;
+/**
+ * Writes a value to a path as it is, without diffing it or keeping keyed values at their homes,
+ * creating the path's route when missing. A path to a route (`/channel/1/`) only creates it.
+ * @throws When the path's parent doesn't exist
+ */
+export declare function WritePath(snapshot: ISnapshotState, root: any, path: string, value: any): void;
+/** The value at a path, or undefined when any segment of it doesn't exist; see ReadPathFound */
+export declare function ReadPath(root: any, path: string): any;
+/**
+ * The value at a path, and whether its parent was found: a property missing from an existing
+ * parent is found as undefined.
+ */
+export declare function ReadPathFound(root: any, path: string): [any, boolean];
+/** The value at the first `depth` parts of a property path */
+export declare function ReadPathParts(value: any, parts: string[], depth: number): any;
+/**
+ * The snapshot of the value at a path, whether it was found, and the route it was read through,
+ * when there is one. A property path is read from the snapshot of its first segment alone, not of
+ * the whole route, so a write to the route's other keys neither rebuilds what it reads nor changes it.
+ */
+export declare function ReadSnapshot(snapshot: ISnapshotState, root: any, path: string): [any, boolean, IRouteSource | undefined];
+/**
+ * Whether a key's value still has the snapshot taken of it, told by a cache lookup without
+ * taking a new one. A primitive value has no snapshot of its own and is compared as it is. A
+ * value with no cached snapshot was written since, even where the snapshot was undefined.
+ */
+export declare function KeyUnchanged(snapshot: ISnapshotState, state: object, key: string, keySnapshot: any): boolean;
+export declare function Remove(snapshot: ISnapshotState, parent: any, prop: string | number): void;
+export declare function Assign(snapshot: ISnapshotState, parent: any, prop: string | number, value: any): void;
+/**
+ * Deletes a route's state, child routes included, from its parent route. Every cached snapshot
+ * that embedded a value from it, such as one reading a keyed value through its home in the
+ * route, is invalidated.
+ * @param route A non-root route path, e.g. `/channel/1/`
+ */
+export declare function DeleteRouteState(snapshot: ISnapshotState, root: any, route: string): void;
+/**
+ * Expands a wildcard path's route against the route state under `root`.
+ * @returns Each matching path, keyed by the segment the wildcard matched
+ */
+export declare function ExpandWildcardPath(root: any, path: string): {
+    [segment: string]: string;
+};