j-templates 9.0.0 → 10.0.0

package/Store/Diff/channelClient.js

@@ -0,0 +1,228 @@
+/** Ids are unique across clients, so several can share one channel */
+let nextId = 1;
+/**
+ * The client side of a `HostPublisher` channel: it sends batches and subscriptions, and routes
+ * the host's posts and acks back by id. Messages for ids it didn't send are left alone, so
+ * other clients and the app's own messages share the channel.
+ */
+export class ChannelClient {
+    constructor(channel) {
+        this.channel = channel;
+        this.subscriptions = new Map();
+        this.batches = new Map();
+        this.listener = (event) => this.Receive(event.data);
+        channel.addEventListener("message", this.listener);
+        channel.start?.();
+    }
+    /**
+     * Sends a batch of calls.
+     * @returns A promise that resolves on the batch's `jt-ack`, after the commit's posts have been
+     *   delivered, or rejects with the batch's error.
+     */
+    Batch(calls) {
+        return new Promise((resolve, reject) => {
+            const id = nextId++;
+            this.batches.set(id, { calls, resolve, reject });
+            this.channel.postMessage({ type: "jt-batch", id, calls });
+        });
+    }
+    /** Rejects the batches waiting for an ack with `error`; this client stops waiting for them */
+    RejectBatches(error) {
+        const batches = Array.from(this.batches.values());
+        this.batches.clear();
+        batches.forEach(batch => batch.reject(error));
+    }
+    /** See `DiffTree.MarkOpaque` */
+    MarkOpaque(keys) {
+        this.channel.postMessage({ type: "jt-markopaque", keys });
+    }
+    /**
+     * Subscribes to the host's tree. Deliveries arrive as the host posts them.
+     * @param onSubscribed Called once the host has posted the first state, with its error when
+     *   subscribing failed.
+     * @returns The subscription's id.
+     */
+    Subscribe(options, callback, onSubscribed) {
+        const sub = nextId++;
+        this.subscriptions.set(sub, { callback, onSubscribed });
+        this.channel.postMessage({ type: "jt-subscribe", sub, roots: options.roots, form: options.form ?? "diff" });
+        return sub;
+    }
+    Unsubscribe(sub) {
+        if (this.subscriptions.delete(sub))
+            this.channel.postMessage({ type: "jt-unsubscribe", sub });
+    }
+    /**
+     * Ends this client's subscriptions and stops listening. Batches waiting for an ack are left
+     * unsettled. The channel stays open.
+     */
+    Destroy() {
+        for (const sub of Array.from(this.subscriptions.keys()))
+            this.Unsubscribe(sub);
+        this.batches.clear();
+        this.channel.removeEventListener("message", this.listener);
+    }
+    Receive(message) {
+        switch (message?.type) {
+            case "jt-post":
+                this.subscriptions.get(message.sub)?.callback(message);
+                break;
+            case "jt-ack": {
+                const batch = this.batches.get(message.id);
+                if (!batch)
+                    break;
+                this.batches.delete(message.id);
+                "error" in message && message.error !== undefined ? batch.reject(message.error) : batch.resolve();
+                break;
+            }
+            case "jt-subscribed": {
+                const subscription = this.subscriptions.get(message.sub);
+                if (!subscription)
+                    break;
+                if ("error" in message && message.error !== undefined)
+                    this.subscriptions.delete(message.sub);
+                subscription.onSubscribed?.(message.error);
+                break;
+            }
+        }
+    }
+}
+/**
+ * A subscription to a tree served on a channel that outlives the channel: when the tree is
+ * replaced (a restarted worker, given on a new port), `Connect` subscribes to the new one, and its
+ * first state also deletes the roots this subscription delivered that the new tree doesn't hold. A
+ * subscriber that applies every delivery, a store or a tree, then holds the new tree's state, and
+ * a wildcard read of it reads nothing the old tree left behind.
+ *
+ * - The first state after a reconnect is one delivery: the new tree's roots, then a `delete` record
+ *   (in the `"diff"` form) or a `deleted` key (in the `"snapshot"` form) for each root gone, so
+ *   nothing applied in between holds both. With no roots in the new tree, it's the deletes alone.
+ * - A root is delivered while it was written by the last delivery that touched it, and gone once a
+ *   delivery deletes it, as a `HostPublisher`'s deliveries say.
+ *
+ * @example
+ * const engine = new ChannelSubscription({ roots: ["run", "$projection_*"] }, (post, first) => {
+ *   tree.ApplyDiff(post.diff, "/engine/");
+ *   tree.RunProjections();
+ *   tree.Commit();
+ * });
+ * OnConnect("engine", port => engine.Connect(port));
+ */
+export class ChannelSubscription {
+    /**
+     * @param options The roots, and the form, as `ObservableDiffTree.Subscribe` takes them.
+     * @param callback Each delivery, and whether it's the first state of a `Connect`.
+     */
+    constructor(options, callback) {
+        this.options = options;
+        this.callback = callback;
+        /** The source's root keys delivered and not deleted */
+        this.delivered = new Set();
+        this.ownClient = false;
+    }
+    /**
+     * Subscribes over a channel, or a client of one, in place of the last: the first state arrives
+     * as one delivery, with the deletes for the roots the last tree had and this one hasn't.
+     * @param onSubscribed Called once the first state is out, with the error when subscribing failed.
+     * @returns What ends this connection's subscription.
+     */
+    Connect(channel, onSubscribed) {
+        this.Stop();
+        const client = this.client = channel instanceof ChannelClient ? channel : new ChannelClient(channel);
+        this.ownClient = !(channel instanceof ChannelClient);
+        const previous = this.delivered;
+        this.delivered = new Set();
+        const snapshot = this.options.form === "snapshot";
+        // After a tree that delivered something, the first state waits for jt-subscribed to take the deletes
+        const hold = previous.size > 0;
+        let first;
+        let subscribed = false;
+        const sub = this.sub = client.Subscribe(this.options, delivery => {
+            if (subscribed || !hold) {
+                this.Track(delivery, snapshot);
+                this.callback(delivery, !subscribed);
+                return;
+            }
+            first = delivery;
+        }, error => {
+            subscribed = true;
+            if (error === undefined && hold) {
+                const delivery = first ?? (snapshot ? { seq: 0, roots: {}, deleted: [] } : { seq: 0, diff: [] });
+                this.Track(delivery, snapshot);
+                for (const key of previous)
+                    if (!this.delivered.has(key))
+                        snapshot ? delivery.deleted.push(key) : delivery.diff.push({ type: "delete", path: [key] });
+                (first !== undefined || (snapshot ? delivery.deleted.length > 0 : delivery.diff.length > 0)) && this.callback(delivery, true);
+            }
+            onSubscribed?.(error);
+        });
+        return () => this.sub === sub && this.Stop();
+    }
+    /** Ends the subscription on the current channel; what it delivered is kept for the next `Connect` */
+    Stop() {
+        if (this.client && this.sub !== undefined)
+            this.ownClient ? this.client.Destroy() : this.client.Unsubscribe(this.sub);
+        this.client = undefined;
+        this.sub = undefined;
+    }
+    Track(delivery, snapshot) {
+        if (snapshot) {
+            for (const key of Object.keys(delivery.roots))
+                this.delivered.add(key);
+            for (const key of delivery.deleted)
+                this.delivered.delete(key);
+            return;
+        }
+        for (const record of delivery.diff) {
+            const key = String(record.path[0]);
+            record.type === "delete" && record.path.length === 1 ? this.delivered.delete(key) : this.delivered.add(key);
+        }
+    }
+}
+export function Subscribe(channel, options, callback) {
+    const client = new ChannelClient(channel);
+    client.Subscribe(options, callback, error => error !== undefined && client.Destroy());
+    return () => client.Destroy();
+}
+/**
+ * Waits on a channel for the first delivery in which every key has a value: at once when they
+ * all have one, otherwise the commit that adds the last. See `ObservableDiffTree.Once`.
+ * @param keys Exact root keys; no patterns.
+ * @param options `signal` cancels the wait, rejecting with its reason.
+ * @returns Each key's value.
+ */
+export function Once(channel, 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);
+        // Updates carry only the roots that changed, so the values seen so far are kept
+        const values = {};
+        const client = new ChannelClient(channel);
+        const onAbort = () => {
+            finish();
+            reject(signal.reason);
+        };
+        const finish = () => {
+            client.Destroy();
+            signal?.removeEventListener("abort", onAbort);
+        };
+        client.Subscribe({ roots: keys, form: "snapshot" }, (update) => {
+            Object.assign(values, update.roots);
+            for (const key of update.deleted)
+                delete values[key];
+            if (keys.every(key => values[key] !== undefined)) {
+                finish();
+                resolve(Object.fromEntries(keys.map(key => [key, values[key]])));
+            }
+        }, error => {
+            if (error !== undefined) {
+                finish();
+                reject(error);
+            }
+        });
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/Store/Diff/defaultDiffTreeWorker.js

