j-templates 8.2.0 → 9.0.0

package/Store/Diff/utils/state.js

@@ -0,0 +1,155 @@
+import { JsonType } from "../../../Utils/json";
+import { Snapshot } from "../../Tree/snapshot";
+import { PROP_DELIMETER, ROUTE_DELIMETER, RouteAndProperty, SplitRouteAndPath, WILDCARD } from "./paths";
+/**
+ * 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 const ROUTE_STATE = Symbol("ROUTE_STATE");
+/**
+ * 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 function RouteState(root, route, create = false) {
+    let state = root;
+    for (let start = 1; state !== undefined && state !== null && start < route.length;) {
+        const end = route.indexOf(ROUTE_DELIMETER, start);
+        const segment = route.slice(start, end);
+        if (create && !Object.hasOwn(state, ROUTE_STATE))
+            Object.defineProperty(state, ROUTE_STATE, { value: {} });
+        state = create ? state[ROUTE_STATE][segment] ??= {} : state[ROUTE_STATE]?.[segment];
+        start = end + 1;
+    }
+    return state;
+}
+/**
+ * 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 function WritePath(snapshot, root, path, value) {
+    const [route, property] = RouteAndProperty(path);
+    const state = RouteState(root, route, true);
+    if (property === "")
+        return;
+    const parts = property.split(PROP_DELIMETER);
+    const parent = ReadPathParts(state, parts, parts.length - 1);
+    if (!parent)
+        throw new Error("Unable to write value to path: " + path);
+    Assign(snapshot, parent, parts[parts.length - 1], value);
+}
+/** The value at a path, or undefined when any segment of it doesn't exist; see ReadPathFound */
+export function ReadPath(root, path) {
+    return ReadPathFound(root, path)[0];
+}
+/**
+ * The value at a path, and whether its parent was found: a property missing from an existing
+ * parent is found as undefined.
+ */
+export function ReadPathFound(root, path) {
+    const [route, property] = RouteAndProperty(path);
+    const state = RouteState(root, route);
+    if (property === "")
+        return [state, !!state];
+    const parts = property.split(PROP_DELIMETER);
+    const parent = ReadPathParts(state, parts, parts.length - 1);
+    return [parent?.[parts[parts.length - 1]], !!parent];
+}
+/** The value at the first `depth` parts of a property path */
+export function ReadPathParts(value, parts, depth) {
+    let curr = value;
+    for (let x = 0; curr !== undefined && curr !== null && x < depth; x++)
+        curr = curr[parts[x]];
+    return curr;
+}
+/**
+ * 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 function ReadSnapshot(snapshot, root, path) {
+    const [route, property] = SplitRouteAndPath(path);
+    const routeState = RouteState(root, route);
+    if (!routeState)
+        return [undefined, false, undefined];
+    if (property === "") {
+        const routeSnapshot = Snapshot.Get(snapshot, routeState);
+        return [routeSnapshot, !!routeSnapshot, { route, state: routeState, snapshot: routeSnapshot }];
+    }
+    const dot = property.indexOf(PROP_DELIMETER);
+    const key = dot < 0 ? property : property.slice(0, dot);
+    const keySnapshot = Snapshot.Child(snapshot, routeState, key);
+    const source = { route, state: routeState, key, snapshot: keySnapshot };
+    if (dot < 0)
+        return [keySnapshot, true, source];
+    const [value, valueFound] = ReadPathFound(keySnapshot, property.slice(dot + 1));
+    return [value, valueFound, source];
+}
+/**
+ * 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 function KeyUnchanged(snapshot, state, key, keySnapshot) {
+    const value = state[key];
+    if (JsonType(value) === "value")
+        return value === keySnapshot;
+    const cached = Snapshot.Peek(snapshot, value);
+    return cached !== undefined && cached === keySnapshot;
+}
+// Removing or replacing a value changes its parent, not the value: its snapshot stays valid. That
+// matters for a slot, whose value is a home still held, and read, elsewhere.
+export function Remove(snapshot, parent, prop) {
+    delete parent[prop];
+    Snapshot.Invalidate(snapshot, parent);
+}
+export function Assign(snapshot, parent, prop, value) {
+    parent[prop] = value;
+    Snapshot.Invalidate(snapshot, parent);
+}
+/**
+ * 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 function DeleteRouteState(snapshot, root, route) {
+    const parentRoute = route.slice(0, route.lastIndexOf(ROUTE_DELIMETER, route.length - 2) + 1);
+    const segment = route.slice(parentRoute.length, -1);
+    const routeStates = RouteState(root, parentRoute)?.[ROUTE_STATE];
+    if (!routeStates || !Object.hasOwn(routeStates, segment))
+        return;
+    InvalidateState(snapshot, routeStates[segment]);
+    delete routeStates[segment];
+}
+function InvalidateState(snapshot, value) {
+    if (JsonType(value) === "value")
+        return;
+    Snapshot.Invalidate(snapshot, value);
+    const keys = Object.keys(value);
+    for (let x = 0; x < keys.length; x++)
+        InvalidateState(snapshot, value[keys[x]]);
+    const routeStates = value[ROUTE_STATE];
+    for (const segment in routeStates)
+        InvalidateState(snapshot, routeStates[segment]);
+}
+/**
+ * Expands a wildcard path's route against the route state under `root`.
+ * @returns Each matching path, keyed by the segment the wildcard matched
+ */
+export function ExpandWildcardPath(root, path) {
+    const [route, property] = SplitRouteAndPath(path);
+    const parts = route.split(ROUTE_DELIMETER);
+    const index = parts.findIndex(part => part.endsWith(WILDCARD));
+    const prefix = parts[index].slice(0, -1);
+    const parent = RouteState(root, parts.slice(0, index).join(ROUTE_DELIMETER) + ROUTE_DELIMETER);
+    const children = parent?.[ROUTE_STATE] ?? {};
+    const paths = {};
+    for (const segment of Object.keys(children))
+        if (segment.startsWith(prefix)) {
+            parts[index] = segment;
+            paths[segment] = parts.join(ROUTE_DELIMETER) + property;
+        }
+    return paths;
+}

