README.md

<br>

<p align="center">
    <img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/surreal.svg" />
    &nbsp;
    <img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/javascript.svg" />
</p>

<h3 align="center">A type-safe TypeScript ORM for SurrealDB.</h3>

<br>

<p align="center">
    <a href="https://github.com/surrealdb/surqlize"><img src="https://img.shields.io/badge/status-dev-ff00bb.svg?style=flat-square"></a>
    &nbsp;
    <a href="https://surrealdb.com/docs/sdk/javascript"><img src="https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square"></a>
    &nbsp;
    <a href="https://www.npmjs.com/package/surqlize"><img src="https://img.shields.io/npm/v/surqlize?style=flat-square"></a>
    <!--&nbsp;
    <a href="https://www.npmjs.com/package/surqlize"><img src="https://img.shields.io/npm/dm/surqlize?style=flat-square"></a>
    &nbsp;
    <a href="https://deno.land/x/surqlize"><img src="https://img.shields.io/npm/v/surqlize?style=flat-square&label=deno"></a>-->
</p>

<p align="center">
    <a href="https://surrealdb.com/discord"><img src="https://img.shields.io/discord/902568124350599239?label=discord&style=flat-square&color=5a66f6"></a>
    &nbsp;
    <a href="https://twitter.com/surrealdb"><img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=flat-square"></a>
    &nbsp;
    <a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square"></a>
    &nbsp;
    <a href="https://www.youtube.com/@SurrealDB"><img src="https://img.shields.io/badge/youtube-subscribe-fc1c1c.svg?style=flat-square"></a>
</p>

# Surqlize

A type-safe TypeScript ORM for SurrealDB that provides full type inference, a fluent query builder, comprehensive CRUD operations, and first-class support for graph relationships, and database functions.

## Features

- **Type-safe schema definitions** - Define your database schema using intuitive `t.*` builders
- **Automatic type inference** - Get full TypeScript types without code generation
- **Fluent query builder** - Chain `.select()`, `.where()`, `.return()` with full type safety
- **Complete CRUD operations** - SELECT, CREATE, UPDATE, DELETE, and UPSERT queries
- **Live queries** - Real-time `LIVE SELECT` subscriptions with typed notifications that survive reconnects
- **Cancellation, timeouts and retries** - Abort queries with an `AbortSignal`, bound them with a request timeout, and retry them on transaction conflicts
- **Graph relationships** - First-class support for edges and graph traversal
- **Runtime validation** - Opt in to checking written data against the schema before it is sent, with every failing field reported
- **Rich type system** - Objects, arrays, unions, literals, options, and more
- **SurrealDB functions** - Integrated string, array, and record operations
- **Schema DDL** - Generate `DEFINE` statements from the same schema that types your queries
- **Migrations** - Diff a schema against a live database and converge it, with `surqlize plan` / `migrate` / `rollback`

## Installation

```bash
bun add surqlize
# or
npm install surqlize
```

### Requirements

- **SurrealDB server ≥ 3.0** — surqlize targets the SurrealDB 3.x server. Some
  features degrade or are unavailable on older servers; for example, filtering
  or projecting a live query relies on query parameters that require **server ≥
  3.0** (`FETCH` requires ≥ 2.2.0).
- **`surrealdb` JavaScript SDK ≥ 2.1.0 (2.x)** — declared as a peer
  dependency, so install it alongside surqlize. (The SDK and the server are
  versioned independently: the 2.x SDK is what connects to a 3.x server.)
- **TypeScript 5 or 6** for full type inference.

### One copy of `surrealdb`

The connection you pass to surqlize and surqlize itself must resolve the **same
copy** of the `surrealdb` package. The SDK encodes values with `instanceof`, so
with two copies it fails to recognise the `Table` that surqlize binds as a
query subject and sends an empty object, and the server answers with
`Cannot execute CREATE statement using value: {  }`. surqlize detects this and
throws a `DuplicateSurrealError` instead, which points back here.

To fix it, check `npm ls surrealdb` (or `bun pm ls --all`), dedupe so a single
version is installed (an `overrides` / `resolutions` entry helps), and avoid
`file:` dependencies, which copy the package along with its own
`node_modules`. In a symlinked setup where TypeScript reports `Property
'#private' in type 'Surreal' refers to a different member`, set
`preserveSymlinks: true`.

## Quick start

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

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

// Create ORM instance
const db = orm(new Surreal(), user);

// Build type-safe queries
const query = db
  .select("user")
  .where((user) => user.age.gte(18))
  .return((user) => ({
    name: user.name,
    email: user.email,
  }));

// TypeScript knows the exact return type!
type Result = t.infer<typeof query>;
// Result: Array<{ name: string; email: string }>
```

## Schema definition

### Tables

Define tables using the `table()` function with a rich type system:

```typescript
import { table, t } from "surqlize";

const user = table("user", {
  // Basic types
  name: t.string(),
  age: t.number(),
  isActive: t.bool(),
  created: t.date(),
  duration: t.duration(),
  userId: t.uuid(),

  // Complex objects
  address: t.object({
    street: t.string(),
    city: t.string(),
    zipCode: t.string(),
  }),

  // Arrays
  tags: t.array(t.string()),
  scores: t.array(t.number()),

  // Mixed-type arrays (tuples)
  mixedData: t.array([t.string(), t.number(), t.bool()]),

  // Sets: a JavaScript `Set` (not an array), stored as `set<string>`
  labels: t.set(t.string()), // new Set(["a", "b"])

  // Optional fields
  bio: t.option(t.string()),
  
  // Record references (foreign keys)
  authorId: t.record("author"),

  // Union types
  status: t.union([
    t.literal("active"),
    t.literal("inactive"),
    t.literal("pending"),
  ]),

  // Literals
  role: t.literal("admin"),
});
```

**Note**: Every table automatically includes an `id` field of type `RecordId<TableName>`.

### Default values

Call `.default()` on any field type to give it a default. The field becomes optional when creating a record, while the type you read back stays non-optional:

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

const user = table("user", {
  name: t.string(),
  isVerified: t.bool().default(false),             // static value
  createdAt: t.date().default(() => new Date()),   // function, called each time a query is built
  seenAt: t.date().default(expr("time::now()")),   // SurrealQL expression, evaluated by SurrealDB
});

const db = orm(new Surreal(), user);

await db.create("user").content({ name: "Ada" }); // isVerified, createdAt and seenAt are optional
// Result type: { id, name: string, isVerified: boolean, createdAt: Date, seenAt: Date }
```

Defaults are applied by `CREATE` (`.content()`, `.merge()`, `.set()`, or no data) and `INSERT` (object and `.fields().values()` forms) when the field is omitted, and an explicit value always wins. `.content()`, `.merge()` and `INSERT` also apply the default when the key is present but `undefined`. `.set()` does not: a key passed as `undefined` counts as supplied, so the field is stored as absent. They are filled in by the query itself, so no `DEFINE FIELD ... DEFAULT` is needed. `RELATE` applies an edge's defaults in the same way. `UPSERT`, `UPDATE`, `.replace()` and `.patch()` do not apply defaults. `.default()` returns a copy, so a shared field type is never mutated.

`expr()` text is inserted into the query verbatim: only pass trusted, hard-coded SurrealQL, never user input.

### Computed fields

A computed field is read-only: SurrealDB derives its value from an expression each time the record is read (`DEFINE FIELD … COMPUTED`, which needs **SurrealDB ≥ 3.0**). Add one with `.computed(name, type, expression)`. The expression receives the row (rendered as `$this`) and the ORM, so it can run subqueries:

```typescript
import { type Orm, table, t } from "surqlize";

const post = table("post", { title: t.string(), author: t.record("user") });

const user = table("user", { first: t.string(), last: t.string() })
  .computed("fullName", t.string(), (row) => row.first.concat(" ", row.last))
  .computed("postCount", t.number(), (row, db: Orm<[typeof post]>) =>
    db
      .select("post")
      .where((p) => p.author.eq(row.id))
      .return((p) => p.id)
      .wrap()
      .len(),
  );
```

Computed fields are part of the row type of selects, and can be used in `where`, `orderBy` and `return` like any other field. They are left out of the input types of `create`, `update`, `upsert`, `insert` and `relate`, so writing one is a compile-time error:

```typescript illustrative
const [u] = await db.select("user").where((u) => u.postCount.gt(0)); // u.fullName: string
await db.create("user").set({ first: "Ada", last: "Lovelace" });
await db.create("user").set({ fullName: "x" }); // type error
```

The field must exist in the database before it can be read. Create it with `db.defineComputed()` (all tables, or pass table names), or put the statements from `user.computedStatements(db)` into a migration:

```typescript illustrative
await db.defineComputed();
// DEFINE FIELD OVERWRITE fullName ON TABLE user COMPUTED (string::concat($this.first, " ", $this.last))
```

Notes:

- The `db` passed to the expression is untyped, because the tables are registered after they are defined. Annotate the parameter (`db: Orm<[typeof post]>`) to type the tables it queries.
- Tables read by an expression must exist when a record is read, and the expression is inlined into the `DEFINE` statement, so it cannot use query parameters.

### Linking a class to a table

Pass a class as the third argument of `table()` to give rows methods and
computed properties. Rows selected from (or returned by a write to) the table
are instances of the class, and instances of the class are accepted as record
content:

```typescript
import { orm, t, table } from "surqlize";
import { Surreal } from "surrealdb";
class User {
  given_name!: string;
  family_name!: string;

  get fullName() {
    return `${this.given_name} ${this.family_name}`;
  }
}

const user = table(
  "user",
  { given_name: t.string(), family_name: t.string() },
  User,
);

const db = orm(new Surreal(), user);

const ada = await db.select("user", "ada").only();
ada instanceof User; // true
ada.fullName; // "Ada Lovelace" (typed as string)

const input = Object.assign(new User(), { given_name: "Grace", family_name: "Hopper" });
await db.create("user").content(input);
```

Type inference is unchanged and needs no code generation: the row type is the
fields declared in the table plus the instance type of the class. Notes:

- Rows are hydrated without running the class constructor, so declare fields
  with `!` rather than initializers. Instances passed as content are sent as
  their own enumerable properties; getters and methods are not stored.
- Hydration also applies to rows resolved by `.fetch()`, each with its own class.
  Queries with a `.return()` projection return plain objects.
- Helpers that issue queries themselves (such as `this.update()` or static
  `findByEmail()` methods) are not provided: write them against your `db`
  instance, e.g. `db.select("user").where(...)`.

### Edges and graph relations

Define graph edges to model relationships between tables:

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

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

const post = table("post", {
  title: t.string(),
  content: t.string(),
});

// Define an edge from user to post
const authored = edge("user", "authored", "post", {
  created: t.date(),
  role: t.union([t.literal("author"), t.literal("co-author")]),
});

const db = orm(new Surreal(), user, post, authored);
```

**Automatic fields**: Edges automatically include:
- `id`: RecordId of the edge
- `in`: RecordId of the source table (user)
- `out`: RecordId of the target table (post)

## Registering schemas

Pass your tables and edges to `orm()` to get a type-safe client. Schemas can be
supplied either as individual arguments or grouped in a single object — both
produce an identical, fully typed ORM:

```typescript illustrative
// As individual arguments
const db = orm(new Surreal(), user, post, authored);

// Or grouped in an object
const db = orm(new Surreal(), { user, post, authored });
```

The object form pairs nicely with a dedicated schema module, letting you define
your tables once and reuse them across multiple ORM instances:

```typescript illustrative
// database/schema.ts
import { edge, t, table } from "surqlize";

export const user = table("user", {
  name: t.string(),
  email: t.string(),
});

export const post = table("post", {
  title: t.string(),
  content: t.string(),
});

export const authored = edge("user", "authored", "post", {
  created: t.date(),
});
```

```typescript illustrative
// src/db.ts
import { Surreal } from "surrealdb";
import { orm } from "surqlize";
import * as schema from "../database/schema";

const db = orm(new Surreal(), schema);
```

> Tables are always addressed by their `tb` name in queries (e.g. `db.select("user")`),
> regardless of how they are registered. The object keys are purely organizational.

## CRUD Operations

### SELECT statements

```typescript illustrative
// Select all records
const allUsers = db.select("user");

// Select with WHERE clause
const adults = db
  .select("user")
  .where((user) => user.age.gte(18));

// Project specific fields with RETURN
const userNames = db
  .select("user")
  .return((user) => ({
    fullName: user.name,
    email: user.email,
  }));

// Pagination
const paginatedUsers = db
  .select("user")
  .start(10)
  .limit(20);

// Select a single record by ID (returns array with 0 or 1 item)
const specificUser = await db.select(new RecordId("user", "john"));
// To get the first item, use .val() or .at(0):
const specificUser = await db.select(new RecordId("user", "john")).then.val();
// Or get a specific item:
const specificUser = await db.select(new RecordId("user", "john")).then.at(0);

// Use .only() to emit SurrealQL ONLY and return a single object instead of an array
const user = await db.select("user", "john").only();
// user: User  (not User[])

// Nested queries (JOIN-like)
const postsWithAuthors = db.select("post").return((post) => ({
  title: post.title,
  author: post.authorId.select().only().return((author) => ({
    name: author.name,
    email: author.email,
  })),
}));

