j-templates 9.0.1 → 10.0.1

package/Store/Diff/observableDiffTree.d.ts

@@ -0,0 +1,93 @@
+import { JsonDiffResult } from "../../Utils/json";
+import { DiffTree } from "./diffTree";
+import { IDiffPost, IObservableDiffTreeConfig, ISnapshotUpdate, ISubscribeOptions } from "./diffTree.types";
+import type { IDiffTreeEndpoint } from "./diffTreeEndpoint.types";
+import type { IKeyFunc } from "./utils/diffTree.types";
+/**
+ * A `DiffTree` that delivers every `Commit()` to its subscribers: the tree, observable.
+ *
+ * - **`Commit()` diffs and delivers; it doesn't run projections.** Call `RunProjections()` first
+ *   when the change needs them. A commit without it delivers the changed roots with the projection
+ *   outputs as they were, which is how to send a small change (a flag) ahead of a long write.
+ * - **Each subscription names its roots and form** (`ISubscribeOptions`). The diff is computed
+ *   once per commit and shaped for each: diff records, or whole changed roots. A commit with no
+ *   changes delivers nothing.
+ * - **A new subscription gets the committed state first**, inside `Subscribe`, then every commit.
+ *   Uncommitted writes arrive with the next commit, like everyone else's.
+ * - **Delivery is synchronous**, inside `Commit()`. A subscriber may write to another tree, but
+ *   a change to this one, or a commit, during its delivery throws. Values are shared with the
+ *   tree, never cloned: treat them as read-only.
+ * - When a subscriber throws, the others still get the commit, and `Commit()` throws the first error.
+ *
+ * @example
+ * const tree = new ObservableDiffTree({ keyFunc, routes });
+ * const stop = tree.Subscribe({ roots: ["loading", "$projection_*"] }, post => store.Apply(post.diff));
+ * tree.WritePath("loading", true);
+ * tree.Commit();
+ */
+export declare class ObservableDiffTree extends DiffTree {
+    private subscriptions;
+    private seq;
+    /** How many deliveries are running: changes and commits throw while it isn't 0 */
+    private delivering;
+    /** The endpoint the tree was built for, which `DiffTreeEndpoint.Host` checks */
+    readonly Endpoint?: IDiffTreeEndpoint;
+    /** How the tree keys its data: its config's, or its endpoint's. A `StoreSync` given the tree takes it. */
+    readonly KeyFunc?: IKeyFunc;
+    /**
+     * @param config The tree's endpoint, keyFunc, routes and opaque keys (`IObservableDiffTreeConfig`).
+     * @throws When a keyFunc is given with an endpoint (the endpoint's is the tree's), or a route of
+     *   the tree's own is one of the endpoint's follow routes.
+     */
+    constructor(config?: IObservableDiffTreeConfig);
+    /** The number of the last commit that changed something; 0 before the first */
+    get Seq(): number;
+    /**
+     * Diffs the tree since the last commit and delivers the changes to every subscription whose
+     * roots they touch.
+     * @returns The diff.
+     * @throws During a delivery from this tree, or the first error a subscriber threw.
+     */
+    Commit(): JsonDiffResult;
+    /**
+     * Subscribes to the tree's commits. The committed state of the matching roots is delivered
+     * first, before this returns, in the subscription's form: a `write` record per root, or every
+     * root; nothing when no root matches. Every later commit that touches them follows. A
+     * subscriber that held roots from an earlier subscription clears them before subscribing again.
+     * @returns A function that ends the subscription.
+     * @throws The first delivery's error, after ending the subscription.
+     */
+    Subscribe(options: ISubscribeOptions & {
+        form: "snapshot";
+    }, callback: (update: ISnapshotUpdate) => void): () => void;
+    Subscribe(options: ISubscribeOptions & {
+        form?: "diff";
+    }, callback: (post: IDiffPost) => void): () => void;
+    /**
+     * Waits for the first delivery in which every key has a committed value: at once when they all
+     * have one, otherwise the commit that adds the last. The values come from one commit.
+     * @param keys Exact root keys; no patterns.
+     * @param options `signal` cancels the wait, rejecting with its reason.
+     * @returns Each key's committed value.
+     */
+    Once(keys: readonly string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    /** Ends every subscription made with this `group`; see `ISubscribeOptions.group` */
+    Disconnect(group: unknown): void;
+    /** How many subscriptions name a root key exactly now; see `SubscriptionManager.SubscriberCount` */
+    SubscriberCount(key: string): number;
+    /**
+     * Calls back when a root key matching a pattern loses its last exact subscription. It only
+     * reports: whether and when to delete the key is the caller's. It runs inside the unsubscribe,
+     * which may be inside a delivery, so a callback that deletes the key does it later (a timer).
+     * @param pattern An exact key or a pattern ending in `*`.
+     * @returns A function that removes the callback.
+     */
+    OnReleased(pattern: string, callback: (key: string) => void): () => void;
+    private Deliver;
+    /** A subscriber can't change or commit the tree delivering to it */
+    protected BeforeChange(): void;
+}

package/Store/Diff/observableDiffTree.js

@@ -0,0 +1,200 @@
+import { IsPattern } from "../../Utils/pattern";
+import { SubscriptionManager } from "../../Utils/subscriptionManager";
+import { DiffTree } from "./diffTree";
+import { FollowRoutes } from "./utils/routes";
+/**
+ * A `DiffTree` that delivers every `Commit()` to its subscribers: the tree, observable.
+ *
+ * - **`Commit()` diffs and delivers; it doesn't run projections.** Call `RunProjections()` first
+ *   when the change needs them. A commit without it delivers the changed roots with the projection
+ *   outputs as they were, which is how to send a small change (a flag) ahead of a long write.
+ * - **Each subscription names its roots and form** (`ISubscribeOptions`). The diff is computed
+ *   once per commit and shaped for each: diff records, or whole changed roots. A commit with no
+ *   changes delivers nothing.
+ * - **A new subscription gets the committed state first**, inside `Subscribe`, then every commit.
+ *   Uncommitted writes arrive with the next commit, like everyone else's.
+ * - **Delivery is synchronous**, inside `Commit()`. A subscriber may write to another tree, but
+ *   a change to this one, or a commit, during its delivery throws. Values are shared with the
+ *   tree, never cloned: treat them as read-only.
+ * - When a subscriber throws, the others still get the commit, and `Commit()` throws the first error.
+ *
+ * @example
+ * const tree = new ObservableDiffTree({ keyFunc, routes });
+ * const stop = tree.Subscribe({ roots: ["loading", "$projection_*"] }, post => store.Apply(post.diff));
+ * tree.WritePath("loading", true);
+ * tree.Commit();
+ */
+export class ObservableDiffTree extends DiffTree {
+    /**
+     * @param config The tree's endpoint, keyFunc, routes and opaque keys (`IObservableDiffTreeConfig`).
+     * @throws When a keyFunc is given with an endpoint (the endpoint's is the tree's), or a route of
+     *   the tree's own is one of the endpoint's follow routes.
+     */
+    constructor(config = {}) {
+        const { endpoint, routes = {} } = config;
+        if (endpoint && config.keyFunc)
+            throw new Error(`ObservableDiffTree: the endpoint ${endpoint.name} gives the tree its keyFunc; leave it out of the config.`);
+        const follow = endpoint ? FollowRoutes(Object.fromEntries(endpoint.remotes.map(remote => [remote.source, remote.keyFunc]))) : {};
+        for (const route of Object.keys(follow))
+            if (route in routes)
+                throw new Error(`ObservableDiffTree: the route ${route} is ${endpoint.name}'s follow route for a source; rename it.`);
+        const keyFunc = endpoint ? endpoint.keyFunc : config.keyFunc;
+        super(keyFunc, { ...routes, ...follow });
+        this.subscriptions = new SubscriptionManager();
+        this.seq = 0;
+        /** How many deliveries are running: changes and commits throw while it isn't 0 */
+        this.delivering = 0;
+        this.Endpoint = endpoint;
+        this.KeyFunc = keyFunc;
+        config.opaque && this.MarkOpaque(config.opaque);
+    }
+    /** The number of the last commit that changed something; 0 before the first */
+    get Seq() {
+        return this.seq;
+    }
+    /**
+     * Diffs the tree since the last commit and delivers the changes to every subscription whose
+     * roots they touch.
+     * @returns The diff.
+     * @throws During a delivery from this tree, or the first error a subscriber threw.
+     */
+    Commit() {
+        this.BeforeChange();
+        const diff = super.Commit();
+        if (diff.length === 0)
+            return diff;
+        const seq = ++this.seq;
+        const changed = new Set();
+        const deleted = new Set();
+        for (let x = 0; x < diff.length; x++) {
+            const record = diff[x];
+            const key = record.path[0];
+            changed.add(key);
+            record.type === "delete" && record.path.length === 1 && deleted.add(key);
+        }
+        const errors = [];
+        for (const { id, subscription, keys } of this.subscriptions.Matching(changed)) {
+            // An earlier subscriber's delivery may have ended this one
+            if (!this.subscriptions.Has(id))
+                continue;
+            let delivery;
+            if (subscription.form === "diff") {
+                const matched = this.subscriptions.MatchesAll(id) ? diff : FilterDiff(diff, new Set(keys));
+                delivery = { seq, diff: matched };
+            }
+            else {
+                const roots = {};
+                const gone = [];
+                for (const key of keys)
+                    deleted.has(key) ? gone.push(key) : roots[key] = this.Committed(key);
+                delivery = { seq, roots, deleted: gone };
+            }
+            try {
+                this.Deliver(subscription, delivery);
+            }
+            catch (err) {
+                errors.push(err);
+            }
+        }
+        if (errors.length > 0)
+            throw errors[0];
+        return diff;
+    }
+    Subscribe(options, callback) {
+        const subscription = { form: options.form ?? "diff", callback };
+        const id = this.subscriptions.Subscribe(options.roots, subscription, { group: options.group });
+        const keys = this.subscriptions.MatchingKeys(id, this.CommittedKeys());
+        const delivery = subscription.form === "diff"
+            ? { seq: this.seq, diff: keys.map(key => ({ type: "write", path: [key], value: this.Committed(key) })) }
+            : { seq: this.seq, roots: Object.fromEntries(keys.map(key => [key, this.Committed(key)])), deleted: [] };
+        try {
+            keys.length > 0 && this.Deliver(subscription, delivery);
+        }
+        catch (err) {
+            this.subscriptions.Unsubscribe(id);
+            throw err;
+        }
+        return () => { this.subscriptions.Unsubscribe(id); };
+    }
+    /**
+     * Waits for the first delivery in which every key has a committed value: at once when they all
+     * have one, otherwise the commit that adds the last. The values come from one commit.
+     * @param keys Exact root keys; no patterns.
+     * @param options `signal` cancels the wait, rejecting with its reason.
+     * @returns Each key's committed value.
+     */
+    Once(keys, options = {}) {
+        const { signal } = options;
+        return new Promise((resolve, reject) => {
+            if (keys.some(IsPattern))
+                return reject(new Error(`Once takes exact keys, not patterns: ${keys.join(", ")}`));
+            if (signal?.aborted)
+                return reject(signal.reason);
+            let done = false;
+            let stop;
+            const onAbort = () => {
+                finish();
+                reject(signal.reason);
+            };
+            const finish = () => {
+                done = true;
+                stop?.();
+                signal?.removeEventListener("abort", onAbort);
+            };
+            stop = this.Subscribe({ roots: keys, form: "snapshot" }, () => {
+                if (done)
+                    return;
+                const values = {};
+                for (const key of keys) {
+                    const value = this.Committed(key);
+                    if (value === undefined)
+                        return;
+                    values[key] = value;
+                }
+                finish();
+                resolve(values);
+            });
+            // Resolved by the first delivery, before `stop` was set
+            if (done)
+                stop();
+            else
+                signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    /** Ends every subscription made with this `group`; see `ISubscribeOptions.group` */
+    Disconnect(group) {
+        this.subscriptions.Disconnect(group);
+    }
+    /** How many subscriptions name a root key exactly now; see `SubscriptionManager.SubscriberCount` */
+    SubscriberCount(key) {
+        return this.subscriptions.SubscriberCount(key);
+    }
+    /**
+     * Calls back when a root key matching a pattern loses its last exact subscription. It only
+     * reports: whether and when to delete the key is the caller's. It runs inside the unsubscribe,
+     * which may be inside a delivery, so a callback that deletes the key does it later (a timer).
+     * @param pattern An exact key or a pattern ending in `*`.
+     * @returns A function that removes the callback.
+     */
+    OnReleased(pattern, callback) {
+        return this.subscriptions.OnReleased(pattern, callback);
+    }
+    Deliver(subscription, delivery) {
+        this.delivering++;
+        try {
+            subscription.callback(delivery);
+        }
+        finally {
+            this.delivering--;
+        }
+    }
+    /** A subscriber can't change or commit the tree delivering to it */
+    BeforeChange() {
+        if (this.delivering > 0)
+            throw new Error("ObservableDiffTree: a subscriber can't write to or commit the tree delivering to it.");
+    }
+}
+/** The records whose root is one of `keys` */
+function FilterDiff(diff, keys) {
+    return diff.filter(record => keys.has(record.path[0]));
+}

package/Store/Diff/onConnect.d.ts

@@ -0,0 +1,33 @@
+import { IChannel } from "./diffTree.types";
+type ConnectHandler = (port: MessagePort) => (() => void) | void;
+/**
+ * Handles a worker's ports to a source it reads from, given by a `DiffTreeHub` (`Register(name,
+ * factory, { sources })`). The handler runs for each port: when the worker starts, and again when the source
+ * restarts. Before it runs for a new port, the cleanup it returned for the last one runs and that
+ * port is closed. A port that arrives before the handler is registered is kept for it, once the
+ * worker listens: `HostPublisher` starts listening, and so does the first `OnConnect`.
+ *
+ * The source must be one the worker was registered with (`sources`). The hub tells the worker its
+ * sources when it starts: `OnConnect` for another source throws then, or, when it was called
+ * before they arrived (while the worker's module first runs), throws as the worker's uncaught
+ * error when they do, which the main thread sees as the `Worker`'s `error` event.
+ *
+ * @example
+ * // trace worker
+ * OnConnect("engine", port => {
+ *   tree.DeleteRoute("/engine/");
+ *   return Subscribe(port, { roots: ["index"], form: "snapshot" }, update => { ... });
+ * });
+ * @param source The source worker's registered name.
+ * @param handler Subscribes over the port; may return a function that ends what it started.
+ * @param scope The worker's own channel; `self` when omitted.
+ * @returns A function that runs the current cleanup and removes the handler.
+ * @throws When the hub has told the worker its sources, and `source` isn't one.
+ */
+export declare function OnConnect(source: string, handler: ConnectHandler, scope?: IChannel): () => void;
+/**
+ * Starts keeping the `jt-connect` ports that arrive on a worker's channel, so a port that arrives
+ * before its `OnConnect` handler is registered is kept for it. `HostPublisher` calls it.
+ */
+export declare function ListenForConnections(scope: IChannel): void;
+export {};

package/Store/Diff/onConnect.js

@@ -0,0 +1,83 @@
+const registries = new WeakMap();
+/**
+ * Handles a worker's ports to a source it reads from, given by a `DiffTreeHub` (`Register(name,
+ * factory, { sources })`). The handler runs for each port: when the worker starts, and again when the source
+ * restarts. Before it runs for a new port, the cleanup it returned for the last one runs and that
+ * port is closed. A port that arrives before the handler is registered is kept for it, once the
+ * worker listens: `HostPublisher` starts listening, and so does the first `OnConnect`.
+ *
+ * The source must be one the worker was registered with (`sources`). The hub tells the worker its
+ * sources when it starts: `OnConnect` for another source throws then, or, when it was called
+ * before they arrived (while the worker's module first runs), throws as the worker's uncaught
+ * error when they do, which the main thread sees as the `Worker`'s `error` event.
+ *
+ * @example
+ * // trace worker
+ * OnConnect("engine", port => {
+ *   tree.DeleteRoute("/engine/");
+ *   return Subscribe(port, { roots: ["index"], form: "snapshot" }, update => { ... });
+ * });
+ * @param source The source worker's registered name.
+ * @param handler Subscribes over the port; may return a function that ends what it started.
+ * @param scope The worker's own channel; `self` when omitted.
+ * @returns A function that runs the current cleanup and removes the handler.
+ * @throws When the hub has told the worker its sources, and `source` isn't one.
+ */
+export function OnConnect(source, handler, scope = globalThis) {
+    const connections = Connections(scope);
+    if (connections.declared && !connections.declared.has(source))
+        throw UndeclaredError([source], connections.declared);
+    connections.cleanups.get(source)?.();
+    connections.cleanups.delete(source);
+    connections.handlers.set(source, handler);
+    const port = connections.ports.get(source);
+    port && Run(connections, source, port);
+    return () => {
+        if (connections.handlers.get(source) !== handler)
+            return;
+        connections.cleanups.get(source)?.();
+        connections.cleanups.delete(source);
+        connections.handlers.delete(source);
+    };
+}
+/**
+ * Starts keeping the `jt-connect` ports that arrive on a worker's channel, so a port that arrives
+ * before its `OnConnect` handler is registered is kept for it. `HostPublisher` calls it.
+ */
+export function ListenForConnections(scope) {
+    Connections(scope);
+}
+function Connections(scope) {
+    let connections = registries.get(scope);
+    if (!connections) {
+        const created = connections = { ports: new Map(), handlers: new Map(), cleanups: new Map() };
+        registries.set(scope, created);
+        scope.addEventListener("message", (event) => {
+            const message = event.data;
+            if (message?.type === "jt-sources") {
+                const declared = created.declared = new Set(message.sources);
+                const undeclared = Array.from(created.handlers.keys()).filter(source => !declared.has(source));
+                if (undeclared.length > 0)
+                    throw UndeclaredError(undeclared, declared);
+                return;
+            }
+            if (message?.type !== "jt-connect")
+                return;
+            const { source, port } = message;
+            created.cleanups.get(source)?.();
+            created.cleanups.delete(source);
+            created.ports.get(source)?.close();
+            created.ports.set(source, port);
+            created.handlers.has(source) && Run(created, source, port);
+        });
+    }
+    return connections;
+}
+function UndeclaredError(sources, declared) {
+    const list = declared.size > 0 ? Array.from(declared).join(", ") : "none";
+    return new Error(`OnConnect: ${sources.join(", ")} isn't a source this worker was registered with (sources: ${list}); add it to the worker's sources in DiffTreeHub.Register.`);
+}
+function Run(connections, source, port) {
+    const cleanup = connections.handlers.get(source)(port);
+    cleanup && connections.cleanups.set(source, cleanup);
+}

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

@@ -95,6 +95,13 @@ export type IRouteDefinition = {
     projections: IProjectionDefinitions;
     keyFunc?: IKeyFunc;
     routes?: IRouteDefinitions;
+    /**
+     * A follow route: it holds another tree's roots, written only by `ApplyDiff` from a subscription
+     * to that tree, under the source's own keys. It has no projections of its own, so a source's
+     * projection output (`$projection_<key>`) is held as it is, and any other write to it throws.
+     * Projections elsewhere read it as any route. See `FollowRoutes`.
+     */
+    follow?: boolean;
 };
 export type IRouteDefinitions = {
     [route: string]: IRouteDefinition;
@@ -110,4 +117,6 @@ export type IRoute = {
     childPartCounts: number[];
     keyFunc?: IKeyFunc;
     routeDefinitions?: IRouteDefinitions;
+    /** A follow route, written only by `ApplyDiff`; see `IRouteDefinition.follow` */
+    follow: boolean;
 };

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

@@ -1,3 +1,4 @@
+import { JsonDiffResult } from "../../../Utils/json";
 import { ISnapshotState } from "../../Tree/snapshot";
 type KeyFunc = {
     (value: any): string | undefined;
@@ -43,4 +44,15 @@ export declare function ApplyValueToPath(context: WriteContext, path: string, va
  * @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;
+/**
+ * Applies another tree's diff records to a route, in order, as writes: a `write` as
+ * ApplyValueToPath writes it, a `splice` as SpliceValueAtPath splices, its inserted values
+ * flattened, and a `delete` by removing the property its path ends with, a root key's from the
+ * route's state. The records' paths are parts, relative to the route, so a key holding `.` or `/`
+ * is applied as it is. Records from a tree with the same keyFunc never write inside a slot: the
+ * change to an entity comes as its own root's records.
+ * @param route A full route path, e.g. `/` or `/engine/`
+ * @throws When a record's parent doesn't exist, or a splice's path holds no array
+ */
+export declare function ApplyRecords(context: WriteContext, records: JsonDiffResult, route: string): void;
 export {};

package/Store/Diff/utils/homes.js

@@ -74,6 +74,46 @@ export function SpliceValueAtPath(context, path, start, deleteCount, items) {
     JsonApplySplices(array, [{ index, delete: actualDelete, insert }], KeepValue);
     Snapshot.Invalidate(context.snapshot, array);
 }
+/**
+ * Applies another tree's diff records to a route, in order, as writes: a `write` as
+ * ApplyValueToPath writes it, a `splice` as SpliceValueAtPath splices, its inserted values
+ * flattened, and a `delete` by removing the property its path ends with, a root key's from the
+ * route's state. The records' paths are parts, relative to the route, so a key holding `.` or `/`
+ * is applied as it is. Records from a tree with the same keyFunc never write inside a slot: the
+ * change to an entity comes as its own root's records.
+ * @param route A full route path, e.g. `/` or `/engine/`
+ * @throws When a record's parent doesn't exist, or a splice's path holds no array
+ */
+export function ApplyRecords(context, records, route) {
+    const routeRoot = RouteState(context.root, route, true);
+    const keyFunc = context.routeKeyFunc(route);
+    for (let x = 0; x < records.length; x++) {
+        const record = records[x];
+        const parts = record.path.map(String);
+        if (record.type === "write") {
+            WriteValue(context, route, parts, record.value);
+            continue;
+        }
+        if (record.type === "delete") {
+            const parent = ReadPathParts(routeRoot, parts, parts.length - 1);
+            if (JsonType(parent) !== "value" && Object.hasOwn(parent, parts[parts.length - 1]))
+                Remove(context.snapshot, parent, parts[parts.length - 1]);
+            continue;
+        }
+        const array = ReadPathParts(routeRoot, parts, parts.length);
+        if (!Array.isArray(array))
+            throw new Error(`Unable to apply a splice at ${parts.join(PROP_DELIMETER)}: no array there`);
+        const targetPath = JoinPaths(route, parts.join(PROP_DELIMETER));
+        const splices = record.splices.map(splice => ({
+            ...splice,
+            insert: splice.insert.map(item => item.type === SPLICE_ACTION.INSERT
+                ? { type: SPLICE_ACTION.INSERT, value: Flatten(context, keyFunc, route, targetPath, item.value) }
+                : item)
+        }));
+        JsonApplySplices(array, splices, 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);

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

@@ -3,11 +3,12 @@
  * path `value.item` in the route `/channel/1/`. A path without a route (`value.item`) is in the
  * root route.
  */
+import { WILDCARD } from "../../../Utils/pattern";
 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 { 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

package/Store/Diff/utils/paths.js

@@ -3,11 +3,12 @@
  * path `value.item` in the route `/channel/1/`. A path without a route (`value.item`) is in the
  * root route.
  */
+import { PatternMatches, WILDCARD } from "../../../Utils/pattern";
 export const ROOT_ROUTE = "/";
 export const PROJECTION_PREFIX = "$projection_";
 export const ROUTE_DELIMETER = "/";
 export const PROP_DELIMETER = ".";
-export const WILDCARD = "*";
+export { WILDCARD };
 export function SplitRouteAndPath(path) {
     const lastSlash = path.lastIndexOf(ROUTE_DELIMETER);
     const route = path.slice(0, lastSlash + 1);
@@ -56,7 +57,7 @@ export function RouteMatches(pattern, route) {
     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])
+        if (!PatternMatches(patternParts[x], routeParts[x]))
             return false;
     return true;
 }

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

@@ -25,3 +25,21 @@ export declare class RouteInstances {
      */
     Delete(route: string): void;
 }
+/**
+ * The follow routes for the trees a tree follows, one per source by name: `/<name>/`, holding the
+ * source's roots under their own keys, each keyed entity at its home in the route (its key is
+ * joined to the route, so it can't meet the tree's own). Give each source's keyFunc: the trees that
+ * pass data identify it the same way, or a slot holding an entity elsewhere in the source keeps its
+ * first value here. Merge them into the tree's route definitions; a tree built from an endpoint
+ * (`IObservableDiffTreeConfig.endpoint`) has its sources' added for it.
+ * @example
+ * const tree = new ObservableDiffTree({ routes: {
+ *   "/": { projections: { ... } },
+ *   ...FollowRoutes({ project: entityKey, engine: undefined }),
+ * } });
+ * // a subscription to the project's tree applies its posts at /project/
+ * subscription.Connect(port); // callback: post => tree.ApplyDiff(post.diff, "/project/")
+ */
+export declare function FollowRoutes(sources: {
+    [name: string]: IKeyFunc | undefined;
+}): IRouteDefinitions;

package/Store/Diff/utils/routes.js

@@ -1,4 +1,4 @@
-import { IsWildcardPath, JoinPaths, PathsOverlap, PROJECTION_PREFIX, ROOT_ROUTE, RouteSegments, ValidateWildcardPath } from "./paths";
+import { IsWildcardPath, JoinPaths, PathsOverlap, PROJECTION_PREFIX, ROOT_ROUTE, ROUTE_DELIMETER, 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.
@@ -124,6 +124,9 @@ function MatchRouteDefinition(definitions, segments, index) {
  * @param defaultKeyFunc The tree's keyFunc, used when the definition doesn't define one
  */
 function CreateRoute(parts, routePath, definition, defaultKeyFunc) {
+    const follow = definition.follow === true;
+    if (follow && Object.keys(definition.projections).length > 0)
+        throw new Error(`Invalid follow route ${routePath}: a follow route holds another tree's roots and has no projections of its own.`);
     const projections = [];
     for (const key in definition.projections) {
         const projectionDefinition = definition.projections[key];
@@ -156,9 +159,37 @@ function CreateRoute(parts, routePath, definition, defaultKeyFunc) {
         childRoutes: new Map(),
         childPartCounts: PartCounts(definition.routes),
         keyFunc: definition.keyFunc ?? defaultKeyFunc,
-        routeDefinitions: definition.routes
+        routeDefinitions: definition.routes,
+        follow
     };
 }
+/** A source's keyFunc when it has none: a follow route doesn't take the tree's. */
+const NoKey = () => undefined;
+/**
+ * The follow routes for the trees a tree follows, one per source by name: `/<name>/`, holding the
+ * source's roots under their own keys, each keyed entity at its home in the route (its key is
+ * joined to the route, so it can't meet the tree's own). Give each source's keyFunc: the trees that
+ * pass data identify it the same way, or a slot holding an entity elsewhere in the source keeps its
+ * first value here. Merge them into the tree's route definitions; a tree built from an endpoint
+ * (`IObservableDiffTreeConfig.endpoint`) has its sources' added for it.
+ * @example
+ * const tree = new ObservableDiffTree({ routes: {
+ *   "/": { projections: { ... } },
+ *   ...FollowRoutes({ project: entityKey, engine: undefined }),
+ * } });
+ * // a subscription to the project's tree applies its posts at /project/
+ * subscription.Connect(port); // callback: post => tree.ApplyDiff(post.diff, "/project/")
+ */
+export function FollowRoutes(sources) {
+    const definitions = {};
+    for (const name of Object.keys(sources)) {
+        if (name === "" || name.includes(ROUTE_DELIMETER) || IsParam(name))
+            throw new Error(`Invalid follow route name ${name}: one route segment, not a parameter.`);
+        // A route without a keyFunc takes the tree's: a source without one is given one that keys nothing
+        definitions[`${ROUTE_DELIMETER}${name}`] = { projections: {}, keyFunc: sources[name] ?? NoKey, follow: true };
+    }
+    return definitions;
+}
 /** Whether a projection definition is a keyed projection: it has no `reads` */
 function IsKeyedDefinition(definition) {
     return definition.reads === undefined;

package/Store/Diff/utils/state.js

@@ -1,6 +1,7 @@
 import { JsonType } from "../../../Utils/json";
 import { Snapshot } from "../../Tree/snapshot";
-import { PROP_DELIMETER, ROUTE_DELIMETER, RouteAndProperty, SplitRouteAndPath, WILDCARD } from "./paths";
+import { PROP_DELIMETER, ROUTE_DELIMETER, RouteAndProperty, SplitRouteAndPath } from "./paths";
+import { IsPattern, PatternPrefix } from "../../../Utils/pattern";
 /**
  * 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.
@@ -141,8 +142,8 @@ function InvalidateState(snapshot, value) {
 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 index = parts.findIndex(part => IsPattern(part));
+    const prefix = PatternPrefix(parts[index]);
     const parent = RouteState(root, parts.slice(0, index).join(ROUTE_DELIMETER) + ROUTE_DELIMETER);
     const children = parent?.[ROUTE_STATE] ?? {};
     const paths = {};