j-templates 8.1.2 → 9.0.0

package/SYNTAX_PRIMER.md

@@ -537,7 +537,7 @@ A store holds reactive data under string keys and diffs every write into existin
 
 |  | `StoreSync` | `StoreAsync` | `PushStore` |
 | --- | --- | --- | --- |
-| Constructor | `new StoreSync(keyFunc?, projections?)` | `new StoreAsync(worker, keyFunc?)` | `new PushStore(source, keyFunc?, cloneData?)` |
+| Constructor | `new StoreSync(keyFunc?, projections?)` | `new StoreAsync(worker, keyFunc?)` | `new PushStore(source, keyFunc?)` |
 | Diffing | main thread, synchronous | in the `Worker` you supply | in the `DiffTreeWriter` that pushes to it |
 | Writes | `void`; readable immediately | `Promise`; batched per tick, readable only after `await` | none; read-only. Changes arrive when the writer calls `Commit()` |
 | `Destroy()` | none | required; terminates the worker | required; stops listening, leaves the worker running |
@@ -652,7 +652,7 @@ store.Destroy();        // stops listening; terminate the worker yourself
 - **Create the store before the first `Commit()`.** Messages are diffs against the writer's tree, so a store created later misses the earlier changes and holds partial roots (from source). There is no catch-up message.
 - **A failed change doesn't stop either side.** After a write throws, every later write before `Commit()` throws the same error. `Commit()` still sends the writes made before the failure, skips projections, then posts `DIFF_TREE_ERROR`. The store applies the changes and sets `Error` (verified). The next commit brings projections up to date.
 - `store.Error` is reactive: the last commit's error, or `null`. It's cleared when a later commit's changes arrive (verified).
-- `cloneData` (default `false`): a `Worker` or `MessagePort` already delivers a structured-clone copy, so no copy is made. A same-thread `EventTarget` delivers the writer's own objects; post copies, or pass `true`. The flag only covers new roots and splices; changes to an existing root are always copied (from source).
+- The store deep-clones every value it applies, so even a same-thread `EventTarget` that delivers the writer's own objects never leaves the store sharing them with the writer's tree (from source).
 
 ## ObservableScope and ObservableNode
 
@@ -707,13 +707,12 @@ ObservableNode.Unwrap(proxy)          // raw underlying value
 ObservableNode.Apply(node, value)     // merge a full value in place; node identity kept
 ObservableNode.Snapshot(node)         // cached plain copy
 ObservableNode.Clone(value)           // replaces proxies with plain data, mutating plain containers in place; returns value
-ObservableNode.Update(node, prop?)    // force a change notification
 ObservableNode.CreateFactory(alias?)  // proxy factory with aliasing (used by stores)
 ```
 
 - `Snapshot` returns the same object on repeated calls until a write. After a write, unchanged nested parts are shared (`===`) with the previous snapshot. Snapshots are **not frozen**; treat them as read-only.
 - `JSON.stringify(node)` and `node.toJSON()` use the cached snapshot.
-- `ApplyDiff`, `ApplySplice`, `Assign`, `Touch` and `Read` also exist; they are internal to the stores.
+- `ApplyDiff`, `ApplySplice` and `Touch` also exist; they are internal to the stores. `ApplyDiff` and `ApplySplice` deep-clone what they write, so the node never shares objects with the caller.
 
 **Snapshot reads do not subscribe.** `JSON.stringify(node)`, `node.toJSON()` and `ObservableNode.Snapshot(node)` register no dependencies, so a scope that reads only through them never updates (verified). Read properties directly, or use `ObservableNode.Clone(node)`, which tracks every nested field and leaves the source untouched:
 

package/Store/Diff/diffTree.d.ts

@@ -1,47 +1,53 @@
-import { type JsonDiffResult } from "../../Utils/json";
-import { DiffSpliceResult, DiffTreeProjectionMap } from "./diffTree.types";
+import { JsonDiffResult } from '../../Utils/json';
+import { IKeyFunc, IRouteDefinitions } from './utils/diffTree.types';
 /**
- * Diff tree implementation. Maintains root state and computes diffs for path/value updates.
- * 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).
+ * A tree of JSON state in routes, with projections, that tracks its changes as diffs. The work is
+ * split across `utils/`:
+ * - `homes`: writes, which keep every keyed value at its home
+ * - `state`: reading and writing route state, and snapshots of it
+ * - `routes`: route instances, created from the route definitions
+ * - `projections`: running each route instance's projections
+ * - `paths`: path strings
  */
 export declare class DiffTree {
-    private keyFunc?;
     private rootState;
-    private projectionOrder;
-    private projectionMemo;
+    private snapshot;
+    private routes;
+    private projections;
+    /** Each root key's snapshot as of the last commit */
+    private commitedSnapshot;
+    private writeContext;
+    constructor(keyFunc?: IKeyFunc, routeDefinitions?: IRouteDefinitions);
+    WritePath(path: string, value: any): void;
+    PatchPath(path: string, patch: any): void;
+    PushPath(path: string, items: unknown[]): void;
+    SplicePath(path: string, start: number, deleteCount: number, items: any[]): void;
+    private Splice;
     /**
-     * Creates a DiffTree instance.
-     * @param keyFunc - Optional function to extract a key from objects
-     * @param projections - Optional map of derived-value projections, keyed by id. Cycles
-     *   and reads of an unregistered projection id are rejected here, at construction.
+     * Deletes a route: its state, its child routes and projection outputs, and its route
+     * instances. The projection order is rebuilt on the next `RunProjections`, so deleting
+     * several routes in a row sorts once.
+     * @param routePath The route to delete, e.g. `/channel/1/`
+     * @throws When the path is the root route or has a property path, e.g. `/channel/1/name`
      */
-    constructor(keyFunc?: {
-        (val: any): string;
-    }, projections?: DiffTreeProjectionMap);
-    RunProjections(): JsonDiffResult;
+    DeleteRoute(routePath: string): void;
     /**
-     * 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
+     * Reads the raw value at a path, root (`value.prop`) or routed (`/channel/1/value.prop`).
+     * @returns The value, or undefined when any segment of the path doesn't exist
      */
-    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;
+    ReadPath(path: string): any;
+    /** Runs every projection of every route instance; see `Projections.Run` */
+    RunProjections(): void;
     /**
-     * Retrieves the current value at a path.
-     * @param path - Dot-separated path to the value
-     * @returns The value at the specified path
+     * The changes since the last commit. The root is a flat record of keys, so each key's snapshot
+     * is taken and compared on its own, without building a snapshot of the whole root: a key no
+     * write touched has the same cached snapshot as the last commit, and is skipped.
      */
-    GetPath(path: string): any;
+    Commit(): JsonDiffResult;
     /**
-     * Returns an immutable, cached snapshot of the value at a path (empty string for the
-     * whole tree). Not part of `IDiffTree`; internal, for a future feature.
-     * @param path - Dot-separated path to the value
+     * The snapshot of the value at a path. Only the path's first property is snapshotted, not
+     * its whole route.
+     * @returns The snapshot, or undefined when any segment of the path doesn't exist
      */
     Snapshot(path: string): any;
 }