@rindle/client 0.2.0 → 0.3.1

package/src/view.ts

@@ -9,7 +9,7 @@
 // and untouched subtrees keep their object identity (React/Solid memoize on it).
 
 import { compareRows } from "./compare.ts";
-import type { ColType, FlatChange, FlatOp, ResultType, WireNode, WireSchema, WireValue } from "./types.ts";
+import type { ColType, FlatChange, FlatOp, QueryId, ResultType, WireNode, WireSchema, WireValue } from "./types.ts";
 
 /** Per-level column types (parallel to the WireSchema), used to JSON.parse json columns on
  *  projection. Built by the Store from the typed schema; absent ⇒ no parsing (bare values). */
@@ -22,6 +22,15 @@ export interface ViewTypes {
 export interface ArrayView<R> {
   /** The current materialized result (reference-stable where data is unchanged). */
   readonly data: readonly R[];
+  /** The engine query id the Store assigned this view (1:1 with the view). The same `qid` the raw
+   *  change stream ({@link Store.subscribeChanges}) tags each frame with, so a consumer can
+   *  correlate this query with its `ChangeEvent`s (e.g. to bind a narrator) straight off
+   *  `materialize(query).qid` — no separate handle needed. */
+  readonly qid: QueryId;
+  /** The query's view `WireSchema` (the position→name source for {@link resolveChange}), captured
+   *  from its `hello` frame. `null` while PENDING — a remote backend's `hello` arrives async; an
+   *  in-process backend (wasm/replica) populates it synchronously during `materialize`. */
+  readonly schema: WireSchema | null;
   /** The query's SERVER-CHANNEL state (`unknown` while loading, `complete` once server-authoritative;
    *  the `error` variant is reserved and currently unproduced). A pending optimistic mutation no
    *  longer moves this — it is a separate axis (FOLDED-MUTATIONS-DESIGN §7). `complete` for backends
@@ -40,6 +49,10 @@ export interface ArrayView<R> {
 export interface SingularArrayView<R> {
   /** The single current row, or `null` when the query matches nothing. */
   readonly data: R | null;
+  /** The engine query id — see {@link ArrayView.qid}. */
+  readonly qid: QueryId;
+  /** The query's view `WireSchema` — see {@link ArrayView.schema}. */
+  readonly schema: WireSchema | null;
   /** The query's lifecycle state — see {@link ArrayView.resultType}. */
   readonly resultType: ResultType;
   /** Subscribe; fires immediately with the current row, then after each applied batch (and after
@@ -62,6 +75,14 @@ export class SingularView<R> implements SingularArrayView<R> {
     return this.inner.data[0] ?? null;
   }
 
+  get qid(): QueryId {
+    return this.inner.qid;
+  }
+
+  get schema(): WireSchema | null {
+    return this.inner.schema;
+  }
+
   get resultType(): ResultType {
     return this.inner.resultType;
   }
@@ -124,6 +145,22 @@ function cloneNode(n: Node): Node {
   return { row: n.row.slice(), rc: n.rc, rels: n.rels.map((r) => r.map(cloneNode)), out: null };
 }
 
+/** Reconstruct a positional {@link WireNode} (row + its populated child slots) from a maintained
+ *  {@link Node} — the inverse of {@link buildNode}. Used to attach a removed subtree to a `remove`
+ *  op so a change consumer (a narrator) can resolve its nested subs, which a bare positional remove
+ *  (just the leaving row) cannot carry. Only in-view (`child !== null`), non-empty slots are emitted,
+ *  matching how an `add` node ships only populated relationships. */
+function toWireNode(node: Node, schema: WireSchema): WireNode {
+  const rels: { rel: number; children: WireNode[] }[] = [];
+  for (const rel of schema.relationships) {
+    if (rel.child === null) continue;
+    const childList = node.rels[rel.slot] ?? [];
+    if (childList.length === 0) continue;
+    rels.push({ rel: rel.slot, children: childList.map((c) => toWireNode(c, rel.child as WireSchema)) });
+  }
+  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]));
 }
