j-templates 9.0.1 → 10.0.0

package/Store/Diff/diffTreeHub.d.ts

@@ -0,0 +1,139 @@
+import { ILocalLease, IWorkerLease } from "./diffTree.types";
+import { ObservableDiffTree } from "./observableDiffTree";
+import type { IDiffTreeEndpoint } from "./diffTreeEndpoint.types";
+/** What a `DiffTreeHub` needs of a worker: a `Worker`, or anything shaped like one */
+export interface IDiffTreeWorker {
+    postMessage(message: any, transfer: Transferable[]): void;
+    terminate(): void;
+}
+/**
+ * Creates an endpoint's tree, on its first start and each restart: a worker hosting the tree
+ * (`DiffTreeEndpoint.Host` in its entry), or the `ObservableDiffTree` itself, to run on this thread. What it
+ * returns decides the key's kind, and a key's factory always returns the same kind.
+ */
+export type TreeFactory = () => IDiffTreeWorker | ObservableDiffTree;
+/** Where a key's tree runs: in a worker (`"worker"`), or on this thread (`"local"`) */
+export type TreeKind = "worker" | "local";
+/** `DiffTreeHub.Register` options */
+export interface IRegisterOptions {
+    /**
+     * Milliseconds to keep the tree after its last lease ends; a lease opened meanwhile keeps the
+     * same tree. Omitted, the tree is released at once.
+     */
+    releaseDebounce?: number;
+}
+/**
+ * Owns the app's trees by endpoint: one key is one tree in the app's dependency graph, running in a
+ * worker or on this thread. The hub creates each one from its factory when it's first needed, hands
+ * out leases on it, connects each tree to the ones it follows, re-creates one on request, and ends
+ * each one when its last lease ends. It never carries data: posts go directly between each port's
+ * two ends.
+ *
+ * - **`Register(endpoint, factory)`** records how to create a tree, and takes the trees it follows
+ *   from the endpoint's definition (`DiffTreeEndpoint.Define`), each registered before it. It creates
+ *   nothing.
+ * - **The factory returns a worker or a tree.** A worker hosts its own tree (`DiffTreeEndpoint.Host` in its
+ *   entry). A returned `ObservableDiffTree` runs on this thread: the hub hosts it with the same call,
+ *   on a channel of its own. Either way, the hub manages it the same way. What the first start
+ *   returns fixes the key's kind.
+ * - **`Open`** leases a worker's tree, as a port, for a `StoreAsync`. **`OpenLocal`** leases a tree on
+ *   this thread, as the tree, for a `StoreSync`. The leases are different types, so a store given the
+ *   wrong one doesn't compile, and each throws for a key of the other kind: that's configuration to
+ *   fix, not a state to recover from. The first lease starts the tree; a store owns its lease and
+ *   releases it when it's destroyed. Any number of stores can be opened on one tree.
+ * - **A tree is released when its last lease ends**, at once or after its `releaseDebounce`. A tree
+ *   that must outlive every view is held by a store the app keeps.
+ * - **A tree that follows others** holds a lease on each while it runs, and its `OnConnect` handlers
+ *   (`DiffTreeEndpoint.Connect`) get a port to each source's tree, again whenever either restarts.
+ * - **`Restart`** creates the tree again from its factory. The tree is the source of truth: every
+ *   store on it starts over with the new tree, as when it first subscribed, and nothing a store
+ *   wrote is written back. State that must outlive a restart belongs in a tree of its own that the
+ *   restarted one follows.
+ *
+ * @example
+ * const hub = new DiffTreeHub();
+ * hub.Register(ledgerEndpoint, () => new Worker(new URL("./ledger-worker.ts", import.meta.url), { type: "module" }));
+ * hub.Register(totalsEndpoint, () => new Worker(new URL("./totals-worker.ts", import.meta.url), { type: "module" }), { releaseDebounce: 5_000 });
+ * hub.Register(budgetEndpoint, newBudgetTree);   // follows the ledger, on this thread
+ *
+ * const totals = new StoreAsync(hub.Open("totals"));       // starts totals, and the ledger for it
+ * const budget = new StoreSync(hub.OpenLocal("budget"));
+ * // teardown: each store releases its lease
+ * totals.Destroy();
+ * budget.Destroy();
+ */
+export declare class DiffTreeHub {
+    private entries;
+    /**
+     * Records how to create an endpoint's tree. Creates nothing: the first lease does.
+     * @param endpoint The endpoint's definition: its name, and the endpoints it follows (`sources`),
+     *   each registered first.
+     * @param factory Returns a worker hosting the tree, or the tree itself, to run on this thread; runs
+     *   on every start.
+     * @param options `releaseDebounce`: see `IRegisterOptions`.
+     * @throws When the name is already registered, or a source isn't registered yet.
+     */
+    Register(endpoint: IDiffTreeEndpoint, factory: TreeFactory, options?: IRegisterOptions): void;
+    /**
+     * Opens a lease on a worker's tree, starting the worker when it isn't running. Give it to a
+     * `StoreAsync`.
+     * @throws When the name isn't registered, or its factory returns a tree to run on this thread.
+     */
+    Open(name: string): IWorkerLease;
+    /**
+     * Opens a lease on a tree on this thread, creating the tree when it isn't running. Give it to a
+     * `StoreSync`.
+     * @throws When the name isn't registered, or its factory returns a worker.
+     */
+    OpenLocal(name: string): ILocalLease;
+    /**
+     * Ends a running tree and creates a new one from its factory, then re-issues every connection to
+     * it: each worker lease gets a new port (`IWorkerLease.OnPort`), each tree lease the new tree
+     * (`ILocalLease.OnTree`), each tree following it a new `jt-connect`, and the new tree new ports to
+     * its own sources. The stores on it start over with the new tree. Does nothing when the tree isn't
+     * running.
+     * @throws When the name isn't registered, or the factory returns the other kind than it did before,
+     *   or neither kind. Nothing is recovered: the tree stays ended.
+     */
+    Restart(name: string): void;
+    /**
+     * Ends the tree if it runs, ends every lease on it, releases its sources, and forgets it. `Open`
+     * on the name throws after.
+     * @throws When a registered endpoint follows it: unregister that one first.
+     */
+    Unregister(name: string): void;
+    /**
+     * Unregisters every name, the last registered first, so each tree goes before its sources: every
+     * tree is ended and every lease with it.
+     */
+    Destroy(): void;
+    /** Whether a registered tree is running */
+    IsRunning(name: string): boolean;
+    /** Where a key's tree runs, known from its first start; `undefined` before it */
+    KindOf(name: string): TreeKind | undefined;
+    private Entry;
+    /**
+     * Keeps a tree running for a new lease, starting it when it isn't. With a `kind`, a tree of the
+     * other kind throws; one started for this check ends first.
+     */
+    private Run;
+    /** Throws when the key is known to be of the other kind */
+    private Expect;
+    private Start;
+    /** Opens the leases a tree holds on its sources, each one a port the hub gives it */
+    private Hold;
+    /**
+     * Runs the factory, checks what it returned, and wires it up to match: a worker as it is, a tree
+     * hosted on a channel of its own on this thread. Then tells it its sources, before anything else
+     * the hub sends.
+     */
+    private Create;
+    /** Serves a new channel for the lease on its tree, and gives the other end to its holder */
+    private Issue;
+    /** Ends a lease, and releases its tree when it was the last */
+    private Release;
+    /** Ends a lease without releasing its tree */
+    private End;
+    /** Ends a tree and releases the leases it holds */
+    private Stop;
+}

