SurrealDB JavaScript SDK

SQON is a family of data representation formats used by SurrealDB to encode its rich value system. It provides three main capabilities:

1. Value classes: Specialized classes for types that have no direct JavaScript equivalent, such as RecordId, Table, DateTime, and Decimal.
2. Codecs: Serializers and deserializers (CborCodec and JsonCodec) that allow converting between JavaScript value instances and wire formats without losing type information.
3. Utilities: Helper functions for comparing (equals), converting (jsonify), and escaping (escapeIdent, toSurqlString) SurrealQL values.

Note: The full surrealdb SDK re-exports everything from @surrealdb/sqon.

The SDK provides automatic retries for certain operations:

• Idempotent GET requests: Automatically retry on 5xx and connection failures with an exponential backoff (250ms, 500ms, 1000ms) up to a default of 3 retries.
• remember and rememberMany: These write operations are safe to retry because they include an Idempotency-Key derived from the request, valid for a 30-second window.
• Other mutating methods: These are not retried automatically.

The WebAssembly engine supports two primary storage backends:

• mem://: In-memory storage. Data is lost when the browser tab is closed.
• indxdb://<name>: IndexedDB persistence. Data persists across sessions.

// In-memory (data is lost when the tab closes)
await db.connect("mem://");

// IndexedDB persistence
await db.connect("indxdb://myapp");

SQON JSON (MIME: application/vnd.surrealdb.sqon+json) is a JSON-compatible serialization format for SurrealDB values. It is designed for portability and readability in environments where only JSON is available, such as HTTP APIs, browser clients, and logging infrastructure.

It achieves full type fidelity by using $ prefixed keys to describe custom SurrealDB types, similar to the EJSON specification. While less compact than the binary SQON-B format, it is highly portable and LLM-friendly.

A read lens narrows the region from which a query reads. You can use the /* wildcard to select an entire subtree.

Important Security Note: A lens can only narrow the region. The key's existing grants still apply on top of the lens. If a lens attempts to access a region outside of the currently granted region, it will return no rows rather than throwing a 403 error.

// Using a subtree wildcard
client.recall("...", { lens: "team/eng/*" });

// Using an OR of lenses
client.documents.query({
  query: "...", 
  lens: ["team/eng/*", "org/acme"]
});

// Using a lens in keyword search
client.documents.keywords.search({
  query: "...", 
  lens: "team/eng/*"
});

SQON (SurrealQL Object Notation) is a family of data representation formats used by SurrealDB to encode its rich data value system. There are three semantically equivalent representations optimized for different environments:

• SQON (Textual): Uses SurrealQL syntax. Best for direct database interaction, queries, and SurrealQL expressions.
• SQON Binary (CBOR): Uses CBOR with custom tags. Best for efficient wire transport, compact storage, and binary-safe environments.
• SQON JSON (Textual): Standard JSON. Best for HTTP APIs, browser environments, and human-readable interchange.

Any value expressible in one format can be round-tripped through any other without loss of type information.

The @surrealdb/node package is a native engine plugin that embeds SurrealDB directly into your server-side JavaScript runtime (Node.js, Bun, or Deno) using a NAPI addon. This allows you to run a database in-process without a separate server.

To use it, register the engine using createNodeEngines() when constructing your Surreal client, then connect to an embedded endpoint (e.g., mem://).

import { createNodeEngines } from "@surrealdb/node";
import { Surreal } from "surrealdb";

const db = new Surreal({
    engines: createNodeEngines(),
});

await db.connect("mem://");

await db.use({ namespace: "test", database: "test" });

await db.query("CREATE person SET name = 'Tobie'");

Add the @surrealdb/memory SDK to your project using your preferred package manager. This is a lightweight, typed REST client for the Agent Memory API that uses the platform's native fetch and has no runtime dependencies.

# using npm
npm i @surrealdb/memory

# or using pnpm
pnpm i @surrealdb/memory

# or using yarn
yarn add @surrealdb/memory

# or using bun
bun add @surrealdb/memory

To keep your UI responsive, you can offload database operations to a Web Worker using createWasmWorkerEngines. This requires importing a worker agent from @surrealdb/wasm/worker?worker.

import { createWasmWorkerEngines } from "@surrealdb/wasm";
import WorkerAgent from "@surrealdb/wasm/worker?worker";
import { Surreal, createRemoteEngines } from "surrealdb";

const db = new Surreal({
    engines: {
        ...createRemoteEngines(),
        ...createWasmWorkerEngines({
            createWorker: () => new WorkerAgent(),
        }),
    },
});

await db.connect("mem://");