// Without .only(), post.authorId.select() returns an array per post.
// With .only(), each post returns a single author object.
```

#### Using `.only()` for single-record queries

By default surqlize queries always return arrays. The `.only()` modifier emits the SurrealQL `ONLY` clause and changes both the generated query and the TypeScript return type to a single object:

```typescript
// Without .only() — returns User[] (array with 0 or 1 item)
const users = await db.select("user", "john");

// With .only() — emits "SELECT * FROM ONLY user:john" and returns User
const user = await db.select("user", "john").only();
```

This is different from `.then.val()` which extracts the first element client-side from an array result. `.only()` changes the query sent to SurrealDB.

#### Nested record selects with `.only()`

When selecting through a record link, omitting `.only()` returns an array per parent record. Use `.only()` when each parent has exactly one related record:

```typescript illustrative
// Without .only(): post.author.select() returns User[] per post → nested arrays
const posts = await db.select("post").return((post) => ({
  title: post.title,
  author: post.author.select().return((author) => ({
    id: author.id,
    username: author.username,
  })),
}));

// With .only(): each post returns a single author object
const posts = await db.select("post").return((post) => ({
  title: post.title,
  author: post.author.select().only().return((author) => ({
    id: author.id,
    username: author.username,
  })),
}));
// Result: Array<{ title: string; author: { id: RecordId<"user">; username: string } }>
```

#### Sorting with ORDER BY

```typescript illustrative
// Order by single field
const sorted = db.select("user")
  .orderBy("age", "DESC");

// Order by multiple fields
const multiSort = db.select("user")
  .orderBy("lastName", "ASC")
  .orderBy("firstName", "ASC");

// Order by with callback (for nested fields)
const nestedSort = db.select("user")
  .orderBy(user => user.name.last, "ASC");

// Order by an expression: any function or operator built from the typed builders
const longestEmail = db.select("user")
  .orderBy(user => user.email.len(), "DESC");

// Numeric sorting
const numericSort = db.select("user")
  .orderByNumeric("age", "DESC");

// Collation sorting
const collateSort = db.select("user")
  .orderByCollate("name", "ASC");

// Object form: field -> "asc" | "desc" (see "Object-based filters and sorting")
const objectSort = db.select("user")
  .orderBy({ age: "desc", name: { last: "asc" } });
```

SurrealQL only sorts by a field path, so a callback that returns anything else (a function call, an operator, a standalone function) is sorted through an alias. The query selects `*` plus the expression as `__order_N` and drops it again with `OMIT`, so the rows come back with exactly the fields you expect. Field-path callbacks and field names render as plain `ORDER BY` terms, as before.

An expression sort cannot be combined with `.return()`: a returned object would have to carry the sort key, so that combination throws an `OrmError` when the query is built. Compute the value in `.return()` and sort the results in your code, or sort by a field.

#### Grouping with GROUP BY

```typescript
import { count, math } from "surqlize";

// Group by a field: the return() projection selects the key and the aggregates
const perAuthor = db.select("post")
  .groupBy("author")
  .return((post) => ({ writer: post.author, posts: count(post) }));

// Group all rows into one: the return() projection holds table-wide aggregates
const totals = db.select("user")
  .groupAll()
  .return((user) => ({ total: count(user), avgAge: math.mean(user.age) }));
```

A grouped query needs a `.return()` projection, because SurrealDB cannot group `SELECT *`. The projection must select each `groupBy()` field (here `post.author`, aliased as `writer`), and its other fields are aggregates such as `count()` and `math.mean()`. A single aggregate can also be returned on its own, as in `groupAll().return((user) => count(user))`. `groupBy()` and `groupAll()` throw an `OrmError` when the projection is missing or does not select a grouped field. `groupBy()` and `groupAll()` cannot be combined with `split()`, because SurrealDB does not allow SPLIT and GROUP in one query. Aggregate functions are listed under [Standalone functions](#standalone-functions).

Select only the grouped fields and aggregates in a grouped projection. SurrealDB returns any other field as an array of its values per group (`title: ["A", "B"]`), which does not match the field's declared type, so it fails to parse.

#### Loading relations with FETCH

```typescript illustrative
// Fetch linked records
const withAuthor = db.select("post")
  .fetch("author");

// Fetch multiple relations
const deepFetch = db.select("post")
  .fetch("author", "comments");

// Project a subset of a fetched relation with RETURN. The result is typed and
// validated against the projected shape, so you can pick fields from the linked
// records (in / out) and omit the edge's own fields without errors.
const authorships = db.select("authored")
  .fetch("in", "out")
  .return((edge) => ({
    user: edge.in.name,   // from the fetched `user` record
    post: edge.out.title, // from the fetched `post` record
    role: edge.role,
  }));
```

`fetch` also follows nested record paths. Like SurrealDB, fetching a nested
path expands every record link along the way, and the result type is resolved
accordingly — `out` becomes the linked record's object, and `out.author`
expands the `author` link inside it:

```typescript
// purchased is an edge: user ->purchased-> product, and product.author -> author
const purchases = await db.select("purchased")
  .fetch("out", "out.author")
  .execute();

purchases[0]!.out.title;        // string  (product fetched)
purchases[0]!.out.author.name;  // string  (nested author fetched)
purchases[0]!.in;               // RecordId<"user">  (left as a link)
```

Record links wrapped in `option<…>` or `array<…>` are resolved too, so
`fetch("tags")` on an `array<record<tag>>` field yields an array of full `tag`
objects.

#### Splitting arrays with SPLIT

```typescript
// Split array field into multiple records
const splitTags = db.select("post")
  .split("tags");

// Split multiple arrays
const multiSplit = db.select("post")
  .split("tags", "categories");

// One row per tag. The projection must select the split field, here as `tag`.
const perTag = db.select("post")
  .split("tags")
  .return((post) => ({ tag: post.tags, title: post.title }));
```

After `split()`, each split field holds a single element, so it is typed as the element type (`string` for `array<string>`), not the array. A `.where()` after `split()` still filters on the whole array, since SurrealDB applies WHERE before SPLIT. `split()` cannot be combined with `groupBy()` or `groupAll()`, and it must be called before `.return()`, because a projection is typed from the rows before the split (calling it after throws an `OrmError`).

#### Setting query timeout

```typescript
// Set timeout duration
const withTimeout = db.select("user")
  .where(user => user.age.gt(18))
  .timeout("5s");
```

#### Combining clauses

```typescript
// Complex query with multiple clauses
const complexQuery = db.select("post")
  .where(post => post.title.startsWith("Hello"))
  .split("tags")
  .orderBy("created", "DESC")
  .limit(20)
  .fetch("author")
  .timeout("10s");
```

### CREATE statements

Create a new record with a specific id or a generated id.

```typescript illustrative
// Create with SET
const newUser = await db.create("user").set({
  name: "Alice",
  email: "alice@example.com",
  age: 30,
  created: new Date(),
});

// Create with CONTENT
const newPost = await db.create("post").content({
  title: "Hello World",
  body: "First post!",
  authorId: new RecordId("user", "alice"),
  published: true,
});

// Create with explicit ID
const user = await db.create("user", "alice123").set({
  name: "Alice",
  email: "alice@example.com",
});

// Control return value
const created = await db.create("user")
  .set({ name: "Bob" })
  .return("after"); // or "before", "none", "diff"

// Use .only() to return a single object instead of an array
const user = await db
  .create("user", "john")
  .only()
  .set({ name: "John" });
// user: one row, typed as described in "What a partial write returns" (not an array)
```

#### Which write method enforces required fields?

Only `.content()` requires the full record on `CREATE`: its input type is the table's fields, minus those with a `.default()` or `option<…>` type, and minus `id` and computed fields. The other ways of writing are deliberately permissive, to mirror SurrealQL (and so that the database can supply the rest, for example through its own `DEFINE FIELD … DEFAULT`):

| Method | Required fields | Type of the argument |
| --- | --- | --- |
| `.content()` | Enforced on `create`; optional on `update` / `upsert` | The record |
| `.set()` | Not enforced | A partial record, per field (`+=` / `-=` and dotted paths work) |
| `.merge()` | Not enforced | A partial record |
| `.replace()` | Not enforced | A partial record |
| `.patch()` | Not checked at all | JSON Patch operations, with the `path` as a plain string |

Use `.content()` when you want the compiler to enforce required fields. With [runtime validation](#runtime-validation) enabled, `.content()` is checked as a full record, `.set()` field by field, and `.patch()` is not checked.

#### What a partial write returns

A write that does not supply the whole record still succeeds, and returns only the fields it knows are present. The record is stored as written, so a required field left unset stays unset, and the query does not throw after the write has committed. With [runtime validation](#runtime-validation) on (`validated()`), a new record must still supply its required fields, and the write is rejected before it is sent. The result type follows what was written:

| Write | Fields the returned row is typed with |
| --- | --- |
| `create().content()` | Every field (required fields are enforced) |
| `create().set()` / `.merge()` | `id`, the fields written, fields with a `.default()` (CREATE applies them), and `option<…>` fields |
| `create().replace()` | `id`, the fields written, and `option<…>` fields (REPLACE does not apply defaults) |
| `create()` with no data | `id`, fields with a `.default()`, and `option<…>` fields |
| `create().patch()` | `id`; every other field is optional |
| `relate().content()` | Every field, including `in` and `out` |
| `relate().set()` / `.merge()` | `id`, `in`, `out`, the fields written, fields with a `.default()` (RELATE applies them, as CREATE does), and `option<…>` fields |
| `relate().replace()` | `id`, `in`, `out`, the fields written, and `option<…>` fields (REPLACE does not apply defaults) |
| `update()` / `upsert()` `.set()` / `.merge()` | `id` and the fields written. The other fields may already be stored, so they are optional |
| `update()` / `upsert()` `.content()` / `.replace()` | `id` and the fields written. The record is replaced, so no other field remains |
| `update()` / `upsert()` `.patch()`, and `RETURN BEFORE` on update / upsert | `id`; every other field is optional |
| `delete()` with `RETURN BEFORE` or a projection | `id`; every other field is optional. The record may have been stored partially, and it is deleted before the row is read |
| `select()` | Every field. Each record is parsed in full, so a record stored without a required field cannot be read until it is completed |

A field whose value may be `undefined` (an optional key, or a value typed `T | undefined`) counts as not written: it may be absent, so it is typed as optional. A `.set()` that passes a field as `undefined` does not apply that field's `.default()`, because the field was supplied. A dotted key (`.set({ "name.first": "Ada" })`) writes into the nested object `name`. CREATE and RELATE need that parent object set in full in the same call (`.set({ name: { first, last }, "name.first": "Ada" })`). Without it the call does not type-check, and `.set()` throws an `OrmError` before anything is sent, because the write would store a partial object. UPDATE and UPSERT cannot know whether the object exists on the stored record, so a dotted key into a missing object is accepted there and stores a partial object; reading that record back with the full schema then fails until the missing fields are set. A dotted key into an object that already exists is fine on every write.

`.unset()` removes the unset fields from the result type. A `.return((row) => …)` projection only sees the fields the row is typed with, so it cannot read a field the write did not set. Inserts with `.onDuplicate()` return rows that may have been updated rather than inserted, so only `id` is required for those.

```typescript
import { t, table } from "surqlize";
const user = table("user", {
  name: t.string(),
  email: t.string(),
  nickname: t.option(t.string()),
  role: t.string().default("guest"),
});

const [ada] = await db.create("user").set({ name: "Ada" }).execute();
// ada: { id, name: string, nickname: string | undefined, role: string }
// Stored without an email. db.select("user") throws until one is set.
```

Class-linked tables still return instances of their class.

### INSERT statements

Insert one or multiple records with support for bulk operations and conflict handling.

```typescript illustrative
import { RecordId } from "surrealdb";

// Insert single record (object style)
await db.insert("user", {
  name: "Alice",
  email: "alice@example.com",
  age: 30,
});

// Bulk insert (object style)
await db.insert("user", [
  { name: "Alice", email: "alice@example.com", age: 30 },
  { name: "Bob", email: "bob@example.com", age: 25 },
  { name: "Charlie", email: "charlie@example.com", age: 28 },
]);

// VALUES tuple syntax
await db.insert("user")
  .fields(["name", "email", "age"])
  .values(
    ["Alice", "alice@example.com", 30],
    ["Bob", "bob@example.com", 25]
  );

// IGNORE duplicates (skip conflicts silently)
await db.insert("user", userData).ignore();

// ON DUPLICATE KEY UPDATE (update on conflict). An id is a RecordId, not a string.
await db.insert("user", { 
  id: new RecordId("user", "alice"), 
  name: "Alice", 
  email: "alice@example.com",
  age: 30 
})
.onDuplicate({
  age: { "+=": 1 },
  lastSeen: new Date(),
});

// With operators in ON DUPLICATE
await db.insert("post", posts)
  .onDuplicate({
    views: { "+=": 1 },
    tags: { "+=": ["updated"] },
  });

// With RETURN clause
const inserted = await db.insert("user", data).return("after");

// With RETURN projection
const insertedNames = await db.insert("user", data)
  .return(u => ({ name: u.name }));
```

### UPSERT statements

Create a record if it doesn't exist, update records if matching records exist.

```typescript
// Upsert with SET
await db.upsert("user", "alice")
  .set({
    name: "Alice",
    email: "alice@example.com",
    age: 30,
  });

// Upsert with operators (atomic increment)
await db.upsert("pageview", "homepage")
  .set({
    count: { "+=": 1 },
    lastViewed: new Date(),
  });

