j-templates 9.0.1 → 10.0.0

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

@@ -1,27 +1,29 @@
 import type { JsonDiffResult } from "../../Utils/json";
+import type { ObservableDiffTree } from "./observableDiffTree";
+import type { IDiffTreeEndpoint } from "./diffTreeEndpoint.types";
+import type { IKeyFunc, IRouteDefinitions } from "./utils/diffTree.types";
 /**
- * `type` of the message a `DiffTreeWriter` posts on `Commit()`: the diff since the last commit,
- * which a `PushStore` applies.
+ * An `ObservableDiffTree`'s configuration, in one place.
+ *
+ * Config shared with the stores opened on the tree, `opaque` say, belongs in a file both sides
+ * import, spread into this and into each store's options: the tree lives in its worker, and a
+ * store on the main thread sees only what it imports.
  */
-export declare const DIFF_TREE_EVENT = "DIFF_TREE_EVENT";
-/**
- * `type` of the message a `DiffTreeWriter` posts on `Commit()` when a change in the batch
- * failed, after the `DIFF_TREE_EVENT` carrying the changes that were applied.
- */
-export declare const DIFF_TREE_ERROR = "DIFF_TREE_ERROR";
-/**
- * A message a `DiffTreeWriter` posts to its `PushStore`. Both arrive as ordinary
- * `"message"` events, so the channel can carry other traffic too; listeners tell them apart
- * by `type`.
- */
-export type IDiffPushEvent = {
-    type: typeof DIFF_TREE_EVENT;
-    data: JsonDiffResult;
-} | {
-    type: typeof DIFF_TREE_ERROR;
-    data: any;
-};
-/** A `DiffTree` method call sent to a worker connected with `ConnectWorkerToDiffTree` */
+export interface IObservableDiffTreeConfig {
+    /**
+     * The endpoint the tree is hosted as (`DiffTreeEndpoint.Host`). It gives the tree its keyFunc
+     * and a follow route per source (`FollowRoutes`). `Host` refuses a tree built from another
+     * endpoint, or from none when the endpoint follows sources.
+     */
+    endpoint?: IDiffTreeEndpoint;
+    /** How the tree's data is keyed, for a tree without an endpoint; with one, the endpoint's (giving both throws). */
+    keyFunc?: IKeyFunc;
+    /** The tree's own routes and projections. The endpoint's follow routes are added to them. */
+    routes?: IRouteDefinitions;
+    /** Root keys written whole (`DiffTree.MarkOpaque`). A store holding a key whole needs it here. */
+    opaque?: readonly string[];
+}
+/** An `ObservableDiffTree` method call in a `jt-batch` */
 export interface IDiffMethod {
     /** The method to call */
     method: "writepath" | "patchpath" | "pushpath" | "splicepath";
@@ -29,3 +31,171 @@ export interface IDiffMethod {
     arguments: Array<any>;
 }
 export type IDiffMethodBatch = IDiffMethod[];
+/**
+ * How an `ObservableDiffTree` delivers a commit to a subscription:
+ * - `"diff"`: the commit's diff records for the matching roots (`IDiffPost`), which a store applies.
+ * - `"snapshot"`: each matching root that changed, whole, as last committed (`ISnapshotUpdate`), which
+ *   another tree writes.
+ */
+export type DeliveryForm = "diff" | "snapshot";
+/** A subscription to an `ObservableDiffTree` */
+export interface ISubscribeOptions {
+    /**
+     * The root keys it receives: exact keys, and patterns ending in `*` (`task_*`). Omitted, every
+     * root. With a `keyFunc`, include the entity roots the received roots refer to.
+     */
+    roots?: readonly string[];
+    /** How it's delivered; `"diff"` when omitted */
+    form?: DeliveryForm;
+    /** A group `ObservableDiffTree.Disconnect` ends it with, e.g. the channel it came from */
+    group?: unknown;
+}
+/** A `"diff"` delivery */
+export interface IDiffPost {
+    /** The commit it comes from; on the delivery made on subscribing, the last commit's */
+    seq: number;
+    /** The commit's records for the matching roots; on subscribing, a `write` per matching committed root */
+    diff: JsonDiffResult;
+}
+/** A `"snapshot"` delivery */
+export interface ISnapshotUpdate {
+    /** The commit it comes from; on the delivery made on subscribing, the last commit's */
+    seq: number;
+    /** Each matching root that changed, as committed, or on subscribing every matching committed root: shared with the tree, so read-only */
+    roots: {
+        [key: string]: unknown;
+    };
+    /** Matching roots deleted by the commit */
+    deleted: string[];
+}
+/**
+ * A channel between threads: a `Worker`, a `MessagePort`, or a worker's own `self`. Messages are
+ * read with `addEventListener`, never `onmessage`, so other messages can share the channel.
+ */
+export interface IChannel {
+    postMessage(message: any, transfer?: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: any) => void): void;
+    removeEventListener(type: "message", listener: (event: any) => void): void;
+    /** A `MessagePort` delivers nothing to `addEventListener` until it's started */
+    start?(): void;
+    /** A `MessagePort` is closed when it's no longer served */
+    close?(): void;
+}
+/** A `jt-` message a client (a `StoreAsync`, `Subscribe`, `Once`) sends to a `HostPublisher` */
+export type IHostRequest = 
+/** Runs the calls, then projections, commits, and answers with a `jt-ack` */
+{
+    type: "jt-batch";
+    id: number;
+    calls: IDiffMethodBatch;
+}
+/** Subscribes; the first state is posted, then `jt-subscribed` */
+ | {
+    type: "jt-subscribe";
+    sub: number;
+    roots?: readonly string[];
+    form: DeliveryForm;
+} | {
+    type: "jt-unsubscribe";
+    sub: number;
+}
+/** Ends every subscription on the channel */
+ | {
+    type: "jt-disconnect";
+}
+/** See `DiffTree.MarkOpaque` */
+ | {
+    type: "jt-markopaque";
+    keys: readonly string[];
+}
+/** From a `DiffTreeHub`, on the worker's own channel: serve `port`, a lease's channel, as `id` */
+ | {
+    type: "jt-serve";
+    id: number;
+    port: MessagePort;
+}
+/** From a `DiffTreeHub`: stop serving lease `id`, ending its subscriptions */
+ | {
+    type: "jt-unserve";
+    id: number;
+};
+/**
+ * From a `DiffTreeHub` to a tree that follows `source`, on its own channel: a port to `source`'s tree,
+ * for its `OnConnect` handler. Sent when the follower starts, and again when either restarts.
+ */
+export interface IConnectMessage {
+    type: "jt-connect";
+    source: string;
+    port: MessagePort;
+}
+/**
+ * From a `DiffTreeHub` to a tree it started, on the tree's own channel, first on every start: the
+ * sources it follows (its endpoint's `sources`). `OnConnect` throws for a source that isn't listed.
+ */
+export interface ISourcesMessage {
+    type: "jt-sources";
+    sources: readonly string[];
+}
+/**
+ * A lease on a worker's tree, from `DiffTreeHub.Open`: a port to it, served by the worker's
+ * `HostPublisher`. The worker runs while it has leases. Give it to a `StoreAsync`, which owns it from
+ * then on and releases it when it's destroyed.
+ */
+export interface IWorkerLease {
+    /** The endpoint's name */
+    readonly name: string;
+    /** The endpoint the tree is registered as */
+    readonly endpoint: IDiffTreeEndpoint;
+    /** The current port to the worker; replaced when the worker restarts */
+    readonly port: MessagePort;
+    readonly released: boolean;
+    /**
+     * Calls back with the new port each time the worker restarts.
+     * @returns A function that removes the callback.
+     */
+    OnPort(callback: (port: MessagePort) => void): () => void;
+    /** Ends the lease: its subscriptions end and its port closes. The last one releases the worker. */
+    Release(): void;
+}
+/**
+ * A lease on a tree on this thread, from `DiffTreeHub.OpenLocal`: the tree itself. The tree runs while
+ * it has leases. Give it to a `StoreSync`, which owns it from then on and releases it when it's
+ * destroyed.
+ */
+export interface ILocalLease {
+    /** The endpoint's name */
+    readonly name: string;
+    /** The endpoint the tree is registered as */
+    readonly endpoint: IDiffTreeEndpoint;
+    /** The current tree; replaced when it restarts */
+    readonly tree: ObservableDiffTree;
+    readonly released: boolean;
+    /**
+     * Calls back with the new tree each time it restarts.
+     * @returns A function that removes the callback.
+     */
+    OnTree(callback: (tree: ObservableDiffTree) => void): () => void;
+    /** Ends the lease. The last one ends the tree, and the leases it holds on its sources. */
+    Release(): void;
+}
+/** A `jt-` message a `HostPublisher` posts to its clients */
+export type IHostMessage = 
+/** A delivery for subscription `sub` */
+({
+    type: "jt-post";
+    sub: number;
+} & (IDiffPost | ISnapshotUpdate))
+/** Batch `id` was applied and committed, after the commit's posts; `error` when it failed */
+ | {
+    type: "jt-ack";
+    id: number;
+    error?: unknown;
+}
+/** Subscription `sub`'s first state has been posted (none when no root matched); `error` when subscribing failed */
+ | {
+    type: "jt-subscribed";
+    sub: number;
+    error?: unknown;
+};
+/** The prefix of every message the framework sends on a channel */
+export declare const MESSAGE_PREFIX = "jt-";

