j-templates 8.0.26 → 8.0.28

package/SYNTAX_PRIMER.md

@@ -1,14 +1,14 @@
 # j-templates Syntax Primer
 
-Oct 3, 2026 · @Jay Landrum
+Oct 13, 2026 · @Jay Landrum
 
-Reference for building apps with j-templates 8.0.21. Every behavioral claim was checked by running the library in jsdom; claims taken from type declarations or source alone are marked as such.
+Reference for building apps with j-templates 8.0.27. Every behavioral claim was checked by running the library in jsdom; claims taken from type declarations or source alone are marked as such.
 
 ## How to use this document
 
 Read Mental model, then Templates and State decorators before writing a component. Check the Traps checklist before shipping.
 
-- **Version:** j-templates 8.0.21. The 8.0.19 claims were tested in jsdom with TypeScript (`experimentalDecorators`). 8.0.21 changed `peek`, how `@Computed` notifies readers, and emitter re-entry; those sections were re-verified against 8.0.21 in jsdom.
+- **Version:** j-templates 8.0.27. The 8.0.19 claims were tested in jsdom with TypeScript (`experimentalDecorators`). 8.0.21 changed `peek`, how `@Computed` notifies readers, and emitter re-entry. 8.0.23 moved `Bound()` after the first render and added `Connected()`. 8.0.24 fixed dotted projection reads through keyed entities. 8.0.27 batches `StoreAsync` changes. Each of those sections was re-verified in jsdom against the version that changed it.
 - **Not verified:** a real browser `Worker` (a structured-clone shim stood in), real focus behavior, and the `docs/`, `examples/` and `src/` folders the package does not ship.
 - **Convention:** `this.x` in examples is a component field decorated with `@Value` or `@State` unless shown otherwise. Imports are omitted after the first example.
 
@@ -102,20 +102,27 @@ Component.Attach(document.getElementById("app")!, counter({}));
 **Members:**
 
 - `Template(): vNode | vNode[]` — override to render. May return an array. Not overriding renders an empty host.
-- `Bound()` / `Destroy()` — optional overrides. If you override either, call `super.Bound()` / `super.Destroy()`. `super.Bound()` starts `@Watch`; `super.Destroy()` tears down scopes and runs `@Destroy` properties.
+- `Bound()` / `Connected()` / `Destroy()` — optional overrides. If you override `Bound()` or `Destroy()`, call `super.Bound()` / `super.Destroy()`. `super.Bound()` starts `@Watch`; `super.Destroy()` tears down scopes and runs `@Destroy` properties. The base `Connected()` is empty.
 - `Fire(event, payload?)` — sends a component event to the parent's `on:` handler. The payload is optional.
-- `this.Data`, `this.Templates`, `this.Injector`, `this.VNode` (host vNode; `this.VNode.node` is the host element), `this.Destroyed`.
+- `this.Data`, `this.Templates`, `this.Injector`, `this.VNode` (host vNode; `this.VNode.node` is the host element), `this.IsConnected`, `this.Destroyed`.
 - Never override the constructor. Use field initializers and `Bound()`.
 
-**Lifecycle (verified order):**
+**Lifecycle (verified order, 8.0.23+):**
 
 1. Field initializers run.
-2. `Bound()` runs. The host element exists but is **not in the document and has no children**. `@Watch` handlers fire here with their initial values.
-3. `Template()` runs.
-4. Children functions run and build the DOM. By default this happens **after** `Attach` returns; with `SYNC_SCHEDULING=true`, before.
-5. The host is in the document.
+2. `Template()` runs and its children functions build the DOM. Child components go through their own steps 1–3 here, so a child's `Bound()` runs before its parent's.
+3. `Bound()` runs once the initial subtree is in the host: `querySelector` on the host finds rendered elements, including a child component's content. `@Watch` handlers fire inside `super.Bound()` with their initial values, so they can use those elements too. Code placed before `super.Bound()` runs before the first `@Watch` call.
+4. `Connected()` runs once the host is first in the document, after `Bound()`. It runs parent first, then children. It fires once per component instance; a component that is removed and rendered again is a new instance and fires again.
 