// Upsert with MERGE
await db.upsert("user", "alice")
  .merge({ lastLogin: new Date() });

// Bulk upsert with WHERE
await db.upsert("user")
  .where((u) => u.email.eq("alice@example.com"))
  .set({ lastSeen: new Date() });

// Use .only() to return a single object instead of an array
const upserted = await db
  .upsert("user", "john")
  .only()
  .set({ name: "John" });
// upserted: one row, typed as described in "What a partial write returns" (not an array)
```

### UPDATE statements

Update a record or multiple records in a table.

```typescript illustrative
// Update with SET
await db.update("user", "alice")
  .set({ age: 31 });

// Bulk update with WHERE
await db.update("user")
  .where((u) => u.age.lt(18))
  .set({ status: "minor" });

// Array and number operators
await db.update("user", "alice")
  .set({
    age: { "+=": 1 },                // Increment
    tags: { "+=": ["developer"] },   // Append to array
    oldTags: { "-=": ["beginner"] }, // Remove from array
  });

// CONTENT (replace entire record)
await db.update("user", "alice")
  .content({
    name: "Alice Smith",
    email: "alice@example.com",
    age: 31,
  });

// MERGE (partial update)
await db.update("user", "alice")
  .merge({ email: "newemail@example.com" });

// PATCH (JSON Patch operations)
await db.update("user", "alice")
  .patch([
    { op: "replace", path: "/age", value: 32 },
    { op: "remove", path: "/oldField" },
  ]);

// UNSET (remove fields)
await db.update("user", "alice")
  .set({ name: "Alice" })
  .unset(["oldField1", "oldField2"]);

// Return modified records
const updated = await db.update("user")
  .where((u) => u.age.gt(65))
  .set({ status: "senior" })
  .return("after");

// Use .only() to return a single object instead of an array
const user = await db
  .update("user", "john")
  .only()
  .set({ name: "Johnny" });
// user: one row, typed as described in "What a partial write returns" (not an array)
```

An update leaves the fields it does not set in place, so the result types them as optional. `.content()` and `.replace()` replace the record, so only the fields given remain. See [What a partial write returns](#what-a-partial-write-returns).

### RELATE statements

Create graph edges between records using defined edge schemas.

```typescript illustrative
import { RecordId } from "surrealdb";
// Single edge between two records
const edge = await db.relate(
  "authored",
  new RecordId("user", "alice"),
  new RecordId("post", "hello-world")
);

// With edge data using content()
const friendship = await db.relate(
  "knows",
  new RecordId("user", "user1"),
  new RecordId("user", "user2")
).content({
  since: new Date(),
  strength: 5,
});

// With edge data using set()
const likes = await db.relate(
  "likes",
  new RecordId("user", "userId"),
  new RecordId("post", "postId")
).set({
  created: new Date(),
  rating: 5,
});

// Cartesian product: create multiple edges
// Creates: alice->authored->post1, alice->authored->post2,
//          bob->authored->post1, bob->authored->post2
const edges = await db.relate(
  "authored",
  [new RecordId("user", "alice"), new RecordId("user", "bob")],
  [new RecordId("post", "post1"), new RecordId("post", "post2")]
);

// Control return mode
await db.relate(
  "authored",
  new RecordId("user", "user"),
  new RecordId("post", "post")
).content({ created: new Date(), role: "author" })
.return("after"); // or "before", "none", "diff"

// With return projection
const edgeInfo = await db.relate(
  "follows",
  new RecordId("user", "follower"),
  new RecordId("user", "followee")
).set({ since: new Date() })
.return(edge => ({
  id: edge.id,
  from: edge.in,
  to: edge.out,
  since: edge.since,
}));


// Using with query results
const userQuery = db.select("user", "alice");
const postQuery = db.select("post", "hello");
await db.relate("authored", userQuery, postQuery);

// Use .only() to return a single edge object instead of an array
const relation = await db
  .relate("authored", new RecordId("user", "alice"), new RecordId("post", "hello-world"))
  .only();
// relation: Authored  (not Authored[])
```

### DELETE statements

```typescript illustrative
// Delete single record (no RETURN, so it resolves to an empty array)
await db.delete("user", "alice");

// Bulk delete with WHERE
await db.delete("user")
  .where((u) => u.age.lt(13));

// Return deleted records
const deleted = await db.delete("user")
  .where((u) => u.status.eq("inactive"))
  .return("before");

// Delete with projection
const deletedNames = await db.delete("user")
  .where((u) => u.email.endsWith("@spam.com"))
  .return((u) => ({ name: u.name }));

// Use .only() to return a single object instead of an array.
// DELETE ONLY is most useful with RETURN BEFORE when the deleted record should be returned.
const deleted = await db
  .delete("user", "alice")
  .only()
  .return("before");
// deleted: one row, typed as described in "What a partial write returns" (not an array).
// Only `id` is guaranteed: the stored record may be partial.
```

## Runtime validation

TypeScript checks your data at compile time, but data from a form, an API request or `JSON.parse` is only checked when you check it. Surqlize can validate the data a write carries against the table schema **before** it is sent to SurrealDB. It is off by default.

### Validating every write

`db.validated()` returns a view of the ORM (sharing the same connection, like `withSignal()`) in which `create`, `insert`, `update`, `upsert` and `relate` check their data first:

```typescript illustrative
const db = orm(surreal, user).validated();

await db.create("user").content({ name: 42, address: { city: 1 }, tags: ["a", 2] });
// Throws before anything is sent:
// ValidationError: Invalid data for table "user": 4 validation errors
//   - name: expected string, received 42
//   - age: expected number, received undefined
//   - address.city: expected string, received 1
//   - tags[1]: expected string, received 2
```

A single query can opt in or out with `.validated()` / `.validated(false)`. Validation also applies in batches, inside transactions, to `.prepare()`, and survives `withSignal()`.

**`validated()` is needed to stop incomplete records being stored.** Without it, `db.create("user").set({ name: "Ada" })` on a table with a required `email` stores the record without `email`, and the write returns. A later `db.select("user")` of that record throws `TypeParseError`, because the record cannot be parsed. With `validated()`, the same write throws `ValidationError` (`email: required field is not set`) before anything is sent. The ORM does not check for incomplete records when validation is off.

`ValidationError` extends `OrmError`. It does not stop at the first problem: `error.issues` lists every failing field as `{ path, expected, received, message }`, where `path` looks like `address.city` or `tags[1]` (or `[2].age` for the third row of an `insert`), and `error.table` names the table.

### What is checked

| Data | Checked as |
| --- | --- |
| `create().content()`, `create().set()`, `create().merge()`, `insert()` rows | the new record: every required field must be present and valid. `option<...>` fields, fields with a `.default()` (CREATE and INSERT fill them), and `id` are not required |
| `create().replace()` | the new record: every required field must be present. REPLACE does not fill defaults, so fields with a `.default()` are required too |
| `relate().content()`, `.set()`, `.merge()`, `.replace()` | the new edge: every required field must be present, including fields with a `.default()`, since RELATE does not fill defaults. `id`, `in` and `out` are not required |
| `update` / `upsert` `.content()`, `.replace()` | the whole record, which replaces the stored one: every required field must be present, including fields with a `.default()`, since neither fills defaults |
| `update` / `upsert` `.set()`, `.merge()` | each supplied field, including dotted paths such as `"address.city"` for `.set()`. The stored fields are kept, so a missing field is not an error |
| `.set()` and `.onDuplicate()` | each assigned field, including dotted paths such as `"address.city"`. `+=` / `-=` operands are checked for number and array fields |
| `.patch()` | not checked |

A required field is one the schema does not mark `option<...>` and that the write does not supply. A field passed as `undefined` counts as not supplied.

- Nested objects, arrays, tuples, unions, record links (including the linked table) and tables linked to a class are all checked.
- **Computed fields are read-only**: supplying a value for one is an issue.
- Fields the schema does not declare are ignored, and so are `.patch()` operations.
- Values SurrealDB evaluates itself, such as `expr(...)` defaults and subquery expressions, are not checked client-side.
- Validation never changes your data: what is checked is what is sent. Defaults are still filled in by the query as before.
- The result of a partial write is typed to match what was written, as described in [What a partial write returns](#what-a-partial-write-returns). Under validation, a new record (`create`, `relate`) must still be given every required field, as the table above says, so `create().set({ name })` on a table with a required `email` is rejected even though its result type leaves `email` out. A value that is supplied is always checked.

### Validating data yourself

Tables and edges have the same check as a standalone helper, for example at the edge of your API:

```typescript illustrative
const result = user.safeParse(body);            // mode "create" by default
if (!result.success) return respond(400, result.error.issues);
await db.create("user").content(result.data);   // result.data is typed as the create input

const input = user.parse(body);                 // returns the typed data, or throws ValidationError
user.safeParse(patch, { mode: "update" });      // a partial write
user.safeParse(row, { mode: "row" });           // a whole stored record, id and computed fields included
```

`safeParse` never throws, and `parse` throws the same `ValidationError`. The `mode` option selects `"create"` (default), `"update"` or `"row"`, and the type of `data` follows it. On a table linked to a class, `"row"` mode returns an instance of the class, as selects do (the other modes return the data as given). The existing `table.validate(value)` type guard and the `t.*` types' `validate()` / `parse()` are unchanged.

## Custom functions and API endpoints

Describe a `DEFINE FUNCTION` with `fn(name, params, returns)` and call it with `db.run()`, or call a `DEFINE API` endpoint through a typed client from `db.api()`. Both are typed from the description, and results are parsed against the declared types. Define the function or endpoint in the database first; surqlize only calls it.

```ts
import { api, fn, orm, t } from "surqlize";

const greet = fn("greet", [t.string()], t.string()); // fn::greet
const greeting = await db.run(greet, ["world"]);     // string

const echo = api("/echo", {
  post: {
    request: t.object({ text: t.string() }),
    response: t.object({ text: t.string() }),
  },
});
const res = await db.api(echo).post("/echo", { text: "hi" });
res.body?.text; // string | undefined
```

An API call whose status is outside 2xx rejects with the SDK's `UnsuccessfulApiError` (from `surrealdb`), whose `response` holds the status, the headers and the raw body. A failure body is never parsed against the declared `response` type, which describes the success.

A function is also callable inside a query: `db.select("user").return((u) => ({ hi: greet(u, u.name) }))`.

On a [validated](#runtime-validation) ORM (`db.validated()`), `db.run()` checks its arguments against the parameter types, and API calls check the request body against the declared `request` type, before anything is sent. Every failing argument or field is reported in a single `ValidationError`. Arguments passed to a function inside a query are expressions evaluated by the database, so they are not checked.

### Using a schema with the `surrealdb` SDK

Every `t.*` type implements [Standard Schema](https://standardschema.dev), so a definition can validate in any library that accepts one, including the `surrealdb` SDK's `.args()`, `.returns()`, `.request()` and `.response()` call methods (in the first `surrealdb` release that includes them):

```ts illustrative
const sum = await surreal.run("fn::add", [1, 2]).returns(t.number());
```

## Batch

Execute multiple queries as a single atomic operation in one round-trip. No intermediate results are available — all queries succeed or all fail together.

```typescript
// Multiple queries in a single atomic operation
const [user, updated, allUsers] = await db.batch(
  db.create("user").set({ name: "Alice", age: 30 }),
  db.update("user", "bob").set({ age: 31 }),
  db.select("user"),
);
// Results are fully typed as a tuple
```

A batch is sent as one request using the SDK's stateless `transaction()`, so it works over HTTP as well as WebSockets. If it fails, the promise rejects with the error that made it fail, and none of its statements take effect.

Because it is a single request, a batch is safe to replay. Use `.retry()` to re-send it when it fails because of a conflict with a concurrent transaction (see [Retrying conflicts](#retrying-conflicts)). A batch also takes `.signal()` and `.requestTimeout()`, as described in [Cancellation, timeouts and retries](#cancellation-timeouts-and-retries):

```typescript
const [created] = await db
  .batch(db.create("user").set({ name: "Alice", age: 30 }))
  .retry()
  .requestTimeout(5_000);
```

You can also inspect the generated SurrealQL before executing:

```typescript
const b = db.batch(
  db.create("user").set({ name: "Alice" }),
  db.update("user", "bob").set({ age: 31 }),
);

console.log(b.toString());
// BEGIN TRANSACTION; CREATE user SET name = $_v0; UPDATE user:bob SET age = $_v1; COMMIT TRANSACTION;

