j-templates 8.2.0 → 9.0.1

package/Store/Diff/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./diffTree.types";
 export * from "./utils/diffTree.types";
+export { PROJECTION_PREFIX } from "./utils/paths";

package/Store/Diff/index.js

@@ -1,2 +1,3 @@
 export * from "./diffTree.types";
 export * from "./utils/diffTree.types";
+export { PROJECTION_PREFIX } from "./utils/paths";

package/Store/Diff/utils/diffTree.types.d.ts

@@ -43,10 +43,15 @@ export type IKeyedState = {
     /** Whether it reads its route's own state, which leaves out the route's projection outputs */
     routeState: boolean;
 };
-/** A route a read resolved through on its last full read: its path, raw state and the snapshot read from it */
+/**
+ * A route a read resolved through on its last full read: its path, raw state and the snapshot read
+ * from it. A read of a property path reads only the route state's `key`, the path's first segment,
+ * and `snapshot` is that key's; a read of the whole route has no `key`, and `snapshot` is the route's.
+ */
 export type IRouteSource = {
     route: string;
     state: object;
+    key?: string;
     snapshot: any;
 };
 /** A route a wildcard read matched: the segment, the path read in it, and what was read */

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

@@ -0,0 +1,46 @@
+import { ISnapshotState } from "../../Tree/snapshot";
+type KeyFunc = {
+    (value: any): string | undefined;
+};
+/** Returns the keyFunc for a route path (`/channel/1/`, or `""`/`/` for the root) */
+export type RouteKeyFunc = {
+    (route: string): KeyFunc | undefined;
+};
+/** What a write needs: the tree's snapshot cache, its root state, and each route's keyFunc */
+export type WriteContext = {
+    snapshot: ISnapshotState;
+    root: any;
+    routeKeyFunc: RouteKeyFunc;
+};
+/**
+ * Writes a value to a path, keeping every keyed value at its home.
+ *
+ * A keyed value is written to its home, and every other place it appears (a "slot") holds that
+ * home object itself rather than a copy. So reading through a slot reads the home, a write through a
+ * slot writes the home, and a home's snapshot is shared by every slot. Homes keep their identity: a
+ * home is only ever changed in place.
+ *
+ * A write is applied in three steps:
+ * 1. A path that runs through a slot is a write to the first such slot's home. When the write would change
+ *    the entity's key, the changed entity is written to the slot instead, which writes it to its new
+ *    home and leaves the old one alone.
+ * 2. The value is flattened: each keyed value in it is written to its home and replaced by the home
+ *    object. A keyed value whose home is inside the written path stays where it is: it's its own home.
+ * 3. The flattened value is diffed into what's at the path, in place. A slot is never diffed into,
+ *    since that would change another entity's home: a slot written with anything else is replaced,
+ *    and so is an array of keyed values, which holds nothing but slots.
+ *
+ * @param path The path, e.g. `value.item` or `/First/Second/value.item`
+ * @throws When the path's parent doesn't exist, or a home would be replaced with a value of
+ *   another type, which would break the slots holding it
+ */
+export declare function ApplyValueToPath(context: WriteContext, path: string, value: any): void;
+/**
+ * Splices the array at a path in place, as `Array.prototype.splice` would: a start past the end
+ * splices at the end, and a delete past the end deletes to it. A path through a slot splices the
+ * slot's home's array. Inserted items are flattened like a written value (see ApplyValueToPath).
+ * @param path The array's path, e.g. `items` or `/channel/1/value.list`
+ * @throws When there's no array at the path
+ */
+export declare function SpliceValueAtPath(context: WriteContext, path: string, start: number, deleteCount: number, items: readonly unknown[]): void;
+export {};

package/Store/Diff/utils/homes.js

