Browser/WASM client: @relate/relate-wasm
Install
npm install @relate/relate-wasmThe npm packages are pending their first publish (the docs/PUBLISHING.md
runbook); until then build the bundle from a repo checkout with
make build-wasm (writes surfaces/relate-wasm/pkg/). The package is a
wasm-bindgen --target web ESM bundle.
Minimal usage
import init, { RelateDb } from "@relate/relate-wasm";
await init();
const db = new RelateDb(); // in-memory database
const result = JSON.parse(db.execute("RETURN 1 AS n", null));
// result.columns: string[] // ["n"]
// result.columnTypes: string[] // ["INTEGER"]
// result.rows: Array<Record<string, unknown>> // [{ n: 1 }]
// result.stats: { nodes_created, ... }
// result.notifications: Array<Record<string, unknown>> // [] on a plain run
// result.error: string | null // null on successexecute(query, paramsJson) runs one statement; paramsJson is a JSON
object string, or null/blank for none. A statement that references a
parameter missing from it fails with ParameterMissing: Expected parameter(s): <names> (no null binding). executeScript(script, paramsJson)
runs several and returns one envelope per statement.
Gotchas
await init()before any use — it fetchesrelate_bg.wasmrelative to the module. Bundlers that move assets need the URL handed in explicitly. With Vite:import wasmUrl from "@relate/relate-wasm/relate_bg.wasm?url"thenawait init(wasmUrl). In Node,fetchhas nofile:scheme — read the.wasmfrom disk and pass the bytes toinit().- TypeScript lib set — the generated
relate.d.tsdeclaresSymbol.dispose(wasm-bindgen's Disposable support) and the browser globalsinit()accepts, so checking it withoutskipLibCheckneeds"lib": ["esnext", "dom"]; withskipLibCheckon, the types resolve under any modern lib set. - Wire-JSON envelope —
executereturns a string; alwaysJSON.parseit. Rows are column-keyed objects ([{ n: 1 }]), not positional arrays. Engine errors (parse, planning, execution) flow througherrorin the envelope — they do not throw; checkresult.error. notificationsis always there — the envelope carries an ADR-0363notificationsarray (code,gql_status,severity,category,title,description,remedy, plusoperator_idon operator-scoped kinds). It is empty on a plain run and holds the plan-time list onEXPLAIN/PROFILE, e.g.Neo.ClientNotification.Statement.CartesianProductfor a disjoint multi-patternMATCH.renderResultignores the key.- OPFS is worker-only —
await RelateDb.open("opfs://<name>")is the durable browser store (<name>: one segment, 1–64 chars of[A-Za-z0-9_-]) and only runs in a dedicated worker (FileSystemSyncAccessHandle); on the page thread it throws.new RelateDb()(:memory:) may run on the page thread. isWasmTrapfor poisoned instances — a Rust panic traps the module (JS sees aWebAssembly.RuntimeError) and the instance is dead: replace it (new worker or page reload). Classify withisWasmTrapfrom@relate/relate-wasm/trap.js; false means the instance is still usable.- No byte arrays — the engine's byte array (ADR-0327) is Bolt-only and
statement-scoped; were one in a result it would arrive as a list of
integers 0–255 with column type
BINARY, and it can never be stored as a property. - JSON snapshots, single-threaded — no Parquet codec and no background
checkpointing on wasm32;
:memory:and OPFS both use the JSON codec.
Full contract: docs/api/wasm/spec.md (API, build pipeline, wire envelope).