// Execute when ready
const [created, updated] = await b;
```

> A batch cannot be used inside an interactive [transaction](#transactions) — it is already atomic, and transactions cannot be nested. `tx.batch()` throws; run the queries on `tx` instead.

## Transactions

Open a server-side transaction, execute queries one-by-one with intermediate results, and decide whether to commit or cancel based on the outcomes.

### Callback form (auto-commit/cancel)

The callback form automatically commits on success and cancels on error:

```typescript
const result = await db.transaction(async (tx) => {
  const user = await tx.create("user").only().set({
    name: "Alice",
    age: 30,
  });

  // Use intermediate results to make decisions
  if (user.age > 25) {
    await tx.update(user.id).set({ status: "senior" });
  }

  return user;
});
// Transaction is committed automatically
```

### Manual form (explicit commit/cancel)

For full control, use the manual form:

```typescript
import { RecordId } from "surrealdb";
const tx = await db.transaction();
try {
  const user = await tx.create("user").only().set({ name: "Alice" });
  await tx.relate("authored", user.id, new RecordId("post", "hello"));
  await tx.commit();
} catch (e) {
  await tx.cancel();
  throw e;
}
```

The transaction object (`tx`) has all the same query-builder methods as the main `db` instance — `select`, `create`, `insert`, `update`, `upsert`, `delete`, and `relate` — except `batch`, which is itself atomic and cannot be nested.

To abandon the queries of a transaction when a request is aborted, use `tx.withSignal(signal)`. It returns a handle on the same transaction, so `commit()` and `cancel()` work on either. They are deliberately not bound to the signal: a request that is being abandoned cannot leave the outcome of a commit in doubt.

## Live queries

Subscribe to real-time changes with `db.live()`. It compiles to a SurrealDB [`LIVE SELECT`](https://surrealdb.com/docs/surrealql/statements/live) statement and resolves to a typed `LiveSubscription`:

```typescript
// Open a subscription to every change on the `user` table
const sub = await db.live("user");

// Handle notifications (returns a function that unsubscribes this handler)
const off = sub.subscribe((msg) => {
  // msg.action:   "CREATE" | "UPDATE" | "DELETE" | "KILLED"
  // msg.recordId: the affected RecordId
  // msg.value:    the affected record, parsed against the schema
  if (msg.action === "KILLED") return; // see "Handling KILLED" below
  console.log(msg.action, msg.value);
});

// Stop receiving updates on this handler...
off();
// ...or kill the subscription entirely
await sub.kill();
```

The notification `value` is parsed against the table schema, so it is fully typed once you have narrowed to a record change:

```typescript illustrative
const sub = await db.live("user");
sub.subscribe((msg) => {
  if (msg.action === "KILLED") return;
  msg.value.name.first; // string
  msg.value.age; // number
});
```

### Handling `KILLED`

`KILLED` means the server ended the subscription — for example because its table was removed. It is the last message a subscription emits, and it carries no record, so `recordId` and `value` only exist once you have ruled it out. `LiveMessage` is a union, so the compiler enforces this:

```typescript illustrative
sub.subscribe((msg) => {
  if (msg.action === "KILLED") {
    // msg.recordId and msg.value are undefined here
    return;
  }
  msg.recordId; // RecordId
  msg.value; // the record
});
```

`sub.isAlive` turns `false` when a subscription is killed, by `kill()`, by the server, or because the request scope it was made through was aborted.

A subscription is also async-iterable:

```typescript
for await (const msg of await db.live("user")) {
  console.log(msg.action, msg.value);
}
```

### Filtering, projecting and fetching

Live queries support `.where()`, `.return()` (a `VALUE` projection) and `.fetch()`, mirroring `select`:

```typescript
// Only notify for adult users
const adults = await db.live("user").where((user) => user.age.gte(18));

// Project a subset of fields
const names = await db.live("user").return((user) => ({
  name: user.name,
  email: user.email,
}));

// Resolve record links in notifications
const posts = await db.live("post").fetch("author");
```

> **Note:** Filtering or projecting a live query relies on query parameters, which require **SurrealDB ≥ 3.0** (`FETCH` requires ≥ 2.2.0). On older servers a parameterized live query is accepted but never delivers notifications.

> **Note:** A live `.where()` cannot hold a full-text match (`.search()`) or a KNN predicate (`.knn()`) anywhere in it: alone, inside `and()`, `or()` and `not()`, or inside a subquery. SurrealDB accepts one, but at the top of the filter it never causes a notification: alone or under `and()` or `not()` nothing is delivered, and under `or()` only the other conditions deliver. Inside a subquery it did deliver on 3.2.3, but that is untested on other versions, so it is refused too. Building one throws an `OrmError`. Subscribe without that predicate, or refetch a `select()` when the table changes.

### Diffs

Use `.diff()` to receive [JSON Patch](https://jsonpatch.com) arrays instead of full records (`LIVE SELECT DIFF`):

```typescript
const sub = await db.live("user").diff();
sub.subscribe((msg) => {
  // msg.value is a JsonPatchOp[]
});
```

### Subscribe in one step

Calling `.subscribe(handler)` on the builder starts the query and returns a stop function that both unsubscribes and kills the subscription:

```typescript
const stop = await db
  .live("user")
  .where((user) => user.age.gte(18))
  .subscribe((msg) => console.log(msg.action, msg.value));

// later
stop();
```

### Reconnecting

A subscription to a table — with any of `.where()`, `.fetch()` and `.diff()` — is **managed** by the SDK. If the connection drops and comes back, the SDK registers the live query again, so notifications keep flowing. The subscription's `id` changes when that happens, and anything that changed while the connection was down is not replayed.

A subscription with a `.return()` projection cannot be expressed that way and is **unmanaged**: it goes silent after a reconnect, and `isAlive` stays `true`. Check `sub.isManaged` if that matters to you, or subscribe to the whole record and project on the client.

```typescript
const sub = await db.live("user").where((user) => user.age.gte(18));
sub.isManaged; // true

const names = await db.live("user").return((user) => ({ name: user.name }));
names.isManaged; // false
```

> The table must exist before subscribing (define it up front, e.g. with `DEFINE TABLE`).

## Generating the database schema

The tables, edges and fields you describe with `t.*` can be turned into `DEFINE` statements, so the database enforces the same types the client checks.

```ts
import { generateSchema, toSurql } from "surqlize";

const schema = generateSchema(db);

// Apply it...
await surreal.query(schema.statements.map((s) => s.sql).join("\n"));

// ...or write it for a tool that reads `.surql` files.
await Bun.write("database/schema/surqlize.surql", toSurql(schema));
```

`generateSchema(db)` returns the tables before their fields, so the statements can run top to bottom. Each statement has a `kind`, a stable `name` (`user.address.city`, `post.items[*].k`) and its `sql`. It defines every table and edge (`TYPE RELATION IN … OUT …`), every field with its type and `DEFAULT`, indexes, events, and computed fields. Statements use `OVERWRITE` so they can be run again; pass `{ mode: "if-not-exists" }` to leave definitions that already exist.

| Surqlize | SurrealQL |
| --- | --- |
| `t.string()`, `t.number()`, `t.int()`, `t.float()`, `t.bool()`, `t.uuid()`, `t.duration()`, `t.bytes()`, `t.any()` | `string`, `number`, `int`, `float`, `bool`, `uuid`, `duration`, `bytes`, `any` |
| `t.date()`, `t.point()` | `datetime`, `geometry<point>` |
| `t.option(x)` | `option<x>` |
| `t.record("user")`, `t.record(["a", "b"])`, `t.record()` | `record<user>`, `record<a \| b>`, `record` |
| `t.array(x)`, `t.array([x, y])` | `array<x>`, `[x, y]` |
| `t.set(x)`, `t.set(x, max)` | `set<x>`, `set<x, max>` |
| `t.literal("a")`, `t.union([…])` | `'a'`, `a \| b` |
| `t.object({ … })` | `object`, with each field defined as `parent.field` |

- **Tables are `SCHEMAFULL` by default**: the database rejects a field the schema does not declare. Call `.schemaless()` on a table to keep fields it does not declare, as the client-side validation does.
- **Defaults.** A static value or an `expr()` becomes `DEFAULT`; a string is always data, so `expr("time::now()")` calls the function and `"time::now()"` stores the text. A default that is a function (`() => new Date()`) can only run on the client, so it is left out of the statement and listed in `skipped` with the reason.
- **Objects** are defined field by field, which lets them carry defaults, through options and arrays (`items[*].name`, `grid[*][*].v`). An object inside a union or a tuple is written out as a literal object type (`{ kind: 'a', n: number }`), which the database also holds to its exact keys.
- **Sets.** `t.set(x)` is a JavaScript `Set`, not an array: it infers `Set<…>`, accepts and returns `Set` instances, and rejects a plain array, which is what the database does for `set<x>`. It has the `set::` functions (`add`, `union`, `len`, …), not the `array::` ones. `t.set(t.object({ … }))` defines its fields as `parent[*].field`, as an array does.
- **Names** that are not plain identifiers are escaped (`⟨order-item⟩`).

Integration tests apply the statements to a real server and check that it accepts and rejects the same values as the client-side types, for each mapping above.

### Permissions

A table, an edge or a field can carry `PERMISSIONS`, one rule for each operation (`select`, `create`, `update`, `delete`). A rule can be written two ways, and the two can be mixed in one object:

- **SurrealQL as a string**, written as is. This is always available, and the way to say anything the typed form cannot.
- **A typed rule**, `"full"`, `"none"` or `where(…)`: a condition built from the row and the variables SurrealDB gives a permission clause, checked by TypeScript.

#### SurrealQL strings

```ts illustrative
export const users = table("users", {
  name: t.string(),
  // A field takes the whole clause as a string
  avatar_url: t.option(t.string()).permissions("FOR select, create, update, delete FULL"),
}).permissions({
  // A table takes a string for each operation; a bare condition gets its WHERE added
  select: "FULL",
  create: "$auth.id != NONE",
  update: "$auth.id = id",
  delete: "NONE",
});
```

```sql
DEFINE TABLE users TYPE NORMAL SCHEMAFULL PERMISSIONS FOR select FULL, FOR create WHERE $auth.id != NONE, FOR update WHERE $auth.id = id, FOR delete NONE;
DEFINE FIELD name ON TABLE users TYPE string;
DEFINE FIELD avatar_url ON TABLE users TYPE option<string> PERMISSIONS FOR select, create, update, delete FULL;
```

A table also takes a single string for every operation, such as `.permissions("FULL")`.

#### Typed rules

```ts illustrative
import { authenticatedAs, or, t, table, where } from "surqlize";

const user = table("user", { role: t.string() });
const { where: asUser } = authenticatedAs(user); // `auth` is a record of `user`

export const post = table("post", {
  title: t.string(),
  owner: t.record("user"),
  secret: t.string().permissions({
    select: where((row, { auth }) => row.owner.eq(auth.id)),
    update: where((row, { auth }) => row.owner.eq(auth.id)),
    create: "full",
  }),
}).permissions({
  select: "full",
  create: where((_row, { auth }) => auth.id.ne(undefined)),
  update: asUser((row, { auth }) => or(row.owner.eq(auth.id), auth.role.eq("admin"))),
  delete: "none",
});
```

```sql
DEFINE TABLE post TYPE NORMAL SCHEMAFULL PERMISSIONS FOR select FULL, FOR create WHERE $auth.id != NONE, FOR update WHERE $this.owner = $auth.id OR $auth.role = 'admin', FOR delete NONE;
DEFINE FIELD secret ON TABLE post TYPE string PERMISSIONS FOR select WHERE $this.owner = $auth.id, FOR update WHERE $this.owner = $auth.id, FOR create FULL;
```

#### Mixing the two

A string and a typed rule can sit side by side, one operation each:

```ts illustrative
export const note = table("note", {
  title: t.string(),
  owner: t.record("user"),
}).permissions({
  select: "full",
  create: where((row, { auth }) => row.owner.eq(auth.id)),
  delete: "none",
});
```

```sql
DEFINE TABLE note TYPE NORMAL SCHEMAFULL PERMISSIONS FOR select FULL, FOR create WHERE $this.owner = $auth.id, FOR delete NONE;
```

`"full"` and `"none"` are accepted in either case, so `"FULL"` and `"full"` mean the same.

#### Notes

- **Variables.** The second argument holds `auth` (`$auth`), `session`, `token` and `access`. A field's rules also get `value`, `before` and `after`, typed as the field; they are `NONE` in a table's rules, so using one there throws when the schema is generated.
- **Typing `auth`.** What `$auth` is depends on your `DEFINE ACCESS … TYPE RECORD`, so it is not inferred. Plain `where` leaves `auth` loose (its `id` is a link, any other property is untyped); `authenticatedAs(user)` returns a `where` with `auth` typed as a record of that table, so `auth.role` is a string. Pass further tables (`authenticatedAs(user, team)`) to follow links into them.
- **Typing the row.** A table's (or edge's) rules are checked against its fields: `row.nope` and `row.title.eq(1)` are errors. A field's rules see a loose row, as the table does not exist where the field is declared.
- **Defaults.** An operation you leave out takes SurrealDB's default: `FULL` for a field, `NONE` for a table. A field has no `delete`. A table's `update` rule is checked against the record before and after the change.

Typed rules are rendered when the schema is generated, by `generateSchema`, `defineSchema` and `surqlize plan`, so a migration of a table with typed permissions converges like any other.

## Migrations

The `surqlize` command compares a schema with a database and works out what has to change. The migrator is also available as a library from `surqlize/migrate`.

```bash
bunx surqlize init       # write surqlize.config.ts and a starter schema
bunx surqlize plan       # show the statements that would run, without running them
bunx surqlize migrate    # apply them, and record the migration
bunx surqlize status     # list the migrations that have been applied
bunx surqlize rollback   # undo the most recent migration
```

A schema is a module that exports the tables and edges to manage. Running `plan` again after `migrate` reports nothing to do, so a change that fails part-way is recovered by planning again. A field renamed with `.was("old")` is migrated by copying its values, not by dropping it. Database settings come from `surqlize.config.ts`, then `SURREAL_*` environment variables, then flags, and `-e <name>` selects a named environment.

A signing key in an access method is applied but never printed by `plan` or kept in the migration history; from `surqlize/migrate`, `plan()` returns the text that is safe to show as `display`. SurrealDB does not reveal a key once it is stored, so `rollback` refuses a migration that would restore an access method with a hidden key, and names it. Recreate that access by hand, then delete the migration from `_migrations`.

## Reactive store

A store turns a query into a live value. It loads the result, keeps it current from live notifications, and exposes `subscribe` and `getSnapshot`, the shape that `useSyncExternalStore`, Svelte stores and similar bindings expect. It works with any framework and adds no dependency.

```ts illustrative
import { createStore } from "surqlize";

