j-templates 9.0.0 → 10.0.0

package/Store/Diff/index.js

@@ -1,3 +1,6 @@
 export * from "./diffTree.types";
 export * from "./utils/diffTree.types";
 export { PROJECTION_PREFIX } from "./utils/paths";
+export { FollowRoutes } from "./utils/routes";
+export * from "./diffTreeEndpoint.types";
+export { DiffTreeEndpoint } from "./diffTreeEndpoint";

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,199 @@
+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(key => key.endsWith("*")))
+                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/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/Store/store.d.ts

@@ -1,22 +1,46 @@
 import { JsonDiffResult } from "../../Utils/json";
+import type { IKeyFunc } from "../Diff/utils/diffTree.types";
+/** Options shared by `StoreSync` and `StoreAsync` */
+export interface IStoreOptions {
+    /**
+     * Gives a value its key, so the store resolves an object written with an id to its own root. For a
+     * store whose tree has none to give: a `StoreAsync` over a plain channel (pass the worker tree's
+     * key logic), or a `StoreSync` with a tree of its own. A lease's keyFunc is the endpoint's, and a
+     * tree's its own; giving one there too throws.
+     */
+    keyFunc?: IKeyFunc;
+    /**
+     * Root keys the store holds whole, as an `Opaque`: a written root or a projection's
+     * `$projection_<key>`. `Get` returns such a root's raw value, never proxied, the same reference
+     * until the root is written again, and only that write updates its readers. Treat the value as
+     * read-only: a change made inside it notifies no one. An opaque root can't be read through a
+     * key (`keyFunc`). Its tree must write each one whole instead of diffing inside it
+     * (`DiffTree.MarkOpaque`): a store with a tree of its own marks it; for a hub's tree, give the
+     * tree the same keys (`IObservableDiffTreeConfig.opaque`) from a file both import. Write the raw
+     * value: the store boxes it, and an `Opaque` written to a store isn't opened.
+     */
+    opaque?: readonly string[];
+}
 /**
  * Base class for reading observable data: holds root objects as ObservableNode instances
- * and applies diff results to them. Subclasses decide where the diffs come from: `Store`
- * adds the write methods, and `PushStore` takes them from a `DiffTreeWriter`.
+ * and applies diff results to them. Subclasses decide where the diffs come from: `StoreSync`
+ * and `StoreAsync` apply what an `ObservableDiffTree` delivers to them.
  *
  * @see Store
- * @see PushStore
  */
 export declare abstract class ReadStore {
     protected keyFunc?: (value: any) => string | undefined;
     private rootMap;
     private createNode;
+    /** Root keys held whole, see `IStoreOptions.opaque` */
+    protected readonly opaque: ReadonlySet<string | number>;
     /**
      * Creates an instance of ReadStore.
      * @param keyFunc Optional function to generate a key for a given data value.
      * When provided, enables alias functionality where values can reference other root objects.
+     * @param opaque Root keys held whole, see `IStoreOptions.opaque`.
      */
-    constructor(keyFunc?: (value: any) => string | undefined);
+    constructor(keyFunc?: (value: any) => string | undefined, opaque?: readonly string[]);
     /**
      * Retrieves a value from the store by id.
      * @template O - The type of the value to retrieve
@@ -45,6 +69,14 @@ export declare abstract class ReadStore {
      * @protected
      */
     protected UpdateRootMap(results: JsonDiffResult): void;
+    /**
+     * Applies whole-root writes by diffing each one into the root the store already holds, so
+     * readers of an unchanged part aren't notified and keep its objects. Anything else, an opaque
+     * root, or a root the store doesn't hold, is applied as it is.
+     * @param results - Diff results, e.g. a tree's first state after reconnecting
+     * @protected
+     */
+    protected UpdateRootMapInPlace(results: JsonDiffResult): void;
     /**
      * Updates a specific root object with diff results.
      * Creates the root object if it doesn't exist.