package/Store/Diff/diffTree.types.js

@@ -1,10 +1,2 @@
-/**
- * `type` of the message a `DiffTreeWriter` posts on `Commit()`: the diff since the last commit,
- * which a `PushStore` applies.
- */
-export const DIFF_TREE_EVENT = "DIFF_TREE_EVENT";
-/**
- * `type` of the message a `DiffTreeWriter` posts on `Commit()` when a change in the batch
- * failed, after the `DIFF_TREE_EVENT` carrying the changes that were applied.
- */
-export const DIFF_TREE_ERROR = "DIFF_TREE_ERROR";
+/** The prefix of every message the framework sends on a channel */
+export const MESSAGE_PREFIX = "jt-";

package/Store/Diff/diffTreeEndpoint.d.ts

@@ -0,0 +1,101 @@
+import type { IChannel } from "./diffTree.types";
+import type { ObservableDiffTree } from "./observableDiffTree";
+import type { DiffTreeEndpointRemoteFunc, IDiffTreeEndpoint, IDiffTreeEndpointHostOptions, IDiffTreeEndpointOptions } from "./diffTreeEndpoint.types";
+/**
+ * DiffTree endpoints: an endpoint is a key in a `DiffTreeHub`, and one tree in the app's dependency graph.
+ * `Define` describes it once, as plain data, and everything attached to it is derived from that: the
+ * hub's registration (`DiffTreeHub.Register`), the tree built from it (its keyFunc and follow routes,
+ * `IObservableDiffTreeConfig.endpoint`), its hosting (`Host`), and the stores opened on it
+ * (`StoreAsync`, `StoreSync`).
+ *
+ * @example
+ * // ledger-endpoint.ts and totals-endpoint.ts: imported by the main thread and the workers
+ * export const ledgerEndpoint = DiffTreeEndpoint.Define("ledger");
+ * export const totalsEndpoint = DiffTreeEndpoint.Define("totals", remote => ({
+ *   ledger: remote(ledgerEndpoint, ["entries"])      // { entries: "/ledger/entries" }
+ * }));
+ *
+ * // totals-tree.ts
+ * export function newTotalsTree() {
+ *   return new ObservableDiffTree({
+ *     endpoint: totalsEndpoint,
+ *     routes: { "/": { projections: { totals: { reads: [totalsEndpoint.config.ledger.entries], projection: categoryTotals } } } }
+ *   });
+ * }
+ *
+ * // totals-worker.ts
+ * DiffTreeEndpoint.Host(totalsEndpoint, newTotalsTree(), self);
+ */
+export declare namespace DiffTreeEndpoint {
+    /**
+     * Defines an endpoint. `remote(source, roots)`, given to `build`, records a connection when it's
+     * called and returns each root's path in the following tree. It takes the source's definition,
+     * so an endpoint can only follow one defined before it, and the source's `keyFunc` comes with it.
+     * Roots are the source's tree keys as they are: `"$projection_summary"` follows a projection
+     * output, and `"o_*"` follows keyed entities.
+     *
+     * @example
+     * const totalsEndpoint = DiffTreeEndpoint.Define("totals", remote => ({
+     *   ledger: remote(ledgerEndpoint, ["entries"])     // { entries: "/ledger/entries" }
+     * }));
+     * hub.Register(totalsEndpoint, () => new Worker(new URL("./totals-worker.ts", import.meta.url), { type: "module" }));
+     * @param name The endpoint's name: its key in the `DiffTreeHub`, and the segment of its follow route
+     *   in a tree that follows it.
+     * @param build Returns the endpoint's config, the paths `remote` gave included.
+     * @param options `keyFunc`: how the data published here is keyed.
+     * @returns The endpoint's definition: plain data.
+     * @throws When `name` isn't one route segment (or is a parameter, `{id}`), or the endpoint follows itself.
+     */
+    function Define<C extends object = {}>(name: string, build?: (remote: DiffTreeEndpointRemoteFunc) => C, options?: IDiffTreeEndpointOptions): IDiffTreeEndpoint<C>;
+    /**
+     * Where a source's roots are held in a tree that follows it: `/<source>/`. A tree built from the
+     * endpoint (`IObservableDiffTreeConfig.endpoint`) has a follow route at `/<source>` for each source.
+     * @param source The source endpoint's name.
+     */
+    function FollowRoute(source: string): string;
+    /**
+     * Hosts an endpoint's tree on a channel: serves it to stores and followers (`HostPublisher`), and
+     * follows the endpoint's sources into it (`Connect`). Build the tree from the endpoint
+     * (`IObservableDiffTreeConfig.endpoint`), which gives it its keyFunc and follow routes. A
+     * worker entry calls it on its own channel; a `DiffTreeHub` calls it for a tree on the main thread,
+     * on a channel it creates. So every tree is hosted the same way, and a tree file only builds the
+     * tree.
+     *
+     * @example
+     * // totals-worker.ts
+     * DiffTreeEndpoint.Host(totalsEndpoint, newTotalsTree(), self);
+     *
+     * // a tree that acts on what it follows at the end of the turn, and commits then
+     * DiffTreeEndpoint.Host(traceEndpoint, tree.tree, self, { onFollow: () => tree.received() });
+     * @param endpoint The endpoint the tree is registered as.
+     * @param tree The tree, built from `endpoint`. One built from none (a `StoreSync`'s own, say) is
+     *   taken for an endpoint with no sources.
+     * @param scope The channel the hub posts to: the worker's own; `globalThis` when omitted.
+     * @param options `onFollow`: what runs after each source's post is applied. `onConnect`: what
+     *   runs with each new port to a source.
+     * @returns A function that stops following the sources and serving the tree.
+     * @throws When the tree was built from another endpoint, or from none while `endpoint` follows
+     *   sources (it has no follow routes).
+     */
+    function Host(endpoint: IDiffTreeEndpoint, tree: ObservableDiffTree, scope?: IChannel, options?: IDiffTreeEndpointHostOptions): () => void;
+    /**
+     * The following part of `Host`: follows each of an endpoint's sources into `tree`, over the ports
+     * the `DiffTreeHub` posts to `scope` (`OnConnect`). A `ChannelSubscription` per source applies each
+     * post at the source's follow route, then `onFollow` runs. When a source restarts, the hub gives a
+     * new port, and the subscription moves to it: the roots the new source doesn't hold are deleted.
+     * Call it alone only for a tree served some other way.
+     *
+     * @example
+     * const tree = new ObservableDiffTree({ endpoint, routes: { "/": { projections } } });
+     * HostPublisher(tree, self);
+     * DiffTreeEndpoint.Connect(endpoint, tree, self);
+     * @param endpoint The endpoint whose sources are followed.
+     * @param tree The tree, with the endpoint's follow routes (built from it).
+     * @param scope The channel the hub posts to: the worker's own; `globalThis` when omitted.
+     * @param options `onFollow`: what runs after each post is applied; by default the projections run
+     *   and the tree commits. `onConnect`: what runs with each new port to a source, after the
+     *   follow has moved to it.
+     * @returns A function that stops following every source.
+     */
+    function Connect(endpoint: IDiffTreeEndpoint, tree: ObservableDiffTree, scope?: IChannel, options?: IDiffTreeEndpointHostOptions): () => void;
+}

