Surqlize for TypeScript

Surqlize is a type-safe ORM for SurrealDB in TypeScript. You describe your tables and edges in code, then build queries with a fluent API instead of writing SurrealQL strings. It uses the JavaScript SDK to connect to the database and to send queries.

TypeScript infers the type of every query result from the schema, so there is no code generation step. Each query compiles to SurrealQL, and its values are sent as bound parameters.

Define a schema and query it

import { Surreal } from "surrealdb";
import { orm, table, t } from "surqlize";

const user = table("user", {
    name: t.string(),
    email: t.string(),
    age: t.number(),
    created: t.date(),
});

const surreal = new Surreal();
await surreal.connect("ws://localhost:8000", {
    namespace: "app",
    database: "app",
    authentication: { username: "root", password: "secret" },
});

const db = orm(surreal, user);

await db.create("user").content({
    name: "Ada",
    email: "ada@example.com",
    age: 36,
    created: new Date(),
});

const adults = await db
    .select("user")
    .where((user) => user.age.gte(18))
    .return((user) => ({ name: user.name, email: user.email }));
// adults: { name: string; email: string }[]

Key ideas

Schemas live in code. table() and edge() describe your records with the t.* type builders. Surqlize sends no DEFINE TABLE or DEFINE FIELD statements, apart from computed fields when you ask for them with db.defineComputed(). SurrealDB creates a table when the first record is written to it, and reading from a table that does not exist raises an error.
Queries are immutable builders. Every chained method returns a new query, so a partly built query can be reused. Awaiting a query runs it.
Results are typed and parsed. Surqlize parses each result against the schema as it arrives, and a mismatch throws a TypeParseError instead of passing bad data on.
Graph traversal is part of the query builder. Edges are typed, and a traversal step only accepts edges that connect to the current table.
Runtime validation is opt-in. Data you write can be checked against the schema before it is sent. See runtime validation.

Getting started

Installation

Install Surqlize and its peer dependencies.

Schema

Define tables, field types, defaults, computed fields, and class-linked tables.

Connections

Create an ORM instance, use sessions, and share one connection.

Building queries

Querying

Select records with filters, ordering, projections, fetching, and pagination.

Mutations

Create, insert, update, upsert, and delete records, and choose how data is written.

Edges and graph

Define edges, create relations with RELATE, and traverse the graph.

Recursive traversal

Follow a relationship to a fixed or variable depth, collect nodes, and find shortest paths.

Functions

Call SurrealDB functions on fields and use standalone function families.

Search, vector, and geometry

Full-text matching, vector similarity, geometry points, and durations.

Custom functions and APIs

Call user-defined functions and API endpoints with typed arguments and results.

Running queries

Live queries

Subscribe to typed changes on a table or record.

Transactions and batches

Run several queries atomically, with or without intermediate results.

Runtime validation

Check written data against the schema before it is sent.

Cancellation, timeouts, and retries

Control how long and how hard the client waits for an answer.

Performance

What a query costs to build, and how to reuse queries and connections.

Types and errors

Type inference

Extract TypeScript types from tables, queries, and write inputs.

Error handling

The errors Surqlize throws and how to tell them apart.