-To touch rendered DOM from `Bound()`, defer with `requestAnimationFrame` or `setTimeout` (verified: host connected and children present by then). Attach native listeners to an element you render, not to the host.
+By default steps 2–4 happen **after** `Attach` returns; with `SYNC_SCHEDULING=true`, before.
+
+The host is in the document during `Bound()` only for the component passed to `Component.Attach(document.body, …)`. A child's host joins the document when its parent's children are placed, after the child's `Bound()`. So:
+
+- Find and wire up the elements you render in `Bound()`.
+- Put work that needs layout (measuring, sizes), focus, or the document in `Connected()`.
+- An element that a later change renders isn't there at `Bound()` or `Connected()`. Reach it from the code that renders it, or watch for it.
+
+`Connected()` only fires when j-templates itself puts a node in the document. A tree attached to a detached element never gets `Connected()`, even after you append that element to the document (verified). Attach native listeners to an element you render, not to the host.
 
 **Host element.** The name passed to `ToFunction` is the host's tag. `Template()` output renders inside it:
 
@@ -352,7 +359,7 @@ Tracked array methods: `push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `rev
 syncFilter(value: FilterType) { this.localFilter = value; }
 ```
 
-- Fires once in `super.Bound()` with the initial value, then on every change.
+- Fires once in `super.Bound()` with the initial value, then on every change. Since `Bound()` runs after the first render, that first call can use rendered elements.
 - Several synchronous writes in one tick produce one call with the latest value (`n = 1; n = 2; n = 3` → one call with `3`).
 - Without `super.Bound()` it never fires.
 - Use it for side effects and for copying parent `Data` into local `@Value` state. Don't use it to drive rendering; reads in templates are already reactive.
@@ -531,7 +538,7 @@ A store holds reactive data under string keys and diffs every write into existin
 | --- | --- | --- |
 | Constructor | `new StoreSync(keyFunc?, projections?)` | `new StoreAsync(worker, keyFunc?)` |
 | Diffing | main thread, synchronous | in the `Worker` you supply |
-| Writes | `void`; readable immediately | `Promise`; readable only after `await` |
+| Writes | `void`; readable immediately | `Promise`; batched per tick, readable only after `await` |
 | `Destroy()` | none | required; terminates the worker |
 | Backs | nothing (`@Computed` uses `ObservableNode` directly) | `@ComputedAsync` |
 
@@ -547,7 +554,7 @@ Push(key: string, ...items: unknown[]);      // append to the array at key
 Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]); // returns removed items
 ```
 
-`StoreAsync` has the same methods; the four writers return promises.
+`StoreAsync` has the same methods; the four writers return promises. It also has `Flush()` (see below).
 
 ### keyFunc and flattening
 
@@ -585,6 +592,13 @@ store.Destroy();      // when done
 
 Data crosses the worker boundary by structured clone. Class instances arrive as plain objects without their methods; functions cannot be sent. Store plain data.
 
+**Batching (8.0.27).** Every `Write`, `Patch`, `Push` and `Splice` made in the same tick goes to the worker as one message and is applied in call order. The worker runs projections once per batch, after the last change, not after each one. Verified: a `Write`, a `Push` and a `Patch` in one tick sent one message and ran a projection once.
+
+- You don't have to await a change before making the next one. `Patch`, `Push` and `Splice` accept a key whose `Write` is still pending, and `Patch` merges in the worker, on top of everything before it.
+- The pending-key check covers only the key passed to `Write`. Entities that `keyFunc` will flatten out of that write don't exist yet: `Patch("a", …)` right after an un-awaited `Write([{ id: "a" }], "todos")` rejects with `Key not found in store` (verified). Await the write first.
+- `await store.Flush()` waits for every change made before the call. Changes made after it go in a later batch.
+- **A failed change stops the store.** After any change fails in the worker (for example `Splice` on a value that isn't an array), every later `Write`, `Patch`, `Push`, `Splice` and `Flush` rejects with that same error (verified). Validate before writing; a store in this state has to be replaced.
+
 ### Projections
 
 A projection is a derived value the store computes and stores under `$projection_<name>`. Pass them as `StoreSync`'s second argument (for `StoreAsync`, to the worker's `DiffTree`).