@@ -1,4 +1,3 @@
-import { DiffTree } from "./diffTree";
-import { ConnectWorkerToDiffTree } from "./diffTreeWorker";
-const diffTree = new DiffTree();
-ConnectWorkerToDiffTree(diffTree, self);
+import { ObservableDiffTree } from "./observableDiffTree";
+import { HostPublisher } from "./hostPublisher";
+HostPublisher(new ObservableDiffTree(), self);

package/Store/Diff/diffTree.d.ts

@@ -16,6 +16,7 @@ export declare class DiffTree {
     private projections;
     /** Each root key's snapshot as of the last commit */
     private commitedSnapshot;
+    private opaque;
     private writeContext;
     constructor(keyFunc?: IKeyFunc, routeDefinitions?: IRouteDefinitions);
     WritePath(path: string, value: any): void;
@@ -23,6 +24,32 @@ export declare class DiffTree {
     PushPath(path: string, items: unknown[]): void;
     SplicePath(path: string, start: number, deleteCount: number, items: any[]): void;
     private Splice;
+    /**
+     * Applies another tree's diff records, a delivery of its commit, as writes to this tree, in
+     * order: each `write` as `WritePath`, each `splice` as `SplicePath` (moves included), each
+     * `delete` as removing the property, or the root key. The next `Commit` diffs them as it does any
+     * write, and the projections that read them rerun on `RunProjections`.
+     *
+     * Into the root route, the records' root keys are this tree's root keys, and a projection output
+     * (`$projection_<key>`) can't be written. Into a follow route (`FollowRoutes`), which only this
+     * writes, they're held under the source's own keys, projection outputs included, and a route is
+     * never posted: the source's data stays in this tree, and only what its projections derive from it
+     * reaches this tree's subscribers.
+     *
+     * Give the route the source's keyFunc, or one that gives its entities the same keys: the source's
+     * commit carries a change to an entity once, as its own root's records, and skips it wherever
+     * else it appears. Here, as there, each of those places is a slot holding the entity's home, so
+     * it reads the change too. Without the keyFunc, the copy of an entity inside another root would
+     * keep its first value.
+     * @param records A diff, e.g. an `IDiffPost`'s, from a subscription in the `"diff"` form
+     * @param route The route to apply them to: the root route (`/`, the default) or a follow route,
+     *   e.g. `/engine/`
+     * @throws When a record writes a projection output in the root route, the route isn't the root
+     *   or a follow route, or a record's parent doesn't exist
+     */
+    ApplyDiff(records: JsonDiffResult, route?: string): void;
+    /** A write's route isn't a follow route, which only `ApplyDiff` writes */
+    private AssertLocal;
     /**
      * Deletes a route: its state, its child routes and projection outputs, and its route
      * instances. The projection order is rebuilt on the next `RunProjections`, so deleting
@@ -31,13 +58,42 @@ export declare class DiffTree {
      * @throws When the path is the root route or has a property path, e.g. `/channel/1/name`
      */
     DeleteRoute(routePath: string): void;
+    /**
+     * Deletes a root key, a written root that isn't a projection output. The next `Commit` carries
+     * a `delete` at `[key]`. Deleting a key that doesn't exist does nothing.
+     * @param key The root key, e.g. `whatif_14`
+     * @throws When the key is a path (it has a `.` or `/`) or a projection output
+     */
+    DeleteRoot(key: string): void;
+    /**
+     * A root key's value as of the last `Commit`: its snapshot then, shared and never changed. A
+     * key written since and not yet committed reads as it was.
+     * @param key The root key.
+     * @returns The value, or undefined when the key wasn't in the last commit
+     */
+    Committed(key: string): unknown;
+    /** The root keys as of the last `Commit`, in the order they were first committed */
+    CommittedKeys(): string[];
     /**
      * Reads the raw value at a path, root (`value.prop`) or routed (`/channel/1/value.prop`).
      * @returns The value, or undefined when any segment of the path doesn't exist
      */
     ReadPath(path: string): any;
+    /**
+     * Marks root keys, a written root or a root route projection's `$projection_<key>`, as opaque:
+     * `Commit` writes an opaque key's value whole when it changes, never a diff inside it. A Store
+     * with the same keys in its `opaque` option holds each of them whole.
+     * @param keys The root keys.
+     */
+    MarkOpaque(keys: readonly string[]): void;
     /** Runs every projection of every route instance; see `Projections.Run` */
     RunProjections(): void;
+    /**
+     * Runs before every change to the tree's state: each write, splice, applied diff, deleted route
+     * or root, and projection run. A subclass that refuses changes at times (`ObservableDiffTree`,
+     * during a delivery) throws here.
+     */
+    protected BeforeChange(): void;
     /**
      * The changes since the last commit. The root is a flat record of keys, so each key's snapshot
      * is taken and compared on its own, without building a snapshot of the whole root: a key no

package/Store/Diff/diffTree.js

@@ -1,10 +1,10 @@
 import { JsonDiffInto, JsonMerge, JsonType } from '../../Utils/json';
 import { Snapshot } from '../Tree/snapshot';
-import { ApplyValueToPath, SpliceValueAtPath } from './utils/homes';
+import { ApplyRecords, ApplyValueToPath, SpliceValueAtPath } from './utils/homes';
 import { JoinPaths, PROJECTION_PREFIX, ROOT_ROUTE, SplitRouteAndPath } from './utils/paths';
 import { Projections } from './utils/projections';
 import { RouteInstances } from './utils/routes';
-import { DeleteRouteState, KeyUnchanged, ReadPath, ReadSnapshot } from './utils/state';
+import { DeleteRouteState, KeyUnchanged, ReadPath, ReadSnapshot, Remove } from './utils/state';
 /**
  * A tree of JSON state in routes, with projections, that tracks its changes as diffs. The work is
  * split across `utils/`:
@@ -20,6 +20,7 @@ export class DiffTree {
         this.snapshot = Snapshot.Create();
         /** Each root key's snapshot as of the last commit */
         this.commitedSnapshot = new Map();
+        this.opaque = new Set();
         this.routes = new RouteInstances(keyFunc, routeDefinitions);
         this.projections = new Projections(this.snapshot, this.rootState, this.routes);
         this.writeContext = {
@@ -29,7 +30,9 @@ export class DiffTree {
         };
     }
     WritePath(path, value) {
+        this.BeforeChange();
         AssertWritable(SplitRouteAndPath(path)[1]);
+        this.AssertLocal(path);
         // Keyed entities are local to the route written to; a key starting with "/" is a route path from the root
         ApplyValueToPath(this.writeContext, path, value);
     }
@@ -45,11 +48,57 @@ export class DiffTree {
     SplicePath(path, start, deleteCount, items) {
         this.Splice(path, start, deleteCount, items);
     }
-    // Shared by PushPath and SplicePath, which a DiffTreeWriter guards separately
+    // Shared by PushPath and SplicePath
     Splice(path, start, deleteCount, items) {
+        this.BeforeChange();
         AssertWritable(SplitRouteAndPath(path)[1]);
+        this.AssertLocal(path);
         SpliceValueAtPath(this.writeContext, path, start, deleteCount, items);
     }
+    /**
+     * Applies another tree's diff records, a delivery of its commit, as writes to this tree, in
+     * order: each `write` as `WritePath`, each `splice` as `SplicePath` (moves included), each
+     * `delete` as removing the property, or the root key. The next `Commit` diffs them as it does any
+     * write, and the projections that read them rerun on `RunProjections`.
+     *
+     * Into the root route, the records' root keys are this tree's root keys, and a projection output
+     * (`$projection_<key>`) can't be written. Into a follow route (`FollowRoutes`), which only this
+     * writes, they're held under the source's own keys, projection outputs included, and a route is
+     * never posted: the source's data stays in this tree, and only what its projections derive from it
+     * reaches this tree's subscribers.
+     *
+     * Give the route the source's keyFunc, or one that gives its entities the same keys: the source's
+     * commit carries a change to an entity once, as its own root's records, and skips it wherever
+     * else it appears. Here, as there, each of those places is a slot holding the entity's home, so
+     * it reads the change too. Without the keyFunc, the copy of an entity inside another root would
+     * keep its first value.
+     * @param records A diff, e.g. an `IDiffPost`'s, from a subscription in the `"diff"` form
+     * @param route The route to apply them to: the root route (`/`, the default) or a follow route,
+     *   e.g. `/engine/`
+     * @throws When a record writes a projection output in the root route, the route isn't the root
+     *   or a follow route, or a record's parent doesn't exist
+     */
+    ApplyDiff(records, route = ROOT_ROUTE) {
+        this.BeforeChange();
+        const fullRoute = JoinPaths("", route);
+        if (fullRoute === ROOT_ROUTE) {
+            for (let x = 0; x < records.length; x++) {
+                const key = String(records[x].path[0]);
+                AssertWritable(key);
+                if (key.startsWith(ROOT_ROUTE))
+                    throw new Error(`Unable to apply a record at ${key}: a diff's records are in the root route`);
+            }
+        }
+        else if (!this.routes.Get(fullRoute).follow || this.routes.Get(fullRoute).path !== fullRoute)
+            throw new Error(`Unable to apply a diff at ${fullRoute}: only the root route or a follow route (FollowRoutes) takes one.`);
+        ApplyRecords(this.writeContext, records, fullRoute);
+    }
+    /** A write's route isn't a follow route, which only `ApplyDiff` writes */
+    AssertLocal(path) {
+        const route = SplitRouteAndPath(path)[0];
+        if (route !== "" && this.routes.Get(JoinPaths("", route)).follow)
+            throw new Error(`Unable to write ${path}: a follow route is written only by ApplyDiff, from its subscription.`);
+    }
     /**
      * Deletes a route: its state, its child routes and projection outputs, and its route
      * instances. The projection order is rebuilt on the next `RunProjections`, so deleting
@@ -58,6 +107,7 @@ export class DiffTree {
      * @throws When the path is the root route or has a property path, e.g. `/channel/1/name`
      */
     DeleteRoute(routePath) {
+        this.BeforeChange();
         const [route, propertyPath] = SplitRouteAndPath(routePath);
         const fullRoute = JoinPaths("", route);
         if (propertyPath || fullRoute === ROOT_ROUTE)
@@ -65,6 +115,33 @@ export class DiffTree {
         DeleteRouteState(this.snapshot, this.rootState, fullRoute);
         this.routes.Delete(fullRoute);
     }
+    /**
+     * Deletes a root key, a written root that isn't a projection output. The next `Commit` carries
+     * a `delete` at `[key]`. Deleting a key that doesn't exist does nothing.
+     * @param key The root key, e.g. `whatif_14`
+     * @throws When the key is a path (it has a `.` or `/`) or a projection output
+     */
+    DeleteRoot(key) {
+        this.BeforeChange();
+        if (key.includes(".") || key.includes("/"))
+            throw new Error(`Unable to delete ${key}: only a root key, e.g. whatif_14, can be deleted.`);
+        AssertWritable(key);
+        if (Object.hasOwn(this.rootState, key))
+            Remove(this.snapshot, this.rootState, key);
+    }
+    /**
+     * A root key's value as of the last `Commit`: its snapshot then, shared and never changed. A
+     * key written since and not yet committed reads as it was.
+     * @param key The root key.
+     * @returns The value, or undefined when the key wasn't in the last commit
+     */
+    Committed(key) {
+        return this.commitedSnapshot.get(key);
+    }
+    /** The root keys as of the last `Commit`, in the order they were first committed */
+    CommittedKeys() {
+        return Array.from(this.commitedSnapshot.keys());
+    }
     /**
      * Reads the raw value at a path, root (`value.prop`) or routed (`/channel/1/value.prop`).
      * @returns The value, or undefined when any segment of the path doesn't exist
@@ -72,10 +149,27 @@ export class DiffTree {
     ReadPath(path) {
         return ReadPath(this.rootState, path);
     }
+    /**
+     * Marks root keys, a written root or a root route projection's `$projection_<key>`, as opaque:
+     * `Commit` writes an opaque key's value whole when it changes, never a diff inside it. A Store
+     * with the same keys in its `opaque` option holds each of them whole.
+     * @param keys The root keys.
+     */
+    MarkOpaque(keys) {
+        for (let x = 0; x < keys.length; x++)
+            this.opaque.add(keys[x]);
+    }
     /** Runs every projection of every route instance; see `Projections.Run` */
     RunProjections() {
+        this.BeforeChange();
         this.projections.Run();
     }
+    /**
+     * Runs before every change to the tree's state: each write, splice, applied diff, deleted route
+     * or root, and projection run. A subclass that refuses changes at times (`ObservableDiffTree`,
+     * during a delivery) throws here.
+     */
+    BeforeChange() { }
     /**
      * The changes since the last commit. The root is a flat record of keys, so each key's snapshot
      * is taken and compared on its own, without building a snapshot of the whole root: a key no
@@ -87,7 +181,7 @@ export class DiffTree {
         // Diffed key by key into one result
         const diff = [];
         const rootKeyFunc = this.routes.root.keyFunc;
-        const strategy = CommitStrategy(rootKeyFunc);
+        const strategy = OpaqueStrategy(this.opaque, CommitStrategy(rootKeyFunc));
         const identity = CommitIdentity(rootKeyFunc);
         // How many of the committed keys are still in the root, to tell whether any are gone
         let kept = 0;
@@ -124,6 +218,18 @@ export class DiffTree {
         return ReadSnapshot(this.snapshot, this.rootState, path)[0];
     }
 }
+/**
+ * A root key marked opaque is written whole; anything else is left to `strategy`.
+ */
+function OpaqueStrategy(opaque, strategy) {
+    if (opaque.size === 0)
+        return strategy;
+    return function (newValue, oldValue, path) {
+        if (path.length === 1 && opaque.has(path[0]))
+            return "write";
+        return strategy?.(newValue, oldValue, path);
+    };
+}
 /**
  * How `Commit` diffs the root's snapshots for a Store with the same keyFunc:
  * - An array whose first element is keyed is spliced, its elements matched by CommitIdentity.