package/Store/Diff/diffTreeHub.js

@@ -0,0 +1,346 @@
+import { ObservableDiffTree } from "./observableDiffTree";
+import { DiffTreeEndpoint } from "./diffTreeEndpoint";
+let nextServeId = 1;
+class Lease {
+    constructor(entry, release) {
+        this.entry = entry;
+        this.release = release;
+        this.released = false;
+    }
+    get name() {
+        return this.entry.endpoint.name;
+    }
+    get endpoint() {
+        return this.entry.endpoint;
+    }
+    Release() {
+        this.release(this);
+    }
+}
+/** A port to a tree, served by its `HostPublisher`: a store's lease on a worker, or a follower's on any tree */
+class PortLease extends Lease {
+    /** @param holder The tree following this one over the port, for a lease the hub holds */
+    constructor(entry, holder, release) {
+        super(entry, release);
+        this.holder = holder;
+        this.serveId = 0;
+        this.callbacks = [];
+    }
+    OnPort(callback) {
+        return Add(this.callbacks, callback);
+    }
+}
+/** The tree itself, for a store on its thread */
+class TreeLease extends Lease {
+    constructor() {
+        super(...arguments);
+        this.callbacks = [];
+    }
+    get tree() {
+        return this.entry.tree;
+    }
+    OnTree(callback) {
+        return Add(this.callbacks, callback);
+    }
+}
+/**
+ * Owns the app's trees by endpoint: one key is one tree in the app's dependency graph, running in a
+ * worker or on this thread. The hub creates each one from its factory when it's first needed, hands
+ * out leases on it, connects each tree to the ones it follows, re-creates one on request, and ends
+ * each one when its last lease ends. It never carries data: posts go directly between each port's
+ * two ends.
+ *
+ * - **`Register(endpoint, factory)`** records how to create a tree, and takes the trees it follows
+ *   from the endpoint's definition (`DiffTreeEndpoint.Define`), each registered before it. It creates
+ *   nothing.
+ * - **The factory returns a worker or a tree.** A worker hosts its own tree (`DiffTreeEndpoint.Host` in its
+ *   entry). A returned `ObservableDiffTree` runs on this thread: the hub hosts it with the same call,
+ *   on a channel of its own. Either way, the hub manages it the same way. What the first start
+ *   returns fixes the key's kind.
+ * - **`Open`** leases a worker's tree, as a port, for a `StoreAsync`. **`OpenLocal`** leases a tree on
+ *   this thread, as the tree, for a `StoreSync`. The leases are different types, so a store given the
+ *   wrong one doesn't compile, and each throws for a key of the other kind: that's configuration to
+ *   fix, not a state to recover from. The first lease starts the tree; a store owns its lease and
+ *   releases it when it's destroyed. Any number of stores can be opened on one tree.
+ * - **A tree is released when its last lease ends**, at once or after its `releaseDebounce`. A tree
+ *   that must outlive every view is held by a store the app keeps.
+ * - **A tree that follows others** holds a lease on each while it runs, and its `OnConnect` handlers
+ *   (`DiffTreeEndpoint.Connect`) get a port to each source's tree, again whenever either restarts.
+ * - **`Restart`** creates the tree again from its factory. The tree is the source of truth: every
+ *   store on it starts over with the new tree, as when it first subscribed, and nothing a store
+ *   wrote is written back. State that must outlive a restart belongs in a tree of its own that the
+ *   restarted one follows.
+ *
+ * @example
+ * const hub = new DiffTreeHub();
+ * hub.Register(ledgerEndpoint, () => new Worker(new URL("./ledger-worker.ts", import.meta.url), { type: "module" }));
+ * hub.Register(totalsEndpoint, () => new Worker(new URL("./totals-worker.ts", import.meta.url), { type: "module" }), { releaseDebounce: 5_000 });
+ * hub.Register(budgetEndpoint, newBudgetTree);   // follows the ledger, on this thread
+ *
+ * const totals = new StoreAsync(hub.Open("totals"));       // starts totals, and the ledger for it
+ * const budget = new StoreSync(hub.OpenLocal("budget"));
+ * // teardown: each store releases its lease
+ * totals.Destroy();
+ * budget.Destroy();
+ */
+export class DiffTreeHub {
+    constructor() {
+        this.entries = new Map();
+    }
+    /**
+     * Records how to create an endpoint's tree. Creates nothing: the first lease does.
+     * @param endpoint The endpoint's definition: its name, and the endpoints it follows (`sources`),
+     *   each registered first.
+     * @param factory Returns a worker hosting the tree, or the tree itself, to run on this thread; runs
+     *   on every start.
+     * @param options `releaseDebounce`: see `IRegisterOptions`.
+     * @throws When the name is already registered, or a source isn't registered yet.
+     */
+    Register(endpoint, factory, options = {}) {
+        const name = endpoint.name;
+        if (this.entries.has(name))
+            throw new Error(`DiffTreeHub: ${name} is already registered.`);
+        for (const source of endpoint.sources)
+            if (!this.entries.has(source))
+                throw new Error(`DiffTreeHub: ${name} follows ${source}, which isn't registered; register an endpoint's sources before it.`);
+        this.entries.set(name, { endpoint, factory, options, leases: new Set(), held: new Map() });
+    }
+    /**
+     * Opens a lease on a worker's tree, starting the worker when it isn't running. Give it to a
+     * `StoreAsync`.
+     * @throws When the name isn't registered, or its factory returns a tree to run on this thread.
+     */
+    Open(name) {
+        const entry = this.Entry(name);
+        this.Run(entry, "worker");
+        const lease = new PortLease(entry, undefined, lease => this.Release(lease));
+        entry.leases.add(lease);
+        this.Issue(lease);
+        return lease;
+    }
+    /**
+     * Opens a lease on a tree on this thread, creating the tree when it isn't running. Give it to a
+     * `StoreSync`.
+     * @throws When the name isn't registered, or its factory returns a worker.
+     */
+    OpenLocal(name) {
+        const entry = this.Entry(name);
+        this.Run(entry, "local");
+        const lease = new TreeLease(entry, lease => this.Release(lease));
+        entry.leases.add(lease);
+        return lease;
+    }
+    /**
+     * Ends a running tree and creates a new one from its factory, then re-issues every connection to
+     * it: each worker lease gets a new port (`IWorkerLease.OnPort`), each tree lease the new tree
+     * (`ILocalLease.OnTree`), each tree following it a new `jt-connect`, and the new tree new ports to
+     * its own sources. The stores on it start over with the new tree. Does nothing when the tree isn't
+     * running.
+     * @throws When the name isn't registered, or the factory returns the other kind than it did before,
+     *   or neither kind. Nothing is recovered: the tree stays ended.
+     */
+    Restart(name) {
+        const entry = this.Entry(name);
+        if (!entry.worker)
+            return;
+        entry.worker.terminate();
+        entry.worker = undefined;
+        entry.tree = undefined;
+        this.Create(entry);
+        // New leases on the sources first, so releasing the old ones doesn't release a source
+        const old = Array.from(entry.held.values());
+        entry.held = new Map();
+        this.Hold(entry);
+        old.forEach(lease => this.Release(lease));
+        for (const lease of entry.leases)
+            lease instanceof TreeLease ? lease.callbacks.slice().forEach(callback => callback(entry.tree)) : this.Issue(lease);
+    }
+    /**
+     * Ends the tree if it runs, ends every lease on it, releases its sources, and forgets it. `Open`
+     * on the name throws after.
+     * @throws When a registered endpoint follows it: unregister that one first.
+     */
+    Unregister(name) {
+        const entry = this.entries.get(name);
+        if (!entry)
+            return;
+        for (const other of this.entries.values())
+            if (other.endpoint.sources.includes(name))
+                throw new Error(`DiffTreeHub: ${other.endpoint.name} follows ${name}; unregister it first.`);
+        this.entries.delete(name);
+        for (const lease of Array.from(entry.leases))
+            this.End(lease);
+        this.Stop(entry);
+    }
+    /**
+     * Unregisters every name, the last registered first, so each tree goes before its sources: every
+     * tree is ended and every lease with it.
+     */
+    Destroy() {
+        for (const name of Array.from(this.entries.keys()).reverse())
+            this.Unregister(name);
+    }
+    /** Whether a registered tree is running */
+    IsRunning(name) {
+        return !!this.entries.get(name)?.worker;
+    }
+    /** Where a key's tree runs, known from its first start; `undefined` before it */
+    KindOf(name) {
+        return this.entries.get(name)?.kind;
+    }
+    Entry(name) {
+        const entry = this.entries.get(name);
+        if (!entry)
+            throw new Error(`DiffTreeHub: ${name} isn't registered.`);
+        return entry;
+    }
+    /**
+     * Keeps a tree running for a new lease, starting it when it isn't. With a `kind`, a tree of the
+     * other kind throws; one started for this check ends first.
+     */
+    Run(entry, kind) {
+        kind && this.Expect(entry, kind);
+        clearTimeout(entry.timer);
+        entry.timer = undefined;
+        if (entry.worker)
+            return;
+        this.Start(entry);
+        if (kind && entry.kind !== kind) {
+            entry.leases.size === 0 && this.Stop(entry);
+            this.Expect(entry, kind);
+        }
+    }
+    /** Throws when the key is known to be of the other kind */
+    Expect(entry, kind) {
+        if (entry.kind && entry.kind !== kind)
+            throw new Error(`DiffTreeHub: ${entry.endpoint.name} is ${Describe(entry.kind)}; open it with ${entry.kind === "local" ? "OpenLocal" : "Open"}.`);
+    }
+    Start(entry) {
+        this.Create(entry);
+        this.Hold(entry);
+    }
+    /** Opens the leases a tree holds on its sources, each one a port the hub gives it */
+    Hold(entry) {
+        for (const source of entry.endpoint.sources) {
+            const sourceEntry = this.Entry(source);
+            this.Run(sourceEntry);
+            const lease = new PortLease(sourceEntry, entry, lease => this.Release(lease));
+            sourceEntry.leases.add(lease);
+            entry.held.set(source, lease);
+            this.Issue(lease);
+        }
+    }
+    /**
+     * Runs the factory, checks what it returned, and wires it up to match: a worker as it is, a tree
+     * hosted on a channel of its own on this thread. Then tells it its sources, before anything else
+     * the hub sends.
+     */
+    Create(entry) {
+        const name = entry.endpoint.name;
+        const result = entry.factory();
+        const kind = result instanceof ObservableDiffTree ? "local" : IsWorker(result) ? "worker" : undefined;
+        if (!kind)
+            throw new Error(`DiffTreeHub: ${name}'s factory returned neither a worker nor an ObservableDiffTree (an ObservableDiffTree from another copy of j-templates isn't one).`);
+        if (entry.kind && entry.kind !== kind) {
+            kind === "worker" && result.terminate();
+            throw new Error(`DiffTreeHub: ${name}'s factory returned ${Describe(kind)} after ${Describe(entry.kind)}; a key's factory always returns one kind.`);
+        }
+        entry.kind = kind;
+        if (kind === "worker")
+            entry.worker = result;
+        else {
+            entry.tree = result;
+            entry.worker = HostLocal(entry.endpoint, entry.tree);
+        }
+        const sources = { type: "jt-sources", sources: entry.endpoint.sources };
+        entry.worker.postMessage(sources, []);
+    }
+    /** Serves a new channel for the lease on its tree, and gives the other end to its holder */
+    Issue(lease) {
+        const { port1, port2 } = new MessageChannel();
+        lease.serveId = nextServeId++;
+        const serve = { type: "jt-serve", id: lease.serveId, port: port2 };
+        lease.entry.worker.postMessage(serve, [port2]);
+        if (lease.holder) {
+            const connect = { type: "jt-connect", source: lease.name, port: port1 };
+            lease.holder.worker.postMessage(connect, [port1]);
+            return;
+        }
+        const old = lease.port;
+        lease.port = port1;
+        if (old) {
+            old.close();
+            for (const callback of lease.callbacks.slice())
+                callback(port1);
+        }
+    }
+    /** Ends a lease, and releases its tree when it was the last */
+    Release(lease) {
+        if (lease.released)
+            return;
+        this.End(lease);
+        const entry = lease.entry;
+        if (entry.leases.size > 0 || !entry.worker || !this.entries.has(entry.endpoint.name))
+            return;
+        const debounce = entry.options.releaseDebounce;
+        if (debounce !== undefined && debounce > 0)
+            entry.timer = setTimeout(() => this.Stop(entry), debounce);
+        else
+            this.Stop(entry);
+    }
+    /** Ends a lease without releasing its tree */
+    End(lease) {
+        if (lease.released)
+            return;
+        lease.released = true;
+        lease.entry.leases.delete(lease);
+        lease.callbacks = [];
+        if (lease instanceof PortLease) {
+            const unserve = { type: "jt-unserve", id: lease.serveId };
+            lease.entry.worker?.postMessage(unserve, []);
+            lease.port?.close();
+        }
+    }
+    /** Ends a tree and releases the leases it holds */
+    Stop(entry) {
+        clearTimeout(entry.timer);
+        entry.timer = undefined;
+        entry.worker?.terminate();
+        entry.worker = undefined;
+        entry.tree = undefined;
+        const held = Array.from(entry.held.values());
+        entry.held.clear();
+        held.forEach(lease => this.Release(lease));
+    }
+}
+/**
+ * Hosts a tree on this thread as a worker hosts its own: `DiffTreeEndpoint.Host` on one end of a
+ * `MessageChannel`, with the other end as the hub's "worker". Terminating it stops the host and
+ * closes both ends.
+ */
+function HostLocal(endpoint, tree) {
+    const { port1, port2 } = new MessageChannel();
+    const stop = DiffTreeEndpoint.Host(endpoint, tree, port2);
+    port2.start();
+    return {
+        postMessage: (message, transfer) => port1.postMessage(message, transfer),
+        terminate: () => {
+            stop();
+            port1.close();
+            port2.close();
+        }
+    };
+}
+function IsWorker(value) {
+    return typeof value?.postMessage === "function" && typeof value?.terminate === "function";
+}
+function Describe(kind) {
+    return kind === "local" ? "a tree on this thread" : "a worker";
+}
+function Add(callbacks, callback) {
+    callbacks.push(callback);
+    return () => {
+        const index = callbacks.indexOf(callback);
+        index >= 0 && callbacks.splice(index, 1);
+    };
+}

