@rindle/client 0.4.3 → 0.5.0

package/src/view.ts

@@ -18,6 +18,17 @@ export interface ViewTypes {
   rels: Record<number, ViewTypes>;
 }
 
+/** The phase of an {@link ArrayView.onChanges} delivery: the initial hydrate `snapshot` vs a later
+ *  incremental `batch` — the same distinction a narrator draws (`ChangeEvent` `snapshot`/`batch`). */
+export type ChangePhase = "snapshot" | "batch";
+
+/** A per-view change listener ({@link ArrayView.onChanges}): the net `FlatChange[]` this view folded,
+ *  the {@link ChangePhase} it arrived on, and the view's `WireSchema` (the position→name source for
+ *  `resolveChange`). This is the DIFF the data channel ({@link ArrayView.subscribe}) discards — the
+ *  seam a narrator drives off. The `schema` is passed (not closed over) because the first `snapshot`
+ *  fires synchronously inside `materialize`, before the caller holds the view handle. */
+export type ViewChangeListener = (changes: FlatChange[], phase: ChangePhase, schema: WireSchema) => void;
+
 /** The public ArrayView contract `materialize()` returns. */
 export interface ArrayView<R> {
   /** The current materialized result (reference-stable where data is unchanged). */
@@ -39,6 +50,14 @@ export interface ArrayView<R> {
   /** Subscribe; fires immediately with the current data, then after each applied batch (and after
    *  a {@link resultType} change — re-read `resultType` in the listener). */
   subscribe(listener: (data: readonly R[]) => void): () => void;
+  /** Subscribe to this view's folded CHANGE stream — the `FlatChange[]` it applies, NET of no-op
+   *  cycles (a rebase's balanced `remove`+`add` / edit round-trip cancels, so a correctly predicted
+   *  optimistic write delivers nothing here). Carries the diff {@link subscribe} throws away; the
+   *  per-view seam a narrator rides. Does NOT replay on subscribe — attach via
+   *  `store.materialize(query, { onChanges })` to catch a synchronous backend's first snapshot.
+   *  A view with any change listener also enriches its own `remove` ops with the evicted subtree
+   *  (per-view, no global opt-in). Returns a detach function. */
+  onChanges(listener: ViewChangeListener): () => void;
   /** Tear down + stop receiving updates. */
   destroy(): void;
 }
@@ -58,6 +77,10 @@ export interface SingularArrayView<R> {
   /** Subscribe; fires immediately with the current row, then after each applied batch (and after
    *  a {@link resultType} change). */
   subscribe(listener: (data: R | null) => void): () => void;
+  /** Subscribe to the view's folded CHANGE stream — see {@link ArrayView.onChanges}. The changes
+   *  are the same positional `FlatChange`s as the plural view (a `.one()` is just the list capped to
+   *  one), so a narrator resolves them identically. */
+  onChanges(listener: ViewChangeListener): () => void;
   /** Tear down + stop receiving updates. */
   destroy(): void;
 }
@@ -91,6 +114,10 @@ export class SingularView<R> implements SingularArrayView<R> {
     return this.inner.subscribe((d) => listener(d[0] ?? null));
   }
 
+  onChanges(listener: ViewChangeListener): () => void {
+    return this.inner.onChanges(listener);
+  }
+
   destroy(): void {
     this.inner.destroy();
   }
@@ -161,8 +188,159 @@ function toWireNode(node: Node, schema: WireSchema): WireNode {
   return { row: node.row, rels };
 }
 
-function rowsEqual(a: WireValue[], b: WireValue[]): boolean {
-  return a.length === b.length && a.every((v, i) => Object.is(v, b[i]));
+/** Elementwise equality over positional bare-cell rows — THE row comparator for every JS-side
+ *  diff (views, aggregate heads, the persistence mirror), exported so no caller grows a drifted
+ *  private copy. Per cell: `===` keeps `-0 === 0` (the engine's key semantics treat them equal);
+ *  the `Object.is` arm makes a NaN cell equal itself (under `!==` alone, a NaN-bearing row never
+ *  matches any copy of itself, so every diff re-emits it as a spurious edit forever). */
+export function rowsEqual(a: WireValue[], b: WireValue[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i] && !Object.is(a[i], b[i])) return false;
+  }
+  return true;
+}
+
+/** JSON.stringify for keying a row, except the numbers JSON folds together — NaN/±Infinity (→ null)
+ *  and -0 (→ 0) — get a sentinel encoding, so two rows that `rowsEqual` (Object.is) distinguishes
+ *  never share a net key (a `remove [1, Infinity]` must not cancel an `add [1, null]`). */
+function keyRow(row: WireValue[]): string {
+  return JSON.stringify(row, (_k, v: unknown) =>
+    typeof v === "number" && (!Number.isFinite(v) || Object.is(v, -0)) ? [" num", Object.is(v, -0) ? "-0" : String(v)] : v,
+  );
+}
+
+/** The key a subtractive net matches an op on: the path (parent locators, one hop per level) plus the
+ *  row bytes. Two ops with the same key touch the same row at the same tree position. */
+function opRowKey(path: FlatChange["path"], row: WireValue[]): string {
+  let k = "";
+  for (const seg of path) k += seg.rel + ":" + keyRow(seg.parentRow) + "/";
+  return k + "|" + keyRow(row);
+}
+
+/** Walk `path` down `schema` to the changed level's `WireSchema` — `null` when a hop crosses a
+ *  gating (join-only) slot; such ops never fold, so they never reach the net. */
+function levelSchemaAt(schema: WireSchema, path: FlatChange["path"]): WireSchema | null {
+  let level: WireSchema = schema;
+  for (const seg of path) {
+    const child = level.relationships[seg.rel]?.child;
+    if (!child) return null;
+    level = child;
+  }
+  return level;
+}
+
+/** Deep structural equality of two canonical (maintained-order) subtrees: rows via Object.is,
+ *  per-slot children pairwise, rc included — a dup-path child only equals an equally-duplicated one. */
+function nodesEqual(a: Node, b: Node): boolean {
+  if (a.rc !== b.rc || !rowsEqual(a.row, b.row) || a.rels.length !== b.rels.length) return false;
+  for (let s = 0; s < a.rels.length; s++) {
+    const ra = a.rels[s];
+    const rb = b.rels[s];
+    if (ra.length !== rb.length) return false;
+    for (let i = 0; i < ra.length; i++) if (!nodesEqual(ra[i], rb[i])) return false;
+  }
+  return true;
+}
+
+/** Cancel no-op cycles in a folded batch SUBTRACTIVELY — the safe half of the removed engine
+ *  coalescer (OPTIMISTIC-WRITES-DESIGN §3, and `wasm/db.rs` "Step 2 of the removal"). A rebase
+ *  re-invokes a still-pending prediction, emitting a balanced `remove R`+`add R` (or `edit b→a`+
+ *  `edit a→b`) that nets to nothing; so a correctly predicted optimistic write delivers ZERO changes
+ *  to a narrator, and only genuine (mispredicted / other-client) changes survive. We ONLY drop exact
+ *  inverse pairs — byte-identical row at the same path AND a structurally identical subtree: a row
+ *  that leaves and re-enters within one batch carrying a CHANGED child set is NOT an inverse (the
+ *  child never got its own event while the row was out — the re-add is its only carrier), so that
+ *  pair survives. Survivors pass through UNMODIFIED: we never rewrite a locator, reorder, or
+ *  reconstruct a gated subtree (the reconstructive netting that shipped four correctness bugs and
+ *  was pulled from the engine). Because this feeds prose, not a locate-by-value receiver, even an
+ *  imperfect net is at worst a spurious line, never a corrupt view — and every conservative bail
+ *  here (unknown subtree, gated level) errs on the spurious-line side, never the missed-line side.
+ *  Order-preserving for survivors; returns the input array unchanged when nothing cancels. */
+function netChanges(changes: FlatChange[], schema: WireSchema): FlatChange[] {
+  if (changes.length < 2) return changes;
+  const alive = new Array<boolean>(changes.length).fill(true);
+  const removes = new Map<string, number[]>(); // key → indices of not-yet-cancelled removes
+  const adds = new Map<string, number[]>(); // key → indices of not-yet-cancelled adds
+  const edits = new Map<string, number[]>(); // pathKey+old+new → indices of not-yet-cancelled edits
+  // The subtree an add/remove carries, canonicalized to maintained (sorted, dup-folded) form so a
+  // shipped-order `add` node and a maintained-order enriched `remove` node compare structurally.
+  // Built ONLY when two ops collide on the row key — the common no-collision delivery never builds
+  // one — and memoized per op index. `null` ⇒ subtree unknown (a gated level, or a remove that was
+  // not enriched); conservative: an unknown subtree never cancels, so we err toward a spurious line.
+  const subCache = new Map<number, Node | null>();
+  const subtreeOf = (i: number): Node | null => {
+    let s = subCache.get(i);
+    if (s !== undefined) return s;
+    const { path, op } = changes[i];
+    const level = levelSchemaAt(schema, path);
+    // A remove reaching the net actually evicted its node (only applied ops are delivered) and so was
+    // enriched with its subtree on `op.node`; an add always carries `op.node`. Either is canonicalized.
+    const wnode = op.tag === "add" ? op.node : op.tag === "remove" ? op.node : undefined;
+    s = level && wnode ? buildNode(wnode, level) : null;
+    subCache.set(i, s);
+    return s;
+  };
+  // Take the LATEST pending opposite at the same key whose subtree also matches (LIFO, like the
+  // plain `take` below, so nested cycles unwind innermost-first).
+  const takeInverse = (m: Map<string, number[]>, k: string, i: number): number | undefined => {
+    const arr = m.get(k);
+    if (!arr || arr.length === 0) return undefined;
+    const mine = subtreeOf(i);
+    if (mine === null) return undefined;
+    for (let x = arr.length - 1; x >= 0; x--) {
+      const theirs = subtreeOf(arr[x]);
+      if (theirs !== null && nodesEqual(mine, theirs)) {
+        const j = arr[x];
+        arr.splice(x, 1);
+        return j;
+      }
+    }
+    return undefined;
+  };
+  const take = (m: Map<string, number[]>, k: string): number | undefined => {
+    const arr = m.get(k);
+    return arr && arr.length ? arr.pop() : undefined;
+  };
+  const put = (m: Map<string, number[]>, k: string, i: number): void => {
+    const arr = m.get(k);
+    if (arr) arr.push(i);
+    else m.set(k, [i]);
+  };
+  let cancelled = false;
+  for (let i = 0; i < changes.length; i++) {
+    const { path, op } = changes[i];
+    if (op.tag === "remove") {
+      const k = opRowKey(path, op.row);
+      const j = takeInverse(adds, k, i);
+      if (j !== undefined) {
+        alive[i] = alive[j] = false;
+        cancelled = true;
+      } else put(removes, k, i);
+    } else if (op.tag === "add") {
+      const k = opRowKey(path, op.node.row);
+      const j = takeInverse(removes, k, i);
+      if (j !== undefined) {
+        alive[i] = alive[j] = false;
+        cancelled = true;
+      } else put(adds, k, i);
+    } else {
+      // edit: cancel against a prior INVERSE edit (a→b then b→a) at the same path. The old/new
+      // bytes are part of the map key, so the inverse lookup is O(1) instead of a rescan.
+      const pk = opRowKey(path, []);
+      const oldS = keyRow(op.old);
+      const newS = keyRow(op.new);
+      const j = take(edits, pk + "" + newS + "" + oldS);
+      if (j !== undefined) {
+        alive[i] = alive[j] = false;
+        cancelled = true;
+      } else put(edits, pk + "" + oldS + "" + newS, i);
+    }
+  }
+  if (!cancelled) return changes;
+  const out: FlatChange[] = [];
+  for (let i = 0; i < changes.length; i++) if (alive[i]) out.push(changes[i]);
+  return out;
 }
 
 const EMPTY: readonly never[] = Object.freeze([]);
