j-templates 9.0.1 → 10.0.1

package/Store/Store/storeAsync.js

@@ -1,14 +1,40 @@
 import { AsyncQueue } from "../../Utils/asyncQueue";
-import { WorkerQueue } from "../Diff/workerQueue";
+import { EmitterEvent } from "../../Utils/emitter";
+import { PatternMatches } from "../../Utils/pattern";
+import { _queueMicrotask, _setTimeout } from "../../Utils/scheduling";
+import { ChannelClient, ChannelSubscription } from "../Diff/channelClient";
 import { RootOf, Store } from "./store";
+/** How long a demand root no one reads stays subscribed, by default */
+const DEMAND_GRACE = 1000;
 /**
  * StoreAsync class extends the base Store class to provide asynchronous data management operations.
  * This class handles writing, patching, pushing, and splicing data in an asynchronous manner.
  *
- * StoreAsync is designed to work with observable data structures, allowing for efficient updates
- * and notifications when data changes. It is particularly useful for scenarios where asynchronous
- * operations are preferred or required, such as handling large datasets or performing complex diffs
- * without blocking the main thread.
+ * The tree lives in a worker, served by a `HostPublisher`. The store subscribes on construction and
+ * applies every commit the tree posts, whatever caused it: its own batches, other writers, or the
+ * worker's own work. A store created after the tree has committed starts from its committed state.
+ * Without writes it's a read-only view of the tree.
+ *
+ * - Changes made in one tick are sent as one batch, and at most one batch waits behind the one in
+ *   flight. A change's promise resolves on its batch's `jt-ack`, which arrives after the commit's
+ *   posts, so the change has been applied when it resolves.
+ * - A failed batch rejects only its own changes; later batches carry on.
+ *
+ * **Demand roots** (`IStoreAsyncOptions.demand`) are received while they're read: the first reactive
+ * read of one subscribes to it alone, and its first post brings the tree's state of it; a grace
+ * period after the last reader goes, it's unsubscribed and deleted from the store. A read outside
+ * a scope neither subscribes nor keeps one; `Hold` does, for code that reads it that way.
+ *
+ * **Over a lease** (`DiffTreeHub.Open`), the store takes its keyFunc from the lease's endpoint, owns
+ * the lease, and releases it when it's destroyed. When the hub restarts the worker,
+ * the store starts over with the new tree, as when it first subscribed: the tree is the source of
+ * truth, nothing the store wrote is written back, and changes the old tree hadn't acknowledged are
+ * rejected.
+ *
+ * @example
+ * // A store over a hub's lease: it lives as long as the component that holds it
+ * @Inject(DiffTreeHub) hub!: DiffTreeHub;
+ * @Destroy() totals = new StoreAsync(this.hub.Open("totals"));
  *
  * @example
  * // Creating a StoreAsync instance from a bundler-built worker entry file
@@ -28,41 +54,198 @@ import { RootOf, Store } from "./store";
  * // Splicing an array asynchronously
  * await store.Splice("users", 0, 1, { id: 3 });
  *
- * // Cleaning up resources
+ * // Cleaning up resources: the store stops listening; the worker is its creator's to terminate
  * store.Destroy();
+ * worker.terminate();
  *
  * @see Store
  * @see StoreSync
  */
 export class StoreAsync extends Store {
     /**
-     * Creates an instance of StoreAsync.
-     * @param diffWorker A `Worker` running a `DiffTree` connected via `ConnectWorkerToDiffTree`
-     *   (e.g. a bundled `defaultDiffTreeWorker` entry). Any `keyFunc`/routes the diff needs
-     *   must be baked into that worker's own entry file.
-     * @param keyFunc Optional function to generate a key for a given data value, used locally by
-     *   this store to resolve root objects. Pass the same key logic the worker's `DiffTree` was
-     *   constructed with, if any.
+     * Creates an instance of StoreAsync and subscribes to the tree.
+     * @param channel A channel to an `ObservableDiffTree` served by `HostPublisher`: a `Worker` (e.g. a
+     *   bundled `defaultDiffTreeWorker` entry), a `MessagePort`, or a lease from `DiffTreeHub.Open`. Other
+     *   messages may share the channel. Given a lease, the store owns it from then on and releases it
+     *   when it's destroyed, and follows the worker across restarts. A lease on a tree on this thread
+     *   (`DiffTreeHub.OpenLocal`) is for a `StoreSync`, and doesn't compile here.
+     * @param options `keyFunc`, `roots` and `opaque` (`IStoreAsyncOptions`). `keyFunc` is for a plain
+     *   channel: pass the key logic the worker's tree was built with. A lease's is the endpoint's.
+     *   `opaque` is the store's own: the tree must write those keys whole too, from its config
+     *   (`IObservableDiffTreeConfig.opaque`), so share them from a file both import.
+     * @throws When `keyFunc` is given with a lease, whose endpoint has its own.
      */
-    constructor(diffWorker, keyFunc) {
-        super(keyFunc);
+    constructor(channel, options = {}) {
+        const lease = IsLease(channel) ? channel : undefined;
+        if (lease && options.keyFunc)
+            throw new Error(`StoreAsync: the endpoint ${lease.name} gives the store its keyFunc; leave it out of the options.`);
+        if (options.demand && options.demand.length > 0 && !options.roots)
+            throw new Error("StoreAsync: demand roots need roots: a store that receives every root has none left to demand.");
+        const keyFunc = lease ? lease.endpoint.keyFunc : options.keyFunc;
+        super(keyFunc, options.opaque, options.demand ?? [], (key, event) => this.DemandWatched(key, event));
         this.writeKeySet = new Set();
+        this.asyncQueue = new AsyncQueue();
         this.currentBatch = [];
         this.currentBatchPromise = Promise.resolve();
-        this.workerQueue = new WorkerQueue(diffWorker);
-        this.asyncQueue = new AsyncQueue(true);
+        /** Batches not yet acknowledged, for `Flush` */
+        this.inFlight = new Set();
+        /** Demand roots a reactive scope reads now, from their watchers */
+        this.demandRead = new Set();
+        /** `Hold`s, by demand root */
+        this.demandHolds = new Map();
+        /** A subscription for each demand root the store holds */
+        this.demandSubscriptions = new Map();
+        /** The release timers of demand roots no one reads, by key */
+        this.demandReleasing = new Map();
+        /** Demand roots whose readers or holds changed since the last flush */
+        this.demandChanged = new Set();
+        this.demandFlushQueued = false;
+        this.destroyed = false;
+        this.options = options;
+        this.lease = lease;
+        if (lease)
+            this.stopLease = lease.OnPort(port => this.Restarted(port));
+        this.subscription = new ChannelSubscription({ roots: options.roots }, (post, first) => this.Apply(post, first));
+        this.client = this.Connect(lease ? lease.port : channel);
+        this.subscription.Connect(this.client);
+    }
+    /**
+     * The hub restarted the lease's worker: the store moves to the new tree's port, keeping its
+     * readers, and starts over as when it first subscribed. The changes the old tree hadn't
+     * acknowledged are rejected, not sent again, and nothing is written back: the new tree's first
+     * state is diffed into the store's roots in place, with the roots the old tree posted that the
+     * new one lacks deleted (`ChannelSubscription`).
+     */
+    Restarted(port) {
+        this.client.RejectBatches(new Error(`${this.lease.name} restarted before this change was acknowledged.`));
+        this.client.Destroy();
+        this.client = this.Connect(port);
+        this.subscription.Connect(this.client);
+        for (const subscription of this.demandSubscriptions.values())
+            subscription.Connect(this.client);
+    }
+    Connect(channel) {
+        return new ChannelClient(channel);
+    }
+    /**
+     * Holds a demand root without reading it reactively, for code that reads it outside a scope: the
+     * store subscribes to it as for a reader, and keeps it until every hold is released. Its first
+     * post arrives later; until then it reads as its default.
+     * @returns What releases this hold; calling it again does nothing.
+     * @throws When the key is neither a demand root nor one of the store's `roots`. A `roots` root is
+     *   always received: its hold does nothing.
+     */
+    Hold(key) {
+        if (this.IsRootsKey(key))
+            return () => { };
+        if (!this.IsDemandKey(key))
+            throw new Error(`StoreAsync: ${key} isn't a demand root or one of the store's roots.`);
+        this.demandHolds.set(key, (this.demandHolds.get(key) ?? 0) + 1);
+        this.DemandChanged(key);
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            const holds = (this.demandHolds.get(key) ?? 1) - 1;
+            holds > 0 ? this.demandHolds.set(key, holds) : this.demandHolds.delete(key);
+            this.DemandChanged(key);
+        };
+    }
+    IsRootsKey(key) {
+        return !this.options.roots || this.options.roots.some(pattern => PatternMatches(pattern, key));
+    }
+    IsDemandKey(key) {
+        return !this.IsRootsKey(key) && (this.options.demand ?? []).some(pattern => PatternMatches(pattern, key));
+    }
+    /**
+     * A demand root's watcher: it gained its first reactive reader or lost its last. This runs inside
+     * a scope's update, so it only records the change for the next flush.
+     */
+    DemandWatched(key, event) {
+        if (this.IsRootsKey(key))
+            return;
+        event === EmitterEvent.SUBSCRIBED ? this.demandRead.add(key) : this.demandRead.delete(key);
+        this.DemandChanged(key);
+    }
+    DemandChanged(key) {
+        this.demandChanged.add(key);
+        if (this.demandFlushQueued)
+            return;
+        this.demandFlushQueued = true;
+        _queueMicrotask(() => this.FlushDemand());
+    }
+    /**
+     * Subscribes the demand roots read or held now and not yet subscribed, and starts the release of
+     * the ones no one reads or holds. A root read and dropped since the last flush is never subscribed.
+     */
+    FlushDemand() {
+        this.demandFlushQueued = false;
+        if (this.destroyed)
+            return;
+        const keys = Array.from(this.demandChanged);
+        this.demandChanged.clear();
+        for (const key of keys) {
+            if (this.IsDemanded(key)) {
+                const timer = this.demandReleasing.get(key);
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    this.demandReleasing.delete(key);
+                }
+                !this.demandSubscriptions.has(key) && this.SubscribeDemand(key);
+            }
+            else if (this.demandSubscriptions.has(key) && !this.demandReleasing.has(key))
+                this.ReleaseLater(key);
+        }
+    }
+    IsDemanded(key) {
+        return this.demandRead.has(key) || this.demandHolds.has(key);
+    }
+    SubscribeDemand(key) {
+        // A post for a key released since is dropped: an unsubscribe and a commit can cross on the channel
+        const subscription = new ChannelSubscription({ roots: [key] }, (post, first) => this.demandSubscriptions.get(key) === subscription && this.Apply(post, first));
+        this.demandSubscriptions.set(key, subscription);
+        subscription.Connect(this.client);
+    }
+    ReleaseLater(key) {
+        const grace = this.options.demandDebounce ?? DEMAND_GRACE;
+        if (grace <= 0)
+            return this.ReleaseDemand(key);
+        let fired = false;
+        const timer = _setTimeout(() => {
+            fired = true;
+            this.demandReleasing.delete(key);
+            !this.destroyed && !this.IsDemanded(key) && this.ReleaseDemand(key);
+        }, grace);
+        // A timer that ran at once (synchronous scheduling) has nothing left to cancel
+        !fired && this.demandReleasing.set(key, timer);
+    }
+    /** Unsubscribes a demand root and deletes it from the store, so no later reader sees it stale */
+    ReleaseDemand(key) {
+        const subscription = this.demandSubscriptions.get(key);
+        if (!subscription)
+            return;
+        this.demandSubscriptions.delete(key);
+        subscription.Stop();
+        this.Has(key) && this.UpdateRootMap([{ type: "delete", path: [key] }]);
+    }
+    /** Applies a post. A tree's first state is diffed into the roots in place, its deletes with it. */
+    Apply(post, firstState) {
+        firstState ? this.UpdateRootMapInPlace(post.diff) : this.UpdateRootMap(post.diff);
     }
     async Schedule(method) {
         if (this.currentBatch.length === 0) {
             const batch = this.currentBatch;
-            this.currentBatchPromise = this.asyncQueue.Next(async () => {
+            const sent = this.asyncQueue.Next(async () => {
                 await Promise.resolve();
                 if (batch === this.currentBatch)
                     this.currentBatch = [];
-                // The worker's Commit() diff covers every change in the batch
-                const diff = await this.workerQueue.Push(batch);
-                this.UpdateRootMap(diff);
+                // The batch's commit is applied by the subscription, before its ack arrives
+                await this.client.Batch(batch);
             });
+            this.currentBatchPromise = sent;
+            this.inFlight.add(sent);
+            sent.then(() => this.inFlight.delete(sent), () => this.inFlight.delete(sent));
         }
         this.currentBatch.push(method);
         await this.currentBatchPromise;
@@ -75,8 +258,8 @@ export class StoreAsync extends Store {
      * @param data The data to be written. Can be of any type.
      * @param key Optional key for the data. If not provided, the keyFunc will be used to generate a key.
      * @returns A promise that resolves once the write has been applied to the store.
-     * @throws Will throw an error if no key is provided for the data, or reject with the original
-     *   error if an earlier change failed.
+     * @throws Will throw an error if no key is provided for the data, or reject with the error of
+     *   the batch it was sent in.
      */
     async Write(data, key) {
         key = key || this.keyFunc?.(data);
@@ -98,7 +281,7 @@ export class StoreAsync extends Store {
      * @param patch The patch data to be merged with the existing value.
      * @returns A promise that resolves once the patch has been applied to the store.
      * @throws Will throw if the key isn't in the store and has no pending Write, or reject with
-     *   the original error if an earlier change failed.
+     *   the error of the batch it was sent in.
      */
     async Patch(key, patch) {
         if (!this.HasRootOf(key) && !this.writeKeySet.has(RootOf(key)))
@@ -114,7 +297,7 @@ export class StoreAsync extends Store {
      * @param data The data items to be pushed into the array.
      * @returns A promise that resolves once the items have been applied to the store.
      * @throws Will throw if the key isn't in the store and has no pending Write, or reject with
-     *   the original error if an earlier change failed.
+     *   the error of the batch it was sent in.
      */
     async Push(key, ...data) {
         if (!this.HasRootOf(key) && !this.writeKeySet.has(RootOf(key)))
@@ -133,7 +316,7 @@ export class StoreAsync extends Store {
      * @param items Optional elements to insert into the array.
      * @returns A promise that resolves once the splice has been applied to the store.
      * @throws Will throw if the key isn't in the store and has no pending Write, or reject with
-     *   the original error if an earlier change failed.
+     *   the error of the batch it was sent in.
      */
     async Splice(key, start, deleteCount, ...items) {
         if (!this.HasRootOf(key) && !this.writeKeySet.has(RootOf(key)))
@@ -145,20 +328,39 @@ export class StoreAsync extends Store {
     }
     /**
      * Returns a promise that resolves once every change made before this call has been applied
-     * to the store. Changes made after this call are sent in a later batch, so they aren't
-     * waited for and haven't been applied when the promise resolves.
-     * @throws Rejects with the original error if a change made before this call failed.
+     * to the store: when the last batch sent before it is acknowledged, and at once when none is in
+     * flight. Changes made after this call are sent in a later batch, so they aren't waited for and
+     * haven't been applied when the promise resolves.
+     * @throws Rejects with the first error of the batches it waited for.
      */
     async Flush() {
         this.currentBatch = [];
-        return this.asyncQueue.Flush();
+        const pending = Array.from(this.inFlight);
+        const results = await Promise.allSettled(pending);
+        const failed = results.find(result => result.status === "rejected");
+        if (failed)
+            throw failed.reason;
     }
     /**
-     * Destroys the StoreAsync instance, stopping the async queue and cleaning up the diff instance.
-     * This method should be called when the instance is no longer needed to free up resources.
+     * Unsubscribes and stops listening to the channel. Changes not yet acknowledged never settle.
+     * Over a lease, the store then releases it: the last lease on a worker ends it. Over a channel, the
+     * channel stays open: whoever created the worker terminates it.
      */
     Destroy() {
+        this.destroyed = true;
+        this.stopLease?.();
         this.asyncQueue.Stop();
-        this.workerQueue.Destroy();
+        this.subscription.Stop();
+        for (const subscription of this.demandSubscriptions.values())
+            subscription.Stop();
+        this.demandSubscriptions.clear();
+        for (const timer of this.demandReleasing.values())
+            clearTimeout(timer);
+        this.demandReleasing.clear();
+        this.client.Destroy();
+        this.lease?.Release();
     }
 }
+function IsLease(channel) {
+    return typeof channel.OnPort === "function";
+}

package/Store/Store/storeSync.d.ts

@@ -1,5 +1,27 @@
-import { IRouteDefinitions } from "../Diff/utils/diffTree.types";
-import { Store } from "./store";
+import type { EmitterEvent } from "../../Utils/emitter";
+import type { ILocalLease } from "../Diff/diffTree.types";
+import { ObservableDiffTree } from "../Diff/observableDiffTree";
+import { IStoreOptions, Store } from "./store";
+/** Options for a `StoreSync` */
+export interface IStoreSyncOptions extends IStoreOptions {
+    /**
+     * The tree's root keys the store holds: exact keys and patterns ending in `*`. Omitted, every
+     * root. With a `keyFunc`, include the entity roots the held roots refer to.
+     */
+    roots?: readonly string[];
+    /**
+     * Root keys whose readers the store reports to `watchCallback`: exact keys and patterns ending in
+     * `*`. A watched root reports when a reactive scope first reads it with `Get`, and when its last
+     * reader stops; a read outside a scope reports nothing.
+     */
+    watch?: readonly string[];
+    /**
+     * Told when a watched root gains its first reader or loses its last, with the root's key. It runs
+     * inside the scope update that caused it: record the change and act on it later, without reading
+     * or writing the store. Needed with `watch`.
+     */
+    watchCallback?: (rootKey: string, event: EmitterEvent) => void;
+}
 /**
  * StoreSync class extends the base Store class to provide synchronous data management operations.
  * This class handles writing, patching, pushing, and splicing data in a synchronous manner.
@@ -24,24 +46,69 @@ import { Store } from "./store";
  * // Splicing an array
  * store.Splice("user.array", 0, 1, { id: 3 });
  *
+ * The store subscribes to an `ObservableDiffTree` and applies every commit the tree delivers, so
+ * anything else on the thread can subscribe to the same tree (`Tree`), and a commit made on the
+ * tree directly reaches the store too. A change runs the tree's projections and commits
+ * before it returns.
+ *
+ * - **Its own tree** (`new StoreSync()`, `new StoreSync(undefined, { keyFunc })`): the store creates an
+ *   empty tree, and it lives as long as the store.
+ * - **A tree it's given** (`new StoreSync(new ObservableDiffTree({ keyFunc, routes }))`): for a tree
+ *   with routes and projections, whose keyFunc the store takes. Anything else on the thread may hold it too.
+ * - **A hub's tree** (`new StoreSync(hub.OpenLocal(name))`): a tree on this thread a `DiffTreeHub` runs
+ *   for an endpoint, shared by every store opened on it and followed into by the hub. A change from
+ *   any of them reaches all of them, and the trees that follow it, before it returns. The store
+ *   owns the lease and releases it when it's destroyed. When the hub restarts the tree, the store
+ *   moves to the new one, as when it first subscribed.
+ *
+ * @example
+ * // A store on a hub's tree: it lives as long as the component that holds it
+ * @Inject(DiffTreeHub) hub!: DiffTreeHub;
+ * @Destroy() budget = new StoreSync(this.hub.OpenLocal("budget"));
+ *
  * @see Store
  * @see StoreAsync
- * @see DiffTree
+ * @see ObservableDiffTree
  */
 export declare class StoreSync extends Store {
     /**
-     * The tree each change is applied to. Its `Commit()` diff keeps the store in sync.
+     * The tree each change is applied to. The store applies every commit it delivers.
      * @private
      */
     private diff;
+    private unsubscribe?;
+    /** The lease the store owns, when it was given one */
+    private lease?;
+    private stopLease?;
+    private roots?;
+    /** Over a lease: the roots delivered and not deleted, to delete the ones a restarted tree doesn't hold */
+    private delivered;
+    /**
+     * Creates a store and subscribes it to its tree: the tree's state is the store's when this returns.
+     * @param tree The tree:
+     *   - A lease from `DiffTreeHub.OpenLocal`, on a hub's tree on this thread. The store owns the
+     *     lease from then on, and releases it when it's destroyed, and follows the tree across
+     *     restarts. A lease on a worker's tree (`DiffTreeHub.Open`) is for a `StoreAsync`, and doesn't
+     *     compile here.
+     *   - An `ObservableDiffTree`, for a tree with routes (`new ObservableDiffTree({ keyFunc, routes })`).
+     *     A projection in the root route (`"/"`) is readable through `Get` at `$projection_<key>`. The
+     *     store doesn't own it: `Destroy` stops listening.
+     *   - Left out, the store creates an empty tree of its own, with the store's `keyFunc` and `opaque`.
+     * @param options `keyFunc`, `roots`, `opaque`, `watch` and `watchCallback` (`IStoreSyncOptions`).
+     *   `keyFunc` is for the tree the
+     *   store creates: a leased tree's is the endpoint's, and a given tree's its own. A tree given or
+     *   leased must write the `opaque` keys whole already (`IObservableDiffTreeConfig.opaque`): share
+     *   them from one file.
+     * @throws When `keyFunc` is given with a tree or a lease, which has its own; or `watch` without
+     *   `watchCallback`.
+     */
+    constructor(tree?: ObservableDiffTree | ILocalLease, options?: IStoreSyncOptions);
     /**
-     * Creates an instance of StoreSync.
-     * @param keyFunc Optional function to generate a key for a given data value.
-     * @param routes Optional route definitions. A projection in the root route (`"/"`) is
-     * readable through `Get` at `$projection_<key>`.
-     * @throws When projections depend on each other in a cycle.
+     * The store's tree: its own, or the hub's. Subscribe to it to receive the
+     * same commits the store applies; a commit made on it reaches the store too. A subscriber can't
+     * write to the store during a delivery.
      */
-    constructor(keyFunc?: (value: any) => string | undefined, routes?: IRouteDefinitions);
+    get Tree(): ObservableDiffTree;
     /**
      * Writes data to the store synchronously.
      * @param data The data to be written. Can be of any type.
@@ -72,7 +139,20 @@ export declare class StoreSync extends Store {
      */
     Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): void;
     /**
-     * Runs projections and applies everything changed since the last sync to the store.
+     * Stops applying the tree's commits. Over a lease, the store then releases it: the last lease on
+     * a hub's tree ends it. The store's values stay readable, and stop changing.
+     */
+    Destroy(): void;
+    /**
+     * Subscribes to a hub's tree in place of the last. A restarted tree's state is applied in place, so
+     * readers keep their objects, with a delete for each root the last tree had and this one hasn't, in
+     * one update. The first delivery arrives during `Subscribe`.
+     */
+    private Attach;
+    private Track;
+    /**
+     * Runs projections and commits: the commit's delivery applies everything changed since the
+     * last commit to the store.
      * @private
      */
     private Sync;

package/Store/Store/storeSync.js

@@ -1,4 +1,4 @@
-import { DiffTree } from "../Diff/diffTree";
+import { ObservableDiffTree } from "../Diff/observableDiffTree";
 import { Store } from "./store";
 /**
  * StoreSync class extends the base Store class to provide synchronous data management operations.
@@ -24,21 +24,76 @@ import { Store } from "./store";
  * // Splicing an array
  * store.Splice("user.array", 0, 1, { id: 3 });
  *
+ * The store subscribes to an `ObservableDiffTree` and applies every commit the tree delivers, so
+ * anything else on the thread can subscribe to the same tree (`Tree`), and a commit made on the
+ * tree directly reaches the store too. A change runs the tree's projections and commits
+ * before it returns.
+ *
+ * - **Its own tree** (`new StoreSync()`, `new StoreSync(undefined, { keyFunc })`): the store creates an
+ *   empty tree, and it lives as long as the store.
+ * - **A tree it's given** (`new StoreSync(new ObservableDiffTree({ keyFunc, routes }))`): for a tree
+ *   with routes and projections, whose keyFunc the store takes. Anything else on the thread may hold it too.
+ * - **A hub's tree** (`new StoreSync(hub.OpenLocal(name))`): a tree on this thread a `DiffTreeHub` runs
+ *   for an endpoint, shared by every store opened on it and followed into by the hub. A change from
+ *   any of them reaches all of them, and the trees that follow it, before it returns. The store
+ *   owns the lease and releases it when it's destroyed. When the hub restarts the tree, the store
+ *   moves to the new one, as when it first subscribed.
+ *
+ * @example
+ * // A store on a hub's tree: it lives as long as the component that holds it
+ * @Inject(DiffTreeHub) hub!: DiffTreeHub;
+ * @Destroy() budget = new StoreSync(this.hub.OpenLocal("budget"));
+ *
  * @see Store
  * @see StoreAsync
- * @see DiffTree
+ * @see ObservableDiffTree
  */
 export class StoreSync extends Store {
     /**
-     * Creates an instance of StoreSync.
-     * @param keyFunc Optional function to generate a key for a given data value.
-     * @param routes Optional route definitions. A projection in the root route (`"/"`) is
-     * readable through `Get` at `$projection_<key>`.
-     * @throws When projections depend on each other in a cycle.
+     * Creates a store and subscribes it to its tree: the tree's state is the store's when this returns.
+     * @param tree The tree:
+     *   - A lease from `DiffTreeHub.OpenLocal`, on a hub's tree on this thread. The store owns the
+     *     lease from then on, and releases it when it's destroyed, and follows the tree across
+     *     restarts. A lease on a worker's tree (`DiffTreeHub.Open`) is for a `StoreAsync`, and doesn't
+     *     compile here.
+     *   - An `ObservableDiffTree`, for a tree with routes (`new ObservableDiffTree({ keyFunc, routes })`).
+     *     A projection in the root route (`"/"`) is readable through `Get` at `$projection_<key>`. The
+     *     store doesn't own it: `Destroy` stops listening.
+     *   - Left out, the store creates an empty tree of its own, with the store's `keyFunc` and `opaque`.
+     * @param options `keyFunc`, `roots`, `opaque`, `watch` and `watchCallback` (`IStoreSyncOptions`).
+     *   `keyFunc` is for the tree the
+     *   store creates: a leased tree's is the endpoint's, and a given tree's its own. A tree given or
+     *   leased must write the `opaque` keys whole already (`IObservableDiffTreeConfig.opaque`): share
+     *   them from one file.
+     * @throws When `keyFunc` is given with a tree or a lease, which has its own; or `watch` without
+     *   `watchCallback`.
+     */
+    constructor(tree, options = {}) {
+        const lease = tree && !(tree instanceof ObservableDiffTree) ? tree : undefined;
+        if (tree && options.keyFunc)
+            throw new Error(lease
+                ? `StoreSync: the endpoint ${lease.name} gives the store its keyFunc; leave it out of the options.`
+                : "StoreSync: the tree has its keyFunc, which the store takes; leave it out of the options.");
+        super(lease ? lease.endpoint.keyFunc : tree ? tree.KeyFunc : options.keyFunc, options.opaque, options.watch, options.watchCallback);
+        /** Over a lease: the roots delivered and not deleted, to delete the ones a restarted tree doesn't hold */
+        this.delivered = new Set();
+        this.roots = options.roots;
+        if (lease) {
+            this.lease = lease;
+            this.Attach(lease.tree, false);
+            this.stopLease = lease.OnTree(tree => this.Attach(tree, true));
+            return;
+        }
+        this.diff = tree ?? new ObservableDiffTree({ keyFunc: options.keyFunc, opaque: options.opaque });
+        this.unsubscribe = this.diff.Subscribe({ roots: this.roots }, post => this.UpdateRootMap(post.diff));
+    }
+    /**
+     * The store's tree: its own, or the hub's. Subscribe to it to receive the
+     * same commits the store applies; a commit made on it reaches the store too. A subscriber can't
+     * write to the store during a delivery.
      */
-    constructor(keyFunc, routes) {
-        super(keyFunc);
-        this.diff = new DiffTree(keyFunc, routes);
+    get Tree() {
+        return this.diff;
     }
     /**
      * Writes data to the store synchronously.
@@ -91,11 +146,51 @@ export class StoreSync extends Store {
         this.Sync();
     }
     /**
-     * Runs projections and applies everything changed since the last sync to the store.
+     * Stops applying the tree's commits. Over a lease, the store then releases it: the last lease on
+     * a hub's tree ends it. The store's values stay readable, and stop changing.
+     */
+    Destroy() {
+        this.stopLease?.();
+        this.stopLease = undefined;
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        this.lease?.Release();
+    }
+    /**
+     * Subscribes to a hub's tree in place of the last. A restarted tree's state is applied in place, so
+     * readers keep their objects, with a delete for each root the last tree had and this one hasn't, in
+     * one update. The first delivery arrives during `Subscribe`.
+     */
+    Attach(tree, again) {
+        this.unsubscribe?.();
+        this.diff = tree;
+        const previous = this.delivered;
+        this.delivered = new Set();
+        let subscribing = true;
+        let first = [];
+        this.unsubscribe = tree.Subscribe({ roots: this.roots }, post => {
+            this.Track(post.diff);
+            subscribing ? (first = post.diff) : this.UpdateRootMap(post.diff);
+        });
+        subscribing = false;
+        const diff = [...first];
+        for (const key of previous)
+            this.delivered.has(key) || diff.push({ type: "delete", path: [key] });
+        diff.length > 0 && (again ? this.UpdateRootMapInPlace(diff) : this.UpdateRootMap(diff));
+    }
+    Track(diff) {
+        for (const record of diff) {
+            const key = String(record.path[0]);
+            record.type === "delete" && record.path.length === 1 ? this.delivered.delete(key) : this.delivered.add(key);
+        }
+    }
+    /**
+     * Runs projections and commits: the commit's delivery applies everything changed since the
+     * last commit to the store.
      * @private
      */
     Sync() {
         this.diff.RunProjections();
-        this.UpdateRootMap(this.diff.Commit());
+        this.diff.Commit();
     }
 }

package/Store/Tree/observableNode.d.ts

@@ -1,3 +1,4 @@
+import { EmitterEventCallback } from "../../Utils/emitter";
 import { JsonDiffResult } from "../../Utils/json";
 export declare namespace ObservableNode {
     /**
@@ -39,6 +40,8 @@ export declare namespace ObservableNode {
      * @returns A proxied version of the value that emits change events.
      */
     function Create<T>(value: T, unwrapValue?: boolean): T;
+    function WatchProperty<T>(proxy: T, prop: keyof T, callback: EmitterEventCallback): void;
+    function UnwatchProperty<T>(proxy: T, prop: keyof T, callback: EmitterEventCallback): void;
     /**
      * Returns an immutable, cached snapshot of an observable node's current value (plain
      * objects/arrays, with keyed children read through their root). The same snapshot is