j-templates 10.0.0 → 10.0.1

package/SYNTAX_PRIMER.md

@@ -626,7 +626,7 @@ const store = new StoreSync(new ObservableDiffTree({ keyFunc, routes, ...layoutC
 const layout = store.Get<Layout>("$projection_layout"); // the raw value: no proxies inside it
 ```
 
-- The key can be a written root or a projection's `$projection_<key>`. The tree writes it whole whenever it changes (`DiffTree.MarkOpaque`): a `StoreSync` marks the empty tree it creates (`new StoreSync(undefined, { opaque })`), and a tree it's given has the keys in its config. `StoreAsync` sends the keys to its worker ahead of the first change. A store on a hub's tree needs the tree to write the key whole too: give both the same keys from a file both import (`new ObservableDiffTree({ endpoint, routes, ...searchConfig })`, `new StoreAsync(hub.Open("search"), searchConfig)`).
+- The key can be a written root or a projection's `$projection_<key>`. The tree writes it whole whenever it changes (`DiffTree.MarkOpaque`): a `StoreSync` marks the empty tree it creates (`new StoreSync(undefined, { opaque })`), and a tree it's given has the keys in its config. A store never marks a tree: a `StoreAsync` needs its worker's tree to have the keys in its config too. A store on a hub's tree needs the tree to write the key whole too: give both the same keys from a file both import (`new ObservableDiffTree({ endpoint, routes, ...searchConfig })`, `new StoreAsync(hub.Open("search"), searchConfig)`).
 - `Get` returns the same reference until the root changes, and only that change updates its readers. A write that changes nothing updates no one.
 - The value is the store's own: treat it as read-only. A change made inside it notifies no one, and under `StoreSync` it is also the `DiffTree`'s committed snapshot.
 - Write the raw value. Don't pass an `Opaque` to `Write`, `Patch`, `Push` or `Splice`, at any depth: the store boxes the root itself, and a box written to a store isn't opened (under `StoreAsync` it arrives as a plain `{ value }`).

package/Store/Diff/channelClient.d.ts

@@ -18,8 +18,6 @@ export declare class ChannelClient {
     Batch(calls: IDiffMethodBatch): Promise<void>;
     /** Rejects the batches waiting for an ack with `error`; this client stops waiting for them */
     RejectBatches(error: unknown): void;
-    /** See `DiffTree.MarkOpaque` */
-    MarkOpaque(keys: readonly string[]): void;
     /**
      * 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

package/Store/Diff/channelClient.js

@@ -1,3 +1,4 @@
+import { IsPattern } from "../../Utils/pattern";
 /** Ids are unique across clients, so several can share one channel */
 let nextId = 1;
 /**
@@ -32,10 +33,6 @@ export class ChannelClient {
         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
@@ -194,7 +191,7 @@ export function Subscribe(channel, options, callback) {
 export function Once(channel, keys, options = {}) {
     const { signal } = options;
     return new Promise((resolve, reject) => {
-        if (keys.some(key => key.endsWith("*")))
+        if (keys.some(IsPattern))
             return reject(new Error(`Once takes exact keys, not patterns: ${keys.join(", ")}`));
         if (signal?.aborted)
             return reject(signal.reason);

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

@@ -103,11 +103,6 @@ export type IHostRequest =
  | {
     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";

package/Store/Diff/hostPublisher.d.ts

@@ -22,7 +22,6 @@ export interface IHost {
  * - `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

package/Store/Diff/hostPublisher.js

@@ -12,7 +12,6 @@ import { ListenForConnections } from "./onConnect";
  * - `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
@@ -65,9 +64,6 @@ export function HostPublisher(publisher, scope) {
                     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;

package/Store/Diff/observableDiffTree.js

@@ -1,3 +1,4 @@
+import { IsPattern } from "../../Utils/pattern";
 import { SubscriptionManager } from "../../Utils/subscriptionManager";
 import { DiffTree } from "./diffTree";
 import { FollowRoutes } from "./utils/routes";
@@ -125,7 +126,7 @@ export class ObservableDiffTree extends DiffTree {
     Once(keys, options = {}) {
         const { signal } = options;
         return new Promise((resolve, reject) => {
-            if (keys.some(key => key.endsWith("*")))
+            if (keys.some(IsPattern))
                 return reject(new Error(`Once takes exact keys, not patterns: ${keys.join(", ")}`));
             if (signal?.aborted)
                 return reject(signal.reason);

package/Store/Diff/utils/paths.d.ts

@@ -3,11 +3,12 @@
  * path `value.item` in the route `/channel/1/`. A path without a route (`value.item`) is in the
  * root route.
  */
+import { WILDCARD } from "../../../Utils/pattern";
 export declare const ROOT_ROUTE = "/";
 export declare const PROJECTION_PREFIX = "$projection_";
 export declare const ROUTE_DELIMETER = "/";
 export declare const PROP_DELIMETER = ".";
-export declare const WILDCARD = "*";
+export { WILDCARD };
 export declare function SplitRouteAndPath(path: string): readonly [string, string];
 /**
  * A path's route and property path. Only a path starting with `/` has a route: any other path

package/Store/Diff/utils/paths.js

@@ -3,11 +3,12 @@
  * path `value.item` in the route `/channel/1/`. A path without a route (`value.item`) is in the
  * root route.
  */
+import { PatternMatches, WILDCARD } from "../../../Utils/pattern";
 export const ROOT_ROUTE = "/";
 export const PROJECTION_PREFIX = "$projection_";
 export const ROUTE_DELIMETER = "/";
 export const PROP_DELIMETER = ".";
-export const WILDCARD = "*";
+export { WILDCARD };
 export function SplitRouteAndPath(path) {
     const lastSlash = path.lastIndexOf(ROUTE_DELIMETER);
     const route = path.slice(0, lastSlash + 1);
@@ -56,7 +57,7 @@ export function RouteMatches(pattern, route) {
     if (patternParts.length !== routeParts.length)
         return false;
     for (let x = 0; x < patternParts.length; x++)
-        if (patternParts[x].endsWith(WILDCARD) ? !routeParts[x].startsWith(patternParts[x].slice(0, -1)) : patternParts[x] !== routeParts[x])
+        if (!PatternMatches(patternParts[x], routeParts[x]))
             return false;
     return true;
 }

package/Store/Diff/utils/state.js

@@ -1,6 +1,7 @@
 import { JsonType } from "../../../Utils/json";
 import { Snapshot } from "../../Tree/snapshot";
-import { PROP_DELIMETER, ROUTE_DELIMETER, RouteAndProperty, SplitRouteAndPath, WILDCARD } from "./paths";
+import { PROP_DELIMETER, ROUTE_DELIMETER, RouteAndProperty, SplitRouteAndPath } from "./paths";
+import { IsPattern, PatternPrefix } from "../../../Utils/pattern";
 /**
  * The raw state of a DiffTree's routes. A route's state hangs off its parent route's state under
  * `ROUTE_STATE`, keyed by segment, so `Object.keys` of a route's state lists only its own values.
@@ -141,8 +142,8 @@ function InvalidateState(snapshot, value) {
 export function ExpandWildcardPath(root, path) {
     const [route, property] = SplitRouteAndPath(path);
     const parts = route.split(ROUTE_DELIMETER);
-    const index = parts.findIndex(part => part.endsWith(WILDCARD));
-    const prefix = parts[index].slice(0, -1);
+    const index = parts.findIndex(part => IsPattern(part));
+    const prefix = PatternPrefix(parts[index]);
     const parent = RouteState(root, parts.slice(0, index).join(ROUTE_DELIMETER) + ROUTE_DELIMETER);
     const children = parent?.[ROUTE_STATE] ?? {};
     const paths = {};

package/Store/Store/store.d.ts

@@ -1,5 +1,6 @@
 import { JsonDiffResult } from "../../Utils/json";
 import type { IKeyFunc } from "../Diff/utils/diffTree.types";
+import { EmitterEvent } from "../../Utils/emitter";
 /** Options shared by `StoreSync` and `StoreAsync` */
 export interface IStoreOptions {
     /**
@@ -15,8 +16,9 @@ export interface IStoreOptions {
      * until the root is written again, and only that write updates its readers. Treat the value as
      * read-only: a change made inside it notifies no one. An opaque root can't be read through a
      * key (`keyFunc`). Its tree must write each one whole instead of diffing inside it
-     * (`DiffTree.MarkOpaque`): a store with a tree of its own marks it; for a hub's tree, give the
-     * tree the same keys (`IObservableDiffTreeConfig.opaque`) from a file both import. Write the raw
+     * (`DiffTree.MarkOpaque`): a store with a tree of its own marks it; any other tree, a hub's or a
+     * worker's, takes the same keys in its config (`IObservableDiffTreeConfig.opaque`), from a file
+     * both import. A store never marks a tree: opaque is local. Write the raw
      * value: the store boxes it, and an `Opaque` written to a store isn't opened.
      */
     opaque?: readonly string[];
@@ -34,13 +36,15 @@ export declare abstract class ReadStore {
     private createNode;
     /** Root keys held whole, see `IStoreOptions.opaque` */
     protected readonly opaque: ReadonlySet<string | number>;
+    protected readonly watch: readonly string[];
+    protected readonly watchCallback?: (rootProperty: string, event: EmitterEvent) => void;
     /**
      * Creates an instance of ReadStore.
      * @param keyFunc Optional function to generate a key for a given data value.
      * When provided, enables alias functionality where values can reference other root objects.
      * @param opaque Root keys held whole, see `IStoreOptions.opaque`.
      */
-    constructor(keyFunc?: (value: any) => string | undefined, opaque?: readonly string[]);
+    constructor(keyFunc?: (value: any) => string | undefined, opaque?: readonly string[], watch?: readonly string[], watchCallback?: (rootKey: string, event: EmitterEvent) => void);
     /**
      * Retrieves a value from the store by id.
      * @template O - The type of the value to retrieve
@@ -86,6 +90,7 @@ export declare abstract class ReadStore {
      * @private
      */
     private UpdateRootObject;
+    private CreateRootNode;
 }
 /**
  * Base class for observable data store management.

package/Store/Store/store.js

@@ -1,6 +1,7 @@
 import { JsonDeepClone, JsonDiff, JsonType } from "../../Utils/json";
 import { ObservableNode } from "../Tree/observableNode";
 import { Opaque } from "../Tree/opaque";
+import { PatternMatches } from "../../Utils/pattern";
 /**
  * Base class for reading observable data: holds root objects as ObservableNode instances
  * and applies diff results to them. Subclasses decide where the diffs come from: `StoreSync`
@@ -15,10 +16,14 @@ export class ReadStore {
      * When provided, enables alias functionality where values can reference other root objects.
      * @param opaque Root keys held whole, see `IStoreOptions.opaque`.
      */
-    constructor(keyFunc, opaque = []) {
+    constructor(keyFunc, opaque = [], watch = [], watchCallback) {
         this.keyFunc = keyFunc;
         this.rootMap = new Map();
         this.opaque = new Set(opaque);
+        this.watch = watch;
+        if (this.watch.length > 0 && !watchCallback)
+            throw new Error("watchCallback must be provided when passing watch properties");
+        this.watchCallback = watchCallback;
         const aliasFunc = keyFunc &&
             ((value, reactive = true) => {
                 const key = keyFunc(value);
@@ -43,7 +48,7 @@ export class ReadStore {
     Get(id, defaultValue) {
         let result = this.rootMap.get(id);
         if (result === undefined) {
-            result = this.createNode({ [id]: this.opaque.has(id) ? Box(defaultValue) : defaultValue });
+            result = this.CreateRootNode(id, defaultValue);
             this.rootMap.set(id, result);
         }
         return result[id];
@@ -109,7 +114,7 @@ export class ReadStore {
             if (results[0].type !== "write" || results[0].path.length > 1)
                 throw `Unable to initialize root path ${rootPath} with initial path ${results[0].path}`;
             const rootData = JsonDeepClone(results[0].value);
-            const newRootObject = this.createNode({ [rootPath]: rootData }, false);
+            const newRootObject = this.CreateRootNode(rootPath, rootData, false);
             this.rootMap.set(rootPath, newRootObject);
             // Later entries for the same root (e.g. route summaries written one instance at a time)
             // apply to the root just created
@@ -119,6 +124,15 @@ export class ReadStore {
         }
         ObservableNode.ApplyDiff(rootObject, results);
     }
+    CreateRootNode(rootPath, data, unwrap) {
+        const result = this.createNode({ [rootPath]: this.opaque.has(rootPath) ? Box(data) : data }, unwrap);
+        const rootPathStr = rootPath.toString();
+        if (this.watch.some(pattern => PatternMatches(pattern, rootPathStr)))
+            ObservableNode.WatchProperty(result, rootPath, (event) => {
+                this.watchCallback(rootPathStr, event);
+            });
+        return result;
+    }
 }
 /**
  * Base class for observable data store management.

package/Store/Store/storeAsync.d.ts

@@ -8,6 +8,16 @@ export interface IStoreAsyncOptions extends IStoreOptions {
      * `keyFunc`, include the entity roots the received roots refer to.
      */
     roots?: readonly string[];
+    /**
+     * Root keys the store receives only while something reads them: exact keys and patterns ending
+     * in `*`. A demand root is subscribed on its own once a reactive scope reads it with `Get` (or
+     * `Hold` holds it), and released `demandDebounce` ms after its last reader goes: unsubscribed and
+     * deleted from the store. Until its first post arrives it reads as its default. Needs `roots`:
+     * a store that receives every root has none left to demand. A key `roots` names is a `roots` root.
+     */
+    demand?: readonly string[];
+    /** How long a demand root no one reads stays subscribed, in ms; default 1000 */
+    demandDebounce?: number;
 }
 /**
  * StoreAsync class extends the base Store class to provide asynchronous data management operations.
@@ -23,6 +33,11 @@ export interface IStoreAsyncOptions extends IStoreOptions {
  *   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
@@ -76,6 +91,18 @@ export declare class StoreAsync extends Store {
     private currentBatchPromise;
     /** Batches not yet acknowledged, for `Flush` */
     private inFlight;
+    /** Demand roots a reactive scope reads now, from their watchers */
+    private readonly demandRead;
+    /** `Hold`s, by demand root */
+    private readonly demandHolds;
+    /** A subscription for each demand root the store holds */
+    private readonly demandSubscriptions;
+    /** The release timers of demand roots no one reads, by key */
+    private readonly demandReleasing;
+    /** Demand roots whose readers or holds changed since the last flush */
+    private readonly demandChanged;
+    private demandFlushQueued;
+    private destroyed;
     /**
      * 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
@@ -85,8 +112,8 @@ export declare class StoreAsync extends Store {
      *   (`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 sent to the tree before the store subscribes; over a lease, share it with the tree
-     *   (`IObservableDiffTreeConfig.opaque`) from a file both import.
+     *   `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(channel: IChannel | IWorkerLease, options?: IStoreAsyncOptions);
@@ -99,6 +126,33 @@ export declare class StoreAsync extends Store {
      */
     private Restarted;
     private Connect;
+    /**
+     * 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: string): () => void;
+    private IsRootsKey;
+    private IsDemandKey;
+    /**
+     * 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.
+     */
+    private DemandWatched;
+    private DemandChanged;
+    /**
+     * 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.
+     */
+    private FlushDemand;
+    private IsDemanded;
+    private SubscribeDemand;
+    private ReleaseLater;
+    /** Unsubscribes a demand root and deletes it from the store, so no later reader sees it stale */
+    private ReleaseDemand;
     /** Applies a post. A tree's first state is diffed into the roots in place, its deletes with it. */
     private Apply;
     private Schedule;

package/Store/Store/storeAsync.js

@@ -1,6 +1,11 @@
 import { AsyncQueue } from "../../Utils/asyncQueue";
+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.
@@ -15,6 +20,11 @@ import { RootOf, Store } from "./store";
  *   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
@@ -61,22 +71,36 @@ export class StoreAsync extends Store {
      *   (`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 sent to the tree before the store subscribes; over a lease, share it with the tree
-     *   (`IObservableDiffTreeConfig.opaque`) from a file both import.
+     *   `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(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);
+        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();
         /** 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)
@@ -97,11 +121,113 @@ export class StoreAsync extends Store {
         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) {
-        const client = new ChannelClient(channel);
-        this.options.opaque && this.options.opaque.length > 0 && client.MarkOpaque(this.options.opaque);
-        return client;
+        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) {
@@ -221,9 +347,16 @@ export class StoreAsync extends Store {
      * channel stays open: whoever created the worker terminates it.
      */
     Destroy() {
+        this.destroyed = true;
         this.stopLease?.();
         this.asyncQueue.Stop();
         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();
     }

package/Store/Store/storeSync.d.ts

@@ -1,3 +1,4 @@
+import type { EmitterEvent } from "../../Utils/emitter";
 import type { ILocalLease } from "../Diff/diffTree.types";
 import { ObservableDiffTree } from "../Diff/observableDiffTree";
 import { IStoreOptions, Store } from "./store";
@@ -8,6 +9,18 @@ export interface IStoreSyncOptions extends IStoreOptions {
      * 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.
@@ -81,11 +94,13 @@ export declare class StoreSync extends Store {
      *     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` and `opaque` (`IStoreSyncOptions`). `keyFunc` is for the tree the
+     * @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.
+     * @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);
     /**

package/Store/Store/storeSync.js

@@ -60,11 +60,13 @@ export class StoreSync extends Store {
      *     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` and `opaque` (`IStoreSyncOptions`). `keyFunc` is for the tree the
+     * @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.
+     * @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;
@@ -72,7 +74,7 @@ export class StoreSync extends Store {
             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);
+        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;

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

package/Store/Tree/observableNode.js

@@ -416,6 +416,25 @@ export var ObservableNode;
         return DefaultCreateProxy(value, unwrapValue);
     }
     ObservableNode.Create = Create;
+    function WatchProperty(proxy, prop, callback) {
+        if (!proxy[IS_NODE])
+            throw new Error("Parameter proxy is not an ObservableNode");
+        const wrapper = proxy[NODE_WRAPPER];
+        if (Array.isArray(wrapper))
+            throw new Error("Unable to watch individual property on array proxy");
+        const scope = GetPropertyScope(wrapper, prop);
+        ObservableScope.WatchSubscribers(scope, callback);
+    }
+    ObservableNode.WatchProperty = WatchProperty;
+    function UnwatchProperty(proxy, prop, callback) {
+        if (!proxy[IS_NODE])
+            throw new Error("Parameter proxy is not an ObservableNode");
+        const wrapper = proxy[NODE_WRAPPER];
+        if (Array.isArray(wrapper))
+            return;
+        Object.hasOwn(wrapper, prop) && ObservableScope.UnwatchSubscribers(wrapper[prop], callback);
+    }
+    ObservableNode.UnwatchProperty = UnwatchProperty;
     /**
      * 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

package/Store/Tree/observableScope.d.ts

@@ -1,4 +1,4 @@
-import { Emitter, EmitterCallback } from "../../Utils/emitter";
+import { Emitter, EmitterCallback, EmitterEventCallback } from "../../Utils/emitter";
 /**
  * Represents a static (non-reactive) observable scope.
  * Static scopes are immutable and do not track dependencies or emit updates.
@@ -189,6 +189,8 @@ export declare namespace ObservableScope {
      * @param callback The callback function to remove.
      */
     function Unwatch<T>(scope: IObservableScope<T> | IBasicObservableScope<T>, callback: (scope: IObservableScope<T>) => void): void;
+    function WatchSubscribers<T = any>(scope: IObservableScope<T> | IBasicObservableScope<T>, callback: EmitterEventCallback): void;
+    function UnwatchSubscribers<T = any>(scope: IObservableScope<T> | IBasicObservableScope<T>, callback: EmitterEventCallback): void;
     /**
      * Registers a callback to be invoked when the scope's value is updated.
      * Only applies to dynamic scopes; no-op for static scopes.

package/Store/Tree/observableScope.js

@@ -639,6 +639,18 @@ export var ObservableScope;
         Emitter.Remove(scope.emitter, callback);
     }
     ObservableScope.Unwatch = Unwatch;
+    function WatchSubscribers(scope, callback) {
+        if (!scope || scope.destroyed || scope.type === "static")
+            return;
+        Emitter.Watch(scope.emitter, callback);
+    }
+    ObservableScope.WatchSubscribers = WatchSubscribers;
+    function UnwatchSubscribers(scope, callback) {
+        if (!scope || scope.destroyed || scope.type === "static")
+            return;
+        Emitter.Unwatch(scope.emitter, callback);
+    }
+    ObservableScope.UnwatchSubscribers = UnwatchSubscribers;
     /**
      * Registers a callback to be invoked when the scope's value is updated.
      * Only applies to dynamic scopes; no-op for static scopes.

package/Utils/emitter.d.ts

@@ -1,9 +1,16 @@
+export declare enum EmitterEvent {
+    SUBSCRIBED = 0,
+    UNSUBSCRIBED = 1
+}
+export type EmitterEventCallback = (event: EmitterEvent, emitter: Emitter) => void;
 export type EmitterCallback<T extends readonly any[] = any[]> = (...args: T) => void;
-export type Emitter = [[number, number], ...EmitterCallback[]];
+export type Emitter<T extends readonly any[] = any[]> = [[number, number, Emitter<[EmitterEvent, Emitter]> | undefined], ...EmitterCallback<T>[]];
 export declare namespace Emitter {
-    function Create(): Emitter;
-    function On(emitter: Emitter, callback: EmitterCallback): void;
-    function Emit(emitter: Emitter, ...args: any[]): void;
+    function Create<T extends any[] = any[]>(): Emitter<T>;
+    function On<T extends any[]>(emitter: Emitter<T>, callback: EmitterCallback<T>): void;
+    function Watch(emitter: Emitter, callback: EmitterCallback<[EmitterEvent, Emitter]>): void;
+    function Unwatch(emitter: Emitter, callback: EmitterCallback<[EmitterEvent, Emitter]>): void;
+    function Emit<T extends any[]>(emitter: Emitter<T>, ...args: T): void;
     function Remove(emitter: Emitter, callback: EmitterCallback): void;
     function Clear(emitter: Emitter): void;
 }

package/Utils/emitter.js

@@ -1,4 +1,9 @@
 import { _requestIdleCallback } from "./scheduling";
+export var EmitterEvent;
+(function (EmitterEvent) {
+    EmitterEvent[EmitterEvent["SUBSCRIBED"] = 0] = "SUBSCRIBED";
+    EmitterEvent[EmitterEvent["UNSUBSCRIBED"] = 1] = "UNSUBSCRIBED";
+})(EmitterEvent || (EmitterEvent = {}));
 const pendingCompactEmitters = new Set();
 function Compact(emitter) {
     if (emitter.length === 1 || emitter[0][0] === 0)
@@ -29,13 +34,26 @@ function CompactEmitter(emitter) {
 export var Emitter;
 (function (Emitter) {
     function Create() {
-        return [[0, -1]];
+        return [[0, -1, undefined]];
     }
     Emitter.Create = Create;
     function On(emitter, callback) {
         emitter.push(callback);
+        if (emitter.length - emitter[0][0] === 2)
+            emitter[0][2] && Emitter.Emit(emitter[0][2], EmitterEvent.SUBSCRIBED, emitter);
     }
     Emitter.On = On;
+    function Watch(emitter, callback) {
+        emitter[0][2] ??= Emitter.Create();
+        On(emitter[0][2], callback);
+    }
+    Emitter.Watch = Watch;
+    function Unwatch(emitter, callback) {
+        if (!emitter[0][2])
+            return;
+        Remove(emitter[0][2], callback);
+    }
+    Emitter.Unwatch = Unwatch;
     // Re-entry during emit is not supported and considered a bug in client code
     function Emit(emitter, ...args) {
         if (emitter[0][1] !== -1)
@@ -73,11 +91,16 @@ export var Emitter;
             RemoveFromBeginning(emitter, index);
         else
             RemoveFromEnd(emitter, index);
+        if (emitter.length - emitter[0][0] === 1)
+            emitter[0][2] && Emitter.Emit(emitter[0][2], EmitterEvent.UNSUBSCRIBED, emitter);
     }
     Emitter.Remove = Remove;
     function Clear(emitter) {
-        emitter.length > 1 && emitter.splice(1);
+        if (emitter.length - emitter[0][0] === 1)
+            return;
+        emitter.splice(1);
         emitter[0][0] = 0;
+        emitter[0][2] && Emitter.Emit(emitter[0][2], EmitterEvent.UNSUBSCRIBED, emitter);
     }
     Emitter.Clear = Clear;
 })(Emitter || (Emitter = {}));

package/Utils/pattern.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Key patterns: an exact key, or a pattern ending in `*` that matches every key starting with the
+ * text before it (`task_*` matches `task_1`, and `task_` itself). A lone `*` matches every key.
+ * Store roots, subscriptions' key filters and route segments all match this way. The text is
+ * compared as it is: no character but a final `*` is special.
+ */
+/** A pattern's wildcard, its last character */
+export declare const WILDCARD = "*";
+/** Whether `pattern` is a pattern rather than an exact key: it ends in `*` */
+export declare function IsPattern(pattern: string): boolean;
+/** The text a pattern's keys start with: the pattern without its `*` */
+export declare function PatternPrefix(pattern: string): string;
+/** Whether `key` matches `pattern`: it is the exact key, or starts with the pattern's prefix */
+export declare function PatternMatches(pattern: string, key: string): boolean;

package/Utils/pattern.js

@@ -0,0 +1,20 @@
+/**
+ * Key patterns: an exact key, or a pattern ending in `*` that matches every key starting with the
+ * text before it (`task_*` matches `task_1`, and `task_` itself). A lone `*` matches every key.
+ * Store roots, subscriptions' key filters and route segments all match this way. The text is
+ * compared as it is: no character but a final `*` is special.
+ */
+/** A pattern's wildcard, its last character */
+export const WILDCARD = "*";
+/** Whether `pattern` is a pattern rather than an exact key: it ends in `*` */
+export function IsPattern(pattern) {
+    return pattern.endsWith(WILDCARD);
+}
+/** The text a pattern's keys start with: the pattern without its `*` */
+export function PatternPrefix(pattern) {
+    return pattern.slice(0, -WILDCARD.length);
+}
+/** Whether `key` matches `pattern`: it is the exact key, or starts with the pattern's prefix */
+export function PatternMatches(pattern, key) {
+    return IsPattern(pattern) ? key.startsWith(PatternPrefix(pattern)) : pattern === key;
+}

package/Utils/subscriptionManager.js

@@ -1,4 +1,4 @@
-const WILDCARD = "*";
+import { IsPattern, PatternMatches, PatternPrefix } from "./pattern";
 /**
  * Subscriptions to keys, for any use: it matches keys to subscriptions and counts who holds a
  * key, and knows nothing about what a key's value is or how it's delivered.
@@ -34,8 +34,8 @@ export class SubscriptionManager {
         if (keys)
             for (let x = 0; x < keys.length; x++) {
                 const key = keys[x];
-                if (key.endsWith(WILDCARD))
-                    entry.prefixes.push(key.slice(0, -1));
+                if (IsPattern(key))
+                    entry.prefixes.push(PatternPrefix(key));
                 else
                     entry.exact.add(key);
             }
@@ -153,9 +153,6 @@ function Matches(entry, key) {
             return true;
     return false;
 }
-function PatternMatches(pattern, key) {
-    return pattern.endsWith(WILDCARD) ? key.startsWith(pattern.slice(0, -1)) : pattern === key;
-}
 function Remove(list, item) {
     const index = list.indexOf(item);
     index >= 0 && list.splice(index, 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "j-templates",
-  "version": "10.0.0",
+  "version": "10.0.1",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",