WebAssembly API

The @relate/relate-wasm package is relate compiled to WebAssembly (WASM) for the browser: an ES module, relate.js, that loads the engine from relate_bg.wasm and exports one class, RelateDb. A RelateDb is one storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary, in memory or in the Origin Private File System (OPFS), with one connection. Each statementstatement One unit of Cypher that relate parses, plans and runs, such as a MATCH … RETURN read or a CREATE write; a script holds several, separated by ;. Read more in the glossary returns its result as the envelopeenvelope One compact JSON object per result set, printed by --mode envelope, that keeps the column list even when there are no rows. Read more in the glossary, JSON text. This page describes the build this site ships in public/wasm/, the engine behind its cells, the cookbook and the playground; its relate.d.ts is the source of the signatures.

Synopsis

import init, { RelateDb, renderResult } from '@relate/relate-wasm';
import { isWasmTrap } from '@relate/relate-wasm/trap.js';

await init();                                     // loads relate_bg.wasm
const db = new RelateDb();                        // in memory, writable
const ro = new RelateDb(true);                    // in memory, read-only, always empty
const durable = await RelateDb.open('opfs://team'); // OPFS, dedicated worker only

const text = db.execute('RETURN $n AS n', JSON.stringify({ n: 1 }));
const envelope = JSON.parse(text);                // {columns, columnTypes, rows, stats, …, error}
const texts = db.executeScript('CREATE (:A); MATCH (a:A) RETURN count(a) AS n', null);
const recording = JSON.parse(renderResult(texts)); // {kind, text, table, graph, stats}
db.reset();
db.free();

Package files

relate.js and snippets/ resolve their imports relative to relate.js, so the files sit together, unchanged, in one directory. The package's exports map names . (relate.js, types relate.d.ts), ./trap.js (types trap.d.ts), ./opfs.js (types opfs.d.ts) and ./relate_bg.wasm. The site's own copy in public/wasm/ holds the files a page loads, without trap.d.ts, opfs.d.ts, package.json and README.md.

Module exports

Every export except default, initSync and the types needs a finished init() or initSync().

RelateDb

Parameters

Parameters carry JSON values only. Typed values (dates, points, durations) are built in the statement: date($d), point($p).

Transactions

The build has no transaction API. Every statement commits on its own when execute() returns, and BEGIN is a syntax error. Within one statement, all of its writes apply or none do.

OPFS stores

The envelope

execute() returns, and executeScript() returns per statement, one JSON object as text. A successful statement:

A failed statement has only four keys: columns ([]), rows ([]), stats ({}) and error, a string. An engine error starts with its kind (syntax error, semantic error, type error) and, for a typed engine error, its name. The parameter-decoding errors (invalid params JSON: <detail>, params must be a JSON object) and LOAD CSV file unavailable carry no kind.

{"columns":[],"error":"semantic error: ParameterMissing: Expected parameter(s): name","rows":[],"stats":{}}

Value shapes

The JSON text writes a float with its decimal point (1.0); JSON.parse reads it as the number 1.

Recordings

renderResult(envelopes) takes the JSON texts executeScript() returned and returns JSON text, the form this site's cells record:

An empty array renders as (no rows). An entry that is not envelope JSON throws.

Errors

Thrown errors are Error objects; statement errors arrive in the envelope instead.

The errors reference lists the engine's statement errors, which are the same on every surface.

Traps

A crash inside the engine (a Rust panic, stack exhaustion, an out-of-bounds access) traps the WebAssembly instance: the call throws, and the instance cannot be used again. isWasmTrap(err) in trap.js returns true when err is a WebAssembly.RuntimeError or its message matches unreachable, memory access out of bounds, call stack exhausted or maximum call stack size, ignoring case, and false for any other error, after which the instance is still usable. After a trap, a new instance means a new worker or a page reload. An OPFS store reopens with every write it acknowledged.

The OPFS helper

opfs.js is the code RelateDb.open() calls to reach OPFS; relate.js imports its copy in snippets/. It is internal to the engine.

Not in this build

Limits

The limits come from the engine and are the same on every surface: a statement's text is at most 4194304 bytes (syntax error: query text of <n> bytes exceeds the maximum query size of 4194304 bytes), and one value a statement builds is bounded by the expression memory cap. Limits and sizing lists each limit with its default and the setting that changes it.

Capabilities

The capability matrix, narrowed to this surface:

See also

• Use relate from a web page: bundling, workers, OPFS, and traps in an app.
• Run relate in the browser: a page that keeps a graph in OPFS, step by step.
• Errors: every engine error, with its cause and remedy.
• Limitations: what the engine does not do on any surface.
• Embedded graph in an app: the problem the browser build solves.