const store = createStore(db);

const all = store.query("task");                                   // every task
const open = store.query("task", (q) => q.where({ done: false })); // a filtered, ordered or limited query

const stop = open.subscribe(() => render(open.getSnapshot()));
```

A snapshot is one of:

- `{ status: "loading" }` until the first result arrives
- `{ status: "success", data, stale }`, where `stale` is `true` while the connection is down
- `{ status: "error", error }` if loading failed or the server killed the subscription. Call `open.refetch()` to try again.

`getSnapshot()` returns the same object until something changes.

- **Sharing.** Asking for the same query again returns the same store, so every component that shows it shares one live subscription. Two queries share a store when their text and the values they bind are equal: a `Set` and an array of the same items, or two byte arrays with different content, do not. An instance of a class that has no SurrealQL form of its own is compared by its class name only, so two instances of it with different data share a store. The store starts with its first subscriber and stops shortly after the last one leaves (`idleMs`, 100 ms by default), so a component that unmounts and mounts again straight away does not restart it.
- **No lost changes.** The store registers the live query before it reads, and applies the notifications that arrived in the meantime on top of the result.
- **Stores for a short scope.** A store listens to the connection and retries the writes it could not send until it is disposed. A store made for one request, or one test, should end with `store.dispose()`, which also stops every running query, subscribed or not. A write that is on its way ends as the database answers, but nothing is sent or retried after it, and the writes that are still waiting stay in their storage.
- **Signing in first.** If the connection has to be authenticated before the store touches the database, pass `gate`, a function that returns a promise: `createStore(db, { gate: () => signIn() })`. The store calls it the first time something needs the connection (the first subscriber of a query, a write, or `refetch()`), never when the store is made, and not again once it has resolved. Until then it registers no live query, reads nothing and sends no write. A write made meanwhile is queued and shown at once, and a write kept in `storage` from an earlier session is sent after the gate resolves, not anonymously before it. A write kept in `storage` does not call the gate by itself: it waits for the first subscriber, write or `refetch()`. If the gate rejects, queries report the error and writes stay queued; the next write, `refetch()`, or subscriber of a query that is not running calls it again. A query that failed to start is started over by `refetch()` or by a new subscriber, which registers its live query and shows local writes again.
- **Reconnects.** A live subscription does not replay the changes made while the connection was down. When it returns, the store reads the query again. Pass `{ connection }` to `createStore()` if your ORM is not built on a `Surreal` instance.
- **Filtered queries.** SurrealDB sends no notification when an update makes a record stop matching a live query's `WHERE`, so a filtered result cannot be kept current from notifications alone. A query built with a callback (filter, order, limit, projection, `FETCH`) therefore subscribes to the whole table and runs again, after `debounceMs` (20 by default), whenever the table changes. A query without a callback applies each notification as it arrives, and takes an optional `sort` function.

### Optimistic and offline writes

`store.table(name)` makes writes that show in every query of the table straight away, and are sent to the database in order.

```ts illustrative
const tasks = store.table("task");

const { id, committed } = tasks.create({ title: "Write docs", done: false });
tasks.update(id, { done: true });
tasks.delete(id);

await committed; // the stored record, once the database has accepted the write
```

- **The id is known at once.** `create()` generates a record id unless you pass `{ id }`, so the record can be used before the database has seen it.
- **Shown on top of the database's state.** Pending writes are applied to the result of each query of the table. When the database accepts a write, its answer replaces the pending write in the result, so nothing flickers when the live notification for it arrives. See [Filtered queries](#filtered-queries-and-local-writes) for how a write enters or leaves a filtered result.
- **A refusal is taken back.** If the database refuses a write (a failed assertion, a missing record for an update, a permissions error), the change disappears from the results and `committed` rejects with the error.
- **A connection problem is not a refusal.** The write stays queued, is retried with a growing delay, and is sent as soon as the connection returns, before the queries read again. While offline, `committed` stays pending. A conflict with a concurrent write, which the database reports as retryable (SurrealDB 3.1 or later), is treated the same way: the write was not applied, so it is sent again. `store.pending` has `subscribe` and `getSnapshot` for the writes that are waiting, for example to show an "unsaved changes" indicator.
- **Merging.** Writes to the same record that have not been sent yet are combined, so editing a field repeatedly offline sends one write. Updates merge top-level fields: the last write to a field wins, and a nested object is replaced as a whole. Text is not merged.
- **Safe to send twice.** A write that was sent but whose answer was lost is sent again. A create is an upsert of the whole record, an update is a merge, and deleting a missing record is not an error, so repeating any of them leaves the same record.

#### Filtered queries and local writes

When a query is a plain object filter, the store checks each local write against it, so a record enters or leaves the result at once:

```ts illustrative
const open = store.query("task", (q) => q.where({ done: false, priority: { gte: 2 } }));

tasks.create({ title: "A", done: false, priority: 5 }); // appears now
tasks.update(id, { done: true });                        // disappears now
```

The check understands `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `inside`, `notInside`, `contains`, `containsNot`, `containsAll`, `containsAny`, `containsNone`, `allInside`, `anyInside`, `noneInside`, `startsWith` and `endsWith`, nested object fields, and `and`, `or` and `not`. Strings are ordered by code point, as the database orders them. It is a prediction, and the database stays the authority: the answer to each write replaces it, and the refetch that follows corrects any mismatch.

The store does not guess when it cannot be sure, and leaves the result as the database last reported it. That is the case when:

- the filter is a callback (`q.where((r) => r.done.eq(false))`) rather than an object, because a callback builds a SurrealQL expression the client cannot evaluate;
- the filter uses an operator not listed above, compares values it does not order, or reaches into a linked record;
- a created record leaves out a field the filter reads, since the database may fill it in with a default;
- the query has a `LIMIT`, `START`, `GROUP`, `SPLIT`, `FETCH`, a projection, or `.only()`, where it is not just a filter;
- the query is ordered. An update still changes a row in place, but a created record is not added until the database has ordered it.

A record that left the result and is updated back to matching is not shown until the database reports it, because the client holds only the fields of the write, not the whole record.

When the database accepts a write, a query that is not a plain filter (a projection, `LIMIT`, `START` or a callback filter) keeps the keys of its rows. The answer updates the fields a row already has and adds none, so a written field shows at once, a computed column keeps its last value until the query reads again, and a field the query did not select does not appear once the database has accepted the write. While the write is pending, the result shows every field the write sets, including one the query did not select, and that field goes when the database accepts the write. A field the query computes or fetches under the name of a stored field shows the stored value until the query reads again. A row of a projection that leaves out `id` belongs to no write, so a pending write leaves it as the database reported it until the query reads again.

Known limitation: a field that a write clears to `NONE` is left out of the database's answer. A query that is not a plain filter (a projection that selects the field, `LIMIT`, `START`, `FETCH`, or a callback filter) then shows the field's old value from the moment the database accepts the write until the query reads again. The field is absent while the write is pending, and absent again once the query has read. A plain filter replaces its rows with the answer and is not affected.

By default pending writes are kept in memory, so they survive a dropped connection but not a reload. To keep them across reloads, pass an IndexedDB store, and wait for `store.ready` before relying on them:

```ts
import { createStore, indexedDbStorage } from "surqlize";

const store = createStore(db, { storage: indexedDbStorage("my-app") });
await store.ready; // writes left by an earlier session are sent from here
```

Values in a stored write can be strings, numbers, booleans, null, dates, record ids, uuids, durations, bigints, and arrays and plain objects of those. A write holding anything else is rejected when it is made, with the path of the value.

### React

`surqlize/react` binds a store to React 18 and 19 with `useSyncExternalStore`. `react` is an optional peer dependency, and the entry adds no code to the rest of the package.

```tsx
import { createStore } from "surqlize";
import { StoreProvider, usePending, useQuery, useStore } from "surqlize/react";

const store = createStore(db);

function App() {
  return (
    <StoreProvider store={store}>
      <Tasks />
    </StoreProvider>
  );
}

function Tasks() {
  const store = useStore<typeof db>();
  const tasks = store.query("task", (q) => q.where({ done: false }));
  const open = useQuery(tasks);
  const pending = usePending(store);

  if (open.status === "loading") return <p>Loading…</p>;
  if (open.status === "error") return <button onClick={() => tasks.refetch()}>Retry</button>;

  return (
    <>
      {pending.length > 0 && <p>Saving {pending.length} changes…</p>}
      <ul>
        {open.data.map((task) => (
          <li key={String(task.id)}>
            <input
              type="checkbox"
              onChange={() => store.table("task").update(task.id, { done: true })}
            />
            {task.title}
          </li>
        ))}
      </ul>
    </>
  );
}
```

- `useQuery(query)` re-renders when the result changes and returns the same `StoreSnapshot` described above. `store.query()` returns the same object for the same query, so it can be called while rendering. Pass `null` or `undefined` to skip a query until its inputs are known; the result is then `{ status: "skipped" }`.
- The live subscription starts with the first component that uses a query and stops shortly after the last one unmounts, so StrictMode's extra mount and unmount does not restart it.
- On the server, and while hydrating, `useQuery` returns `{ status: "loading" }`; the query runs in the browser.
- `usePending(store)` returns the writes the database has not accepted yet, for an "unsaved changes" indicator.
- `StoreProvider` and `useStore<typeof db>()` pass the store down; you can also import the store directly.

### Vue

`surqlize/vue` binds a store to Vue 3 with composables that return refs. `vue` is an optional peer dependency.

```vue
<script setup lang="ts">
import { useQuery, usePending } from "surqlize/vue";
import { store } from "./store";

const tasks = store.query("task", (q) => q.where({ done: false }));
const open = useQuery(tasks);
const pending = usePending(store);
</script>

<template>
  <p v-if="open.status === 'loading'">Loading…</p>
  <button v-else-if="open.status === 'error'" @click="tasks.refetch()">Retry</button>
  <template v-else-if="open.status === 'success'">
    <p v-if="pending.length > 0">Saving {{ pending.length }} changes…</p>
    <ul>
      <li v-for="task in open.data" :key="String(task.id)">{{ task.title }}</li>
    </ul>
  </template>
</template>
```

- `useQuery(query)` returns a shallow ref of the snapshot. Pass a ref or a getter to change the query over time (use `shallowRef`, since a deep `ref` would wrap the store in a reactive proxy), and `null` or `undefined` to skip it (`{ status: "skipped" }`).
- The live subscription starts with the first component that uses a query and stops shortly after the last one unmounts. Inside a component nothing is subscribed until it has mounted, so rendering on the server starts no live queries and the value stays `{ status: "loading" }`.
- `usePending(store)` holds the writes the database has not accepted yet.
- `provideStore(store)` and `useStore<typeof db>()` pass a store down, or `app.provide(storeKey, store)` on the app, with `storeKey` exported from `surqlize/vue`.
### Svelte

`surqlize/svelte` gives Svelte stores, in the store contract that Svelte 3, 4 and 5 all use, so a query works with `$`, `get()` and `derived()`. It needs nothing beyond Svelte itself.

```svelte
<script>
  import { pendingStore, queryStore } from "surqlize/svelte";
  import { store } from "./store";

  const tasks = store.query("task", (q) => q.where({ done: false }));
  const open = queryStore(tasks);
  const pending = pendingStore(store);
</script>

{#if $open.status === "loading"}
  <p>Loading…</p>
{:else if $open.status === "error"}
  <button onclick={() => tasks.refetch()}>Retry</button>
{:else if $open.status === "success"}
  {#if $pending.length > 0}<p>Saving {$pending.length} changes…</p>{/if}
  <ul>
    {#each $open.data as task (String(task.id))}
      <li>{task.title}</li>
    {/each}
  </ul>
{/if}
```

- `queryStore(query)` calls back at once with the current snapshot and again on each change. The live subscription starts with the first subscriber and stops shortly after the last one leaves. Pass `null` or `undefined` to skip a query; the value is then `{ status: "skipped" }`.
- `pendingStore(store)` holds the writes the database has not accepted yet.
### Solid

`surqlize/solid` binds a store to Solid with primitives that return accessors. `solid-js` is an optional peer dependency.

```tsx
import { createPending, createQuery } from "surqlize/solid";
import { store } from "./store";

function Tasks() {
  const tasks = store.query("task", (q) => q.where({ done: false }));
  const open = createQuery(tasks);
  const pending = createPending(store);

  return (
    <>
      <Show when={pending().length > 0}>
        <p>Saving {pending().length} changes…</p>
      </Show>
      <Switch>
        <Match when={open().status === "loading"}>
          <p>Loading…</p>
        </Match>
        <Match when={open().status === "error"}>
          <button onClick={() => tasks.refetch()}>Retry</button>
        </Match>
        <Match when={open()}>
          {(snap) => (
            <ul>
              <For each={snap().status === "success" ? (snap() as { data: Task[] }).data : []}>
                {(task) => <li>{task.title}</li>}
              </For>
            </ul>
          )}
        </Match>
      </Switch>
    </>
  );
}
```

