@zakkster/lite-project 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 All notable changes to `@zakkster/lite-project` are documented here. The format
 follows Keep a Changelog; this project adheres to semantic versioning.
 
+## [1.2.0] - 2026-09-05
+
+### Added
+
+- **`Projection.forEachPatch(fn, skip?)`** -- emit the staged drafts as a
+  `(key, from, to)` stream, where `from` is the **untracked** current source
+  value and `to` the staged overlay. Read-only and untracked: it touches neither
+  the source nor the overlays and subscribes the caller to nothing, so it is safe
+  inside an effect. Visits exactly the overlaid keys, in `forEachOverlay` order,
+  with a **zero-allocation** per-key body (the source read is hoisted through one
+  closure per projection, never one per key). The optional `skip` reuses the
+  `ReconcilePolicy` shape `(from, to, key) => boolean` -- pass `confirmOnEcho` to
+  drop unchanged drafts. A throwing `source.get` propagates on the offending key
+  with the overlay bag intact (no writes happen anywhere in the call).
+- **`Projection.toPatch(skip?)`** -- the cold convenience that materializes the
+  same stream as `[{ key, from, to }, ...]` (same visit set, order, and values).
+  The per-key record is this form's documented allocation; reach for
+  `forEachPatch` when you need the zero-alloc callback. Both methods are present
+  on the `projectStore` / `projectRoom` / `projectQuery` handles (for
+  `projectQuery`, `from` is the cached record's field value; for `projectRoom`,
+  `room.storage.get`).
+- **`Patch<K, V>`** interface (`{ key, from, to }`) exported from `Project.d.ts`.
+
+  **The decision -- unchanged drafts are emitted by default.** An overlaid key is
+  emitted whether or not `Object.is(from, to)`. This keeps the visit set
+  definitionally equal to `forEachOverlay`, `dirtyCount()`, and `commit()`'s write
+  set, so `toPatch().length === dirtyCount()` always holds; a patch consumer is a
+  protocol (an LWW-Map op, a CRDT timestamp bump, an HTTP PATCH field), not a diff
+  viewer, so dropping an unchanged key would be silent data loss one layer out.
+  Callers who want the filter pass `forEachPatch(fn, confirmOnEcho)`. Recorded in
+  `decisions/0001-patch-emission.md` (dev-only; not shipped).
+
+### Verified
+
+- 17 new `test/patch_test.mjs` cases (visit-set exactness + order, from/to vs
+  source and overlay, `toPatch()` == the callback stream, the emit-by-default and
+  echo-skip pins, the tracking contract, `__proto__` / symbol / numeric keys,
+  `undefined` / `NaN` / `-0` under `Object.is`, fail-closed on a throwing
+  `source.get`, patch-apply == commit, and all four adapter handles); **84 tests
+  total**, `node --test`.
+- Torture green (default seed):
+  `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 |
+  alloc=n/a retained=0.00 B/op growths=0`. T5 gains the metamorphic law (the
+  emitted patch applied to a fresh source copy == `commit()` into it, across the
+  fuzz corpus incl. object drafts). T6 gains Proof 4 -- `forEachPatch` over a
+  warm overlaid set passes both the heap gate (`maxMajor 0`, `maxPauseMs 4`,
+  `maxArrayBuffersGrowth 0`) and the zero-retention gate (`maxBytesPerCall 0`).
+  T9 gains control (g): a per-visit-allocating emitter body demonstrably trips the
+  retained-alloc gate through the same helper.
+
 ## [1.1.1] - 2026-09-03
 
 ### Added

package/Project.d.ts

@@ -1,4 +1,4 @@
-// Type declarations for @zakkster/lite-project v1.1.1
+// Type declarations for @zakkster/lite-project v1.2.0
 // Zero-GC projections for @zakkster/lite-signal.
 // (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com> -- MIT
 
@@ -25,6 +25,17 @@ export interface ProjectionSource<K extends PropertyKey = PropertyKey, V = unkno
 export type ReconcilePolicy<K extends PropertyKey = PropertyKey, V = unknown> =
     (authoritative: V, overlayValue: V, key: K) => boolean;
 
