j-templates 8.1.1 → 8.2.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,78 @@
-import { type JsonDiffResult } from "../../Utils/json";
-import { DiffSpliceResult, DiffTreeProjectionMap } from "./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).
- */
+import { JsonDiffResult } from '../../Utils/json';
+import { IKeyFunc, IRouteDefinitions } from './utils/diffTree.types';
 export declare class DiffTree {
     private keyFunc?;
+    private routeDefinitions;
     private rootState;
+    private rootRoute;
+    private commitedSnapshot;
+    private routeCache;
+    private routeKeyFunc;
+    private resolver;
+    private snapshot;
     private projectionOrder;
-    private projectionMemo;
+    private routeVersion;
+    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;
     /**
-     * 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;
     /**
-     * Retrieves the current value at a path.
-     * @param path - Dot-separated path to the value
-     * @returns The value at the specified path
+     * Runs every projection of every route instance, dependencies first. A projection is skipped
+     * when no route it reads through changed since its last run, when a read's parent is missing,
+     * or when every read value is the same as its last run. Outputs are written as-is to
+     * `$projection_<key>` in their route, without a diff.
+     * @throws When projections depend on each other in a cycle
      */
-    GetPath(path: string): any;
+    RunProjections(): void;
+    Commit(): JsonDiffResult;
+    Snapshot(path: string): any;
     /**
-     * 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
+     * Finds the route instance for a route path (the portion of a path before the last `/`), creating it (and any missing
+     * parent instances) from the matching definition on first use.
+     * @returns The deepest route instance matched by a definition, or the root route when none matches
      */
-    Snapshot(path: string): any;
+    private GetRouteInstance;
+    /**
+     * Whether every route a projection's reads resolved through on its last full read still has
+     * the snapshot it read: a write anywhere under a route clears its cached snapshot, so then no
+     * read can have changed. A wildcard read also needs the same route instances to exist.
+     */
+    private SourcesUnchanged;
+    /**
+     * Takes a new snapshot of every source in the route a projection just wrote its output to. The
+     * write cleared that route's snapshot, but nothing the projection read changed between its read
+     * and the write, so without this the next run would read everything again for nothing.
+     */
+    private RefreshSources;
+    /**
+     * Snapshots of the values at each path, read through the route's root object so keyed
+     * values resolve through their own copy.
+     * @param sources Filled with what each read resolved through; a read after a missing one is left undefined
+     * @param previous The sources of the last full read, so a wildcard read reuses its unchanged matches
+     * @returns The values, or undefined when any of them is missing
+     */
+    private ReadValues;
+    /** The value at a path, whether it was found, and the route it was read through, when there is one */
+    private ReadValue;
+    /**
+     * Reads every route a wildcard path matches. While no route instance was added or removed since
+     * the last read, the matches are the same, and a match whose route has the same snapshot keeps
+     * the value it read.
+     */
+    private ReadWildcard;
+    private ReadMatch;
 }