- `createQuery(query)` returns an accessor of the snapshot. Pass an accessor to change the query over time, and `null` or `undefined` to skip it (`{ status: "skipped" }`).
- The live subscription starts with the first owner that uses a query and stops shortly after the last one is disposed.
- Solid does not run effects when rendering on the server, so nothing is subscribed there and the value stays `{ status: "loading" }`; the query runs in the browser.
- `createPending(store)` holds the writes the database has not accepted yet.
- `StoreProvider` and `useStore<typeof db>()` pass a store down.

## Accessing Single Records

All queries in Surqlize return arrays, even when selecting by a specific record ID. To access the first item from a query result, use `.val()` or `.at(index)`:

```typescript
// .val() - Returns the first item or undefined
const user = await db.select("user", "alice").then.val();
// user: User | undefined

// .at(index) - Returns the item at the specified index or undefined
const firstUser = await db.select("user").then.at(0);
const secondUser = await db.select("user").then.at(1);
const lastUser = await db.select("user").then.at(-1); // negative indexing supported

// Working with arrays directly
const users = await db.select("user", "alice");
// users: User[]
if (users.length > 0) {
  const user = users[0];
}

// Use with update, delete, and upsert
const updated = await db.update("user", "alice")
  .set({ age: 31 })
  .return("after")
  .then.val();

const deleted = await db.delete("user", "alice")
  .return("before")
  .then.val();
```

## Filtering operations

All types support these comparison operators:

```typescript illustrative
db.select("user").where((user) => 
  // Equality
  user.name.eq("John")              // =
  user.age.ne(25)                   // !=
  user.email.ex("john@example.com") // == (exact match)

  // Comparison
  user.age.gt(18)                   // >
  user.age.gte(21)                  // >=
  user.age.lt(65)                   // <
  user.age.lte(64)                  // <=

  // Full-text search
  user.bio.search("typescript")     // @@

  // Array membership
  user.status.inside(["active", "pending"])    // IN
  user.status.notInside(["banned", "deleted"]) // NOT IN

  // Logical operators
  user.age.gte(18).and(user.isActive.eq(true))
  user.role.eq("admin").or(user.role.eq("moderator"))
  user.isActive.not()
  
  // Truthiness checks
  user.bio.trueish()    // !! (double negation - checks for truthy value)
  user.archived.falseish() // ! (negation - checks for falsy value)
);
```

### Compound conditions

For complex conditions, use the standalone `and()` and `or()` combiners. These make precedence explicit and produce correctly parenthesized SurrealQL:

```typescript illustrative
import { orm, table, t, and, or } from "surqlize";

// Simple compound: age >= 18 AND email ends with @example.com
db.select("user").where((user) =>
  and(user.age.gte(18), user.email.endsWith("@example.com"))
);
// WHERE (age >= 18 AND string::ends_with(email, "@example.com"))

// OR with multiple options
db.select("user").where((user) =>
  or(user.role.eq("admin"), user.role.eq("moderator"), user.role.eq("owner"))
);
// WHERE (role = "admin" OR role = "moderator" OR role = "owner")

// Nested: AND with inner OR for grouped conditions
db.select("user").where((user) =>
  and(
    user.age.gte(18),
    or(user.role.eq("admin"), user.role.eq("moderator")),
    user.email.endsWith("@example.com"),
  )
);
// WHERE (age >= 18 AND (role = "admin" OR role = "moderator") AND string::ends_with(email, "@example.com"))

// Chaining .and() / .or() on individual conditions also works
db.select("user").where((user) =>
  user.age.gte(18).and(user.name.first.eq("Alice"))
);
// WHERE (age >= 18 AND name.first = "Alice")
```

Both `and()` and `or()` require at least two conditions and accept any number of additional conditions. Nesting them produces correctly parenthesized output, so precedence is always explicit.

### Chaining `where()` calls