@@ -605,6 +619,8 @@ store.Get<number>(`${PROJECTION_PREFIX}activeCount`);
 - The last read may be a root wildcard such as `"task_*"`: each matching root's key is added to `keys` and its value appended (verified: `[["task_1","task_2"], v1, v2]`).
 - A projection has no value until every read resolves. It re-runs when a read's value changes.
 - A cycle or a read of an undefined projection throws at construction.
+- A dotted read can pass through a keyed entity (`"doc.owner.name"`, where `owner` has an id). It reads the entity's own root, so a `Patch` to the entity reruns the projection with the new value (verified; before 8.0.24 such a read returned the stale embedded copy).
+- `StoreSync` and the `StoreAsync` worker run projections for you. `DiffTree.DiffPath`, `PatchPath`, `PushPath` and `SplicePath` don't (8.0.27): code that drives a `DiffTree` directly, such as a test, must call `tree.RunProjections()` after its writes (verified).
 
 ## ObservableScope and ObservableNode
 
@@ -895,7 +911,7 @@ Component.Attach(document.getElementById("app")!, app({}));
 9. **`@State` deep-tracks plain objects and arrays only**, not class instances, `Map` or `Set`.
 10. **`@Scope` has no equality check**; consumers re-run on every change of its inputs. `gate()` it if it returns a primitive.
 11. **`@Computed` returns a copy**, not the object the getter returned. Its identity changes only when the result's type changes or an object result loses a key.
-12. **`Bound()` runs before `Template()`**, with the host detached and empty. Defer DOM access with `requestAnimationFrame`. Forgetting `super.Bound()` silences `@Watch`.
+12. **`Bound()` runs after the first render**, but a child's host isn't in the document yet. Do layout and focus work in `Connected()`. Forgetting `super.Bound()` silences `@Watch`.
 13. **`@Watch` fires immediately** with the initial value, and coalesces synchronous changes into one call.
 14. **`scope()`, `gate()` and `mapped()` outside a scope throw**, including in `on:` handlers and inside `peek()` callbacks. `peek()` works anywhere.
 15. **Conditional `scope()`/`gate()` calls need ids**, or a later call takes a skipped call's scope. Callbacks are fixed at first run: don't close over locals.
@@ -904,7 +920,7 @@ Component.Attach(document.getElementById("app")!, app({}));
 18. **Native DOM listeners belong on elements you render**, not the host.
 19. **`svg()` is HTML-namespace.** Use namespaced components or `innerHTML` for SVG.
 20. **`ObservableScope.Create` with no reactive reads is static** and ignores `Update()`. Use `Basic`.
-21. **`StoreAsync` writes must be awaited**; data crosses by structured clone (class methods are lost).
+21. **`StoreAsync` writes must be awaited** before reading; data crosses by structured clone (class methods are lost). Changes in one tick are batched, and one failed change makes every later change reject.
 22. **The package needs a bundler or TypeScript runner**; plain Node cannot import it.
 
 23) **Equal-value writes still notify.** Assigning the current value again re-runs every reader. Guard repeated writes or read through `gate()`.
@@ -927,7 +943,9 @@ Component.Attach(document.getElementById("app")!, app({}));
 | `gate()` doesn't stop re-runs | gated value is a new object/array each time | gate a primitive, or use `@Computed` |
 | Async value never resolves (shows a Promise) | callback lacks `async` | `async () => …` |
 | Async value doesn't refresh | reactive read after `await` | read before the first `await` |
-| `querySelector` in `Bound()` finds nothing | children not built yet | `requestAnimationFrame(() => …)` |
+| `querySelector` in `Bound()` finds nothing | the element is rendered later by a change, not by the first render | reach it where it's rendered, or watch for it |
+| Measured size is 0, or `focus()` does nothing, in `Bound()` | the host isn't in the document yet | move the work to `Connected()` |
+| `Connected()` never fires | the tree was attached to a detached element and appended later | attach to an element that's already in the document |
 | Manual service scope never updates | `ObservableScope.Create` with no reactive reads | `ObservableScope.Basic` |
 | Test sees old DOM after a write | asynchronous rendering | `SYNC_SCHEDULING=true` or await a timeout |
 | `ReferenceError: self is not defined` | importing `defaultDiffTreeWorker` on the main thread | write your own worker entry file |
