@rindle/client 0.1.0-rc.5

package/dist/view.js

@@ -0,0 +1,294 @@
+// The JS ArrayView — the materialized, typed result tree a backend's ChangeEvent stream
+// folds into (WASM-CLIENT-DESIGN.md §7, §8). A faithful port of the View's `apply_change`
+// (src/view.rs / src/flat_receiver.rs), the §6 receiver contract of FLAT-CHANGES-DESIGN.md:
+// descend the path with the in-view gate, then Add / Remove / Edit (rc + the edit-move
+// ghost/adjusted-position/merge protocol) located by value-driven binary search.
+//
+// Reads are cheap and reference-stable: each node memoizes its projected output (`out`),
+// invalidated only along the root→mutation spine, so `.data` re-projects only what changed
+// and untouched subtrees keep their object identity (React/Solid memoize on it).
+import { compareRows } from "./compare.js";
+/** Wrap a plural {@link FlatArrayView} as a {@link SingularArrayView} for a `.one()` query
+ *  (the engine caps it to `limit = 1`, so the top list holds at most one node). */
+export class SingularView {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    get data() {
+        return this.inner.data[0] ?? null;
+    }
+    get resultType() {
+        return this.inner.resultType;
+    }
+    subscribe(listener) {
+        return this.inner.subscribe((d) => listener(d[0] ?? null));
+    }
+    destroy() {
+        this.inner.destroy();
+    }
+}
+function binarySearch(list, row, sort) {
+    let lo = 0;
+    let hi = list.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        const c = compareRows(list[mid].row, row, sort);
+        if (c < 0)
+            lo = mid + 1;
+        else if (c > 0)
+            hi = mid;
+        else
+            return { found: true, index: mid };
+    }
+    return { found: false, index: lo };
+}
+/** Build a fresh node (rc = 1) with its inline subtree, mirroring `init_rels_for_new_entry`:
+ *  one list per declared slot; fill in-view slots from the payload (children inserted in the
+ *  order shipped — NEVER re-sorted — folding same-sort-key dups to rc += 1). */
+function buildNode(wnode, schema) {
+    const rels = schema.relationships.map(() => []);
+    for (const { rel, children } of wnode.rels) {
+        const child = schema.relationships[rel]?.child;
+        if (!child)
+            continue; // join-only / gating slot — not materialized
+        const built = [];
+        for (const c of children) {
+            const at = binarySearch(built, c.row, child.sort);
+            if (at.found)
+                built[at.index].rc += 1;
+            else
+                built.splice(at.index, 0, buildNode(c, child));
+        }
+        rels[rel] = built;
+    }
+    return { row: wnode.row, rc: 1, rels, out: null };
+}
+function cloneNode(n) {
+    return { row: n.row.slice(), rc: n.rc, rels: n.rels.map((r) => r.map(cloneNode)), out: null };
+}
+const EMPTY = Object.freeze([]);
+export class FlatArrayView {
+    // `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).
+    schema;
+    types;
+    // 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.
+    seeded = null;
+    top = [];
+    dirty = true;
+    cached = null;
+    // `complete` by default: a backend with no server lifecycle (the in-process engine) never pushes
+    // a resultType, so its views read as authoritative. The Store overrides this for backends that do
+    // (the optimistic backend: `unknown` until hydrated, etc.).
+    rt = "complete";
+    listeners = new Set();
+    constructor(schema, types) {
+        this.schema = schema ?? null;
+        this.types = types;
+    }
+    get resultType() {
+        return this.rt;
+    }
+    /** Set the query's lifecycle state (the Store routes the backend's per-query signal here).
+     *  Notifies subscribers on a change so a status-bound listener (React `useQueryStatus`) re-reads,
+     *  WITHOUT re-projecting data (it is unchanged). */
+    setResultType(rt) {
+        if (this.rt === rt)
+            return;
+        this.rt = rt;
+        for (const l of this.listeners)
+            l(this.data);
+    }
+    /** (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. */
+    reset(schema, types) {
+        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;
+    }
+    /** 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. */
+    seed(rows) {
+        this.seeded = rows;
+    }
+    /** 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) {
+        if (this.schema === null)
+            return;
+        for (const e of events)
+            this.applyAt(this.top, this.schema, e.path, e.op, 0);
+        this.dirty = true;
+        this.notify();
+    }
+    get data() {
+        if (this.schema === null)
+            return this.seeded ?? EMPTY;
+        if (!this.dirty && this.cached !== null)
+            return this.cached;
+        this.cached = this.top.map((n) => this.project(n, this.schema, this.types));
+        this.dirty = false;
+        return this.cached;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.data);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    destroy() {
+        this.listeners.clear();
+        this.top = [];
+    }
+    // --- apply -------------------------------------------------------------------
+    applyAt(list, schema, path, op, depth) {
+        if (depth === path.length) {
+            this.applyOp(list, schema, op);
+            return;
+        }
+        const seg = path[depth];
+        const child = schema.relationships[seg.rel]?.child;
+        if (!child)
+            return; // in-view gate: a gating slot drops the whole change
+        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];
+        node.out = null; // a descendant changed → this node must re-project its rel array
+        this.applyAt(node.rels[seg.rel], child, path, op, depth + 1);
+    }
+    applyOp(list, schema, op) {
+        if (op.tag === "add")
+            this.applyAdd(list, schema, op.node);
+        else if (op.tag === "remove")
+            this.applyRemove(list, schema, op.row);
+        else
+            this.applyEdit(list, schema, op.old, op.new);
+    }
+    applyAdd(list, schema, wnode) {
+        const at = binarySearch(list, wnode.row, schema.sort);
+        if (at.found)
+            list[at.index].rc += 1; // duplicate path to an existing row; ignore subtree
+        else
+            list.splice(at.index, 0, buildNode(wnode, schema));
+    }
+    applyRemove(list, schema, row) {
+        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)
+            list.splice(at.index, 1);
+        else
+            list[at.index].rc -= 1;
+    }
+    applyEdit(list, schema, oldRow, newRow) {
+        const sort = schema.sort;
+        if (compareRows(oldRow, newRow, sort) === 0) {
+            // Sort key unchanged → edit in place (keeps position + children + rc).
+            const at = binarySearch(list, oldRow, sort);
+            if (!at.found)
+                throw new Error("flat ArrayView: edit of a non-existent node");
+            list[at.index].row = newRow;
+            list[at.index].out = null;
+            return;
+        }
+        // Sort key changed → the row may move; rc may be > 1.
+        const oldAt = binarySearch(list, oldRow, sort);
+        if (!oldAt.found)
+            throw new Error("flat ArrayView: edit old node does not exist");
+        const oldPos = oldAt.index;
+        const oldRc = list[oldPos].rc;
+        const raw = binarySearch(list, newRow, sort);
+        const found = raw.found;
+        const pos = raw.index;
+        const oldEntry = cloneNode(list[oldPos]); // capture (with children) BEFORE mutating
+        // Fast path: rc==1 and the row lands in the same slot after removal → edit in place.
+        if (oldRc === 1 && (pos === oldPos || pos - 1 === oldPos)) {
+            list[oldPos].row = newRow;
+            list[oldPos].out = null;
+            return;
+        }
+        // General move.
+        const newRc = oldRc - 1;
+        let adjusted;
+        if (newRc === 0) {
+            list.splice(oldPos, 1);
+            adjusted = oldPos < pos ? pos - 1 : pos;
+        }
+        else {
+            list[oldPos].rc = newRc; // ghost survives for the other path(s); its row is unchanged
+            adjusted = pos;
+        }
+        if (found) {
+            // Merge into the existing destination entry (keep its children); bump its rc.
+            const existingRc = list[adjusted].rc;
+            list[adjusted].row = newRow;
+            list[adjusted].rc = existingRc + 1;
+            list[adjusted].out = null;
+        }
+        else {
+            // Move the (edited) old entry — keeping its children — to the new position.
+            oldEntry.row = newRow;
+            oldEntry.rc = 1;
+            list.splice(adjusted, 0, oldEntry);
+        }
+    }
+    // --- projection (memoized, structurally shared) -----------------------------
+    project(node, schema, types) {
+        if (node.out !== null)
+            return node.out;
+        const obj = {};
+        for (let i = 0; i < schema.columns.length; i++) {
+            const v = node.row[i];
+            // A projected query carries an ABSENT cell (`undefined`, PROJECTION-SUPPORT-DESIGN.md
+            // §5.3) for a column it did not sync; omit it from the result object so a query never
+            // resolves a row from columns it did not select (§6). A present-and-null cell is `null`
+            // and is kept. For a `'*'` query no cell is ever `undefined`, so this is inert (§7).
+            if (v === undefined)
+                continue;
+            // convert-once: a json column's raw string is parsed to an object on store (cached in `out`).
+            obj[schema.columns[i]] = types?.columnTypes[i] === "json" && typeof v === "string" ? JSON.parse(v) : v;
+        }
+        for (const rel of schema.relationships) {
+            if (rel.child === null)
+                continue; // gating slot — not part of .data
+            const childList = node.rels[rel.slot] ?? [];
+            const ct = types?.rels[rel.slot];
+            if (rel.project) {
+                // A scalar-projected relationship aggregate (REDUCE-DESIGN.md §9): unwrap the one-row
+                // child to a bare scalar (its project.col cell), substituting the aggregate identity
+                // when empty (a childless parent). A json-typed projected column is parsed like a column.
+                const cell = childList.length > 0 ? childList[0].row[rel.project.col] : rel.project.identity;
+                const projType = ct?.columnTypes[rel.project.col];
+                obj[rel.name] = projType === "json" && typeof cell === "string" ? JSON.parse(cell) : cell;
+                continue;
+            }
+            obj[rel.name] = rel.child.singular
+                ? childList.length > 0
+                    ? this.project(childList[0], rel.child, ct)
+                    : null
+                : childList.map((c) => this.project(c, rel.child, ct));
+        }
+        node.out = obj;
+        return obj;
+    }
+    notify() {
+        const d = this.data;
+        for (const l of this.listeners)
+            l(d);
+    }
+}
+//# sourceMappingURL=view.js.map

package/dist/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@rindle/client",
+  "version": "0.1.0-rc.5",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rindle-sh/rindle.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "description": "Backend-agnostic flat-change client core: typed schema, query builder, ArrayView, comparator, Backend seam.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@rindle/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsc --noEmit && node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/ast.ts

@@ -0,0 +1,94 @@
+// The Zero-wire query AST — the exact JSON shape the Rust `Ast` deserializes
+// (src/ast.rs). The builder emits these; the wasm `Db.query` (and a remote server) parse
+// them. camelCase keys, `type`-tagged unions, ops as SQL-ish strings, untagged literals.
+
+export type Dir = "asc" | "desc";
+
+/** One `(field, direction)` ordering — serializes as the 2-tuple `["id", "asc"]`. */
+export type OrderPart = [field: string, dir: Dir];
+
+/** An untagged literal (`null | bool | number | string | array`). Numbers are one f64. */
+export type LitValue = null | boolean | number | string | LitValue[];
+
+/** A column reference or a literal — `type`-tagged. */
+export type ValuePosition =
+  | { type: "column"; name: string }
+  | { type: "literal"; value: LitValue };
+
+/** The wire comparison operators (exact strings, `src/ast.rs` `Op`). */
+export type SimpleOp =
+  | "="
+  | "!="
+  | "<"
+  | "<="
+  | ">"
+  | ">="
+  | "IS"
+  | "IS NOT"
+  | "LIKE"
+  | "NOT LIKE"
+  | "ILIKE"
+  | "NOT ILIKE"
+  | "IN"
+  | "NOT IN";
+
+export type ExistsOp = "EXISTS" | "NOT EXISTS";
+
+/** The filter tree — `type`-tagged; recursive. There is no generic NOT node (negation is
+ *  via the negated operators and `NOT EXISTS`, matching `src/ast.rs` `Condition`). */
+export type Condition =
+  | { type: "simple"; op: SimpleOp; left: ValuePosition; right: ValuePosition }
+  | { type: "and"; conditions: Condition[] }
+  | { type: "or"; conditions: Condition[] }
+  | { type: "correlatedSubquery"; related: CorrelatedSubquery; op: ExistsOp; flip?: boolean; scalar?: boolean };
+
+export interface Correlation {
+  parentField: string[];
+  childField: string[];
+}
+
+/** A paging lower bound (`Bound`, `src/ast.rs`). `row` is a *partial* wire row — the bound
+ *  columns by name (only the sort columns are read by the engine's `Skip` comparator).
+ *  `exclusive` ⇒ start *after* the bound row (`Basis::After`); else *at* it (`Basis::At`). */
+export interface Bound {
+  row: Record<string, LitValue>;
+  exclusive: boolean;
+}
+
+export interface CorrelatedSubquery {
+  correlation: Correlation;
+  subquery: Ast;
+  system?: "client" | "permissions" | "test";
+}
+
+/** An aggregate over a (correlated) subquery's rows (`REDUCE-DESIGN.md`). v1: `count(*)`.
+ *  Set on a `related` subquery (`Ast.aggregate`), it marks that relationship a count
+ *  aggregate the builder lowers to a scalar-projected singular relationship (§9). */
+export type Aggregate = "count";
+
+/** The query AST. `table` is the only required field; the builder omits empty/false fields
+ *  (matching the Rust `skip_serializing_if`), which the deserializer treats as absent. */
+export interface Ast {
+  table: string;
+  alias?: string;
+  /** Projection (PROJECTION-SUPPORT-DESIGN.md §6). Absent ⇒ select all columns; present ⇒
+   *  project to just these (drives what syncs + what the view reports). Serializes only when
+   *  set, matching the Rust `Ast.select`'s `skip_serializing_if`. */
+  select?: string[];
+  where?: Condition;
+  related?: CorrelatedSubquery[];
+  start?: Bound;
+  limit?: number;
+  one?: boolean;
+  /** Aggregate this (sub)query's rows instead of materializing them (`REDUCE-DESIGN.md`
+   *  §9). `count` on a `related` subquery surfaces a scalar `commentCount` field; the
+   *  builder lowers it to a scalar-projected singular relationship. Absent ⇒ ordinary rows. */
+  aggregate?: Aggregate;
+  /** The {@link Ast.aggregate} value is **precomputed** — supplied as rows of a (synthetic)
+   *  source table rather than reduced from child rows. Set by the normalized client's AST
+   *  rewrite (`AGGREGATE-SYNC-DESIGN.md` §3.3) so the local engine reads the server's count
+   *  with a plain singular join + the same projection instead of a `reduce`. Only meaningful
+   *  with `aggregate`; absent ⇒ `false`. */
+  aggregatePrecomputed?: boolean;
+  orderBy?: OrderPart[];
+}

package/src/compare.ts

@@ -0,0 +1,85 @@
+// The comparator — a faithful port of the engine's `compare_values` / `compare_rows`
+// (src/value.rs §4 of FLAT-CHANGES-DESIGN.md), the single most correctness-critical unit
+// (WASM-CLIENT-DESIGN.md §8.1). One fixed total order, NO collation.
+//
+// It is **value-driven** — it switches on the runtime JS type, exactly as the engine
+// switches on the `OwnedValue` variant. Bare wire values collapse Int/Float → number and
+// Str/Json → string, but within a sort column values are homogeneous, and number→total_cmp
+// / string→bytewise cover both, so this matches the engine without needing column types:
+//
+//   - null sorts FIRST (null < anything; null == null)
+//   - number:  IEEE-754 totalOrder (=== Rust `f64::total_cmp`) — NOT `<` / `-`
+//   - boolean: false < true
+//   - string:  UTF-8 BYTEWISE (=== SQLite BINARY / Rust `&str` Ord) — NOT `localeCompare`/`<`
+
+import type { WireValue } from "./types.ts";
+
+const enc = new TextEncoder();
+
+/** The `compare_values` / `compare_rows` algorithm-contract version (=== the engine's
+ *  `wire_schema::COMPARATOR_VERSION`). A remote subscriber hard-rejects a `hello` whose
+ *  `comparatorVersion` differs — the total order is a code contract, not data, so a schema
+ *  fingerprint can't cover it. Bump in lockstep with the Rust constant if the order changes. */
+export const COMPARATOR_VERSION = 1;
+
+const SIGN = 0x8000000000000000n;
+const ALL = 0xffffffffffffffffn;
+
+/** Map an f64 to an unsigned 64-bit key whose unsigned order is IEEE-754 totalOrder
+ *  (=== Rust `f64::total_cmp`): flip all bits for negatives (incl. -0 / -NaN), else set
+ *  the sign bit. */
+function orderedKey(x: number): bigint {
+  const dv = new DataView(new ArrayBuffer(8));
+  dv.setFloat64(0, x);
+  const bits = dv.getBigUint64(0);
+  return bits & SIGN ? bits ^ ALL : bits | SIGN;
+}
+
+/** number compare with `f64::total_cmp` semantics (NaN deterministic & last; -0 < +0). */
+export function compareNumber(a: number, b: number): -1 | 0 | 1 {
+  const ka = orderedKey(a);
+  const kb = orderedKey(b);
+  return ka < kb ? -1 : ka > kb ? 1 : 0;
+}
+
+/** UTF-8 bytewise string compare (=== SQLite `BINARY` / Rust `&str` Ord). Correct for
+ *  supplementary-plane code points, where JS `<` / `localeCompare` (UTF-16) would disagree. */
+export function compareString(a: string, b: string): -1 | 0 | 1 {
+  const ba = enc.encode(a);
+  const bb = enc.encode(b);
+  const n = Math.min(ba.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    if (ba[i] !== bb[i]) return ba[i] < bb[i] ? -1 : 1;
+  }
+  return ba.length === bb.length ? 0 : ba.length < bb.length ? -1 : 1;
+}
+
+/** Compare two bare cells, dispatching on the runtime type (null sorts first). */
+export function compareValue(a: WireValue, b: WireValue): -1 | 0 | 1 {
+  const an = a === null || a === undefined;
+  const bn = b === null || b === undefined;
+  if (an && bn) return 0;
+  if (an) return -1;
+  if (bn) return 1;
+  switch (typeof a) {
+    case "number":
+      return compareNumber(a, b as number);
+    case "boolean":
+      return a === b ? 0 : a ? 1 : -1;
+    case "string":
+      return compareString(a, b as string);
+    default:
+      // A parsed-JSON object in a sort column (rare): compare its text bytewise.
+      return compareString(JSON.stringify(a), JSON.stringify(b));
+  }
+}
+
+/** Compare two rows by a resolved sort (`[columnIndex, ascending]` pairs). First non-equal
+ *  column wins; a descending column negates. */
+export function compareRows(a: WireValue[], b: WireValue[], sort: [number, boolean][]): -1 | 0 | 1 {
+  for (const [col, asc] of sort) {
+    const c = compareValue(a[col], b[col]);
+    if (c !== 0) return asc ? c : ((-c) as -1 | 1);
+  }
+  return 0;
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+// @rindle/client — the backend-agnostic flat-change client core: typed schema, query builder,
+// comparator, Backend seam, and the ArrayView contract. (The ArrayView folding impl + the
+// Store/backend wiring land in later slices.)
+
+export * from "./schema.ts"; // table/columns/primaryKey, createSchema, string/number/boolean/json, Col, RowOf, Row, TableDef, tableSpec, SCHEMA
+export * from "./operators.ts"; // eq/ne/gt/ge/lt/le/like/notLike/ilike/notIlike/inList/notInList/is/isNot, and/or, Pred, Cond, Arg
+export * from "./query.ts"; // Query, QueryRoot, queries/newQueryBuilder, defineQuery/NamedQuery, exists, notExists, defineFragment/Fragment/FragmentRef/isFragment
+export * from "./view.ts"; // ArrayView, SingularArrayView, FlatArrayView, SingularView, ViewTypes
+export * from "./store.ts"; // Store, WriteTx, AssembledNode, DehydratedQuery, DehydratedState
+export * from "./ssr.ts"; // createServerStore, ServerStore, OneShotBackend, OneShotQueryFn, OneShotResult, ServerStoreOptions
+
+export { stableKey } from "./key.ts"; // canonical viewKey for an AST (shared with @rindle/react)
+
+export { COMPARATOR_VERSION, compareNumber, compareRows, compareString, compareValue } from "./compare.ts";
+
+export type {
+  Backend,
+  ChangeEvent,
+  ColType,
+  FlatChange,
+  FlatOp,
+  Mutation,
+  MutationEnvelope,
+  NormalizedEvent,
+  NormalizedOp,
+  NormalizedSource,
+  NormalizedTableSchema,
+  OptimisticSource,
+  PathSeg,
+  ProgressFrame,
+  QueryId,
+  RemoteQuery,
+  ResultType,
+  WireNode,
+  WireProjection,
+  WireRel,
+  WireSchema,
+  WireValue,
+} from "./types.ts";
+
+export { CLIENT_MUTATIONS_SCHEMA, CLIENT_MUTATIONS_TABLE, LMID_QUERY_NAME } from "./types.ts";
+
+// The Zero-wire AST types (for backends / advanced use).
+export type {
+  Aggregate,
+  Ast,
+  Bound,
+  Condition,
+  CorrelatedSubquery,
+  Correlation,
+  Dir,
+  ExistsOp,
+  LitValue,
+  OrderPart,
+  SimpleOp,
+  ValuePosition,
+} from "./ast.ts";

package/src/key.ts

@@ -0,0 +1,23 @@
+// A stable, canonical JSON string for a query AST — the `viewKey` shared by the React cache
+// (one cached view per AST) and the SSR dehydrate/hydrate map (seed lookup by AST). Both sides
+// MUST agree byte-for-byte, so the one canonical serializer lives here. Object keys are sorted;
+// `undefined` is encoded distinctly (so `{a:undefined}` ≠ `{}`); cycles throw.
+
+export function stableKey(value: unknown, seen = new WeakSet<object>()): string {
+  if (value === undefined) return '{"$undefined":true}';
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (seen.has(value)) throw new TypeError("Rindle query keys must be acyclic JSON values");
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const out = `[${value.map((v) => stableKey(v, seen)).join(",")}]`;
+    seen.delete(value);
+    return out;
+  }
+  const obj = value as Record<string, unknown>;
+  const out = `{${Object.keys(obj)
+    .sort()
+    .map((k) => `${JSON.stringify(k)}:${stableKey(obj[k], seen)}`)
+    .join(",")}}`;
+  seen.delete(value);
+  return out;
+}