@rindle/wasm 0.1.0-rc.5

package/pkg/rindle_bg.wasm.d.ts

@@ -0,0 +1,36 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __rindle_wasm_start: () => void;
+export const __wbg_db_free: (a: number, b: number) => void;
+export const __wbg_rindleview_free: (a: number, b: number) => void;
+export const __wbg_writetxn_free: (a: number, b: number) => void;
+export const db_destroyQuery: (a: number, b: number) => void;
+export const db_new: () => number;
+export const db_query: (a: number, b: number, c: any) => [number, number, number];
+export const db_registerTable: (a: number, b: number, c: number, d: any) => [number, number];
+export const db_serverBatchBegin: (a: number, b: any) => [number, number];
+export const db_serverBatchEnd: (a: number) => [number, number, number];
+export const db_unregisterTable: (a: number, b: number, c: number) => [number, number];
+export const db_write: (a: number) => number;
+export const rindleview_build: (a: any, b: any, c: any) => [number, number, number];
+export const rindleview_data: (a: number) => any;
+export const rindleview_flush: (a: number) => void;
+export const rindleview_push: (a: number, b: number, c: number, d: any) => [number, number];
+export const rindleview_resultType: (a: number) => any;
+export const rindleview_setResultType: (a: number, b: number, c: number) => void;
+export const rindleview_subscribe: (a: number, b: any) => number;
+export const writetxn_add: (a: number, b: number, c: number, d: any) => [number, number];
+export const writetxn_commit: (a: number) => [number, number, number];
+export const writetxn_edit: (a: number, b: number, c: number, d: any, e: any) => [number, number];
+export const writetxn_get: (a: number, b: number, c: number, d: any) => [number, number, number];
+export const writetxn_remove: (a: number, b: number, c: number, d: any) => [number, number];
+export const writetxn_rollback: (a: number) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_exn_store: (a: number) => void;
+export const __externref_table_alloc: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_start: () => void;

package/src/index.ts