package/Store/Store/store.d.ts

@@ -33,6 +33,12 @@ export declare abstract class ReadStore {
      */
     Get<O>(id: string, defaultValue: O): O;
     Has(id: string): boolean;
+    /**
+     * Whether the store holds the root a path is in: its key, before the first `.`. Push, Splice
+     * and Patch take a path into a root, e.g. `rows.t_1`.
+     * @param path The path, e.g. `user.items`.
+     */
+    protected HasRootOf(path: string): boolean;
     /**
      * Updates the root map with diff results by grouping changes by root path.
      * @param results - Array of diff results to apply
@@ -62,3 +68,5 @@ export declare abstract class Store extends ReadStore {
     abstract Push(key: string, ...data: unknown[]): Promise<void> | void;
     abstract Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): Promise<void> | void;
 }
+/** The root key a path is in: its text before the first `.` */
+export declare function RootOf(path: string): string;

package/Store/Store/store.js

@@ -47,6 +47,14 @@ export class ReadStore {
     Has(id) {
         return this.rootMap.has(id);
     }
+    /**
+     * Whether the store holds the root a path is in: its key, before the first `.`. Push, Splice
+     * and Patch take a path into a root, e.g. `rows.t_1`.
+     * @param path The path, e.g. `user.items`.
+     */
+    HasRootOf(path) {
+        return this.Has(RootOf(path));
+    }
     /**
      * Updates the root map with diff results by grouping changes by root path.
      * @param results - Array of diff results to apply
@@ -96,3 +104,8 @@ export class ReadStore {
  */
 export class Store extends ReadStore {
 }
+/** The root key a path is in: its text before the first `.` */
+export function RootOf(path) {
+    const dot = path.indexOf(".");
+    return dot < 0 ? path : path.slice(0, dot);
+}

package/Store/Store/storeAsync.js

@@ -1,6 +1,6 @@
 import { AsyncQueue } from "../../Utils/asyncQueue";
 import { WorkerQueue } from "../Diff/workerQueue";
-import { Store } from "./store";
+import { RootOf, Store } from "./store";
 /**
  * StoreAsync class extends the base Store class to provide asynchronous data management operations.
  * This class handles writing, patching, pushing, and splicing data in an asynchronous manner.
@@ -82,12 +82,13 @@ export class StoreAsync extends Store {
         key = key || this.keyFunc?.(data);
         if (!key)
             throw new Error("No key provided for data");
-        this.writeKeySet.add(key);
+        // Pending writes by root, so a change to a path in a root being written isn't refused
+        this.writeKeySet.add(RootOf(key));
         await this.Schedule({
             method: "writepath",
             arguments: [key, data]
         });
-        this.writeKeySet.delete(key);
+        this.writeKeySet.delete(RootOf(key));
     }
     /**
      * Patches an existing value in the store with new data asynchronously.
@@ -100,7 +101,7 @@ export class StoreAsync extends Store {
      *   the original error if an earlier change failed.
      */
     async Patch(key, patch) {
-        if (!this.Has(key) && !this.writeKeySet.has(key))
+        if (!this.HasRootOf(key) && !this.writeKeySet.has(RootOf(key)))
             throw "Key not found in store";
         await this.Schedule({
             method: "patchpath",
@@ -116,7 +117,7 @@ export class StoreAsync extends Store {
      *   the original error if an earlier change failed.
      */
     async Push(key, ...data) {
-        if (!this.Has(key) && !this.writeKeySet.has(key))
+        if (!this.HasRootOf(key) && !this.writeKeySet.has(RootOf(key)))
             throw "Key not found in store";
         await this.Schedule({
             method: "pushpath",
@@ -135,7 +136,7 @@ export class StoreAsync extends Store {
      *   the original error if an earlier change failed.
      */
     async Splice(key, start, deleteCount, ...items) {
-        if (!this.Has(key) && !this.writeKeySet.has(key))
+        if (!this.HasRootOf(key) && !this.writeKeySet.has(RootOf(key)))
             throw "Key not found in store";
         await this.Schedule({
             method: "splicepath",

package/Store/Store/storeSync.js

@@ -60,7 +60,7 @@ export class StoreSync extends Store {
      * @throws Will throw an error if the value to be patched is undefined.
      */
     Patch(key, patch) {
-        if (!this.Has(key))
+        if (!this.HasRootOf(key))
             throw "Key not found in store";
         this.diff.PatchPath(key, patch);
         this.Sync();
@@ -71,7 +71,7 @@ export class StoreSync extends Store {
      * @param data The data items to be pushed into the array.
      */
     Push(key, ...data) {
-        if (!this.Has(key))
+        if (!this.HasRootOf(key))
             throw "Key not found in store";
         this.diff.PushPath(key, data);
         this.Sync();
@@ -85,7 +85,7 @@ export class StoreSync extends Store {
      * @param items Optional elements to insert into the array.
      */
     Splice(key, start, deleteCount, ...items) {
-        if (!this.Has(key))
+        if (!this.HasRootOf(key))
             throw "Key not found in store";
         this.diff.SplicePath(key, start, deleteCount ?? Infinity, items);
         this.Sync();

package/Store/Tree/observableNode.js

@@ -109,9 +109,7 @@ function GetPropertyScope(object, prop) {
     return object[prop];
 }
 function SetObjectValue(object, prop, value) {
-    const propExists = Object.hasOwn(object[NODE_VALUE], prop);
-    object[NODE_VALUE][prop] = value;
-    NodeValueSet(object[NODE_VALUE], prop, !propExists, object);
+    AssignNodeValue(object[NODE_VALUE], prop, value, object);
 }
 function SetArrayValue(object, prop, value) {
     object[NODE_VALUE][prop] = value;
@@ -121,25 +119,33 @@ function NodeValueSet(obj, prop, added, wrapper = wrapperCache.get(obj)) {
     InvalidateSnapshotForValue(obj);
     if (!wrapper)
         return;
-    const propScopeExists = !!prop && Object.hasOwn(wrapper, prop);
+    // An array's wrapper is an array with no property scopes: its own `length` isn't one, and a
+    // diff that only shrinks an array writes nothing but `length`
+    const propScopeExists = !!prop && !wrapper[ARRAY_SCOPE] && Object.hasOwn(wrapper, prop);
     if (!prop || added || !propScopeExists)
         ObservableScope.Update(wrapper[ARRAY_SCOPE] ?? wrapper[OBJECT_SCOPE]);
     if (propScopeExists)
         ObservableScope.Update(wrapper[prop]);
 }
-function AssignNodeValue(obj, prop, value) {
+/** A deleted property: the object's keys changed, so its scope updates, and so does the property's. */
+function RemoveNodeValue(obj, prop) {
+    delete obj[prop];
+    NodeValueSet(obj, prop, true);
+}
+/** An array spliced in place: its elements changed, so its scope updates. Moved elements keep their nodes. */
+function SplicedNodeValue(array) {
+    NodeValueSet(array, "", false);
+}
+/** A property assigned: the object's scope updates when it's new, and the property's does */
+function AssignNodeValue(obj, prop, value, wrapper) {
     const added = !Object.hasOwn(obj, prop);
     obj[prop] = value;
-    NodeValueSet(obj, prop, added);
+    NodeValueSet(obj, prop, added, wrapper);
 }
 function CreateProxyFactory(alias) {
     // Keyed children are read through their root. Every factory shares the module-level
     // snapshotState, matching wrapperCache; only the resolver differs per factory.
-    // The alias ignores paths, so the root is snapshotted at the child's own path
-    const resolveSnapshot = alias && function (child, path) {
-        const value = alias(child, false);
-        return value === undefined ? undefined : { value, path: path.slice() };
-    };
+    const resolveSnapshot = alias && (child => alias(child, false));
     function CreateSnapshot(value) {
         return Snapshot.Get(snapshotState, value, resolveSnapshot);
     }
@@ -410,10 +416,7 @@ export var ObservableNode;
      */
     function ApplyDiff(rootNode, diffResult) {
         const root = rootNode[NODE_VALUE];
-        JsonApplyDiff(root, diffResult, AssignNodeValue);
-        // A root replacement is applied in place without calling AssignNodeValue
-        if (diffResult.length === 1 && diffResult[0].path.length === 0)
-            NodeValueSet(root, "", false, rootNode[NODE_WRAPPER]);
+        JsonApplyDiff(root, diffResult, AssignNodeValue, RemoveNodeValue, SplicedNodeValue);
     }
     ObservableNode.ApplyDiff = ApplyDiff;
     /**

package/Store/Tree/snapshot.d.ts

@@ -1,18 +1,8 @@
 /**
- * The keys walked from the snapshot's seed to a value: property names, array indices and
- * hidden (symbol) props. A resolved child continues from the path its resolver returns.
+ * Resolves a keyed child to the root entity it should be read through. Returns the entity, or
+ * undefined when the child isn't keyed (or has no root), in which case the child itself is used.
  */
-export type SnapshotPath = (string | number | symbol)[];
-/**
- * Resolves a keyed child to the root entity it should be read through, given the child's
- * path. Returns the entity and its path, or undefined when the child isn't keyed (or has no
- * root), in which case the child itself is used. `path` is the walk's own stack, so a
- * resolver must not keep it.
- */
-export type SnapshotResolver = (child: any, path: Readonly<SnapshotPath>) => {
-    value: object;
-    path: SnapshotPath;
-} | undefined;
+export type SnapshotResolver = (child: any) => object | undefined;
 /**
  * Snapshot cache state. Each owner (a `DiffTree` instance, or `ObservableNode` at module
  * level) creates its own state, so cached snapshots are never shared between owners.
@@ -22,28 +12,36 @@ export interface ISnapshotState {
     rawToSnapshotCache: WeakMap<object, any>;
     /** Raw value -> every parent whose cached snapshot embedded it */
     hierarchy: WeakMap<object, Set<object>>;
-    /** Default resolver for keyed children; a call to `Snapshot.Get` may override it */
-    resolve: SnapshotResolver | undefined;
 }
 export declare namespace Snapshot {
     /**
      * Creates a new, empty snapshot cache.
-     * @param resolve Optional default resolver for keyed children.
      * @returns A new snapshot state.
      */
-    function Create(resolve?: SnapshotResolver): ISnapshotState;
+    function Create(): ISnapshotState;
     /**
      * Returns an immutable, cached snapshot of a raw value. The same snapshot is returned
      * until a write invalidates it, and unchanged nested parts are shared between snapshots,
      * so `===` holds for any part that hasn't changed.
      * @param state The snapshot cache to read from and populate.
      * @param value The raw value to snapshot.
-     * @param resolve Resolver for keyed children; defaults to the state's resolver.
-     * @param path The value's own path. Snapshots are cached per raw value, so a value must
-     * always be seeded with the same path or a resolver may see a different one.
+     * @param resolve Resolver for keyed children. Snapshots are cached per raw value, so a value
+     * must always be read with the same resolver.
      * @returns The snapshot.
      */
-    function Get<T>(state: ISnapshotState, value: T, resolve?: SnapshotResolver | undefined, path?: SnapshotPath): T;
+    function Get<T>(state: ISnapshotState, value: T, resolve?: SnapshotResolver): T;
+    /**
+     * The snapshot of one property of a raw value, as the value's own snapshot would hold it:
+     * cached, keyed children read through their root, and linked to the value so a write to the
+     * property invalidates the value's snapshot. Reads one property without building a snapshot of
+     * the whole value.
+     * @param state The snapshot cache to read from and populate.
+     * @param parent The raw value the property is on.
+     * @param key The property.
+     * @param resolve Resolver for keyed children.
+     * @returns The property's snapshot.
+     */
+    function Child(state: ISnapshotState, parent: any, key: string | number, resolve?: SnapshotResolver): any;
     /**
      * Invalidates the cached snapshot of a raw value that was just written to, along with
      * every cached ancestor that embedded it.

package/Store/Tree/snapshot.js

@@ -27,7 +27,7 @@ function InvalidateValue(state, value) {
  * unchanged children, so a snapshot handed out never changes and unchanged parts are
  * shared between snapshots. Keyed children are read through their root.
  */
-function CreateSnapshot(state, resolve, value, path) {
+function CreateSnapshot(state, resolve, value) {
     if (JsonType(value) === "value")
         return value;
     const cached = state.rawToSnapshotCache.get(value);
@@ -37,13 +37,13 @@ function CreateSnapshot(state, resolve, value, path) {
     if (Array.isArray(value)) {
         snapshot = new Array(value.length);
         for (let x = 0; x < value.length; x++)
-            snapshot[x] = ChildSnapshot(state, resolve, value, x, path);
+            snapshot[x] = ChildSnapshot(state, resolve, value, x);
     }
     else {
         snapshot = {};
         const keys = Object.keys(value);
         for (let x = 0; x < keys.length; x++)
-            snapshot[keys[x]] = ChildSnapshot(state, resolve, value, keys[x], path);
+            snapshot[keys[x]] = ChildSnapshot(state, resolve, value, keys[x]);
     }
     state.rawToSnapshotCache.set(value, snapshot);
     return snapshot;
@@ -54,23 +54,17 @@ function CreateSnapshot(state, resolve, value, path) {
  * linked too; the parent's own embedded copy stays linked because a positional write
  * (one that changes which entity a slot holds) mutates that copy in place.
  */
-function ChildSnapshot(state, resolve, parent, key, path) {
+function ChildSnapshot(state, resolve, parent, key) {
     const child = parent[key];
     if (JsonType(child) === "value")
         return child;
     CreateSnapshotLink(state, child, parent);
-    path.push(key);
-    try {
-        const resolved = resolve?.(child, path);
-        if (resolved !== undefined && resolved.value !== child) {
-            CreateSnapshotLink(state, resolved.value, parent);
-            return CreateSnapshot(state, resolve, resolved.value, resolved.path);
-        }
-        return CreateSnapshot(state, resolve, child, path);
-    }
-    finally {
-        path.pop();
+    const resolved = resolve?.(child);
+    if (resolved !== undefined && resolved !== child) {
+        CreateSnapshotLink(state, resolved, parent);
+        return CreateSnapshot(state, resolve, resolved);
     }
+    return CreateSnapshot(state, resolve, child);
 }
 function RegisterSnapshot(state, snapshot) {
     if (JsonType(snapshot) !== 'value')
@@ -80,14 +74,12 @@ export var Snapshot;
 (function (Snapshot) {
     /**
      * Creates a new, empty snapshot cache.
-     * @param resolve Optional default resolver for keyed children.
      * @returns A new snapshot state.
      */
-    function Create(resolve) {
+    function Create() {
         return {
             rawToSnapshotCache: new WeakMap(),
             hierarchy: new WeakMap(),
-            resolve,
         };
     }
     Snapshot.Create = Create;
@@ -97,15 +89,29 @@ export var Snapshot;
      * so `===` holds for any part that hasn't changed.
      * @param state The snapshot cache to read from and populate.
      * @param value The raw value to snapshot.
-     * @param resolve Resolver for keyed children; defaults to the state's resolver.
-     * @param path The value's own path. Snapshots are cached per raw value, so a value must
-     * always be seeded with the same path or a resolver may see a different one.
+     * @param resolve Resolver for keyed children. Snapshots are cached per raw value, so a value
+     * must always be read with the same resolver.
      * @returns The snapshot.
      */
-    function Get(state, value, resolve = state.resolve, path = []) {
-        return CreateSnapshot(state, resolve, value, path.slice());
+    function Get(state, value, resolve) {
+        return CreateSnapshot(state, resolve, value);
     }
     Snapshot.Get = Get;
+    /**
+     * The snapshot of one property of a raw value, as the value's own snapshot would hold it:
+     * cached, keyed children read through their root, and linked to the value so a write to the
+     * property invalidates the value's snapshot. Reads one property without building a snapshot of
+     * the whole value.
+     * @param state The snapshot cache to read from and populate.
+     * @param parent The raw value the property is on.
+     * @param key The property.
+     * @param resolve Resolver for keyed children.
+     * @returns The property's snapshot.
+     */
+    function Child(state, parent, key, resolve) {
+        return ChildSnapshot(state, resolve, parent, key);
+    }
+    Snapshot.Child = Child;
     /**
      * Invalidates the cached snapshot of a raw value that was just written to, along with
      * every cached ancestor that embedded it.