Documentation

View the JavaScript SDK documentation here, including the value types, utilities, and codecs concept pages.

What is SQON?

SQON (SurrealQL Object Notation) is the family of data representation formats used by SurrealDB to encode its rich value system. This package provides:

• Value classes - RecordId, Table, DateTime, Decimal, and other SurrealQL types that have no direct JavaScript equivalent
• Codecs - CborCodec and JsonCodec for serialising and deserialising values without losing type information
• Utilities - helpers such as equals, jsonify, escapeIdent, and toSurqlString

The full surrealdb SDK re-exports everything from @surrealdb/sqon for convenience. Install this package directly when you only need value types and codecs - for example when building a custom client, middleware, or data pipeline - without pulling in the database driver.

How to install

Run the following command to add SQON to your project:

# using npm
npm i @surrealdb/sqon

# or using pnpm
pnpm i @surrealdb/sqon

# or using yarn
yarn add @surrealdb/sqon

# or using bun
bun add @surrealdb/sqon

You can now import value types and utilities with:

import { RecordId, Table, DateTime, Decimal, equals, jsonify } from "@surrealdb/sqon";

Or import everything from the SDK instead:

import { RecordId, Table, Surreal } from "surrealdb";

Getting started

Value types

Use value classes to construct and validate SurrealQL values in application code.

import { RecordId, Table, DateTime, Duration, Decimal, Uuid } from "@surrealdb/sqon";

const userId = new RecordId("users", "john");
const users = new Table("users");

const now = DateTime.now();
const duration = Duration.parse("1h30m");
const price = new Decimal("19.99");
const id = Uuid.v7();

const parsed = RecordId.parse("users:john");

Most value classes support parsing from SurrealQL string syntax and expose instance methods such as .equals() and .toString().

Codecs

Codecs convert between JavaScript value instances and wire formats. Two codecs are available today:

| Codec | Wire format | Typical use | | --- | --- | --- | | CborCodec | Uint8Array (CBOR) | WebSocket and HTTP RPC transport to SurrealDB | | JsonCodec | Plain object tree (SQON JSON) | JSON-safe interchange, logging, and HTTP APIs, LLM communication |

import {
    CborCodec,
    JsonCodec,
    RecordId,
    Decimal,
} from "@surrealdb/sqon";

const cbor = CborCodec.DEFAULT;
const json = JsonCodec.DEFAULT;

const value = {
    id: new RecordId("person", "tobie"),
    balance: new Decimal("1234.5678"),
};

const wire = cbor.encode(value);
const restored = cbor.decode(wire);

const sqonJson = json.encode(value);
// { id: { $recordId: { tb: "person", id: "tobie" } }, balance: { $decimal: "1234.5678" } }
const fromJson = json.decode(sqonJson);

Configure codecs with CodecOptions - for example, decode datetimes as native Date objects instead of DateTime:

const codec = new CborCodec({ useNativeDates: true });

The CBOR tag specification is documented in the CBOR protocol reference.

Utilities

SQON provides utilities for comparing, converting, and escaping values:

import {
    equals,
    jsonify,
    escapeIdent,
    escapeValue,
    toSurqlString,
    RecordId,
} from "@surrealdb/sqon";

const a = new RecordId("users", "john");
const b = new RecordId("users", "john");

equals(a, b); // true

jsonify({ id: a }); // { id: "users:john" }

escapeIdent("user-table"); // `user-table`
toSurqlString(a); // r"users:john"

Query-building utilities such as surql, expr, and BoundQuery live in the surrealdb SDK, not in this package.

Using with the SurrealDB SDK

When you create a Surreal client, the SDK registers default codecs and uses CborCodec for WebSocket and HTTP RPC communication. You can customise codec behaviour through DriverOptions:

import { Surreal } from "surrealdb";

const db = new Surreal({
    codecOptions: {
        useNativeDates: true,
    },
});

See the codecs concept page for details on when to use each format and how the SDK wires codecs in.

Package contents

| Export | Description | | --- | --- | | Value classes | RecordId, Table, DateTime, Duration, Decimal, Uuid, Range, FileRef, Geometry*, and more | | Codecs | CborCodec, JsonCodec, CodecOptions, ValueCodec | | Utilities | equals, jsonify, escapeIdent, escapeKey, escapeRid, escapeValue, toSurqlString | | Errors | SqonError, InvalidDateError, InvalidRecordIdError, and related validation errors |

Note: FlatBufferCodec is exported for future API compatibility but is not implemented in this version.

Contributing

This package is part of the surrealdb.js monorepo. See the main README for local setup, build commands, and contribution guidelines.