@@ -0,0 +1,205 @@
+// @rindle/wasm — the WASM backend: the in-process IVM engine (src/wasm/db.rs) behind the
+// @rindle/client `Backend` seam (WASM-CLIENT-DESIGN.md §2.1). Also re-exports @rindle/client so a
+// local app can import everything from here.
+//
+// The wasm is a `--target web` ESM artifact (packages/wasm/pkg, built by ./build.sh): it
+// needs an explicit, one-time init — `await initWasm()` — before constructing a backend.
+// In Node the bytes are read from the package; in a browser/bundler the wasm is fetched.
+
+import init, { Db } from "../pkg/rindle.js";
+import { Store, tableSpec } from "@rindle/client";
+import type {
+  Ast,
+  Backend,
+  ChangeEvent,
+  ColsMap,
+  Mutation,
+  QueryId,
+  Schema,
+} from "@rindle/client";
+
+export * from "@rindle/client";
+
+// The wasm Db surface this backend uses (kept local so it doesn't depend on the generated .d.ts).
+interface WasmDb {
+  registerTable(table: string, spec: { columns: string[]; primaryKey: number[] }): void;
+  unregisterTable(table: string): void;
+  query(queryId: number, ast: Ast): { comparatorVersion: number; schema: unknown; snapshot: unknown[] };
+  destroyQuery(queryId: number): void;
+  write(): WasmWriteTxn;
+  serverBatchBegin(deltas: ServerDeltaOp[]): void;
+  serverBatchEnd(): Array<{ queryId: number; events: unknown[] }>;
+}
+
+/** A raw staged write transaction over the wasm engine — the surface an optimistic client
+ *  mutator runs against (`get` reads the live state under this txn's staged overlay, so a
+ *  read-dependent mutator sees its own writes; OPTIMISTIC-WRITES-DESIGN.md §4.1). */
+export interface WasmWriteTxn {
+  add(table: string, row: unknown[]): void;
+  remove(table: string, row: unknown[]): void;
+  edit(table: string, oldRow: unknown[], newRow: unknown[]): void;
+  get(table: string, pk: unknown[]): unknown[] | undefined;
+  commit(): Array<{ queryId: number; events: unknown[] }>;
+  rollback(): void;
+}
+
+/** One base-table row op of a coherent server delta (the §1.3 `D`), bare cells. */
+export type ServerDeltaOp =
+  | { table: string; type: "add"; row: unknown[] }
+  | { table: string; type: "remove"; row: unknown[] }
+  | { table: string; type: "edit"; row: unknown[]; old: unknown[] };
+
+let initialized: Promise<void> | null = null;
+
+/** Initialize the wasm module (idempotent). Call once at startup before `new WasmBackend`
+ *  / `createWasmStore`. Browser/bundler: no args (the wasm is fetched). Node: the bytes are
+ *  read from the package. Pass `moduleOrPath` to override (a `WebAssembly.Module`, URL, or bytes). */
+export function initWasm(moduleOrPath?: unknown): Promise<void> {
+  if (!initialized) {
+    initialized = (async () => {
+      if (moduleOrPath !== undefined) {
+        await init({ module_or_path: moduleOrPath });
+      } else if ((globalThis as { process?: { versions?: { node?: string } } }).process?.versions?.node) {
+        const { readFile } = await import("node:fs/promises");
+        const bytes = await readFile(new URL("../pkg/rindle_bg.wasm", import.meta.url));
+        await init({ module_or_path: bytes });
+      } else {
+        await init();
+      }
+    })();
+  }
+  return initialized;
+}
+
+/** The in-process WASM backend. Requires {@link initWasm} to have resolved first. */
+/** One engine commit's per-query batches (the shape `WriteTxn.commit` / `serverBatchEnd` return). */
+type BatchSet = Array<{ queryId: number; events: unknown[] }>;
+
+export class WasmBackend<S extends ColsMap> implements Backend {
+  private readonly db: WasmDb;
+  private handler: (qid: QueryId, ev: ChangeEvent) => void = () => {};
+
+  // Non-reentrant delivery (#15): commits dispatch through a FIFO queue. A subscriber that
+  // synchronously triggers another write enqueues that commit's batches; they drain only after
+  // the in-flight commit's batches finish, preserving per-query commit order regardless of what
+  // subscribers do.
+  private readonly dispatchQueue: BatchSet[] = [];
+  private draining = false;
+
+  constructor(schema: Schema<S>) {
+    this.db = new Db() as unknown as WasmDb;
+    for (const name of Object.keys(schema.tables)) {
+      this.db.registerTable(name, tableSpec(schema.tables[name]));
+    }
+  }
+
+  /** Register an additional base table after construction — for a SYNTHETIC aggregate table
+   *  (`AGGREGATE-SYNC-DESIGN.md` §3.3) that is not in the typed schema. The
+   *  `NormalizedBackend` registers each such `__agg_*` table once, before a query that reads
+   *  it, so the local engine can join to it (the relationship `count` it backs is shipped by
+   *  the server, never recomputed). */
+  registerTable(name: string, spec: { columns: string[]; primaryKey: number[] }): void {
+    this.db.registerTable(name, spec);
+  }
+
+  /** Remove a synthetic aggregate table registered by {@link registerTable}, once the last
+   *  query reading it has been unregistered (`AGGREGATE-SYNC-DESIGN.md` §4): frees the engine
+   *  source + its optimistic baseline so aggregate state is reclaimed, not permanent. Throws
+   *  if a query still reads it (the backend refcounts readers, so it calls this only at 0). */
+  unregisterTable(name: string): void {
+    this.db.unregisterTable(name);
+  }
+
+  registerQuery(qid: QueryId, ast: Ast): void {
+    const r = this.db.query(qid, ast);
+    this.handler(qid, { type: "hello", schema: r.schema as never, comparatorVersion: r.comparatorVersion });
+    this.handler(qid, { type: "snapshot", adds: r.snapshot as never, last: true });
+  }
+
+  unregisterQuery(qid: QueryId): void {
+    this.db.destroyQuery(qid);
+  }
+
+  mutate(mutations: Mutation[]): Promise<void> {
+    const tx = this.db.write();
+    for (const m of mutations) {
+      if (m.op === "add") tx.add(m.table, m.row);
+      else if (m.op === "remove") tx.remove(m.table, m.row);
+      else tx.edit(m.table, m.old, m.new);
+    }
+    this.dispatch(tx.commit() as BatchSet);
+    return Promise.resolve();
+  }
+
+  onEvent(handler: (qid: QueryId, ev: ChangeEvent) => void): void {
+    this.handler = handler;
+  }
+
+  /** Deliver one commit's per-query batches. Non-reentrant (#15): if a delivery is already in
+   *  progress (a subscriber re-entered via write()), enqueue and let the active drain pick it
+   *  up FIFO, so each query folds commits in order. Per-query isolated (#11): a view's fold or
+   *  subscriber throwing does NOT drop sibling queries' batches — the first error is re-raised
+   *  only after every query has been delivered. */
+  private dispatch(batches: BatchSet): void {
+    this.dispatchQueue.push(batches);
+    if (this.draining) return; // an outer drain is running; it will deliver this set
+    this.draining = true;
+    let firstError: unknown;
+    let hasError = false;
+    try {
+      while (this.dispatchQueue.length) {
+        const next = this.dispatchQueue.shift()!;
+        for (const b of next) {
+          try {
+            this.handler(b.queryId, { type: "batch", events: b.events as never });
+          } catch (err) {
+            if (!hasError) {
+              hasError = true;
+              firstError = err;
+            }
+          }
+        }
+      }
+    } finally {
+      this.draining = false;
+    }
+    if (hasError) throw firstError;
+  }
+
+  // --- the optimistic-cycle surface (OPTIMISTIC-WRITES-DESIGN.md §1/§3/§9) ----------
+  //
+  // `@rindle/optimistic` drives the engine's fork/rebase loop through these three; the
+  // plain local path never calls them.
+
+  /** Run `f` against a raw staged write txn (with the §4.1 `get` read path), commit, and
+   *  dispatch the resulting batches on the ordinary event stream. Inside an open server
+   *  batch the engine buffers the events into the cycle instead (commit returns `[]`),
+   *  so re-invocations dispatch nothing here — delivery is `serverBatchEnd`'s. */
+  writeWith(f: (tx: WasmWriteTxn) => void): void {
+    const tx = this.db.write();
+    f(tx);
+    this.dispatch(tx.commit() as BatchSet);
+  }
+
+  /** Open a §1.3 reconcile cycle against the coherent server delta: the engine rewinds
+   *  (optimistic layer un-applied, delta folded in, `sync` re-forked) and starts
+   *  buffering. Re-invoke the still-pending mutators via {@link writeWith}, then call
+   *  {@link serverBatchEnd}. On error the optimistic state is poisoned — discard the
+   *  backend and re-hydrate. */
+  serverBatchBegin(deltas: ServerDeltaOp[]): void {
+    this.db.serverBatchBegin(deltas);
+  }
+
+  /** Close the cycle: the whole buffered stream (rewind + re-invocations) coalesces to
+   *  the minimal net per query (§3 — a confirmed-correct prediction delivers nothing)
+   *  and dispatches as ONE batch per affected query on the ordinary event stream. */
+  serverBatchEnd(): void {
+    this.dispatch(this.db.serverBatchEnd() as BatchSet);
+  }
+}
+
+/** Convenience: init the wasm + return a ready local {@link Store}. */
+export async function createWasmStore<S extends ColsMap>(schema: Schema<S>): Promise<Store<S>> {
+  await initWasm();
+  return new Store(schema, new WasmBackend(schema));
+}