Chained `.where()` calls AND together: each one narrows the rows the earlier ones kept. Callbacks and [object filters](#object-based-filters-and-sorting) can be mixed freely. This holds for `select`, `update`, `delete`, `live` and `upsert`, and for the edge filter of a traversal segment (`g("authored").where(...).where(...)`, where `clearWhere()` drops the filter).

```typescript
db.select("user")
  .where((user) => user.age.gte(18))
  .where({ email: { endsWith: "@example.com" } });
// WHERE ($this.age >= 18 AND string::ends_with($this.email, "@example.com"))
```

An object filter with no condition, such as `where({})`, or one whose values are all `undefined`, adds nothing, so the filter already on the query stays. To remove every condition set so far, call `clearWhere()`:

```typescript
const adults = db.select("user").where((user) => user.age.gte(18));

adults.where({ name: undefined }); // still WHERE $this.age >= 18
adults.clearWhere();               // no WHERE clause at all
```

### Object-based filters and sorting

`where()` and `orderBy()` also accept plain objects, which is convenient when filters come from data (a query string, a form, a JSON body) rather than code. Both compile to exactly the same SurrealQL as the fluent callbacks. The objects are fully type-checked against your schema.

```typescript illustrative
const rows = await db.select("user")
  .where({
    name: { first: "Ada" },            // nested object field: name.first = "Ada"
    email: { endsWith: "@example.com" },
    age: { gte: 18, lt: 65 },          // several operators on a field are AND-ed
    role: "admin",                     // a bare value is shorthand for { eq: value }
  })
  .orderBy({ age: "desc", name: { last: "asc" } })
  .limit(20);
```

Keys at the same level are AND-ed together. Combine groups with `and`, `or` and `not`:

```typescript
db.select("user").where({
  or: [{ role: "admin" }, { age: { gt: 65 } }],
  not: { status: "banned" },
});
// WHERE ((role = "admin" OR age > 65) AND !(status = "banned"))
```

Available operators mirror the fluent methods: `eq`, `ne`, `ex`, `gt`, `gte`, `lt`, `lte`, `inside`, `notInside` on every field; `startsWith`, `endsWith`, `contains`, `search` on strings; and `contains`, `containsNot`, `containsAll`, `containsAny`, `containsNone`, `allInside`, `anyInside`, `noneInside` on arrays.

Fields of an object, and fields of a record link, can be filtered or sorted by in place (`author: { age: { gt: 30 } }`, `orderBy({ author: { name: "asc" } })`).

Notes:

- A field whose value is `undefined` is skipped, and an object that imposes no condition (including empty `and` / `or` groups) adds no condition, so optional parameters can be passed straight through. A `where()` with no condition leaves the filter from earlier calls in place (see [Chaining `where()` calls](#chaining-where-calls)).
- A key that names a field always wins over an operator or combinator of the same name.
- Unknown fields, unsupported operators and invalid directions throw an `OrmError` (and are rejected by the type checker).
- Directions are `"asc"` / `"desc"` (upper case also works) and are applied in key order. `orderByNumeric` and `orderByCollate` remain fluent-only and chain after an object `orderBy`.
- Object filters are also accepted by `.where()` on `update`, `delete` and `live` queries (`upsert` takes the callback form only).

## Type-specific functions

### String functions

```typescript illustrative
db.select("user").where((user) =>
  user.bio.search("typescript")
  user.email.startsWith("admin@")
  user.name.endsWith("son")
  user.email.contains("@example.com")
  user.email.isEmail()
);

db.select("user").return((user) => ({
  fullName: user.firstName.join(" ", user.lastName),
  nameLength: user.name.len(),
  upper: user.name.uppercase(),
  lower: user.email.lowercase(),
  trimmed: user.name.trim(),
  slug: user.name.slug(),
  words: user.name.words(),
  reversed: user.name.reverse(),
  replaced: user.email.replace("@old.com", "@new.com"),
  parts: user.email.split("@"),
}));
```

Additional string functions include `capitalize`, `repeat`, `slice`, `matches`, distance functions (`distanceLevenshtein`, `distanceHamming`, etc.), HTML functions (`htmlEncode`, `htmlSanitize`), validation (`isUrl`, `isDomain`, `isUuid`, etc.), semver operations, and similarity scoring.

### Array functions

```typescript illustrative
db.select("user").where((user) =>
  // Single element checks
  user.tags.contains("typescript")          // Array contains element
  user.tags.containsNot("java")             // Array doesn't contain element
  
  // Multiple element checks
  user.tags.containsAll(["javascript", "typescript"]) // Contains all elements
  user.tags.containsAny(["rust", "go", "python"])     // Contains any element
  user.tags.containsNone(["php", "perl"])             // Contains none of elements
  
  // Inside checks (array subset operations)
  user.tags.allInside(allowedTags)   // All elements are in allowedTags
  user.tags.anyInside(popularTags)   // Any element is in popularTags
  user.tags.noneInside(bannedTags)   // No elements are in bannedTags
  
  // Empty check
  user.tags.isEmpty()                // Array is empty
);

db.select("post").return((post) => ({
  title: post.title,
  firstTag: post.tags.at(0),      // Get element at index
  tagCount: post.tags.len(),       // Array length
  first: post.tags.first(),        // First element
  last: post.tags.last(),          // Last element
  sorted: post.tags.sort(),        // Sort array
  unique: post.tags.distinct(),    // Unique values
  flat: post.tags.flatten(),       // Flatten nested arrays
  reversed: post.tags.reverse(),   // Reverse array
  map: post.tags.map((tag, index) => tag.uppercase()) // Map array
}));
```

Additional array functions include mutation (`add`, `append`, `prepend`, `push`, `pop`, `insert`, `remove`, `fill`, `swap`), set operations (`combine`, `complement`, `concat`, `difference`, `intersect`, `union`, `transpose`), boolean operations (`booleanAnd`, `booleanOr`, `logicalAnd`, etc.), and search functions (`findIndex`, `filterIndex`, `max`, `min`).

### Number functions

```typescript
db.select("user").return((user) => ({
  absAge: user.age.abs(),
  rounded: user.age.round(),
  ceiling: user.age.ceil(),
  floored: user.age.floor(),
  squareRoot: user.age.sqrt(),
  squared: user.age.pow(2),
  fixed: user.age.fixed(2),
  clamped: user.age.clamp(0, 100),
  radians: user.age.deg2rad(),
  sine: user.age.sin(),
  cosine: user.age.cos(),
  naturalLog: user.age.ln(),
  log10: user.age.log10(),
}));
```

Additional number functions include `tan`, `cot`, `acos`, `asin`, `atan`, `acot`, `log`, `log2`, `rad2deg`, `sign`, `lerp`, `lerpangle`.

### Date functions

```typescript
db.select("user").return((user) => ({
  year: user.created.year(),
  month: user.created.month(),
  day: user.created.day(),
  hour: user.created.hour(),
  minute: user.created.minute(),
  second: user.created.second(),
  weekDay: user.created.wday(),
  dayOfYear: user.created.yday(),
  unix: user.created.unix(),
  millis: user.created.millis(),
  formatted: user.created.format("%Y-%m-%d"),
  isLeap: user.created.isLeapYear(),
}));
```

Additional date functions include `week`, `micros`, `nano`, and rounding functions (`timeCeil`, `timeFloor`, `timeRound`).

### Option functions

When working with optional values (created with `t.option()`), you can use `map()` to transform the value if it exists:

```typescript
import { t, table } from "surqlize";
const user = table("user", {
  name: t.string(),
  bio: t.option(t.string()),
});

db.select("user").return((user) => ({
  name: user.name,
  // Transform bio to uppercase if it exists (NONE otherwise)
  bioUpper: user.bio.map((b) => b.uppercase()),
  // Chain multiple operations
  bioLength: user.bio.map((b) => b.len()),
}));
```

### Record functions

When you have a record reference, you can perform nested queries:

```typescript
import { t, table } from "surqlize";
const post = table("post", {
  title: t.string(),
  authorId: t.record("user"),
});

// Nested query with .select()
const query = db.select("post").return((post) => ({
  title: post.title,
  author: post.authorId.select().return((author) => ({
    name: author.name,
    email: author.email,
  })),
}));

// TypeScript infers the complete nested type!
type Result = t.infer<typeof query>;
// Result: Array<{
//   title: string;
//   author: { name: string; email: string }[];
// }>
```

## Geospatial points

```typescript
import { GeometryPoint, Surreal } from "surrealdb";
import { geo, orm, table, t, type_ } from "surqlize";

const place = table("place", {
  location: t.point(),
  coordinates: t.array([t.number(), t.number()]),
});
const db = orm(new Surreal(), place);

const center = new GeometryPoint([12.5, 41.9]);
const nearby = db.select("place").where((place) =>
  geo.distance(place.location, center).lt(5000),
);
const nearbyByCoordinates = db.select("place").where((place) =>
  geo.distance(place.coordinates, [12.5, 41.9]).lt(5000),
);
```

`t.point()` describes a native SurrealDB point value. For raw coordinate data,
use `t.array([t.number(), t.number()])`. `type_.point(value)` explicitly emits
`type::point(value)`, while `geo.distance()` automatically accepts a
`GeometryPoint` or `[longitude, latitude]` and performs required coordinate
casts in SurrealDB. Distances are returned by SurrealDB in metres. Coordinates
are always ordered longitude first, latitude second.

## Standalone functions

Standalone functions are not called on a field but used independently within query callbacks. Functions with value parameters extract the query context automatically from the first value. Zero-arg functions and constants require an explicit context source (any `Workable` from the callback).

```typescript
import { count, math, time, crypto, rand, parse } from "surqlize";

// Count and aggregation
db.select("user")
  .groupAll()
  .return((user) => ({
    total: count(user),
    adults: count(user, user.age.gte(18)),
    avgAge: math.mean(user.age),
    totalAge: math.sum(user.age),
    maxAge: math.max(user.age),
  }));

// Time and crypto
db.select("user").return((user) => ({
  now: time.now(user),
  emailHash: crypto.sha256(user.email),
  randomId: rand.uuid(user),
  emailDomain: parse.emailHost(user.email),
}));

// Math constants (zero-arg, need context source)
db.select("user").return((user) => ({
  pi: math.pi(user),
  e: math.e(user),
  tau: math.tau(user),
}));
```

Available standalone function families: `count`, `math` (aggregation + constants), `time`, `crypto`, `rand`, `duration`, `type_`, `encoding`, `geo`, `http`, `meta`, `object`, `parse`, `search`, `session`, `set_`, `sleep`, `value`, `vector`, `bytes`, `not`.

Two details of the search and vector families:

- **Full-text match references.** `search.score()`, `search.highlight()` and `search.offsets()` read a match by its numbered reference. Pass the same N to `.search(value, N)` in the same query, which renders `@N@`. Without a number, `.search(value)` renders `@@`, and several unnumbered matches in one query cannot be told apart. Use numbers whenever more than one match needs its own score.

  ```typescript
  db.select("post")
    .where((post) => post.title.search("hello", 1))
    .return((post) => ({
      score: search.score(post.title, 1),
      marked: search.highlight(post.title, "<b>", "</b>", 1),
    }));
  ```

- **Vector literals.** A plain number array can be passed to a `vector` function beside a field or other expression, so `vector.similarityCosine(post.embedding, [1, 0, 0])` needs no `db.value()`. Single-operand functions (`magnitude`, `normalize`), and calls whose operands are all plain arrays, still need `db.value([...])`, because there is no field to take the query context from.

## Advanced Features

### Return Clauses

Control what gets returned from mutations:

```typescript
// Return nothing
await db.update("user", "alice").set({ age: 31 }).return("none");

// Return state before modification
const before = await db.update("user", "alice")
  .set({ age: 31 })
  .return("before");

// Return state after modification (default)
const after = await db.update("user", "alice")
  .set({ age: 31 })
  .return("after");

// Return diff of changes
const diff = await db.update("user", "alice")
  .set({ age: 31 })
  .return("diff");

// Return specific fields with projection
const projection = await db.update("user", "alice")
  .set({ age: 31, email: "new@email.com" })
  .return((u) => ({ name: u.name, age: u.age }));
```

For a partial write, the projection can only read the fields the result is typed with (see [What a partial write returns](#what-a-partial-write-returns)).

### Query Timeouts

`.timeout()` adds the SurrealQL `TIMEOUT` clause, which the **server** enforces:

```typescript
const users = await db.select("user")
  .where((u) => u.age.gt(18))
  .timeout("5s");

await db.update("user", "alice")
  .set({ age: 31 })
  .timeout("10s");
```

To bound how long the **client** waits instead, see `.requestTimeout()` below.

### Cancellation, timeouts and retries

Every query, and every [batch](#batch), can be configured with how long and how hard the client waits for the answer. These options are applied by the SDK when the request is sent; they do not change the SurrealQL that is rendered.

```typescript
// Stop waiting when the signal aborts: the promise rejects with its reason
await db.select("report").signal(AbortSignal.timeout(2_000));

// Give up with a TimeoutError after 5s (0 waits without limit)
await db.select("report").requestTimeout(5_000);

// Re-send the query if it fails because of a transaction conflict
await db.update("counter", "visits").set({ n: { "+=": 1 } }).retry();
```

Like the other builder methods, they return a new query and leave the original untouched, and signals combine: calling `.signal()` twice abandons the query when either aborts.

> **Aborting means "stop waiting", and nothing more.** The server is not told, and may carry on. A write that was already sent may or may not have been applied. This holds for `.signal()` and for `.requestTimeout()`, which is not the same thing as the `TIMEOUT` clause above.

#### Retrying conflicts

When two transactions write to the same data, one of them fails with a conflict. `.retry()` re-sends the whole query, with exponential backoff, until it succeeds or the attempts run out. It defaults to the connection's retry settings; pass options to override them, or `false` to turn it off.

```typescript
await db.batch(
  db.update("account", "a").set({ balance: { "-=": 10 } }),
  db.update("account", "b").set({ balance: { "+=": 10 } }),
).retry({ attempts: 5 });
```

Only re-send what is safe to replay: a single statement, or a [batch](#batch), which is applied atomically. Do not use it inside an interactive transaction, where a conflict has already failed the transaction.

SurrealDB 3.1.0 and later report a conflict as a structured error, which is what `.retry()` recognises. For earlier servers, give it a predicate:

```typescript illustrative
.retry({
  retryable: (error) =>
    error instanceof Error && /conflict|can be retried/i.test(error.message),
})
```

#### Tying a request to its signal

In a request handler, `db.withSignal(signal)` returns a view of the ORM in which **every** query is abandoned when the signal aborts, so you don't pass it to each call. It shares the connection and session, so it is cheap to make one per request:

```typescript illustrative
export default {
  async fetch(request: Request) {
    const scoped = db.withSignal(request.signal);

    const users = await scoped.select("user");
    await scoped.batch(
      scoped.create("audit").set({ action: "list" }),
    );

    // A live subscription made through the scope is killed when the
    // request is aborted, so it cannot outlive its client.
    const changes = await scoped.live("user");

    return Response.json(users);
  },
};
```

### Vector search (KNN)

Fields declared as `t.array(t.number())` are vectors, and expose `.knn()`, which renders SurrealQL's KNN operator `<|k,…|>`. It composes with `.where()` like any other condition:

```typescript illustrative
import { vector } from "surqlize";

const doc = table("doc", {
  title: t.string(),
  embedding: t.array(t.number()),
});

// Brute force over a metric: the k nearest rows, nearest first
const nearest = db.select("doc")
  .where(d => d.embedding.knn(query, 5, { metric: "COSINE" }))
  .orderBy(d => vector.distanceKnn(d), "ASC");

// Through an HNSW index (or DiskANN with its L value): the search width ef
const approx = db.select("doc")
  .where(d => d.embedding.knn(query, 5, { ef: 40 }));
```

- `query` is a `number[]` or any expression of the same type. It is sent as a bound parameter.
- `k` must be a positive integer. The metric is one of `"EUCLIDEAN"`, `"COSINE"`, `"MANHATTAN"` or `"CHEBYSHEV"`; `ef` must be a positive integer. Anything else throws an `OrmError` before the query is sent, since these values are written into the query text.
- A metric and an `ef` are both required: SurrealQL has no bare `<|k|>` form (SurrealDB 3.2 rejects it).
- `knn()` exists only on `array<number>` fields. Calling it on another type is a compile-time error.
- The HNSW form needs an index on the field, for example `DEFINE INDEX doc_embedding ON doc FIELDS embedding HNSW DIMENSION 3 DIST EUCLIDEAN`. Define it yourself; the library does not create indexes.
- The distance the operator computed is available as `vector.distanceKnn(row)`, which renders `vector::distance::knn()`. It is only meaningful in a query that has a `knn()` predicate, and it can be used in `.return()` and in `.orderBy()`.
- `knn()` is a predicate. Using it as a value in `.return()` is not supported.

Other conditions combine with it through `and()`, as usual. SurrealDB decides how they interact with the `k` nearest rows, so do not assume exactly `k` rows come back when a second condition is present.

### Operators

Use operators for atomic operations:

```typescript
// Increment/decrement numbers
db.update("user", "alice").set({
  age: { "+=": 1 },
  score: { "-=": 10 },
});

// Add/remove from arrays
db.update("post", "post1").set({
  tags: { "+=": ["typescript", "database"] },
  oldTags: { "-=": ["deprecated"] },
});
```

## Type inference

Extract TypeScript types from your queries using `t.infer<>`:

```typescript
import { t, table } from "surqlize";
// Infer query result type
const query = db.select("user").return((user) => ({
  name: user.name,
  age: user.age,
}));

type QueryResult = t.infer<typeof query>;
// QueryResult: Array<{ name: string; age: number }>

// Infer table row type
const userTable = table("user", {
  name: t.string(),
  age: t.number(),
});

type User = (typeof userTable)["type"];
// User: { id: RecordId<"user">; name: string; age: number }

// Infer individual type definitions
const emailType = t.string();
type Email = t.infer<typeof emailType>;
// Email: string
```

## Debugging Queries

Inspect generated SurrealQL:

```typescript
import { displayContext, __display } from "surqlize";

const query = db.select("user").where((u) => u.age.gte(18));

const ctx = displayContext();
const sql = query[__display](ctx);

console.log(sql);           // Generated SurrealQL
console.log(ctx.variables); // Parameterized values
```

## Graph traversal

Traverse graph edges directly inside queries. Call `.out()` on a select row to
follow an edge (`->edge`), or `.in()` to follow it in reverse (`<-edge`). A step
lands on the edge records, so reach the record at the far end with a second step:
`.out("edge").out("target")` (`->edge->target`), or `.in("edge").in("source")`
(`<-edge<-source`). TypeScript only permits edges that actually connect to the
current table, and the result type is inferred automatically.

You can traverse from the row itself (`user.out("authored")`, rooted at the
row's `id`) or from any record-link field (`post.author.out(...)`).

```typescript
import { edge, orm, t, table } from "surqlize";
import { Surreal } from "surrealdb";
const user = table("user", { name: t.string() });
const post = table("post", { title: t.string() });
const tag = table("tag", { label: t.string() });
const authored = edge("user", "authored", "post", {
  created: t.date(),
  role: t.string(),
});
const tagged = edge("post", "tagged", "tag", {});

const db = orm(new Surreal(), user, post, tag, authored, tagged);
```

### Materialising records with `.select()`

Chain `.select().return()` to project the records a traversal lands on. The
traversal compiles to a subquery:

```typescript
const usersWithPosts = db.select("user").return((user) => ({
  name: user.name,
  posts: user
    .out("authored")              // -> the authored edge records
    .out("post")                  // -> post
    .select()
    .return((post) => ({ title: post.title })),
}));
// posts is typed as { title: string }[]
```

### Bare traversals return record links

Used directly in a projection, a traversal yields an array of record links —
exactly like raw SurrealQL `->authored->post`:

```typescript
import { t } from "surqlize";
const query = db.select("user").return((user) => ({
  postIds: user.out("authored").out("post"),
}));

type Result = t.infer<typeof query>;
// Result: Array<{ postIds: RecordId<"post">[] }>
```

### Multi-hop chaining

Steps chain, with every hop re-typed against the table it lands on:

```typescript
db.select("user").return((user) => ({
  tags: user
    .out("authored")   // -> the authored edge records
    .out("post")       // -> post
    .out("tagged")     // -> the tagged edge records
    .out("tag")        // -> tag
    .select()
    .return((tag) => ({ label: tag.label })),
}));
// ->authored->post->tagged->tag
```

### Incoming edges

```typescript
// Who authored this post?
db.select("post").return((post) => ({
  authors: post
    .in("authored")               // <- the authored edge records
    .in("user")                   // <- user
    .select()
    .return((user) => ({ name: user.name })),
}));
```

### Reading edge fields

Edges are tables too, so to read an edge's own fields (such as `created` or
`role`) select the edge table directly. `.in` / `.out` give you its endpoints:

```typescript
db.select("authored").return((e) => ({
  when: e.created,
  role: e.role,
  author: e.in, // the user
  post: e.out, // the post
}));
// SELECT created, role, in, out FROM authored
```

### Filtering traversals

Filter on the edge mid-traversal by passing a callback to `.out()` / `.in()`.
It receives a segment factory `g` bound to the current step: build the edge
segment and add a `.where()` whose callback receives the edge's fields. The step
compiles to `->(edge WHERE …)`, and the following step reaches the target
(`->(edge WHERE …)->target`):

```typescript
db.select("user").return((user) => ({
  posts: user
    .out((g) => g("authored").where((e) => e.role.eq("author")))
    .out("post")
    .select()
    .return((post) => ({ title: post.title })),
}));
// ->(authored WHERE role = "author")->post
```

Plain edge names and filter callbacks are just alternatives for the step, so they
mix in one call — `user.out("a", (g) => g("b").where(...))` compiles to
`->(a, b WHERE …)`.

Traversals also compose inside `WHERE` to filter the outer query. `len()` and
`isEmpty()` are the idiomatic "has any" / "has none" checks:

```typescript
// Users who have authored at least one post
db.select("user").where((user) => user.out("authored").len().gt(0));

// Users who have authored none
db.select("user").where((user) => user.out("authored").isEmpty());
```

### Recursive traversal

Follow a step repeatedly with `recurse`, `collect` and `shortest` (SurrealQL
recursive paths, `.{min..max}(…)`). The repeated step is a callback that receives
the node being expanded and must land back on the **same table**, so every
iteration is typed against one record type. They work on a select row
(`person.recurse(…)`, rooted at its `id`) or on any record link.

```typescript
import { edge, orm, t, table } from "surqlize";
import { Surreal } from "surrealdb";
const person = table("person", { name: t.string() });
const knows = edge("person", "knows", "person", { since: t.number() });
const db = orm(new Surreal(), person, knows);

```

#### Depth ranges: `recurse(depth, step)`

`depth` is a fixed count or a `{ min?, max? }` range (inclusive integers,
`1..256`). A fixed depth returns the nodes exactly that many hops away; a range
returns the nodes at the deepest level reached.

```typescript
db.select("person").return((p) => ({
  // .{2}(->knows->person)
  friendsOfFriends: p.recurse(2, (n) => n.out("knows").out("person")),
  // .{2..4}(…)
  between: p.recurse({ min: 2, max: 4 }, (n) => n.out("knows").out("person")),
  // .{2..}(…)
  atLeast: p.recurse({ min: 2 }, (n) => n.out("knows").out("person")),
  // .{..3}(…)
  atMost: p.recurse({ max: 3 }, (n) => n.out("knows").out("person")),
}));
// each field: RecordId<"person">[]
```

Without a bound, a range on a graph that contains cycles does not terminate in a
useful time. Bound it, or use `collect`.

#### Flattened unique nodes: `collect([depth,] step, { inclusive? })`

`collect` returns every distinct node reached within the depth, nearest first.
It is cycle-safe, so the depth is optional (`{..+collect}`). `inclusive: true`
adds the starting record (`+inclusive`).

```typescript
db.select("person").return((p) => ({
  // .{..+collect}(…)
  network: p.collect((n) => n.out("knows").out("person")),
  // .{..2+collect}(…)
  nearby: p.collect({ max: 2 }, (n) => n.out("knows").out("person")),
  nearbyAndMe: p.collect({ max: 2 }, (n) => n.out("knows").out("person"), { inclusive: true }),
  // Materialise the nodes like any other traversal:
  names: p
    .collect({ max: 2 }, (n) => n.out("knows").out("person"))
    .select()
    .return((f) => ({ name: f.name })),
}));
```

#### Shortest path: `shortest(target, step, { inclusive? })`

`shortest` returns the nodes walked from the start to `target` (the start itself
is only included with `inclusive: true`). The target is bound as a query
parameter. When there is no path, SurrealDB returns `NONE`, so the result is
typed `RecordId<"person">[] | undefined`. Use `.unwrap()` to materialise it:

```typescript
import { RecordId } from "surrealdb";
const route = await db
  .select("person", "alice")
  .return((p) => ({
    // RecordId[] | undefined
    path: p.shortest(new RecordId("person", "dave"), (n) => n.out("knows").out("person")),
    pathNames: p
      .shortest(new RecordId("person", "dave"), (n) => n.out("knows").out("person"))
      .unwrap()
      .select()
      .return((n) => ({ name: n.name })),
  }))
  .execute();
```

Edge filters and multi-edge steps work inside the step, e.g.
`(n) => n.out((g) => g("knows").where((e) => e.since.gte(2015))).out("person")`.
Because the step is typed against the table it starts from, stepping onto a
different table (`n.out("wrote").out("post")`) is a compile error.

Notes and limits:

- Recursive paths need SurrealDB 2.1 or newer; the CI matrix (3.0.5 to 3.3.0) is
  covered by the integration tests.
- `shortest` is unbounded. If the target is the start record itself, the result
  is `NONE` unless a cycle leads back to it, in which case the result is the walk
  around that cycle.
- `+path` (every walked path) is not exposed yet.
- On SurrealDB 3.0, a fixed-depth `collect(n, step)` (`{n+collect}`) returned only
  the nodes first reached at depth `n`, where 3.1 and newer return every node
  `n` hops away (observed on 3.0.5). Use a range or `recurse(n, step)` if you
  need the same answer on 3.0.

### Edge adjacency metadata

The `lookup` maps expose which edges connect which tables at runtime:

```typescript
db.lookup.to;   // { user: ["authored"], post: ["tagged"], tag: [], ... }
db.lookup.from; // { post: ["authored"], tag: ["tagged"], user: [], ... }
```

## Complex example

Here's a complete example showcasing multiple features:

```typescript
import { edge, orm, t, table } from "surqlize";
import { Surreal } from "surrealdb";
const user = table("user", {
  name: t.object({
    first: t.string(),
    last: t.string(),
  }),
  age: t.number(),
  email: t.string(),
  tags: t.array(t.string()),
  bio: t.option(t.string()),
});

const post = table("post", {
  title: t.string(),
  content: t.string(),
  authorId: t.record("user"),
  created: t.date(),
});

const authored = edge("user", "authored", "post", {
  created: t.date(),
});

const db = orm(new Surreal(), user, post, authored);

// Complex query with nested data and string operations
const query = db
  .select("post")
  .where((post) => 
    post.title.startsWith("Guide").and(
      post.created.gte(new Date("2024-01-01"))
    )
  )
  .return((post) => ({
    title: post.title,
    author: post.authorId.select().return((author) => ({
      fullName: author.name.first.join(" ", author.name.last),
      age: author.age,
      hasBio: author.bio.trueish(),
    })),
  }))
  .orderBy("created", "DESC")
  .limit(10);

// Fully typed result
type Result = t.infer<typeof query>;

// Fetch resolves record references into full objects
const posts = await db
  .select("post")
  .fetch("authorId")
  .execute();
// posts[0].authorId is now the full user object, not a RecordId
```

## Multi-session support

Surqlize accepts any `SurrealSession` (or `Surreal`, which extends it) — or the request scope that `withSignal()` returns — enabling multiple ORM instances scoped to different sessions over a single connection. Each session maintains its own namespace, database, authentication state, and variables.

### Multiple databases over one connection

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

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

const surreal = new Surreal();
await surreal.connect("ws://localhost:8000");
await surreal.signin({ username: "root", password: "root" });

// Create separate sessions for different tenants
const tenantA = await surreal.newSession();
await tenantA.signin({ username: "root", password: "root" });
await tenantA.use({ namespace: "app", database: "tenant_a" });

const tenantB = await surreal.newSession();
await tenantB.signin({ username: "root", password: "root" });
await tenantB.use({ namespace: "app", database: "tenant_b" });

// Same schema, same connection, different databases
const dbA = orm(tenantA, user);
const dbB = orm(tenantB, user);

await dbA.create("user").set({ name: "Alice", age: 30 });
await dbB.create("user").set({ name: "Bob", age: 25 });
```

### Forking sessions

Use `forkSession()` to clone an existing session (inheriting its namespace, database, auth, and variables) and then diverge:

```typescript illustrative
const surreal = new Surreal();
await surreal.connect("ws://localhost:8000");
await surreal.signin({ username: "root", password: "root" });
await surreal.use({ namespace: "app", database: "main" });

// Fork inherits namespace, database, auth, and variables
const session = await surreal.forkSession();
await session.authenticate(userToken);

const db = orm(session, user);
const users = await db.select("user");

// Clean up when done
await session.closeSession();
```

### Disposable sessions

Since `SurrealSession` implements `Symbol.asyncDispose`, sessions work with `await using` for automatic cleanup:

```typescript illustrative
{
  await using session = await surreal.forkSession();
  await session.authenticate(userToken);

  const db = orm(session, user);
  const users = await db.select("user");
  // session automatically disposed when scope exits
}
```

### Connections and pooling

Surqlize does not open, own or pool connections: you hand it a `Surreal` (or a session), and the SurrealDB SDK owns the connection, including reconnecting. A pool is not needed for concurrency, because the SDK multiplexes concurrent queries over a single connection, so queries from many `orm()` calls or request handlers can be in flight at once. Use these instead:

- **One `Surreal` connection per process**, created at start-up and shared by every ORM instance.
- **A session per tenant or per request** (`newSession()` / `forkSession()`, above) when you need isolated namespace, database, authentication or variables. Sessions share the connection, so they are cheap to create and close.
- **`db.withSignal(signal)`** for per-request cancellation (see [Cancellation, timeouts and retries](#cancellation-timeouts-and-retries)).
- **`db.batch()` or a transaction** when several statements must run together.

Reach for several `Surreal` connections only when you want to spread load across servers or isolate failure domains, and manage them in your own code.

## Comparison with other ORMs

| Feature | Surqlize | SurrealDB.js | Prisma | Drizzle | TypeORM |
|---------|----------|--------------|--------|---------|---------|
| SurrealDB support | ✅ | ✅ | ❌ | ❌ | ❌ |
| Schema definition | ✅ <sup><sub>Code-first</sub></sup> | ❌ | ✅ <sup><sub>Schema file</sub></sup> | ✅ <sup><sub>Code-first</sub></sup> | ⚠️ <sup><sub>Decorators</sub></sup> |
| Type inference | ✅ <sup><sub>Full</sub></sup> | ⚠️ <sup><sub>Partial</sub></sup> | ✅ <sup><sub>With codegen</sub></sup> | ✅ <sup><sub>Full</sub></sup> | ⚠️ <sup><sub>Decorators</sub></sup> |
| CRUD operations | ✅ <sup><sub>All operations</sub></sup> | ✅ | ✅ | ✅ | ✅ |
| Graph and edges | ✅ <sup><sub>Native</sub></sup> | ✅ <sup><sub>Manual</sub></sup> | ❌ | ❌ | ❌ |
| Query builder | ✅ <sup><sub>Type-safe</sub></sup> | ⚠️ <sup><sub>Manual</sub></sup> | ⚠️ <sup><sub>Limited</sub></sup> | ✅ <sup><sub>Type-safe</sub></sup> | ✅ <sup><sub>Query builder</sub></sup> |
| Database Functions | ✅ <sup><sub>Integrated</sub></sup> | ⚠️ <sup><sub>Manual</sub></sup> | ⚠️ <sup><sub>Limited</sub></sup> | ✅ <sup><sub>SQL functions</sub></sup> | ✅ <sup><sub>Query functions</sub></sup> |
| Nested Queries | ✅ <sup><sub>Type-safe</sub></sup> | ⚠️ <sup><sub>Manual</sub></sup> | ✅ <sup><sub>Relations</sub></sup> | ✅ <sup><sub>Joins</sub></sup> | ✅ <sup><sub>Relations</sub></sup> |
| Fluent API | ✅ | ❌ | ❌ | ✅ | ✅ |

**Why Surqlize?**

- **Native SurrealDB support**: Built specifically for SurrealDB's unique features including graph relationships, flexible schemas, and SurrealQL
- **No code generation**: Full type inference using TypeScript's type system—no codegen required
- **Fluent API**: Natural, chainable syntax that mirrors SurrealQL while providing complete type safety
- **Graph-first**: Edges and relationships are first-class citizens, not an afterthought
- **Complete CRUD**: Full support for SELECT, CREATE, UPSERT, UPDATE, RELATE, and DELETE operations

## Roadmap

This project is in active development. Planned features include:

- [x] **SurrealDB functions** - All 25 built-in function families (string, array, math, time, crypto, rand, and more)
- [x] **Advanced query clauses** - ORDER BY, GROUP BY, FETCH, SPLIT
- [x] **Transaction support** - Batch and interactive transactions
- [x] **Multi-session support** - Multiple sessions over a single connection
- [x] **Live queries** - Real-time `LIVE SELECT` subscriptions with typed notifications
- [x] **Runtime validation** - Validate data at runtime using schema definitions
- [x] **Graph traversal** - Type-safe `.out()` / `.in()` edge navigation, multi-hop chaining, edge-field access, and edge filtering
- [x] **Advanced graph traversal** - Recursive depth ranges, node collection (`collect`), and shortest-path finding (`shortest`)
- [x] **Performance optimizations** - Faster query construction (see [Performance](#performance)); connection pooling is left to the SDK, with sessions for isolation (see [Connections and pooling](#connections-and-pooling))
- [x] **Schema migrations** - Declare the schema, diff it against the database, and converge
- [ ] **Documentation site** - Comprehensive guides and API reference

## Performance

Queries are built from immutable builders, and building and rendering one costs microseconds: a typical `select` with a `where`, `orderBy`, `fetch` and `return` builds and renders in about 10 µs, far below a network round trip. The library therefore does not cache rendered queries. To skip building altogether, build a query once and reuse it: builders are immutable, so a prebuilt query is safe to share and to execute repeatedly.

The benchmarks in `benchmarks/` need no database. Run them with `bun run bench` (optionally a name filter, e.g. `bun run bench select`, and `--json file` to save the results).

## Development

```bash
# Install dependencies
bun install

# Build the project
bun run build

# Run the example file
bun run examples/demo.ts

# Run tests
bun run test:unit          # Unit tests
bun run test:readme        # Type-check the TypeScript examples in this README
bun run test:integration   # Integration tests (requires SurrealDB)
bun run type-check         # TypeScript type checking
bun run bench              # Query construction benchmarks

# Lint and format
bun run qc   # Check for issues
bun run qa   # Auto-fix issues
bun run qau  # Auto-fix with unsafe changes
```

`test:readme` type-checks the TypeScript blocks in this README against the source.
A block marked `typescript illustrative` is a fragment and is not compiled. A block
marked `typescript known-bug` must fail to compile: once it compiles, the test fails
so that the marker is removed.

## Contributing

Contributions are welcome! The project is stabilizing toward a `1.0.0` release; the public API is largely settled, but minor breaking changes are still possible before then. If you'd like to contribute:

1. Open an issue to discuss your idea
2. Fork the repository
3. Create a feature branch
4. Submit a pull request

Please ensure your code passes the linting checks (`bun run qc`).

## License

Apache-2.0

---

**Built with ❤️ for the SurrealDB community**