package/Store/Diff/hostPublisher.d.ts

@@ -0,0 +1,39 @@
+import { ObservableDiffTree } from "./observableDiffTree";
+import { IChannel } from "./diffTree.types";
+/** A `HostPublisher`: the channels it serves */
+export interface IHost {
+    /**
+     * Serves another channel, such as a `MessagePort` the worker was given.
+     * @returns A function that stops serving it, ends its subscriptions, and closes it.
+     */
+    Serve(channel: IChannel): () => void;
+    /** Stops serving every channel and ends their subscriptions */
+    Stop(): void;
+}
+/**
+ * Serves an `ObservableDiffTree` over channels: the worker's own (`self`) and any `MessagePort` given
+ * to `Serve`. On each channel it answers the framework's `jt-` messages and leaves every other
+ * message to the app's own listeners; it never takes `onmessage`.
+ *
+ * - `jt-batch`: runs the calls, then projections, commits, and posts `jt-ack` with the batch's id
+ *   after the commit's posts. When a call throws, the calls after it and the projections are
+ *   skipped, what the batch applied is still committed, and the ack carries the error: only that
+ *   batch fails.
+ * - `jt-subscribe` / `jt-unsubscribe`: a subscription for the channel. Its first state and every
+ *   commit are posted as `jt-post`, then `jt-subscribed` once the first state is out.
+ * - `jt-disconnect`: ends every subscription on the channel.
+ * - `jt-markopaque`: see `DiffTree.MarkOpaque`.
+ * - `jt-serve` / `jt-unserve`: from a `DiffTreeHub`, a lease's port to serve, or to stop serving.
+ *
+ * The worker's own work commits on the same publisher, and its commits reach every subscriber
+ * without a round trip.
+ *
+ * @example
+ * // worker entry
+ * const tree = new ObservableDiffTree({ keyFunc, routes });
+ * HostPublisher(tree, self);
+ * tree.WritePath("results", compute());
+ * tree.RunProjections();
+ * tree.Commit();
+ */
+export declare function HostPublisher(publisher: ObservableDiffTree, scope: IChannel): IHost;