@@ -177,8 +355,10 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   private _schema: WireSchema | null;
   private types?: ViewTypes;
   // SSR first-paint seed (SSR-DESIGN.md §6): pre-projected rows installed by `seed`, returned by
-  // `data` WHILE pending (no live schema yet). Cleared on `reset` — the first live `hello` —
-  // so the maintained tree takes over and the live snapshot reconciles. `null` ⇒ no seed.
+  // `data` until the maintained tree's first live SNAPSHOT lands (the Store calls `retireSeed` then).
+  // It deliberately SURVIVES `reset` (the `hello`), so a seeded view bridges the `hello`→snapshot gap
+  // instead of flashing empty in between (a `hello` sets the schema but its data arrives one round-trip
+  // later, on the snapshot). `null` ⇒ no seed.
   private seeded: readonly R[] | null = null;
   private top: Node[] = [];
   private dirty = true;
@@ -188,6 +368,16 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   // (the optimistic backend: `unknown` until hydrated, etc.).
   private rt: ResultType = "complete";
   private readonly listeners = new Set<(data: readonly R[]) => void>();
+  // The per-view CHANGE stream ({@link onChanges}) — the diff a narrator rides, distinct from the
+  // data channel above. Empty until a narrator attaches: an idle view pays one `.size` check per fold.
+  private readonly changeListeners = new Set<ViewChangeListener>();
+  // Changes folded but not yet delivered to `changeListeners` — buffered while the Store defers a
+  // commit (mirrors the deferred `notify`), then netted + flushed at the commit boundary. Segmented
+  // BY PHASE (not one last-writer-wins phase scalar): a bracket that folds both a `snapshot` and a
+  // `batch` into this view keeps them apart, each netted and delivered under its OWN phase, so a
+  // snapshot is never mislabeled `batch` (nor a batch dropped as `snapshot`). Consecutive same-phase
+  // folds coalesce into one segment so a whole commit's batch nets together.
+  private pendingSegments: { phase: ChangePhase; changes: FlatChange[] }[] = [];
 
   constructor(schema?: WireSchema, types?: ViewTypes, qid: QueryId = 0) {
     this._schema = schema ?? null;
@@ -219,25 +409,45 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   /** (Re)bind to a schema and clear the tree IN PLACE. The first `hello` (pending → ready)
    *  and a re-hydrate (gap → new epoch — FLAT-CHANGES-DESIGN.md §2.3) both go through here, so
    *  the caller's view reference and its subscribers survive a re-subscribe. Does NOT notify —
-   *  the snapshot that follows (`applyChanges`) does, avoiding an empty-then-filled flicker. */
+   *  the snapshot that follows (`applyChanges`) does, avoiding an empty-then-filled flicker.
+   *  KEEPS any SSR `seeded` rows: they are retired only when the first live snapshot lands
+   *  ({@link retireSeed}, driven by the Store), so `data` shows the seed — not an empty tree —
+   *  across the whole `hello`→first-`snapshot` gap. */
   reset(schema: WireSchema, types?: ViewTypes): void {
     this._schema = schema;
     this.types = types;
-    this.seeded = null; // live data takes over; the seed was first-paint only
     this.top = [];
     this.cached = null;
     this.dirty = true;
+    // Drop any changes buffered under the OLD epoch: a re-hydrate cuts a new schema, and
+    // `deliverChanges` resolves against the current `_schema`, so pre-epoch changes must never
+    // survive to be delivered against the new one (mirrors `destroy`). The snapshot that follows
+    // this reset re-establishes the buffer for the new epoch.
+    this.pendingSegments = [];
   }
 
   /** Install a pre-projected SSR first-paint snapshot (SSR-DESIGN.md §6). The rows are already
    *  in result shape (json columns parsed, relationships nested), so a view with no live backend
    *  (the server one-shot Store) reads them directly, and a browser view shows them until its
-   *  first live `hello` (`reset`) swaps in the maintained tree. Does NOT notify — it is set at
-   *  materialize time, before any subscriber, and the live snapshot that follows notifies. */
+   *  first live snapshot lands ({@link retireSeed}). Does NOT notify — it is set at materialize
+   *  time, before any subscriber, and the live snapshot that follows notifies. */
   seed(rows: readonly R[]): void {
     this.seeded = rows;
   }
 
+  /** Retire the SSR first-paint seed — the Store calls this as it folds the maintained tree's first
+   *  live snapshot, so `data` switches from the seed to the live tree with no empty gap between them
+   *  (the seed deliberately survived the earlier `reset`/`hello`). Idempotent. Does NOT notify — the
+   *  snapshot fold it accompanies does; BUT when that fold is empty (a 0-row result, or rows already
+   *  in `top`) it notifies nothing, so the Store forces a {@link notify} on the strength of the `true`
+   *  return here — else the view reads the live tree yet never re-renders (a frozen seed). Returns
+   *  whether a live seed was actually cleared (so the Store knows a forced notify is owed). */
+  retireSeed(): boolean {
+    if (this.seeded === null) return false;
+    this.seeded = null;
+    return true;
+  }
+
   /** Apply a batch (the hydrate snapshot or one transaction's events) in order, then
    *  notify subscribers once. Order is significant (FLAT-CHANGES-DESIGN.md §5.4). A no-op
    *  while pending (changes never precede the `hello` that resets the schema).
@@ -245,21 +455,61 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
    *  `enrichRemoves` ⇒ before a removed node is dropped, reconstruct its full subtree and attach it
    *  to the `remove` op's `node` (in place, so the same event object the Store fans out to its
    *  change subscribers carries it). Off by default — paid only when a consumer asked for it, and
-   *  only on a real eviction (an rc-decrement that keeps the row leaves `node` absent).
+   *  only on a real eviction (an rc-decrement that keeps the row leaves `node` absent). A view with
+   *  an attached {@link onChanges} listener ALSO enriches (per-view, no global opt-in), so a
+   *  narrator can resolve a removed row's subs whether or not the store-global counter is set.
    *
    *  `deferNotify` ⇒ fold but do NOT notify; the caller is responsible for calling {@link flush}
    *  later. The Store uses this to fold every view in one commit before notifying any subscriber
    *  (cross-view-atomic notification — `Store.onCommitBoundary`); standalone use leaves it off, so
    *  a bare view still fires its subscribers after each applied batch.
    *
-   *  Returns whether the batch changed the view (so a deferring caller knows it must be flushed). */
-  applyChanges(events: FlatChange[], enrichRemoves = false, deferNotify = false): boolean {
+   *  `phase` tags the {@link onChanges} delivery (`snapshot` for the hydrate, `batch` otherwise); it
+   *  does not affect the fold. Returns whether the batch changed the view (so a deferring caller
+   *  knows it must be flushed). */
+  applyChanges(events: FlatChange[], enrichRemoves = false, deferNotify = false, phase: ChangePhase = "batch"): boolean {
     if (this._schema === null) return false;
-    let changed = false;
-    for (const e of events) changed = this.applyAt(this.top, this._schema, e.path, e.op, 0, enrichRemoves) || changed;
-    if (!changed) return false;
+    // Enrich this view's removes when a narrator is attached (see the `enrichRemoves` doc above) —
+    // the per-view twin of the store's global `removedSubtree` counter.
+    const enrich = enrichRemoves || this.changeListeners.size > 0;
+    // Deliver ONLY the ops that actually changed the tree: a duplicate-path add (rc bump), an
+    // rc-decrement remove that left the row, a no-op edit, and a gated op all return false — none is
+    // a real change, so none should reach a narrator. (Enrichment already attached the subtree to a
+    // real remove during the fold, so a surviving remove carries its `node`.)
+    const applied: FlatChange[] = [];
+    for (const e of events) {
+      if (this.applyAt(this.top, this._schema, e.path, e.op, 0, enrich)) applied.push(e);
+    }
+    if (applied.length === 0) return false;
     this.dirty = true;
-    if (!deferNotify) this.notify();
+    if (deferNotify) {
+      if (this.changeListeners.size > 0) {
+        const segs = this.pendingSegments;
+        const last = segs.length > 0 ? segs[segs.length - 1] : undefined;
+        if (last && last.phase === phase) for (const e of applied) last.changes.push(e);
+        else segs.push({ phase, changes: applied.slice() });
+      }
+      return true;
+    }
+    // Inline (standalone / no commit bracket): notify data subscribers, then deliver the change
+    // stream — each isolated, first error re-raised once both have run (mirroring the Store's
+    // per-view flush isolation) so a throwing narration listener never starves the data channel,
+    // aborts the fold's return, or propagates raw into the engine's push path.
+    let firstError: unknown;
+    let hasError = false;
+    const note = (e: unknown): void => {
+      if (!hasError) {
+        hasError = true;
+        firstError = e;
+      }
+    };
+    try {
+      this.notify();
+    } catch (e) {
+      note(e);
+    }
+    this.deliverChanges(applied, phase, note);
+    if (hasError) throw firstError;
     return true;
   }
 
@@ -268,11 +518,35 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
    *  touched by the same commit has folded — so a subscriber that re-reads a sibling view inside
    *  its callback observes post-commit data, never a torn mid-commit state. */
   flush(): void {
-    this.notify();
+    // Take the buffer BEFORE delivery so a throwing listener can never leave changes buffered to be
+    // re-delivered — merged and cross-phase-netted — into a LATER commit's flush. Notify and every
+    // segment's delivery are isolated; the first error is re-raised after all have run, so one bad
+    // subscriber starves neither the data channel nor a sibling segment (matching `flushCommit`).
+    const segs = this.pendingSegments;
+    this.pendingSegments = [];
+    let firstError: unknown;
+    let hasError = false;
+    const note = (e: unknown): void => {
+      if (!hasError) {
+        hasError = true;
+        firstError = e;
+      }
+    };
+    try {
+      this.notify();
+    } catch (e) {
+      note(e);
+    }
+    for (const seg of segs) this.deliverChanges(seg.changes, seg.phase, note);
+    if (hasError) throw firstError;
   }
 
   get data(): readonly R[] {
-    if (this._schema === null) return this.seeded ?? (EMPTY as readonly R[]);
+    // A live SSR seed owns `data` until it is retired on the first live snapshot ({@link retireSeed}) —
+    // this spans pending (no schema) AND the post-`hello`, pre-snapshot window (schema set, tree still
+    // empty), so a seeded query never flashes empty during the handoff. `null` seed ⇒ normal behavior.
+    if (this.seeded !== null) return this.seeded;
+    if (this._schema === null) return EMPTY as readonly R[];
     if (!this.dirty && this.cached !== null) return this.cached;
     this.cached = this.top.map((n) => this.project(n, this._schema as WireSchema, this.types)) as R[];
     this.dirty = false;
@@ -287,8 +561,38 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     };
   }
 
+  onChanges(listener: ViewChangeListener): () => void {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
+  }
+
+  /** Net the folded batch and hand the survivors to the change listeners, AFTER the data `notify`
+   *  (the order `Store.subscribeChanges` consumers already observe). A batch that nets to nothing —
+   *  a correctly predicted rebase — makes no call, so a narrator sees only real change. Each listener
+   *  is isolated: a throwing one reports to `note` (the caller re-raises the first) and the rest still
+   *  run, so one bad narration template never starves a sibling listener nor corrupts the view. */
+  private deliverChanges(events: FlatChange[], phase: ChangePhase, note: (e: unknown) => void): void {
+    if (this.changeListeners.size === 0) return;
+    // `_schema` is non-null here: `applyChanges` early-returns while pending, and `flush` runs only
+    // after a fold — so a listener always has the position→name source in hand.
+    const schema = this._schema as WireSchema;
+    const net = netChanges(events, schema);
+    if (net.length === 0) return;
+    for (const l of this.changeListeners) {
+      try {
+        l(net, phase, schema);
+      } catch (e) {
+        note(e);
+      }
+    }
+  }
+
   destroy(): void {
     this.listeners.clear();
+    this.changeListeners.clear();
+    this.pendingSegments = [];
     this.top = [];
   }
 
@@ -438,7 +742,10 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     return obj;
   }
 
-  private notify(): void {
+  /** Notify data subscribers with the current {@link data}. Normally driven by a fold ({@link
+   *  applyChanges}/{@link flush}); the Store also calls it directly to land a seed retirement whose
+   *  accompanying fold was empty (see {@link retireSeed}). */
+  notify(): void {
     const d = this.data;
     for (const l of this.listeners) l(d);
   }