@@ -935,19 +953,22 @@ Component.Attach(document.getElementById("app")!, app({}));
 | A watcher or scope over JSON.stringify/Snapshot never fires | snapshot reads register no dependencies | read properties directly, or JSON.stringify(ObservableNode.Clone(node)) |
 | `Emitter.Emit: re-entry during emit is not supported` | a `Watch`/`OnUpdated` callback updates the scope or value that is notifying it | defer the write, or move it out of the callback |
 | `scope() must be called within a watch context` inside `peek()` | tracking is off inside `peek` | call `scope()`/`gate()` outside the `peek` callback |
+| `Key not found in store` from `StoreAsync.Patch` right after a `Write` | the key is an entity id flattened out of a write that hasn't been applied yet | await the `Write` first |
+| Every `StoreAsync` change rejects with the same old error | an earlier change failed in the worker | fix that change; replace the store |
+| A test's projection never updates | the test drives a `DiffTree` directly | call `tree.RunProjections()` after each write |
 
 ## Corrections from the v5 primer
 
 For maintainers comparing against the previous `SYNTAX_PRIMER.md`. Builders can skip this section.
 
-| Previous claim | Observed in 8.0.18 and 8.0.19 |
+| Previous claim | Observed (8.0.18 and 8.0.19 unless a version is named) |
 | --- | --- |
 | `Injector` is not exported from any public entry point | exported from `j-templates/Utils` |
 | `@Computed` returning `this.tasks` won't re-run on item property changes | it re-runs |
 | a second un-ID'd `scope()`/`gate()` call silently resolves to the first | unconditional duplicates are independent; conditional ones mis-pair |
 | exceptions in children functions/getters propagate uncaught | children-function and `Template()` exceptions are caught and logged; `props:`/`attrs:`/`data:` exceptions halt all rendering |
 | children functions can't return `null`/`undefined` | allowed as the sole return value; forbidden inside arrays |
-| `Bound()` runs with the DOM attached, after the template renders | runs before `Template()`, host detached and empty |
+| `Bound()` runs with the DOM attached, after the template renders | before 8.0.23: ran before `Template()`, host detached and empty. Since 8.0.23: runs after the first render; the host is in the document only for the attached root, and `Connected()` marks entry into the document |
 | `gate()` and `@Scope` are incompatible | fine for primitive-returning getters |
 | `data: this.value` (non-function) in the granular-scopes example | throws `data is not a function` |
 | `StoreAsync` data must be JSON-serialisable (no `Date`, `Map`, `Set`) | transport is structured clone: `Date`, `Map`, `Set` survive; class methods and functions do not |

package/Store/Diff/diffSync.d.ts

@@ -1,10 +1,11 @@
+import { JsonDiffResult } from "../../Utils/json";
 import { DiffSpliceResult, DiffTreeProjectionMap, IDiffTree } from "./diffTree";
 /**
  * Synchronous diff implementation.
  * Computes diffs immediately without queuing or workers.
  *
  * @see StoreSync
- * @see DiffAsync
+ * @see StoreAsync
  */
 export declare class DiffSync implements IDiffTree {
     private diffTree;
@@ -22,15 +23,14 @@ export declare class DiffSync implements IDiffTree {
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path: string, value: any, flatten?: boolean): import("../../Utils/json").JsonDiffResult;
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data: Array<{
-        path: string;
-        value: any;
-    }>): import("../../Utils/json").JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[], flatten?: boolean): DiffSpliceResult;
+    DiffPath(path: string, value: any): {
+        path: (string | number)[];
+        value: unknown;
+    }[];
+    PatchPath(path: string, patch: any): {
+        path: (string | number)[];
+        value: unknown;
+    }[];
+    PushPath(path: string, items: any[]): JsonDiffResult;
+    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[]): DiffSpliceResult;
 }

package/Store/Diff/diffSync.js

@@ -4,7 +4,7 @@ import { DiffTree } from "./diffTree";
  * Computes diffs immediately without queuing or workers.
  *
  * @see StoreSync