+/**
+ * One staged draft as a patch entry: the current source value (`from`) and the
+ * staged overlay value (`to`) for `key`. The materialized shape returned by
+ * {@link Projection.toPatch}.
+ */
+export interface Patch<K extends PropertyKey = PropertyKey, V = unknown> {
+    key: K;
+    from: V;
+    to: V;
+}
+
 /**
  * A projection handle: a granular, derived, non-mutating draft overlay over a
  * keyed source. Each touched key owns one overlay signal + one projected
@@ -53,6 +64,26 @@ export interface Projection<K extends PropertyKey = PropertyKey, V = unknown> {
     peek(key: K): V;
     /** Iterate currently-overlaid keys with their overlay values (untracked). */
     forEachOverlay(fn: (key: K, value: V) => void): void;
+    /**
+     * Emit the staged drafts as a patch stream `fn(key, from, to)` -- `from` is
+     * the UNTRACKED current source value, `to` the staged overlay. Read-only and
+     * untracked: it touches neither the source nor the overlays and subscribes the
+     * caller to nothing, so it is safe inside an effect. Visits exactly the
+     * overlaid keys, in {@link Projection.forEachOverlay} order, with a zero-alloc
+     * per-key body. An overlaid key is emitted whether or not `Object.is(from, to)`
+     * (the visit set stays equal to `dirtyCount()`); pass `skip` -- the same
+     * predicate shape reconcile uses, e.g. {@link confirmOnEcho} -- to drop
+     * unchanged drafts. A throwing `source.get` propagates on that key with the
+     * overlay bag intact (callers needing atomicity use {@link Projection.toPatch}).
+     */
+    forEachPatch(fn: (key: K, from: V, to: V) => void, skip?: ReconcilePolicy<K, V>): void;
+    /**
+     * Cold convenience over {@link Projection.forEachPatch}: materialize the drafts
+     * as `[{ key, from, to }, ...]` -- same visit set, order, and values. The
+     * per-key record is this form's allocation; reach for `forEachPatch` when you
+     * need the zero-alloc callback.
+     */
+    toPatch(skip?: ReconcilePolicy<K, V>): Array<Patch<K, V>>;
     /**
      * Full-snapshot reconciliation: drop every overlay the policy considers
      * confirmed against the current (untracked) source value. Presentation-only --

package/Project.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-project v1.1.1 -- zero-GC projections for @zakkster/lite-signal.
+ * @zakkster/lite-project v1.2.0 -- zero-GC projections for @zakkster/lite-signal.
  * -----------------------------------------------------------------------------
  * A projection is a granular, derived, NON-MUTATING reactive view over a keyed
  * source: a lens that can carry ephemeral overlays (optimistic edits, merges,
@@ -21,6 +21,10 @@
  *                circuit -- does NOT churn downstream consumers. The optimistic value
  *                is stable under source noise.
  *
+ * Patch emission (forEachPatch / toPatch) exposes the staged drafts as a
+ * (key, from, to) stream for a save/sync trigger. It is READ-ONLY and UNTRACKED:
+ * it never touches the source or the overlays and subscribes the caller to nothing.
+ *
  * -- OWNERSHIP (why createRoot) --
  * Per-key nodes are created LAZILY, on the first get/set of a key -- which happens
  * inside whatever consumer effect first reads that key. Without detachment the
@@ -59,7 +63,7 @@ import {
     hasObservers as _hasObservers,
 } from "@zakkster/lite-signal";
 
-export const VERSION = "1.1.1";
+export const VERSION = "1.2.0";
 
 // Module-level sentinel for "this key has no overlay". A unique symbol, never a
 // per-operation allocation. Stored directly in the overlay signal's value slot, so
@@ -129,6 +133,8 @@ export function createProjector(reg) {
      *   isDirty:()=>boolean,                     // TRACKED: any staged overlays? (reactive)
      *   peek:(key:PropertyKey)=>unknown,         // untracked effective read (no subscribe)
      *   forEachOverlay:(fn:(key:PropertyKey, value:unknown)=>void)=>void, // iterate overlaid keys (untracked)
+     *   forEachPatch:(fn:(key:PropertyKey, from:unknown, to:unknown)=>void, skip?:Function)=>void, // patch stream (untracked, read-only)
+     *   toPatch:(skip?:Function)=>Array<{key:PropertyKey, from:unknown, to:unknown}>, // materialized patch (cold convenience)
      *   reconcileAll:(policy?:(authoritative:unknown, overlayValue:unknown, key:PropertyKey)=>boolean)=>void, // drop confirmed overlays
      *   commit:(key?:PropertyKey)=>void,         // write one key's overlay, or all, into the source then clear
      *   revert:()=>void,                         // drop all overlays
@@ -160,6 +166,28 @@ export function createProjector(reg) {
             return s;
         };
 
+        // Patch emission: iterate exactly the overlaid keys, handing scalars
+        // (key, from, to) to `fn` -- `from` is the UNTRACKED current source value,
+        // `to` the staged overlay. Read-only: overlays via .peek(), source under
+        // untrack, so calling this inside an effect subscribes to nothing. The
+        // visit set / order is byte-identical to forEachOverlay. Optional `skip`
+        // reuses ReconcilePolicy: (from, to, key) => true drops that key from the
+        // stream (e.g. `forEachPatch(fn, confirmOnEcho)` skips echoes); default
+        // undefined emits every overlaid key, changed or not. A throwing
+        // source.get propagates on the offending key with no writes anywhere, so
+        // the overlay bag is intact by construction (fn may already have run for
+        // earlier keys; callers needing atomicity use toPatch()).
+        const forEachPatch = (fn, skip) => {
+            for (const [key, s] of slots) {
+                const to = s.ov.peek();
+                if (to === ABSENT) continue;
+                _pk = key;
+                const from = untrack(_readSrc);
+                if (skip !== undefined && skip(from, to, key)) continue;
+                fn(key, from, to);
+            }
+        };
+
         // Reactive dirty state. ONE fixed signal per projection (created detached so
         // dispose() owns its teardown, like the per-key nodes). `dirty` is the
         // source-of-truth count of staged overlays, mirrored into the signal on every
@@ -169,6 +197,12 @@ export function createProjector(reg) {
         const dirtySig = createRoot(() => signal(0));
         let dirty = 0;
 
+        // Hoisted scratch for forEachPatch's untracked source read: ONE closure
+        // per projection, never per key/call, so the per-key emit body allocates
+        // nothing. `untrack` needs a function; _readSrc is it.
+        let _pk;
+        const _readSrc = () => source.get(_pk);
+
         return {
             get: (key) => slotFor(key).read(),
             set: (key, v) => {
@@ -208,6 +242,18 @@ export function createProjector(reg) {
                     if (o !== ABSENT) fn(key, o);
                 }
             },
+            // Emit the overlaid keys as a patch stream fn(key, from, to). Untracked,
+            // read-only, zero-alloc per-key body. See forEachPatch above.
+            forEachPatch,
+            // Cold convenience over forEachPatch: materialize the drafts as
+            // [{ key, from, to }, ...] (same visit set, order, values). The
+            // per-key record is the documented allocation of this form; reach for
+            // forEachPatch when you need the zero-alloc callback.
+            toPatch: (skip) => {
+                const out = [];
+                forEachPatch((key, from, to) => { out.push({ key, from, to }); }, skip);
+                return out;
+            },
             // Full-snapshot reconciliation: drop every overlay the policy considers
             // confirmed against the CURRENT (untracked) source value. For sources that
             // sync wholesale rather than per-key. Presentation-only -- the source owns

package/README.md

@@ -110,6 +110,8 @@ Bind the primitives to a lite-signal registry. Pass the default namespace for no
 | `overlaidCount()` | untracked diagnostic: number of overlaid keys |
 | `peek(key)` | untracked effective read (no subscribe) |
 | `forEachOverlay(fn)` | iterate overlaid keys + values (untracked) |
+| `forEachPatch(fn, skip?)` | emit staged drafts as a `(key, from, to)` stream (untracked, read-only, zero-alloc per key) <sub>1.2</sub> |
+| `toPatch(skip?)` | materialize the drafts as `[{ key, from, to }, ...]` (cold convenience over `forEachPatch`) <sub>1.2</sub> |
 | `reconcileAll(policy?)` | drop overlays the policy confirms against the current source |
 | `prune()` | release slots for keys that are neither overlaid nor observed; returns how many were freed <sub>1.1</sub> |
 | `dispose()` | recycle every projection-owned node back to the pool |
@@ -175,6 +177,30 @@ Projects a single query entry's data **object**, exposing its **fields** as the
 
 The default merge copies **own enumerable** properties, symbols included, and defines them rather than assigning them. That matters for three field names you would otherwise lose silently: a field literally called `__proto__` lands as a real own key (assignment would retarget the prototype and drop it), inherited properties on `prev` are not absorbed into the record, and a symbol-keyed draft survives the commit instead of evaporating while `dirtyCount()` reports it saved. A custom `merge` is on its own for all three.
 
+## Patch emission <sub>1.2</sub>
+
+The overlay bag already knows every staged draft's `to`; `forEachPatch` adds the source's `from` so a draft can cross the wire without re-walking the view.
+
+```js
+const draft = project(source);
+draft.set("name", "Ada");
+draft.set("email", "ada@x.dev");
+
+// Zero-alloc callback: hand each draft to a serializer / transport.
+draft.forEachPatch((key, from, to) => {
+  wire.send({ op: "set", key, prev: from, next: to });
+});
+
+// Cold convenience: materialize the same deltas as an array.
+const patch = draft.toPatch();   // [{ key: "name", from: undefined, to: "Ada" }, ...]
+```
+
+`from` is the **untracked** current source value, `to` the staged overlay. Both methods are read-only and untracked -- calling them inside an effect subscribes it to nothing -- and visit exactly the overlaid keys, in `forEachOverlay` order. `forEachPatch` allocates nothing per key; `toPatch` is the cold convenience whose per-key record is its documented allocation.
+
+An overlaid key is emitted whether or not `Object.is(from, to)`: the visit set stays equal to `dirtyCount()` and `commit()`'s write set, so a patch consumer (an LWW-Map op, a CRDT bump, an HTTP PATCH field) is never silently dropped. To suppress unchanged drafts, pass the same predicate shape reconcile uses -> `draft.forEachPatch(fn, confirmOnEcho)`. A throwing `source.get` propagates on the offending key with the overlay bag intact; callers needing atomicity use `toPatch()` (a partial array never escapes). The patch and `commit()` are two views of one delta: applying `toPatch()` to a copy of the source yields the same state `commit()` would write.
+
+Present on the `projectStore` / `projectRoom` / `projectQuery` handles too (for `projectQuery`, `from` is the cached record's field value).
+
 ## Conventions
 
 ESM only. ASCII source. `node:test`. MIT.

package/llms.txt

@@ -26,6 +26,7 @@ Peer dependency: @zakkster/lite-signal ^1.5.0 (uses createRoot). ESM only. MIT.
 - createProjector(reg) -> { project, keyedStore }   // bind to any lite-signal registry
 - project(source) -> Projection                       // default registry
 - keyedStore(initial?) -> { get, set, has, keys }     // minimal built-in source
+- VERSION -> string                                   // shipped package version, synced to package.json
 
 ## Projection handle
 
@@ -33,6 +34,16 @@ get(key) | set(key,value) | clear(key) | commit(key?) [one key or all] | revert(
 dirtyCount() [TRACKED reactive] | isDirty() [TRACKED reactive] |
 isOverlaid(key) | overlaidCount() | peek(key) [untracked effective read] |
 forEachOverlay(fn) | reconcileAll(policy?) | dispose() [recycle all owned nodes] |
+forEachPatch(fn, skip?) [1.2] | toPatch(skip?) -> [{key,from,to}] [1.2]
+  [patch emission: iterate exactly the overlaid keys as fn(key, from, to) -- from =
+  UNTRACKED current source value, to = staged overlay. Read-only + untracked: safe
+  inside an effect, subscribes to nothing. Same visit set/order as forEachOverlay,
+  zero-alloc per-key body. Emits UNCHANGED drafts by default (visit set stays equal
+  to dirtyCount()); pass a reconcile-policy predicate (from,to,key)=>bool, e.g.
+  confirmOnEcho, to skip echoes. A throwing source.get propagates on that key with
+  the overlay bag intact. toPatch() is the cold convenience that materializes the
+  stream (its per-key record is the documented allocation). Present on the
+  projectStore/projectRoom/projectQuery handles too.] |
 prune() -> number [1.1] [release slots that are BOTH un-overlaid AND unobserved;
   returns how many were freed. A slot = 1 overlay signal + 1 projected computed,
   created by the first READ of a key and retained until dispose() (its computed may

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-project",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Zero-GC projections for @zakkster/lite-signal: granular, derived, non-mutating reactive overlays with commit / revert / reconcile, and draft adapters for lite-store and lite-room.",
   "type": "module",
   "main": "./Project.js",