package/Store/Diff/diffTreeEndpoint.js

@@ -0,0 +1,173 @@
+import { ChannelSubscription } from "./channelClient";
+import { HostPublisher } from "./hostPublisher";
+import { OnConnect } from "./onConnect";
+// An endpoint on a hub, defined once, and the function that hosts its tree: `Host` serves it and
+// connects it to the endpoint's sources, the same for a worker's tree (the worker calls it) and one on the main thread (`DiffTreeHub` calls it). Imports only
+// the Diff modules, never the Store barrel (which reads `window`), so every side imports the same
+// definition: the main thread to register it and open stores on it, the tree that publishes it, and
+// the endpoints that follow it.
+/**
+ * DiffTree endpoints: an endpoint is a key in a `DiffTreeHub`, and one tree in the app's dependency graph.
+ * `Define` describes it once, as plain data, and everything attached to it is derived from that: the
+ * hub's registration (`DiffTreeHub.Register`), the tree built from it (its keyFunc and follow routes,
+ * `IObservableDiffTreeConfig.endpoint`), its hosting (`Host`), and the stores opened on it
+ * (`StoreAsync`, `StoreSync`).
+ *
+ * @example
+ * // ledger-endpoint.ts and totals-endpoint.ts: imported by the main thread and the workers
+ * export const ledgerEndpoint = DiffTreeEndpoint.Define("ledger");
+ * export const totalsEndpoint = DiffTreeEndpoint.Define("totals", remote => ({
+ *   ledger: remote(ledgerEndpoint, ["entries"])      // { entries: "/ledger/entries" }
+ * }));
+ *
+ * // totals-tree.ts
+ * export function newTotalsTree() {
+ *   return new ObservableDiffTree({
+ *     endpoint: totalsEndpoint,
+ *     routes: { "/": { projections: { totals: { reads: [totalsEndpoint.config.ledger.entries], projection: categoryTotals } } } }
+ *   });
+ * }
+ *
+ * // totals-worker.ts
+ * DiffTreeEndpoint.Host(totalsEndpoint, newTotalsTree(), self);
+ */
+export var DiffTreeEndpoint;
+(function (DiffTreeEndpoint) {
+    /**
+     * Defines an endpoint. `remote(source, roots)`, given to `build`, records a connection when it's
+     * called and returns each root's path in the following tree. It takes the source's definition,
+     * so an endpoint can only follow one defined before it, and the source's `keyFunc` comes with it.
+     * Roots are the source's tree keys as they are: `"$projection_summary"` follows a projection
+     * output, and `"o_*"` follows keyed entities.
+     *
+     * @example
+     * const totalsEndpoint = DiffTreeEndpoint.Define("totals", remote => ({
+     *   ledger: remote(ledgerEndpoint, ["entries"])     // { entries: "/ledger/entries" }
+     * }));
+     * hub.Register(totalsEndpoint, () => new Worker(new URL("./totals-worker.ts", import.meta.url), { type: "module" }));
+     * @param name The endpoint's name: its key in the `DiffTreeHub`, and the segment of its follow route
+     *   in a tree that follows it.
+     * @param build Returns the endpoint's config, the paths `remote` gave included.
+     * @param options `keyFunc`: how the data published here is keyed.
+     * @returns The endpoint's definition: plain data.
+     * @throws When `name` isn't one route segment (or is a parameter, `{id}`), or the endpoint follows itself.
+     */
+    function Define(name, build = () => ({}), options = {}) {
+        if (name === "" || name.includes("/") || (name.startsWith("{") && name.endsWith("}")))
+            throw new Error(`DiffTreeEndpoint: invalid name ${name}, one route segment, not a parameter.`);
+        const remotes = new Map();
+        const remote = (source, roots) => {
+            if (source.name === name)
+                throw new Error(`DiffTreeEndpoint: ${name} can't follow itself.`);
+            let spec = remotes.get(source.name);
+            if (!spec) {
+                spec = { source: source.name, keyFunc: source.keyFunc, roots: [] };
+                remotes.set(source.name, spec);
+            }
+            for (let x = 0; x < roots.length; x++)
+                spec.roots.includes(roots[x]) || spec.roots.push(roots[x]);
+            const route = FollowRoute(source.name);
+            return Object.fromEntries(roots.map(root => [root, route + root]));
+        };
+        const config = build(remote);
+        return {
+            name,
+            keyFunc: options.keyFunc,
+            config,
+            remotes: Array.from(remotes.values()),
+            sources: Array.from(remotes.keys())
+        };
+    }
+    DiffTreeEndpoint.Define = Define;
+    /**
+     * Where a source's roots are held in a tree that follows it: `/<source>/`. A tree built from the
+     * endpoint (`IObservableDiffTreeConfig.endpoint`) has a follow route at `/<source>` for each source.
+     * @param source The source endpoint's name.
+     */
+    function FollowRoute(source) {
+        return `/${source}/`;
+    }
+    DiffTreeEndpoint.FollowRoute = FollowRoute;
+    /**
+     * Hosts an endpoint's tree on a channel: serves it to stores and followers (`HostPublisher`), and
+     * follows the endpoint's sources into it (`Connect`). Build the tree from the endpoint
+     * (`IObservableDiffTreeConfig.endpoint`), which gives it its keyFunc and follow routes. A
+     * worker entry calls it on its own channel; a `DiffTreeHub` calls it for a tree on the main thread,
+     * on a channel it creates. So every tree is hosted the same way, and a tree file only builds the
+     * tree.
+     *
+     * @example
+     * // totals-worker.ts
+     * DiffTreeEndpoint.Host(totalsEndpoint, newTotalsTree(), self);
+     *
+     * // a tree that acts on what it follows at the end of the turn, and commits then
+     * DiffTreeEndpoint.Host(traceEndpoint, tree.tree, self, { onFollow: () => tree.received() });
+     * @param endpoint The endpoint the tree is registered as.
+     * @param tree The tree, built from `endpoint`. One built from none (a `StoreSync`'s own, say) is
+     *   taken for an endpoint with no sources.
+     * @param scope The channel the hub posts to: the worker's own; `globalThis` when omitted.
+     * @param options `onFollow`: what runs after each source's post is applied. `onConnect`: what
+     *   runs with each new port to a source.
+     * @returns A function that stops following the sources and serving the tree.
+     * @throws When the tree was built from another endpoint, or from none while `endpoint` follows
+     *   sources (it has no follow routes).
+     */
+    function Host(endpoint, tree, scope = globalThis, options = {}) {
+        if (tree.Endpoint ? tree.Endpoint !== endpoint : endpoint.sources.length > 0)
+            throw new Error(`DiffTreeEndpoint: the tree hosted as ${endpoint.name} was built from ${tree.Endpoint ? tree.Endpoint.name : "no endpoint, so it has no follow routes"}; build it with that endpoint (IObservableDiffTreeConfig.endpoint).`);
+        const host = HostPublisher(tree, scope);
+        const stop = Connect(endpoint, tree, scope, options);
+        return () => {
+            stop();
+            host.Stop();
+        };
+    }
+    DiffTreeEndpoint.Host = Host;
+    /**
+     * The following part of `Host`: follows each of an endpoint's sources into `tree`, over the ports
+     * the `DiffTreeHub` posts to `scope` (`OnConnect`). A `ChannelSubscription` per source applies each
+     * post at the source's follow route, then `onFollow` runs. When a source restarts, the hub gives a
+     * new port, and the subscription moves to it: the roots the new source doesn't hold are deleted.
+     * Call it alone only for a tree served some other way.
+     *
+     * @example
+     * const tree = new ObservableDiffTree({ endpoint, routes: { "/": { projections } } });
+     * HostPublisher(tree, self);
+     * DiffTreeEndpoint.Connect(endpoint, tree, self);
+     * @param endpoint The endpoint whose sources are followed.
+     * @param tree The tree, with the endpoint's follow routes (built from it).
+     * @param scope The channel the hub posts to: the worker's own; `globalThis` when omitted.
+     * @param options `onFollow`: what runs after each post is applied; by default the projections run
+     *   and the tree commits. `onConnect`: what runs with each new port to a source, after the
+     *   follow has moved to it.
+     * @returns A function that stops following every source.
+     */
+    function Connect(endpoint, tree, scope = globalThis, options = {}) {
+        const onFollow = options.onFollow ?? Commit;
+        const stops = endpoint.remotes.map(remote => {
+            const follow = Follower(remote, tree, onFollow);
+            return OnConnect(remote.source, port => {
+                const stopFollow = follow.Connect(port);
+                const stopMore = options.onConnect?.(tree, remote.source, port);
+                return () => {
+                    typeof stopMore === "function" && stopMore();
+                    stopFollow();
+                };
+            }, scope);
+        });
+        return () => stops.forEach(stop => stop());
+    }
+    DiffTreeEndpoint.Connect = Connect;
+    /** Applies a source's posts at its follow route, over the ports `Connect` gives it */
+    function Follower(remote, tree, onFollow) {
+        const route = FollowRoute(remote.source);
+        return new ChannelSubscription({ roots: remote.roots }, (post) => {
+            tree.ApplyDiff(post.diff, route);
+            onFollow(tree, remote.source);
+        });
+    }
+    function Commit(tree) {
+        tree.RunProjections();
+        tree.Commit();
+    }
+})(DiffTreeEndpoint || (DiffTreeEndpoint = {}));