@@ -0,0 +1,213 @@
+import { JsonApplyDiff, JsonApplySplices, JsonDiff, JsonType, SPLICE_ACTION } from "../../../Utils/json";
+import { ArraysEqual } from "../../../Utils/array";
+import { Snapshot } from "../../Tree/snapshot";
+import { IsPathWithin, JoinPaths, PROP_DELIMETER, ROUTE_DELIMETER, SplitRouteAndPath } from "./paths";
+import { Assign, ReadPath, ReadPathParts, Remove, RouteState } from "./state";
+/**
+ * Where a keyed value lives ("its home"): its key joined to the route it's written in. A key
+ * starting with `/` is a route path from the root.
+ * @returns The home's path, or undefined when the value isn't keyed or its key names a route the
+ *   value's own route ends with, which can't be its home
+ */
+function HomePath(keyFunc, route, value) {
+    const key = JsonType(value) === "value" ? undefined : keyFunc?.(value);
+    if (!key)
+        return undefined;
+    if (key.includes(ROUTE_DELIMETER)) {
+        const [keyRoute] = SplitRouteAndPath(key);
+        if (keyRoute && !keyRoute.startsWith(ROUTE_DELIMETER) && route.endsWith(keyRoute))
+            return undefined;
+    }
+    return JoinPaths(route, key);
+}
+/**
+ * Writes a value to a path, keeping every keyed value at its home.
+ *
+ * A keyed value is written to its home, and every other place it appears (a "slot") holds that
+ * home object itself rather than a copy. So reading through a slot reads the home, a write through a
+ * slot writes the home, and a home's snapshot is shared by every slot. Homes keep their identity: a
+ * home is only ever changed in place.
+ *
+ * A write is applied in three steps:
+ * 1. A path that runs through a slot is a write to the first such slot's home. When the write would change
+ *    the entity's key, the changed entity is written to the slot instead, which writes it to its new
+ *    home and leaves the old one alone.
+ * 2. The value is flattened: each keyed value in it is written to its home and replaced by the home
+ *    object. A keyed value whose home is inside the written path stays where it is: it's its own home.
+ * 3. The flattened value is diffed into what's at the path, in place. A slot is never diffed into,
+ *    since that would change another entity's home: a slot written with anything else is replaced,
+ *    and so is an array of keyed values, which holds nothing but slots.
+ *
+ * @param path The path, e.g. `value.item` or `/First/Second/value.item`
+ * @throws When the path's parent doesn't exist, or a home would be replaced with a value of
+ *   another type, which would break the slots holding it
+ */
+export function ApplyValueToPath(context, path, value) {
+    const [route, property] = WriteRoute(path);
+    if (!property)
+        throw new Error("Unable to write to root path");
+    RouteState(context.root, route, true);
+    WriteValue(context, route, property.split(PROP_DELIMETER), value);
+}
+/**
+ * Splices the array at a path in place, as `Array.prototype.splice` would: a start past the end
+ * splices at the end, and a delete past the end deletes to it. A path through a slot splices the
+ * slot's home's array. Inserted items are flattened like a written value (see ApplyValueToPath).
+ * @param path The array's path, e.g. `items` or `/channel/1/value.list`
+ * @throws When there's no array at the path
+ */
+export function SpliceValueAtPath(context, path, start, deleteCount, items) {
+    const [route, property] = WriteRoute(path);
+    const keyFunc = context.routeKeyFunc(route);
+    const targetPath = JoinPaths(route, property);
+    // Flattened first: a home it writes could be the one holding the array
+    const insert = items.map(item => ({ type: SPLICE_ACTION.INSERT, value: Flatten(context, keyFunc, route, targetPath, item) }));
+    const array = ReadPath(context.root, path);
+    if (!array)
+        throw new Error(`Array not found at path: ${path}`);
+    if (!Array.isArray(array))
+        throw new Error(`Value at path ${path} is not an array`);
+    const index = Math.min(start, array.length);
+    const actualDelete = Math.max(0, Math.min(deleteCount, array.length - index));
+    if (actualDelete === 0 && insert.length === 0)
+        return;
+    JsonApplySplices(array, [{ index, delete: actualDelete, insert }], KeepValue);
+    Snapshot.Invalidate(context.snapshot, array);
+}
+/** A written path's route from the root (`/` for the root route) and its property path */
+function WriteRoute(path) {
+    const [route, property] = SplitRouteAndPath(path);
+    return [JoinPaths("", route), property];
+}
+function WriteValue(context, route, parts, value) {
+    const keyFunc = context.routeKeyFunc(route);
+    const routeRoot = ReadPath(context.root, route);
+    // Step 1: the first slot the path runs through, below the route's root and above the target.
+    // Values inside a home are keyed by the home's own route, so any slot past this one is found by
+    // the write to the home.
+    let slotDepth = -1;
+    let slotHome;
+    for (let x = 0, curr = routeRoot; keyFunc && x < parts.length - 1; x++) {
+        curr = curr?.[parts[x]];
+        if (JsonType(curr) === "value")
+            break;
+        const homePath = HomePath(keyFunc, route, curr);
+        // The path is only joined for a keyed value
+        if (homePath !== undefined && IsSlot(homePath, JoinPaths(route, parts.slice(0, x + 1).join(PROP_DELIMETER)))) {
+            slotDepth = x + 1;
+            slotHome = homePath;
+            break;
+        }
+    }
+    if (slotHome !== undefined) {
+        const home = ReadPathParts(routeRoot, parts, slotDepth);
+        const rest = parts.slice(slotDepth);
+        const changed = SetPath(home, rest, value);
+        if (keyFunc(changed) === keyFunc(home)) {
+            const [homeRoute, homeProperty] = SplitRouteAndPath(slotHome);
+            WriteValue(context, homeRoute, homeProperty.split(PROP_DELIMETER).concat(rest), value);
+        }
+        else
+            WriteValue(context, route, parts.slice(0, slotDepth), changed);
+        return;
+    }
+    // Step 2: flatten first, so the homes it writes exist before the slots pointing to them
+    const targetPath = JoinPaths(route, parts.join(PROP_DELIMETER));
+    const flattened = Flatten(context, keyFunc, route, targetPath, value);
+    // Step 3
+    const parent = ReadPathParts(routeRoot, parts, parts.length - 1);
+    if (JsonType(parent) === "value")
+        throw new Error("Unable to write value to path: " + targetPath);
+    const prop = parts[parts.length - 1];
+    const current = parent[prop];
+    if (current === flattened)
+        return;
+    const currentType = JsonType(current);
+    const currentHome = HomePath(keyFunc, route, current);
+    if (currentType !== "value" && currentType === JsonType(flattened) && !IsSlot(currentHome, targetPath) && !IsSlot(HomePath(keyFunc, route, flattened), targetPath)) {
+        const diff = JsonDiff(flattened, current, undefined, IngestStrategy(keyFunc, route, flattened));
+        if (diff.length > 0) {
+            JsonApplyDiff(current, diff, (target, key, written) => Assign(context.snapshot, target, key, written), (target, key) => Remove(context.snapshot, target, key), (array) => Snapshot.Invalidate(context.snapshot, array), KeepValue);
+        }
+        return;
+    }
+    // The current value is the home at this path
+    if (currentHome === targetPath && flattened !== undefined)
+        throw new Error(`Unable to replace the keyed value at ${targetPath}: a keyed value keeps its type and key at its home`);
+    Assign(context.snapshot, parent, prop, flattened);
+}
+/** Whether a value with this home, held at `path`, is a slot: its home is somewhere else */
+function IsSlot(homePath, path) {
+    return homePath !== undefined && homePath !== path;
+}
+/**
+ * How a flattened value is diffed into the tree: a slot, or an array of them, is replaced rather
+ * than diffed into, and so is any value replacing a slot. The value being written is diffed into
+ * its target even when it's keyed, which is how a home is updated in place.
+ *
+ * An array of slots holding the same homes as before, in the same order, is skipped rather than
+ * replaced, so it keeps its object and its snapshot: rewriting an entity whose keyed children didn't
+ * change leaves the entity's snapshot, and every projection reading it, alone.
+ */
+function IngestStrategy(keyFunc, route, rootValue) {
+    return keyFunc && function (newValue, oldValue) {
+        if (newValue === rootValue)
+            return undefined;
+        if (Array.isArray(newValue)) {
+            if (newValue.length === 0 || HomePath(keyFunc, route, newValue[0]) === undefined)
+                return undefined;
+            return Array.isArray(oldValue) && ArraysEqual(newValue, oldValue) ? "skip" : "write";
+        }
+        return HomePath(keyFunc, route, newValue) !== undefined || HomePath(keyFunc, route, oldValue) !== undefined ? "write" : undefined;
+    };
+}
+/**
+ * A copy of a value the tree owns, with each keyed value written to its home and replaced by the
+ * home object. A keyed value whose home is inside `targetPath`, the path being written, is copied
+ * in place instead.
+ */
+function Flatten(context, keyFunc, route, targetPath, value) {
+    const type = JsonType(value);
+    if (type === "value")
+        return value;
+    const homePath = HomePath(keyFunc, route, value);
+    if (homePath !== undefined && !IsPathWithin(homePath, targetPath)) {
+        // A home written back to itself, e.g. one read through a slot, has nothing to write
+        const home = ReadPath(context.root, homePath);
+        if (home === value)
+            return home;
+        const [homeRoute, homeProperty] = SplitRouteAndPath(homePath);
+        home === undefined && RouteState(context.root, homeRoute, true);
+        WriteValue(context, homeRoute, homeProperty.split(PROP_DELIMETER), value);
+        // An existing home is updated in place, so only a new one needs reading
+        return home ?? ReadPath(context.root, homePath);
+    }
+    if (type === "array") {
+        const result = new Array(value.length);
+        for (let x = 0; x < value.length; x++)
+            result[x] = Flatten(context, keyFunc, route, targetPath, value[x]);
+        return result;
+    }
+    const result = {};
+    const keys = Object.keys(value);
+    for (let x = 0; x < keys.length; x++)
+        result[keys[x]] = Flatten(context, keyFunc, route, targetPath, value[keys[x]]);
+    return result;
+}
+/** The flattened value is already the tree's own, slots included, so it's written as is */
+function KeepValue(value) {
+    return value;
+}
+/**
+ * A copy of `value` with `path` set, copying only the objects along the path
+ * @throws When an object along the path doesn't exist
+ */
+function SetPath(value, path, set) {
+    if (path.length === 0)
+        return set;
+    if (JsonType(value) === "value")
+        throw new Error("Unable to write value to path: " + path.join(PROP_DELIMETER));
+    const copy = Array.isArray(value) ? value.slice() : { ...value };
+    copy[path[0]] = SetPath(value[path[0]], path.slice(1), set);
+    return copy;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Path strings. A path is a route and a property path: `/channel/1/value.item` is the property
+ * path `value.item` in the route `/channel/1/`. A path without a route (`value.item`) is in the
+ * root route.
+ */
+export declare const ROOT_ROUTE = "/";
+export declare const PROJECTION_PREFIX = "$projection_";
+export declare const ROUTE_DELIMETER = "/";
+export declare const PROP_DELIMETER = ".";
+export declare const WILDCARD = "*";
+export declare function SplitRouteAndPath(path: string): readonly [string, string];
+/**
+ * A path's route and property path. Only a path starting with `/` has a route: any other path
+ * is a property path from the root.
+ */
+export declare function RouteAndProperty(path: string): readonly [string, string];
+export declare function JoinPaths(basePath: string, targetPath: string): string;
+/** A route's segments: `/channel/1/` is `channel` and `1` */
+export declare function RouteSegments(route: string): string[];
+/** Whether `path` is `basePath` or a property below it: `/a.b` is within `/a`, `/ab` isn't */
+export declare function IsPathWithin(path: string, basePath: string): boolean;
+/** Whether a path's route has a wildcard segment, e.g. a `row_*` segment */
+export declare function IsWildcardPath(path: string): boolean;
+/**
+ * Whether a route matches a route pattern segment by segment. A pattern segment ending in `*`
+ * matches any segment starting with the text before it: a `row_*` segment matches `row_1`.
+ */
+export declare function RouteMatches(pattern: string, route: string): boolean;
+/**
+ * Throws when a read path's wildcard is invalid: more than one wildcard segment, a `*` that
+ * doesn't end its segment, or a `*` in the property path.
+ */
+export declare function ValidateWildcardPath(path: string): void;
+/**
+ * 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.
+ */
+export declare function PathsOverlap(read: string, output: string): boolean;
+/** Whether a read's property path and an output's in a matching route overlap; see `PathsOverlap` */
+export declare function PropertiesOverlap(readProperty: string, outputProperty: string): boolean;

package/Store/Diff/utils/paths.js

@@ -0,0 +1,87 @@
+/**
+ * Path strings. A path is a route and a property path: `/channel/1/value.item` is the property
+ * path `value.item` in the route `/channel/1/`. A path without a route (`value.item`) is in the
+ * root route.
+ */
+export const ROOT_ROUTE = "/";
+export const PROJECTION_PREFIX = "$projection_";
+export const ROUTE_DELIMETER = "/";
+export const PROP_DELIMETER = ".";
+export const WILDCARD = "*";
+export function SplitRouteAndPath(path) {
+    const lastSlash = path.lastIndexOf(ROUTE_DELIMETER);
+    const route = path.slice(0, lastSlash + 1);
+    const propertyPath = path.slice(lastSlash + 1);
+    return [route, propertyPath];
+}
+/**
+ * A path's route and property path. Only a path starting with `/` has a route: any other path
+ * is a property path from the root.
+ */
+export function RouteAndProperty(path) {
+    return path.startsWith(ROUTE_DELIMETER) ? SplitRouteAndPath(path) : ["", path];
+}
+export function JoinPaths(basePath, targetPath) {
+    if (targetPath.startsWith(ROUTE_DELIMETER))
+        return targetPath;
+    if (basePath === '')
+        return `/${targetPath}`;
+    return basePath.concat(targetPath);
+}
+/** A route's segments: `/channel/1/` is `channel` and `1` */
+export function RouteSegments(route) {
+    return route.split(ROUTE_DELIMETER).filter(part => part !== "");
+}
+/** Whether `path` is `basePath` or a property below it: `/a.b` is within `/a`, `/ab` isn't */
+export function IsPathWithin(path, basePath) {
+    return path.startsWith(basePath) && (path.length === basePath.length || path[basePath.length] === PROP_DELIMETER);
+}
+/** Whether a path's route has a wildcard segment, e.g. a `row_*` segment */
+export function IsWildcardPath(path) {
+    return SplitRouteAndPath(path)[0].includes(WILDCARD);
+}
+/**
+ * Whether a route matches a route pattern segment by segment. A pattern segment ending in `*`
+ * matches any segment starting with the text before it: a `row_*` segment matches `row_1`.
+ */
+export function RouteMatches(pattern, route) {
+    if (pattern === route)
+        return true;
+    // Every route but a few fails on the text before the wildcard, so that's checked before splitting
+    const wildcard = pattern.indexOf(WILDCARD);
+    if (wildcard < 0 || !route.startsWith(pattern.slice(0, wildcard)))
+        return false;
+    const patternParts = pattern.split(ROUTE_DELIMETER);
+    const routeParts = route.split(ROUTE_DELIMETER);
+    if (patternParts.length !== routeParts.length)
+        return false;
+    for (let x = 0; x < patternParts.length; x++)
+        if (patternParts[x].endsWith(WILDCARD) ? !routeParts[x].startsWith(patternParts[x].slice(0, -1)) : patternParts[x] !== routeParts[x])
+            return false;
+    return true;
+}
+/**
+ * Throws when a read path's wildcard is invalid: more than one wildcard segment, a `*` that
+ * doesn't end its segment, or a `*` in the property path.
+ */
+export function ValidateWildcardPath(path) {
+    const [route, property] = SplitRouteAndPath(path);
+    const wildcards = route.split(ROUTE_DELIMETER).filter(part => part.includes(WILDCARD));
+    if (property.includes(WILDCARD) || wildcards.length > 1 || wildcards.some(part => part.indexOf(WILDCARD) !== part.length - 1))
+        throw new Error(`Invalid wildcard read ${path}: only one route segment may end in ${WILDCARD}.`);
+}
+/**
+ * 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.
+ */
+export function PathsOverlap(read, output) {
+    const [readRoute, readProperty] = SplitRouteAndPath(read);
+    const [outputRoute, outputProperty] = SplitRouteAndPath(output);
+    return RouteMatches(readRoute, outputRoute) && PropertiesOverlap(readProperty, outputProperty);
+}
+/** Whether a read's property path and an output's in a matching route overlap; see `PathsOverlap` */
+export function PropertiesOverlap(readProperty, outputProperty) {
+    return readProperty === "" || IsPathWithin(readProperty, outputProperty) || IsPathWithin(outputProperty, readProperty);
+}

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

@@ -0,0 +1,55 @@
+import { ISnapshotState } from "../../Tree/snapshot";
+import { RouteInstances } from "./routes";
+/** Runs the projections of a DiffTree's route instances against its state */
+export declare class Projections {
+    private snapshot;
+    private rootState;
+    private routes;
+    private order;
+    private orderVersion;
+    constructor(snapshot: ISnapshotState, rootState: object, routes: RouteInstances);
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private SourcesUnchanged;
+    /**
+     * 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).
+     */
+    private SourceUnchanged;
+    /**
+     * 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.
+     */
+    private RefreshSources;
+    /**
+     * 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
+     */
+    private ReadValues;
+    /**
+     * 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.
+     */
+    private ReadWildcard;
+    private ReadMatch;
+}