- * @see DiffAsync
+ * @see StoreAsync
  */
 export class DiffSync {
     /**
@@ -21,18 +21,21 @@ export class DiffSync {
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path, value, flatten = true) {
-        return this.diffTree.DiffPath(path, value, flatten);
+    DiffPath(path, value) {
+        const diff = this.diffTree.DiffPath(path, value);
+        return diff.concat(this.diffTree.RunProjections());
     }
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data) {
-        return this.diffTree.DiffBatch(data);
+    PatchPath(path, patch) {
+        const diff = this.diffTree.PatchPath(path, patch);
+        return diff.concat(this.diffTree.RunProjections());
+    }
+    PushPath(path, items) {
+        const diff = this.diffTree.PushPath(path, items);
+        return diff.concat(this.diffTree.RunProjections());
     }
-    SplicePath(path, start, deleteCount, items, flatten) {
-        return this.diffTree.SplicePath(path, start, deleteCount, items, flatten);
+    SplicePath(path, start, deleteCount, items) {
+        const spliceResult = this.diffTree.SplicePath(path, start, deleteCount, items);
+        spliceResult.diffResult.push(...this.diffTree.RunProjections());
+        return spliceResult;
     }
 }

package/Store/Diff/diffTree.d.ts

@@ -3,23 +3,16 @@ import { type JsonDiffResult } from "../../Utils/json";
  * Interface for diff tree operations.
  */
 export interface IDiffTree {
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data: Array<{
-        path: string;
-        value: any;
-    }>): JsonDiffResult;
     /**
      * Computes the diff between a new value and the current value at a path.
      * @param path - Dot-separated path to the value
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path: string, value: any, flatten?: boolean): JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[], flatten?: boolean): DiffSpliceResult;
+    DiffPath(path: string, value: any): JsonDiffResult;
+    PatchPath(path: string, patch: any): JsonDiffResult;
+    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[]): DiffSpliceResult;
+    PushPath(path: string, items: any[]): JsonDiffResult;
 }
 /**
  * Constructor interface for IDiffTree.
@@ -70,12 +63,13 @@ export type DiffSpliceResult<T = unknown> = {
     /** Required by the splice operation **/
     start: number;
     deleteCount: number;
+    items: any[];
     spliceResult: any[];
     diffResult: JsonDiffResult;
 };
 /**
  * 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
+ * Used directly by `DiffSync`, and is the building block for a `StoreAsync` 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).
@@ -94,27 +88,17 @@ export declare class DiffTree {
     constructor(keyFunc?: {
         (val: any): string;
     }, projections?: DiffTreeProjectionMap);
-    private RunProjections;
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data: Array<{
-        path: string;
-        value: any;
-    }>): {
-        path: (string | number)[];
-        value: unknown;
-    }[];
+    RunProjections(): JsonDiffResult;
     /**
      * Computes the diff between a new value and the current value at a path.
      * @param path - Dot-separated path to the value
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path: string, value: any, flatten?: boolean): JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number, items: any[], flatten?: boolean): DiffSpliceResult<unknown>;
+    DiffPath(path: string, value: any): JsonDiffResult;
+    PatchPath(path: string, patch: any): JsonDiffResult;
+    PushPath(path: string, items: unknown[]): JsonDiffResult;
+    SplicePath(path: string, start: number, deleteCount: number, items: any[]): DiffSpliceResult<unknown>;
     /**
      * Retrieves the current value at a path.
      * @param path - Dot-separated path to the value

package/Store/Diff/diffTree.js

@@ -1,5 +1,5 @@
 import { ArraysEqual } from "../../Utils/array";
-import { JsonDeepClone, JsonDiff, JsonType } from "../../Utils/json";
+import { JsonDeepClone, JsonDiff, JsonMerge, JsonType } from "../../Utils/json";
 /** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
 export const PROJECTION_PREFIX = "$projection_";
 /**
@@ -247,8 +247,8 @@ function RunProjections(source, keyFunc, projections, memo) {
                 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,
-                // and the diff reported here is unfiltered, the same as DiffPath/DiffBatch return.
-                diffResult.push(...UpdateSource(source, PROJECTION_PREFIX + id, result, true, keyFunc));
+                // and the diff reported here is unfiltered, the same as DiffPath returns.
+                diffResult.push(...UpdateSource(source, PROJECTION_PREFIX + id, result, keyFunc));
             }
         }
     }
@@ -294,18 +294,18 @@ function ResolveKeyPath(source, path, keyFunc) {
  * @param keyFunc - Optional function to extract keys from objects
  * @returns Diff results showing all changes made
  */