@@ -131,9 +168,13 @@ function rowsEqual(a: WireValue[], b: WireValue[]): boolean {
 const EMPTY: readonly never[] = Object.freeze([]);
 
 export class FlatArrayView<R = unknown> implements ArrayView<R> {
+  // The engine query id (Store-assigned, 1:1 with this view), exposed read-only via {@link qid}.
+  // `0` ⇒ unbound (a bare view never registered with a Store); the Store passes it at construction.
+  private readonly _qid: QueryId;
   // `null` ⇒ PENDING (no schema yet): a remote backend's `hello` arrives async, so the view
   // exists (and reads as `[]`) before its schema lands. Set by `reset` (first hello / re-hydrate).
-  private schema: WireSchema | null;
+  // Exposed read-only via the {@link schema} getter (the position→name source for `resolveChange`).
+  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` —
@@ -148,9 +189,18 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   private rt: ResultType = "complete";
   private readonly listeners = new Set<(data: readonly R[]) => void>();
 
-  constructor(schema?: WireSchema, types?: ViewTypes) {
-    this.schema = schema ?? null;
+  constructor(schema?: WireSchema, types?: ViewTypes, qid: QueryId = 0) {
+    this._schema = schema ?? null;
     this.types = types;
+    this._qid = qid;
+  }
+
+  get qid(): QueryId {
+    return this._qid;
+  }
+
+  get schema(): WireSchema | null {
+    return this._schema;
   }
 
   get resultType(): ResultType {
@@ -171,7 +221,7 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
    *  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. */
   reset(schema: WireSchema, types?: ViewTypes): void {
-    this.schema = schema;
+    this._schema = schema;
     this.types = types;
     this.seeded = null; // live data takes over; the seed was first-paint only
     this.top = [];
@@ -190,20 +240,41 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
 
   /** 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). */
-  applyChanges(events: FlatChange[]): void {
-    if (this.schema === null) return;
+   *  while pending (changes never precede the `hello` that resets the schema).
+   *
+   *  `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).
+   *
+   *  `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 {
+    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) || changed;
-    if (!changed) return;
+    for (const e of events) changed = this.applyAt(this.top, this._schema, e.path, e.op, 0, enrichRemoves) || changed;
+    if (!changed) return false;
     this.dirty = true;
+    if (!deferNotify) this.notify();
+    return true;
+  }
+
+  /** Notify subscribers with the current data. The deferred half of {@link applyChanges} (when
+   *  `deferNotify` was set): the Store calls this at the commit-notify barrier — after every view
+   *  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();
   }
 
   get data(): readonly R[] {
-    if (this.schema === null) return this.seeded ?? (EMPTY as readonly R[]);
+    if (this._schema === null) return this.seeded ?? (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.cached = this.top.map((n) => this.project(n, this._schema as WireSchema, this.types)) as R[];
     this.dirty = false;
     return this.cached;
   }
@@ -223,9 +294,9 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
 
   // --- apply -------------------------------------------------------------------
 
-  private applyAt(list: Node[], schema: WireSchema, path: FlatChange["path"], op: FlatOp, depth: number): boolean {
+  private applyAt(list: Node[], schema: WireSchema, path: FlatChange["path"], op: FlatOp, depth: number, enrichRemoves: boolean): boolean {
     if (depth === path.length) {
-      return this.applyOp(list, schema, op);
+      return this.applyOp(list, schema, op, enrichRemoves);
     }
     const seg = path[depth];
     const child = schema.relationships[seg.rel]?.child;
@@ -233,14 +304,20 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     const { found, index } = binarySearch(list, seg.parentRow, schema.sort);
     if (!found) throw new Error("flat ArrayView: parent not found at path hop (inconsistent stream)");
     const node = list[index];
-    const changed = this.applyAt(node.rels[seg.rel], child, path, op, depth + 1);
+    const changed = this.applyAt(node.rels[seg.rel], child, path, op, depth + 1, enrichRemoves);
     if (changed) node.out = null; // a descendant changed → this node must re-project its rel array
     return changed;
   }
 
-  private applyOp(list: Node[], schema: WireSchema, op: FlatOp): boolean {
+  private applyOp(list: Node[], schema: WireSchema, op: FlatOp, enrichRemoves: boolean): boolean {
     if (op.tag === "add") return this.applyAdd(list, schema, op.node);
-    if (op.tag === "remove") return this.applyRemove(list, schema, op.row);
+    if (op.tag === "remove") {
+      const removed = this.applyRemove(list, schema, op.row);
+      // Attach the full removed subtree (in place) for an opted-in consumer; absent when the row
+      // only lost a reference (rc > 1) and so did not actually leave the result.
+      if (removed && enrichRemoves) op.node = toWireNode(removed, schema);
+      return removed !== null;
+    }
     return this.applyEdit(list, schema, op.old, op.new);
   }
 
@@ -254,15 +331,19 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     return true;
   }
 
-  private applyRemove(list: Node[], schema: WireSchema, row: WireValue[]): boolean {
+  /** Drop one path to `row`. Returns the evicted {@link Node} (its full subtree intact) when the
+   *  last path went away — `null` when another path still holds it (rc decremented, nothing left
+   *  the result). */
+  private applyRemove(list: Node[], schema: WireSchema, row: WireValue[]): Node | null {
     const at = binarySearch(list, row, schema.sort);
     if (!at.found) throw new Error("flat ArrayView: remove of a non-existent node");
-    if (list[at.index].rc === 1) {
+    const node = list[at.index];
+    if (node.rc === 1) {
       list.splice(at.index, 1);
-      return true;
+      return node;
     }
-    list[at.index].rc -= 1;
-    return false;
+    node.rc -= 1;
+    return null;
   }
 
   private applyEdit(list: Node[], schema: WireSchema, oldRow: WireValue[], newRow: WireValue[]): boolean {