package/Store/Diff/diffTreeEndpoint.types.d.ts

@@ -0,0 +1,71 @@
+import type { ObservableDiffTree } from "./observableDiffTree";
+import type { IKeyFunc } from "./utils/diffTree.types";
+/** A connection to another endpoint, recorded by the `remote` given to `DiffTreeEndpoint.Define` */
+export interface IDiffTreeEndpointRemote {
+    /** The source's name: its name in the `DiffTreeHub`, and its follow route's segment */
+    source: string;
+    /** The source's keyFunc, for its follow route */
+    keyFunc?: IKeyFunc;
+    /** The source's root keys followed, as the source's tree holds them; patterns included */
+    roots: string[];
+}
+/**
+ * Follows `roots` of `source`. Recorded on the endpoint being defined when it's called.
+ * @returns Each root's path in the following tree, e.g. `{ entries: "/ledger/entries" }`.
+ */
+export type DiffTreeEndpointRemoteFunc = <const K extends string>(source: IDiffTreeEndpoint<object>, roots: readonly K[]) => {
+    readonly [P in K]: string;
+};
+/** `DiffTreeEndpoint.Define` options */
+export interface IDiffTreeEndpointOptions {
+    /**
+     * How the data published here is keyed: the tree built from the endpoint takes it, the stores
+     * opened on it, and the follow routes of the endpoints that follow this one.
+     */
+    keyFunc?: IKeyFunc;
+}
+/**
+ * An endpoint on a `DiffTreeHub`, defined: its name, how its data is keyed and the endpoints it
+ * follows. Plain data that drives the creation of what's attached to it: the hub's registration, the
+ * tree that publishes it (`IObservableDiffTreeConfig.endpoint`), the stores opened on it. What the
+ * tree and its stores otherwise share, `opaque` say, is theirs: a shared file each imports.
+ */
+export interface IDiffTreeEndpoint<C extends object = object> {
+    readonly name: string;
+    readonly keyFunc?: IKeyFunc;
+    /** What `Define`'s callback returned: the paths `remote` gave, and anything else kept there */
+    readonly config: C;
+    /** One per source, in the order first followed */
+    readonly remotes: readonly IDiffTreeEndpointRemote[];
+    /** The sources' names, in the same order */
+    readonly sources: readonly string[];
+}
+/**
+ * Runs after a source's post is applied at its follow route in the following tree.
+ * @param tree The following tree.
+ * @param source The name of the source the post came from.
+ */
+export type DiffTreeEndpointFollowFunc = (tree: ObservableDiffTree, source: string) => void;
+/**
+ * Runs with each new port to a source, after the follow has moved to it: when the tree starts,
+ * and again when the source restarts.
+ * @param tree The following tree.
+ * @param source The source's name.
+ * @param port The port to the source, for reads besides the follow (a one-off `Once`, say).
+ * @returns Optionally, what ends what it started; it runs before the next port's call.
+ */
+export type DiffTreeEndpointConnectFunc = (tree: ObservableDiffTree, source: string, port: MessagePort) => (() => void) | void;
+/** `DiffTreeEndpoint.Host` and `DiffTreeEndpoint.Connect` options */
+export interface IDiffTreeEndpointHostOptions {
+    /**
+     * Runs after each post from a source is applied. Default: run the projections and commit, so the
+     * tree's own subscribers get the change at once. A tree that acts later (at the end of the turn,
+     * say) does its own committing here instead.
+     */
+    onFollow?: DiffTreeEndpointFollowFunc;
+    /**
+     * Runs with each new port to a source, after the follow has moved to it. For a tree that reads
+     * from a source besides what it follows; the port stays the follow's, so don't close it.
+     */
+    onConnect?: DiffTreeEndpointConnectFunc;
+}

package/Store/Diff/diffTreeEndpoint.types.js

@@ -0,0 +1 @@
+export {};