package/Store/Diff/hostPublisher.js

@@ -0,0 +1,151 @@
+import { MESSAGE_PREFIX } from "./diffTree.types";
+import { ListenForConnections } from "./onConnect";
+/**
+ * Serves an `ObservableDiffTree` over channels: the worker's own (`self`) and any `MessagePort` given
+ * to `Serve`. On each channel it answers the framework's `jt-` messages and leaves every other
+ * message to the app's own listeners; it never takes `onmessage`.
+ *
+ * - `jt-batch`: runs the calls, then projections, commits, and posts `jt-ack` with the batch's id
+ *   after the commit's posts. When a call throws, the calls after it and the projections are
+ *   skipped, what the batch applied is still committed, and the ack carries the error: only that
+ *   batch fails.
+ * - `jt-subscribe` / `jt-unsubscribe`: a subscription for the channel. Its first state and every
+ *   commit are posted as `jt-post`, then `jt-subscribed` once the first state is out.
+ * - `jt-disconnect`: ends every subscription on the channel.
+ * - `jt-markopaque`: see `DiffTree.MarkOpaque`.
+ * - `jt-serve` / `jt-unserve`: from a `DiffTreeHub`, a lease's port to serve, or to stop serving.
+ *
+ * The worker's own work commits on the same publisher, and its commits reach every subscriber
+ * without a round trip.
+ *
+ * @example
+ * // worker entry
+ * const tree = new ObservableDiffTree({ keyFunc, routes });
+ * HostPublisher(tree, self);
+ * tree.WritePath("results", compute());
+ * tree.RunProjections();
+ * tree.Commit();
+ */
+export function HostPublisher(publisher, scope) {
+    const served = new Map();
+    /** Lease ports a `DiffTreeHub` asked this host to serve, by id */
+    const leases = new Map();
+    function Serve(channel) {
+        const existing = served.get(channel);
+        if (existing)
+            return existing;
+        const subscriptions = new Map();
+        const listener = (event) => {
+            const message = event.data;
+            if (!IsRequest(message))
+                return;
+            switch (message.type) {
+                case "jt-batch": {
+                    const error = RunBatch(publisher, message.calls);
+                    Post(channel, error === undefined ? { type: "jt-ack", id: message.id } : { type: "jt-ack", id: message.id, error });
+                    break;
+                }
+                case "jt-subscribe": {
+                    const sub = message.sub;
+                    let error;
+                    try {
+                        subscriptions.set(sub, publisher.Subscribe({ roots: message.roots, form: message.form, group: channel }, (delivery) => Post(channel, { type: "jt-post", sub, ...delivery })));
+                    }
+                    catch (err) {
+                        error = err;
+                    }
+                    Post(channel, error === undefined ? { type: "jt-subscribed", sub } : { type: "jt-subscribed", sub, error });
+                    break;
+                }
+                case "jt-unsubscribe":
+                    subscriptions.get(message.sub)?.();
+                    subscriptions.delete(message.sub);
+                    break;
+                case "jt-disconnect":
+                    publisher.Disconnect(channel);
+                    subscriptions.clear();
+                    break;
+                case "jt-markopaque":
+                    publisher.MarkOpaque(message.keys);
+                    break;
+                case "jt-serve":
+                    leases.set(message.id, Serve(message.port));
+                    break;
+                case "jt-unserve":
+                    leases.get(message.id)?.();
+                    leases.delete(message.id);
+                    break;
+            }
+        };
+        channel.addEventListener("message", listener);
+        channel.start?.();
+        const stop = () => {
+            if (served.get(channel) !== stop)
+                return;
+            served.delete(channel);
+            channel.removeEventListener("message", listener);
+            publisher.Disconnect(channel);
+            subscriptions.clear();
+            channel !== scope && channel.close?.();
+        };
+        served.set(channel, stop);
+        return stop;
+    }
+    Serve(scope);
+    // A hub's jt-connect ports can arrive before the worker's OnConnect handlers are registered
+    ListenForConnections(scope);
+    return {
+        Serve,
+        Stop() {
+            for (const stop of Array.from(served.values()))
+                stop();
+        },
+    };
+}
+/**
+ * Applies a batch, runs projections and commits. A failed call skips the rest and the
+ * projections; what was applied is committed either way.
+ * @returns The batch's error, or undefined
+ */
+function RunBatch(publisher, calls) {
+    let error;
+    try {
+        for (let x = 0; x < calls.length; x++)
+            RunMethod(publisher, calls[x]);
+        publisher.RunProjections();
+    }
+    catch (err) {
+        error = err;
+    }
+    try {
+        publisher.Commit();
+    }
+    catch (err) {
+        error ??= err;
+    }
+    return error;
+}
+function RunMethod(publisher, call) {
+    const args = call.arguments;
+    switch (call.method) {
+        case "writepath": return publisher.WritePath(args[0], args[1]);
+        case "splicepath": return publisher.SplicePath(args[0], args[1], args[2], args[3]);
+        case "pushpath": return publisher.PushPath(args[0], args[1]);
+        case "patchpath": return publisher.PatchPath(args[0], args[1]);
+        default: throw new Error(`Unknown ObservableDiffTree method: ${call.method}`);
+    }
+}
+function IsRequest(message) {
+    return typeof message?.type === "string" && message.type.startsWith(MESSAGE_PREFIX);
+}
+/** Posts a message; an `error` that can't be cloned is sent as its text */
+function Post(channel, message) {
+    if (!("error" in message) || message.error === undefined)
+        return channel.postMessage(message);
+    try {
+        channel.postMessage(message);
+    }
+    catch {
+        channel.postMessage({ ...message, error: String(message.error) });
+    }
+}

package/Store/Diff/index.d.ts

@@ -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";