j-templates 8.0.15 → 8.0.17

package/SYNTAX_PRIMER.md

@@ -1,6 +1,6 @@
-# j-templates Syntax Primer — v4
+# j-templates Syntax Primer — v5
 
-Complete reference for the **j-templates** framework syntax. This documents **j-templates v7.0.98** (see `package.json`). For pattern-oriented guides, see `docs/patterns/`; for step-by-step tutorials, see `docs/tutorials/`.
+Complete reference for the **j-templates** framework syntax. This documents **j-templates v8.0.16** (see `package.json`). For pattern-oriented guides, see `docs/patterns/`; for step-by-step tutorials, see `docs/tutorials/`.
 
 > **Core concepts:** Components define UI via `Template()`. State decorators (`@Value`, `@State`, `@Computed`) enable reactivity. DOM functions (`div()`, `button()`) create virtual nodes. No compile step, minimal dependencies.
 
@@ -1339,42 +1339,59 @@ class Child extends Component {
 
 Both stores share the same API and flattening model, but differ fundamentally in where and how diffing occurs.
 
-**StoreSync** computes diffs synchronously on the main thread. Writes are immediate and consistent — a value written is readable in the same tick. It has no worker overhead, no serialisation constraints, and no `Destroy()` requirement. Use StoreSync for the vast majority of application state: user data, UI state, app config, form data, and any dataset where diff computation is not a bottleneck. `@Computed` uses `StoreSync` internally.
+**StoreSync** computes diffs synchronously on the main thread. Writes are immediate and consistent — a value written is readable in the same tick. It has no worker overhead and no `Destroy()` requirement. Use StoreSync for the vast majority of application state: user data, UI state, app config, form data, and any dataset where diff computation is not a bottleneck. `@Computed` uses `StoreSync` internally.
 
-**StoreAsync** offloads all diff computation to a dedicated Web Worker via a serialised message queue, computing minimal diffs off the main thread so large dataset operations don't block rendering or input. Use StoreAsync when diffing genuinely large or deeply nested datasets — message feeds, large tables, real-time data. `@ComputedAsync` uses `StoreAsync` internally.
+**StoreAsync** runs diff computation on a `Worker` you supply, off the main thread, so large dataset operations don't block rendering or input. Use StoreAsync when diffing genuinely large or deeply nested datasets — message feeds, large tables, real-time data. `@ComputedAsync` uses `StoreAsync` internally, with a shared prebuilt worker.
 
 **If you are unsure which to use, start with StoreSync.** StoreAsync introduces meaningful constraints (see below) that are only worth accepting when the dataset size justifies off-thread diffing.
 
 | Aspect | StoreSync | StoreAsync |
 |--------|-----------|------------|
-| Diff execution | Main thread, synchronous | Web Worker, asynchronous |
+| Diff execution | Main thread, synchronous | Caller-supplied `Worker`, asynchronous |
 | Write consistency | Immediate — readable same tick | Eventual — must `await` before reading |
-| `keyFunc` constraint | None — can close over outer scope | **Must be self-contained** — serialised and executed in worker |
-| Data constraint | Any JS value | **JSON-serialisable only** — no class instances, methods, `Date`, `Map`, `Set`, circular refs |
-| `Destroy()` required | No | Yes — terminates worker and queue |
+| Construction | `new StoreSync(keyFunc?, projections?)` | `new StoreAsync(diffWorker, keyFunc?)` — the worker is built separately (see below) |
+| `keyFunc`/projections used for diffing | Passed straight to the constructor, can close over outer scope | Must be baked into the worker's own entry file — the constructor's `keyFunc` only resolves aliases locally, on the main thread |
+| Data constraint | Any JS value | **JSON-serialisable only** — no class instances, methods, `Date`, `Map`, `Set`, circular refs (carried over `postMessage`'s structured clone) |
+| `Destroy()` required | No | Yes — terminates the worker and queue |
 | Best for | Most app state | Large / real-time datasets |
 | Decorator backend | `@Computed` | `@ComputedAsync` |
 
-### StoreAsync Constraints
+### StoreAsync: Supplying the Worker
 
-StoreAsync's worker is bootstrapped by serialising `keyFunc` and the diff engine and executing them in a worker context. This has two hard constraints:
+`StoreAsync` doesn't build or serialize a worker itself anymore — you construct a real `Worker` (a bundler-built module, not a Blob) and hand it in. Internally, a worker becomes usable by connecting a `DiffTree` to it with `ConnectWorkerToDiffTree`; that's what a worker *entry file* does.
 
-**1. `keyFunc` must be self-contained — no closed-over variables.**
+**Most portable option — write your own tiny entry file.** This always works regardless of bundler, because it's a relative import inside your own source tree, exactly like any other bundler-built worker:
 
-The function is serialised and evaluated in the worker context. Any variable from the outer scope will be undefined inside the worker.
+```typescript
+// diff-worker.ts — a separate entry file; your bundler compiles it as its own chunk
+import { DiffTree } from "j-templates/Store/Diff/diffTree";
+import { ConnectWorkerToDiffTree } from "j-templates/Store/Diff/diffTreeWorker";
+
+const diffTree = new DiffTree(/* keyFunc, projections — see below */);
+ConnectWorkerToDiffTree(diffTree, self as any as Worker);
+```
 
 ```typescript
-// ❌ Breaks at runtime — prefix is not accessible in the worker
-const prefix = "user";
-const store = new StoreAsync((val) => val?.id ? `${prefix}_${val.id}` : undefined);
+// wherever you construct the store
+import { StoreAsync } from "j-templates/Store";
+
+const worker = new Worker(new URL("./diff-worker.ts", import.meta.url), { type: "module" });
+const store = new StoreAsync(worker, keyFunc); // pass the same keyFunc for local alias resolution
+```
 
-// ✅ Self-contained — no outer scope references
-const store = new StoreAsync((val) => val?.id ? `user_${val.id}` : undefined);
+**No custom `keyFunc`/projections needed?** The package ships a ready no-argument entry file, `defaultDiffTreeWorker.js`, which is what `@ComputedAsync` builds internally (see `src/Utils/decorators.ts`) via a relative import from inside the package itself:
+
+```typescript
+const worker = new Worker(
+  new URL("../Store/Diff/defaultDiffTreeWorker.js", import.meta.url),
+  { type: "module" },
+);
+const store = new StoreAsync(worker);
 ```
 
-**2. All data must be JSON-serialisable.**
+That relative path only resolves correctly from *inside* the installed package (it's relative to the file doing the importing), so from your own app code, writing your own entry file (above) is the reliable choice.
 
-The worker communicates via `postMessage`, which uses the structured clone algorithm. Class instances with methods, `Date` objects, `Map`, `Set`, `undefined` values, and circular references will be lost or throw.
+Because the worker module runs in its own realm, its `keyFunc`/projections can only close over things defined in that file — there's no shared runtime state with the main thread, and nothing is serialised with `.toString()`/`eval` (unlike older versions of this library). Data crossing the worker boundary, via `postMessage`, still goes through the structured clone algorithm, so it must be JSON-serialisable:
 
 ```typescript
 // ❌ Methods and class instances are stripped by structured clone
@@ -1392,6 +1409,7 @@ class Store {
   constructor(keyFunc?: (value: any) => string | undefined);
   Get<O>(id: string): O | undefined;        // Returns undefined if not found
   Get<O>(id: string, defaultValue: O): O;   // Creates and returns default if not found
+  Has(id: string): boolean;                 // Whether a root object exists for id
 }
 ```
 
@@ -1399,6 +1417,7 @@ class Store {
 
 ```typescript
 class StoreSync extends Store {
+  constructor(keyFunc?: (value: any) => string | undefined, projections?: DiffTreeProjectionMap);
   Write(data: unknown, key?: string): void;
   Patch(key: string, patch: unknown): void;       // Deep merge; throws if key not found
   Push(key: string, ...data: unknown[]): void;
@@ -1411,14 +1430,39 @@ class StoreSync extends Store {
 
 ```typescript
 class StoreAsync extends Store {
+  constructor(diffWorker: Worker, keyFunc?: (value: any) => string | undefined);
   async Write(data: unknown, key?: string): Promise<void>;
   async Patch(key: string, patch: unknown): Promise<void>;  // Deep merge; throws if key not found
   async Push(key: string, ...data: unknown[]): Promise<void>;
   async Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): Promise<unknown[]>;
-  Destroy(): void;  // Always call when service is destroyed — terminates worker
+  Destroy(): void;  // Always call when service is destroyed — terminates the worker
 }
 ```
 
+### Projections — Derived Values Computed Inside the Store
+
+A projection is a derived value the store computes for you and stores alongside your written data, readable through `Get` like anything else. Declare a map of them at construction (`StoreSync`'s second argument; for `StoreAsync`, baked into the worker's `DiffTree` as shown above):
+
+```typescript
+import { StoreSync } from "j-templates/Store";
+import { PROJECTION_PREFIX } from "j-templates/Store/Diff/diffTree";
+
+const store = new StoreSync((value: any) => value?.id, {
+  activeCount: {
+    reads: ["todos"],
+    projection: (keys: string[], todos: Todo[]) => todos.filter((t) => !t.completed).length,
+  },
+});
+
+store.Write(todos, "todos");
+store.Get<number>(`${PROJECTION_PREFIX}activeCount`); // "$projection_activeCount"
+```
+
+- `reads` is a list of dot-separated paths: a plain tree path (`"todos"`), a keyed entity's id (whatever `keyFunc` returns for it), or another projection's output via `` `${PROJECTION_PREFIX}otherId` `` (i.e. `"$projection_otherId"`) — chaining. The dependency graph is topologically sorted at construction, so a cycle (or a read of an unregistered id) throws immediately rather than on first write.
+- `projection` is called as `(keys, ...values)` — every resolved read path, then each value positionally in the same order as `reads`.
+- The final `reads` entry may instead be a wildcard root prefix (e.g. `"task_*"`, no dot nesting) — every root key with that prefix is read and appended as its own trailing key/value pair, so `projection` receives one extra `(key, value)` pair per match. Only the last read may be a wildcard, and it can't target a projection's `$projection_<id>` key.
+- A projection only runs once every one of its `reads` resolves — a path never written, an entity never seen, or a projection that hasn't produced a value yet blocks it (and blocks anything chaining off it). It re-runs whenever a read's resolved value changes, and its result is diffed and applied in place like any other write, so only the fields that actually changed reach reactive readers.
+
 ### keyFunc and Automatic Flattening
 
 `keyFunc` teaches the store how to extract an ID from any object. On `Write` and `Push`, the store eagerly recurses the entire object tree, calling `keyFunc` on each node. Any node that returns a valid ID is registered as an independently addressable entry in the flat internal map. The original shape is preserved because stored objects are `ObservableNode` proxies — nested objects are virtual getters into the flat map rather than copies, which is what allows `Get` to return the original structure while `Patch` operates on individual entries.
@@ -1462,7 +1506,7 @@ If an object has no `id` property (or `keyFunc` returns `undefined`), it is stor
 | Splice | sync | async (Promise) |
 | Get | sync | sync |
 | Destroy | N/A | `Destroy(): void` — required |
-| keyFunc constraint | None | Self-contained, no closed-over vars |
+| Construction | `keyFunc`/`projections` args | `diffWorker` (required) + local `keyFunc` |
 | Data constraint | Any JS value | JSON-serialisable only |
 
 ---
@@ -1499,9 +1543,12 @@ scope whose value doesn't derive from reactive state, use `Basic` instead, which
 ### Service Patterns
 
 ```typescript
-// Derived state in services
+// Derived state in services — worker built once, e.g. in a module-level helper
+// (see "StoreAsync: Supplying the Worker" above for how diff-worker.ts is written)
+const worker = new Worker(new URL("./diff-worker.ts", import.meta.url), { type: "module" });
+
 class DataService implements IDestroyable {
-  private store = new StoreAsync((value) => value.id);
+  private store = new StoreAsync(worker, (value) => value.id);
   private derived = ObservableScope.Create(() => {
     const items = this.store.Get<Item[]>("items", []);
     return ObservableNode.Unwrap(items).filter(i => i.active);
@@ -1531,6 +1578,7 @@ namespace ObservableNode {
   Create<T>(value: T): T;                                       // Wrap in reactive proxy
   Unwrap<T>(value: T): T;                                      // Get raw value from proxy
   Clone<T>(value: T): T;                                        // Strip proxies into plain data (mutates plain objects in place)
+  Snapshot<T>(proxy: T): T | undefined;                         // Immutable cached plain-value snapshot of a node
   Update(value: unknown, prop?: string | number): void;         // Manually trigger change on a node/property
   Apply(rootNode: any, value: any): void;                       // Merge a full value in-place, preserving identity (public)
   ApplyDiff(rootNode: any, diffResult: JsonDiffResult): void;   // Apply diff in-place (internal — used by Store/@Computed)
@@ -1540,6 +1588,8 @@ namespace ObservableNode {
 
 **`Apply` vs `ApplyDiff`:** `Apply(rootNode, value)` merges a full replacement value into an observable node in-place, preserving the node's reference (so `===` checks and DOM reuse stay stable). Use this when you want to update an observable node in place — assigning a property directly on an observable node does **not** generate a diff. `ApplyDiff` is internal-only (used by `StoreSync`/`StoreAsync`/`@Computed`) — ignore it.
 
+**`Snapshot` and `toJSON`.** `ObservableNode.Snapshot(proxy)` returns an immutable plain copy of a node's current value (arrays/objects only; keyed children are read through their root). The same snapshot is returned on repeated calls until a write invalidates it, and unchanged nested parts are shared between snapshots, so `===` holds for anything that hasn't changed — useful for cheap change detection or handing data to non-reactive code. Calling `.toJSON()` on an observable node (e.g. via `JSON.stringify`) returns this same cached snapshot.
+
 **Array operations on ObservableNode proxies:** `push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse` — all trigger reactive updates.
 
 ---
@@ -1568,7 +1618,7 @@ These are the subtle behaviors that cause the most bugs. Read this before writin
 10. **`@Computed` only tracks what the getter touches.** Returning `this.tasks` without reading item properties won't re-trigger on per-item mutations. Touch every property you track.
 11. **`scope()`/`gate()`/`peek()`/`mapped()` throw outside a watch context.** They must be called inside a children function, `data:`/`props:`/`attrs:` function, `@Scope`/`@Computed`/`@ComputedAsync` getter, or `@Watch` callback — not inside `on:` event handlers.
 12. **`Injector` is not publicly exported.** Use `@Inject` and `this.Injector` on components.
-13. **StoreAsync data must be JSON-serialisable** and `keyFunc` must be self-contained (no closed-over variables). Always `await` StoreAsync writes before reading.
+13. **StoreAsync data must be JSON-serialisable** (carried over `postMessage`'s structured clone), and `StoreAsync` now takes an already-running `Worker` as its first constructor argument — any `keyFunc`/projections needed for diffing must be baked into that worker's own entry file, not passed to `StoreAsync` directly. Always `await` StoreAsync writes before reading.
 14. **Two-way binding needs reactive props** (`props: () => ({ value })`). A static `props: { value }` object causes input focus loss.
 15. **The Destructuring Trap.** Reading a scope or `this.Data` at the top of `Template()` subscribes the whole component — the React instinct to hoist state reads is backwards here. Read scopes inside children functions or `data:` bindings for fine-grained updates. See Mental Model.
 16. **`scope()`/`gate()`/`peek()` ID collisions are per-scope.** Multiple calls to the same helper in one watch context without IDs silently resolve to the first scope. Provide distinct IDs when calling the same helper more than once in a single ObservableScope definition.
@@ -1645,12 +1695,13 @@ These are the subtle behaviors that cause the most bugs. Read this before writin
 | **ObservableNode** | A reactive proxy wrapper around objects/arrays that tracks property-level mutations |
 | **Injector** | Scoped dependency injection container with parent-chain resolution (not publicly exported) |
 | **keyFunc** | A function passed to Store that extracts an ID from objects for automatic flattening |
+| **Projection** | A derived value declared at Store construction (`reads` + a computing function), stored and read like any other data at `$projection_<id>` |
 
 ---
 
 ## References
 
-- **Source of truth:** `src/` (this primer documents `j-templates` v7.0.98).
+- **Source of truth:** `src/` (this primer documents `j-templates` v8.0.16).
 - **Pattern guides:** `docs/patterns/01-components.md`, `docs/patterns/02-reactivity.md`, `docs/patterns/03-templates-and-data.md`, `docs/patterns/04-dependency-injection.md`.
 - **Tutorials:** `docs/tutorials/` (01-getting-started through 08-building-complete-app).
 - **Worked example:** `examples/smart-tasks/src/` (the Smart Tasks app used above).

package/Store/Diff/diffAsync.d.ts

@@ -16,11 +16,10 @@ type IDiffTreeAsync = {
 export declare class DiffAsync implements IDiffTreeAsync {
     private workerQueue;
     /**
-     * Creates a DiffAsync instance and initializes the worker.
-     * @param keyFunc - Optional function to extract a key from objects
-     * @param projections - Optional map of derived-value projections, keyed by id. Each
-     *   projection's function is serialized with `.toString()` and `eval`'d back into a
-     *   function in the worker, the same mechanic used for `keyFunc`.
+     * Creates a DiffAsync instance around an already-running worker.
+     * @param diffWorker - A `Worker` running a `DiffTree` connected via
+     *   `ConnectWorkerToDiffTree` (e.g. a bundled `defaultDiffTreeWorker` entry, or a custom
+     *   entry file for a non-default `keyFunc`/`projections` baked into the worker thread).
      */
     constructor(diffWorker: Worker);
     /**

package/Store/Diff/diffAsync.js

@@ -8,11 +8,10 @@ import { WorkerQueue } from "./workerQueue";
  */
 export class DiffAsync {
     /**
-     * Creates a DiffAsync instance and initializes the worker.
-     * @param keyFunc - Optional function to extract a key from objects
-     * @param projections - Optional map of derived-value projections, keyed by id. Each
-     *   projection's function is serialized with `.toString()` and `eval`'d back into a
-     *   function in the worker, the same mechanic used for `keyFunc`.
+     * Creates a DiffAsync instance around an already-running worker.
+     * @param diffWorker - A `Worker` running a `DiffTree` connected via
+     *   `ConnectWorkerToDiffTree` (e.g. a bundled `defaultDiffTreeWorker` entry, or a custom
+     *   entry file for a non-default `keyFunc`/`projections` baked into the worker thread).
      */
     constructor(diffWorker) {
         this.workerQueue = new WorkerQueue(diffWorker);

package/Store/Diff/diffTree.d.ts

@@ -35,17 +35,24 @@ export interface IDiffTreeConstructor {
     }, projections?: DiffTreeProjectionMap): IDiffTree;
 }
 /**
- * A pure function computing a derived value from the current values at `reads`, passed
- * positionally in the same order, so each parameter can be typed at the call site instead of
- * cast out of a generic read.
+ * A pure function computing a derived value from the current values at `reads`. Called with
+ * the resolved read paths (`keys`) first, then each value positionally in the same order as
+ * `reads`, so each value parameter can be typed at the call site instead of cast out of a
+ * generic read. A trailing wildcard read expands to one key/value pair per matched root key,
+ * so `keys` lets the function tell which root each trailing value came from.
  */
-export type DiffTreeProjectionFunc = (...values: any[]) => any;
+export type DiffTreeProjectionFunc = (keys: string[], ...values: any[]) => any;
 /**
  * A projection's declaration: the dot-separated paths it reads (a plain tree path, an
  * entity's key, or another projection's `$projection_<id>` key for chaining) and the
  * function computing its result from their current values, positionally. Declaring `reads`
  * up front lets the tree topologically sort projections and reject a dependency cycle at
  * construction instead of on first write.
+ *
+ * The final entry in `reads` may instead be a wildcard root key (e.g. `"user_*"`, no dot
+ * nesting) matching every root key with that prefix; each match is read and passed to the
+ * projection as its own trailing key/value pair. A wildcard read can't be chained off a
+ * projection's `$projection_<id>` key and can't appear anywhere but last.
  */
 export type DiffTreeProjectionDefinition = {
     reads: string[];
@@ -67,9 +74,11 @@ export type DiffSpliceResult<T = unknown> = {
     diffResult: JsonDiffResult;
 };
 /**
- * Internal diff tree implementation.
- * Maintains root state and computes diffs for path/value updates.
- * @private
+ * Diff tree implementation. Maintains root state and computes diffs for path/value updates.
+ * Used directly by `DiffSync`, and is the building block for a `DiffAsync` worker entry
+ * file: construct one with the desired `keyFunc`/`projections` and connect it to the worker
+ * thread with `ConnectWorkerToDiffTree` (see `defaultDiffTreeWorker.ts` for the no-argument
+ * case, or a custom entry file when either is needed).
  */
 export declare class DiffTree {
     private keyFunc?;

package/Store/Diff/diffTree.js

@@ -146,6 +146,9 @@ function ChildSnapshot(source, keyFunc, parent, child) {
  * sequentially: a read of another projection's `$projection_<id>` output is a dependency
  * edge, so that projection is sorted earlier. Runs once, at construction, so a cycle (or a
  * read of an id that isn't registered) is rejected immediately instead of on first write.
+ * Also validates each projection's wildcard reads here, at construction: a wildcard must be
+ * the final read, must not have dot nesting, and can't target a projection's
+ * `$projection_<id>` key.
  */
 function BuildProjectionOrder(projections) {
     const order = [];
@@ -199,6 +202,11 @@ function BuildProjectionOrder(projections) {
  * makes a blocked dependency propagate for free: a projection that never runs never writes
  * `$projection_<id>`, so anything chaining off it stays blocked in turn.
  *
+ * A trailing wildcard read is expanded against the current root keys before the projection
+ * runs: every root key matching the prefix is read and appended as its own key/value pair,
+ * so the projection is called with `(keys, ...values)` where `keys` is every resolved read
+ * path (fixed reads first, then each matched wildcard key) positional with `values`.
+ *
  * @param source - The root tree object
  * @param keyFunc - Optional function to extract a key from objects, for reading through roots
  * @param projections - Dependency-sorted projection entries, from `BuildProjectionOrder`
@@ -211,27 +219,30 @@ function RunProjections(source, keyFunc, projections, memo) {
     for (let x = 0; x < projections.length; x++) {
         const { id, reads, projection } = projections[x];
         const values = [];
+        const keys = [];
         let allPathsExist = true;
         let y = 0;
         for (; allPathsExist && y < reads.length && !reads[y].endsWith("*"); y++) {
             const read = reads[y];
             const [value, found] = GetPathValue(source, read);
             allPathsExist = found;
-            values[y] = (found && CreateSnapshot(source, keyFunc, value)) || value;
+            keys.push(read);
+            values.push((found && CreateSnapshot(source, keyFunc, value)) || value);
         }
         if (y < reads.length && reads[y].endsWith("*")) {
             const prefix = reads[y].slice(0, reads[y].length - 1);
-            const keys = Object.keys(source).filter(key => key.startsWith(prefix));
-            for (let z = 0; z < keys.length; z++) {
-                const [value, found] = GetPathValue(source, keys[z]);
+            const matchedKeys = Object.keys(source).filter(key => key.startsWith(prefix));
+            for (let z = 0; z < matchedKeys.length; z++) {
+                const [value, found] = GetPathValue(source, matchedKeys[z]);
                 allPathsExist = allPathsExist && found;
+                keys.push(matchedKeys[z]);
                 values.push((found && CreateSnapshot(source, keyFunc, value)) || value);
             }
         }
         if (allPathsExist) {
             const priorValues = memo.get(id);
             if (!ArraysEqual(priorValues, values)) {
-                const result = projection(...values);
+                const result = projection(keys, ...values);
                 memo.set(id, values);
                 // The same diff-and-apply UpdateSource uses for any other write, so a keyed entity
                 // embedded in a projection's result is flattened to its own root like any other write,
@@ -333,9 +344,11 @@ function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc)
     return spliceResult;
 }
 /**
- * Internal diff tree implementation.
- * Maintains root state and computes diffs for path/value updates.
- * @private
+ * Diff tree implementation. Maintains root state and computes diffs for path/value updates.
+ * Used directly by `DiffSync`, and is the building block for a `DiffAsync` worker entry
+ * file: construct one with the desired `keyFunc`/`projections` and connect it to the worker
+ * thread with `ConnectWorkerToDiffTree` (see `defaultDiffTreeWorker.ts` for the no-argument
+ * case, or a custom entry file when either is needed).
  */
 export class DiffTree {
     /**

package/Store/Store/storeAsync.d.ts

@@ -9,8 +9,9 @@ import { Store } from "./store";
  * without blocking the main thread.
  *
  * @example
- * // Creating a StoreAsync instance
- * const store = new StoreAsync();
+ * // Creating a StoreAsync instance from a bundler-built worker entry file
+ * const worker = new Worker(new URL("./Store/Diff/defaultDiffTreeWorker.js", import.meta.url), { type: "module" });
+ * const store = new StoreAsync(worker);
  *
  * // Writing data to the store asynchronously
  * await store.Write({ name: "John", age: 30 }, "user");
@@ -44,18 +45,21 @@ export declare class StoreAsync extends Store {
     private queue;
     /**
      * Creates an instance of StoreAsync.
-     * @param keyFunc Optional function to generate a key for a given data value.
-     * @param projections Optional map of derived-value projections, keyed by id. A
-     * projection's result is readable through `Get` at `$projection_<id>`. Each projection's
-     * function is serialized with `.toString()` and `eval`'d back into a function in the
-     * worker, the same mechanic used for `keyFunc`, so it must not close over state that
-     * doesn't survive that round trip.
+     * @param diffWorker A `Worker` running a `DiffTree` connected via
+     *   `ConnectWorkerToDiffTree` (e.g. a bundled `defaultDiffTreeWorker` entry). Any
+     *   `keyFunc`/projections the diff needs must be baked into that worker's own entry file,
+     *   since the worker now runs standard bundled code rather than a serialized function.
+     * @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.
      */
     constructor(diffWorker: Worker, keyFunc?: (value: any) => string | undefined);
     /**
      * Returns a promise that resolve once all current queued writes have completed
      */
     Flush(): Promise<void>;
+    private nextWritePromise;
+    private nextWriteBatch;
     /**
      * Writes data to the store asynchronously.
      * This method ensures that write operations are queued and executed in a non-blocking manner.

package/Store/Store/storeAsync.js

@@ -12,8 +12,9 @@ import { Store } from "./store";
  * without blocking the main thread.
  *
  * @example
- * // Creating a StoreAsync instance
- * const store = new StoreAsync();
+ * // Creating a StoreAsync instance from a bundler-built worker entry file
+ * const worker = new Worker(new URL("./Store/Diff/defaultDiffTreeWorker.js", import.meta.url), { type: "module" });
+ * const store = new StoreAsync(worker);
  *
  * // Writing data to the store asynchronously
  * await store.Write({ name: "John", age: 30 }, "user");
@@ -37,12 +38,13 @@ import { Store } from "./store";
 export class StoreAsync extends Store {
     /**
      * Creates an instance of StoreAsync.
-     * @param keyFunc Optional function to generate a key for a given data value.
-     * @param projections Optional map of derived-value projections, keyed by id. A
-     * projection's result is readable through `Get` at `$projection_<id>`. Each projection's
-     * function is serialized with `.toString()` and `eval`'d back into a function in the
-     * worker, the same mechanic used for `keyFunc`, so it must not close over state that
-     * doesn't survive that round trip.
+     * @param diffWorker A `Worker` running a `DiffTree` connected via
+     *   `ConnectWorkerToDiffTree` (e.g. a bundled `defaultDiffTreeWorker` entry). Any
+     *   `keyFunc`/projections the diff needs must be baked into that worker's own entry file,
+     *   since the worker now runs standard bundled code rather than a serialized function.
+     * @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.
      */
     constructor(diffWorker, keyFunc) {
         super(keyFunc, false);
@@ -51,6 +53,8 @@ export class StoreAsync extends Store {
          * @private
          */
         this.queue = new AsyncQueue();
+        this.nextWritePromise = null;
+        this.nextWriteBatch = null;
         this.diff = new DiffAsync(diffWorker);
     }
     /**
@@ -67,13 +71,21 @@ export class StoreAsync extends Store {
      * @throws Will throw an error if no key is provided for the data.
      */
     async Write(data, key) {
-        await this.queue.Next(async () => {
-            key = key || this.keyFunc?.(data);
-            if (!key)
-                throw "No key provided for data";
-            const diffResult = await this.diff.DiffPath(key, data);
-            this.UpdateRootMap(diffResult);
+        const nextWriteBatch = this.nextWriteBatch ??= [];
+        const init = nextWriteBatch.length === 0;
+        nextWriteBatch.push({
+            path: key || this.keyFunc?.(data),
+            value: data
         });
+        if (init) {
+            this.nextWritePromise = this.queue.Next(async () => {
+                await Promise.resolve();
+                this.nextWriteBatch = null;
+                const diffResult = await this.diff.DiffBatch(nextWriteBatch);
+                this.UpdateRootMap(diffResult);
+            });
+        }
+        return this.nextWritePromise;
     }
     /**
      * Patches an existing value in the store with new data asynchronously.

package/Store/Tree/observableNode.d.ts

@@ -39,6 +39,14 @@ export declare namespace ObservableNode {
      * @returns A proxied version of the value that emits change events.
      */
     function Create<T>(value: T): T;
+    /**
+     * 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
+     * returned until a write invalidates it, and unchanged nested parts are shared between
+     * snapshots, so `===` holds for any part that hasn't changed.
+     * @param proxy The observable node to snapshot.
+     * @returns The snapshot, or `undefined` if `proxy` is not an observable node.
+     */
     function Snapshot<T>(proxy: T): T | undefined;
     /**
      * Marks an observable node or its property as changed, triggering reactive updates.
@@ -69,12 +77,24 @@ export declare namespace ObservableNode {
      * @remarks No-op when `value` deep-equals the node's current value (empty diff).
      */
     function Apply(rootNode: any, value: any): void;
+    /**
+     * Splices an observable node's underlying array in-place, invalidating its snapshot and
+     * touching its scope so reactive readers update.
+     * @param rootNode The observable array node to splice.
+     * @param start Index at which to start changing the array.
+     * @param deleteCount Number of elements to remove starting at `start`.
+     * @param items Elements to insert at `start`.
+     * @param cloneData Whether to deep-clone `items` before inserting them (true by default,
+     *   so the store isn't left holding a reference the caller can still mutate).
+     */
     function ApplySplice(rootNode: any, start: number, deleteCount: number, items: any[], cloneData?: boolean): void;
     /**
      * Applies a JSON diff result to an observable node, efficiently updating only changed properties.
      * Optimizes nested object updates by computing paths incrementally and touching modified properties.
      * @param rootNode The observable node to apply the diff to.
      * @param diffResult The diff result from JsonDiff containing path-value pairs of changes.
+     * @param cloneData Whether to deep-clone each diff value before writing it in (true by
+     *   default), so the store isn't left holding a reference the caller can still mutate.
      */
     function ApplyDiff(rootNode: any, diffResult: JsonDiffResult, cloneData?: boolean): void;
     /**

package/Store/Tree/observableNode.js

@@ -377,6 +377,14 @@ export var ObservableNode;
         return DefaultCreateProxy(value);
     }
     ObservableNode.Create = Create;
+    /**
+     * 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
+     * returned until a write invalidates it, and unchanged nested parts are shared between
+     * snapshots, so `===` holds for any part that hasn't changed.
+     * @param proxy The observable node to snapshot.
+     * @returns The snapshot, or `undefined` if `proxy` is not an observable node.
+     */
     function Snapshot(proxy) {
         if (proxy[IS_NODE])
             return proxy[NODE_SNAPSHOT];
@@ -453,6 +461,16 @@ export var ObservableNode;
         ApplyDiff(rootNode, diff);
     }
     ObservableNode.Apply = Apply;
+    /**
+     * Splices an observable node's underlying array in-place, invalidating its snapshot and
+     * touching its scope so reactive readers update.
+     * @param rootNode The observable array node to splice.
+     * @param start Index at which to start changing the array.
+     * @param deleteCount Number of elements to remove starting at `start`.
+     * @param items Elements to insert at `start`.
+     * @param cloneData Whether to deep-clone `items` before inserting them (true by default,
+     *   so the store isn't left holding a reference the caller can still mutate).
+     */
     function ApplySplice(rootNode, start, deleteCount, items, cloneData = true) {
         const root = rootNode[NODE_VALUE];
         InvalidateSnapshotForValue(rootNode[NODE_VALUE]);
@@ -466,6 +484,8 @@ export var ObservableNode;
      * Optimizes nested object updates by computing paths incrementally and touching modified properties.
      * @param rootNode The observable node to apply the diff to.
      * @param diffResult The diff result from JsonDiff containing path-value pairs of changes.
+     * @param cloneData Whether to deep-clone each diff value before writing it in (true by
+     *   default), so the store isn't left holding a reference the caller can still mutate.
      */
     function ApplyDiff(rootNode, diffResult, cloneData = true) {
         const root = rootNode[NODE_VALUE];

package/Store/Tree/observableScope.d.ts

@@ -140,7 +140,9 @@ export declare namespace ObservableScope {
      * Creates a lightweight basic scope that stores a value directly without a proxy.
      * Used by `@Value` for primitives. Basic scopes do not automatically track dependencies —
      * after creation, `ObservableScope.Update` must be called for the scope to emit. They also do
-     * not cache a value internally: the valueFunction is invoked on every read.
+     * not cache a value internally: the valueFunction is invoked on every read, with dependency
+     * tracking suspended, so any reactive value it reads is never registered as a dependency of
+     * whichever scope happened to be executing when the read occurred.
      * @template T The type of value stored in the scope.
      * @param valueFunction Function that returns the scope's value.
      * @returns A new basic observable scope.

package/Store/Tree/observableScope.js

@@ -565,7 +565,9 @@ export var ObservableScope;
      * Creates a lightweight basic scope that stores a value directly without a proxy.
      * Used by `@Value` for primitives. Basic scopes do not automatically track dependencies —
      * after creation, `ObservableScope.Update` must be called for the scope to emit. They also do
-     * not cache a value internally: the valueFunction is invoked on every read.
+     * not cache a value internally: the valueFunction is invoked on every read, with dependency
+     * tracking suspended, so any reactive value it reads is never registered as a dependency of
+     * whichever scope happened to be executing when the read occurred.
      * @template T The type of value stored in the scope.
      * @param valueFunction Function that returns the scope's value.
      * @returns A new basic observable scope.

package/package.json

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