-function UpdateSource(source, path, value, flatten, keyFunc) {
+function UpdateSource(source, path, value, keyFunc) {
     const diffResult = [];
     if (keyFunc) {
         const keyPath = ResolveKeyPath(source, path, keyFunc);
         if (keyPath !== path) {
-            const keyDiffResult = UpdateSource(source, keyPath, value, flatten, keyFunc);
+            const keyDiffResult = UpdateSource(source, keyPath, value, keyFunc);
             diffResult.push(...keyDiffResult);
         }
     }
     const [sourceValue] = GetPathValue(source, path);
     JsonDiff(value, sourceValue, path, diffResult);
-    if (flatten && keyFunc) {
+    if (keyFunc) {
         let flattened = {};
         flattened = FlattenValue(flattened, value, keyFunc);
         flattened = JsonDeepClone(flattened);
@@ -319,7 +319,37 @@ function UpdateSource(source, path, value, flatten, keyFunc) {
     }
     return diffResult;
 }
-function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc) {
+function PushSource(source, path, items, keyFunc) {
+    const [sourceValue, found] = GetPathValue(source, path);
+    if (!found)
+        throw `Value not found at path ${path}`;
+    if (!Array.isArray(sourceValue))
+        throw `Value found at path ${path} is not an array`;
+    const results = items.map(function (value, index) {
+        return {
+            path: `${path}.${sourceValue.length + index}`.split('.'),
+            value
+        };
+    });
+    sourceValue.push(...items);
+    if (items.length > 0)
+        results.push({
+            path: `${path}.length`.split('.'),
+            value: sourceValue.length
+        });
+    if (keyFunc) {
+        const flattened = JsonDeepClone(FlattenValue({}, items, keyFunc));
+        const keys = Object.keys(flattened);
+        for (let x = 0; x < keys.length; x++)
+            JsonDiff(flattened[keys[x]], source[keys[x]], keys[x], results);
+    }
+    const filteredDiffResult = results.filter((diff) => diff.value !== undefined);
+    for (let x = 0; x < filteredDiffResult.length; x++) {
+        SetPathValue(source, filteredDiffResult[x].path, filteredDiffResult[x].value);
+    }
+    return results;
+}
+function SpliceSource(source, path, start, deleteCount, items, keyFunc) {
     const [sourceValue, found] = GetPathValue(source, path);
     if (!found)
         throw `Value not found at path ${path}`;
@@ -329,13 +359,14 @@ function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc)
     const spliceResult = {
         path: path.split("."),
         start,
+        items,
         deleteCount,
         spliceResult: null,
         diffResult: [],
     };
     spliceResult.spliceResult = sourceValue.splice(start, deleteCount, ...items);
     InvalidateSnapshotForValue(sourceValue);
-    if (flatten && keyFunc) {
+    if (keyFunc) {
         // Register the keyed entities the new items carry, diffed against the roots
         // already held: a new entity is added whole, one re-inserted unchanged (an undo)
         // produces no diff, so its readers aren't woken.
@@ -352,7 +383,7 @@ function SpliceSource(source, path, start, deleteCount, items, flatten, keyFunc)
 }
 /**
  * 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
+ * Used directly by `DiffSync`, and is the building block for a `StoreAsync` 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).
@@ -375,33 +406,25 @@ export class DiffTree {
             return [];
         return RunProjections(this.rootState, this.keyFunc, this.projectionOrder, this.projectionMemo);
     }
-    /**
-     * Computes diffs for a batch of path/value pairs.
-     * @param data - Array of objects with path and value properties
-     * @returns Combined diff results
-     */
-    DiffBatch(data) {
-        const results = data
-            .map(({ path, value }) => UpdateSource(this.rootState, path, value, true, this.keyFunc))
-            .flat(1);
-        results.push(...this.RunProjections());
-        return results;
-    }
     /**
      * Computes the diff between a new value and the current value at a path.
      * @param path - Dot-separated path to the value
      * @param value - The new value to compare
      * @returns Diff results showing changes
      */
-    DiffPath(path, value, flatten = true) {
-        const results = UpdateSource(this.rootState, path, value, flatten, this.keyFunc);
-        results.push(...this.RunProjections());
-        return results;
+    DiffPath(path, value) {
+        return UpdateSource(this.rootState, path, value, this.keyFunc);
+    }
+    PatchPath(path, patch) {
+        const value = this.Snapshot(path);
+        const merged = JsonMerge(value, patch);
+        return UpdateSource(this.rootState, path, merged, this.keyFunc);
+    }
+    PushPath(path, items) {
+        return PushSource(this.rootState, path, items, this.keyFunc);
     }
-    SplicePath(path, start, deleteCount, items, flatten = true) {
-        const spliceResult = SpliceSource(this.rootState, path, start, deleteCount, items, flatten, this.keyFunc);
-        spliceResult.diffResult.push(...this.RunProjections());
-        return spliceResult;
+    SplicePath(path, start, deleteCount, items) {
+        return SpliceSource(this.rootState, path, start, deleteCount, items, this.keyFunc);
     }
     /**
      * Retrieves the current value at a path.

package/Store/Diff/diffTreeWorker.d.ts

@@ -1,7 +1,16 @@
-import { DiffTree } from "./diffTree";
+import { JsonDiffResult } from "../../Utils/json";
+import { DiffSpliceResult, DiffTree } from "./diffTree";
+export type IDiffMethodBatch = IDiffMethod[];
+export type IDiffMethodBatchResult = ({
+    type: "diff";
+    result: JsonDiffResult;
+} | {
+    type: "splice";
+    result: DiffSpliceResult;
+})[];
 export interface IDiffMethod {
     /** The method to call */
-    method: "create" | "diffpath" | "splicepath" | "diffbatch" | "updatepath" | "getpath";
+    method: "diffpath" | "splicepath" | "pushpath" | "patchpath";
     /** Arguments for the method call */
     arguments: Array<any>;
 }

package/Store/Diff/diffTreeWorker.js

@@ -1,27 +1,44 @@
 export function ConnectWorkerToDiffTree(diffTree, worker) {
     worker.onmessage = function (event) {
         const data = event.data;
-        switch (data.method) {
-            case "diffpath": {
-                const diff = diffTree.DiffPath(data.arguments[0], data.arguments[1], data.arguments[2]);
-                worker.postMessage(diff);
-                break;
-            }
-            case "splicepath": {
-                const diff = diffTree.SplicePath(data.arguments[0], data.arguments[1], data.arguments[2], data.arguments[3], data.arguments[4]);
-                worker.postMessage(diff);
-                break;
-            }
-            case "diffbatch": {
-                const diff = diffTree.DiffBatch(data.arguments[0]);
-                worker.postMessage(diff);
-                break;
-            }
-            case "getpath": {
-                const ret = diffTree.GetPath(data.arguments[0]);
-                worker.postMessage(ret);
-                break;
+        const result = new Array(data.length + 1);
+        for (let x = 0; x < data.length; x++) {
+            const call = data[x];
+            switch (call.method) {
+                case "diffpath": {
+                    result[x] = {
+                        type: "diff",
+                        result: diffTree.DiffPath(call.arguments[0], call.arguments[1])
+                    };
+                    break;
+                }
+                case "splicepath": {
+                    result[x] = {
+                        type: "splice",
+                        result: diffTree.SplicePath(call.arguments[0], call.arguments[1], call.arguments[2], call.arguments[3])
+                    };
+                    break;
+                }
+                case "pushpath": {
+                    result[x] = {
+                        type: "diff",
+                        result: diffTree.PushPath(call.arguments[0], call.arguments[1])
+                    };
+                    break;
+                }
+                case "patchpath": {
+                    result[x] = {
+                        type: "diff",
+                        result: diffTree.PatchPath(call.arguments[0], call.arguments[1])
+                    };
+                    break;
+                }
             }
         }
+        result[result.length - 1] = {
+            type: "diff",
+            result: diffTree.RunProjections()
+        };
+        worker.postMessage(result);
     };
 }