Cookbook

Need a quick pattern without reading the whole tutorial? Grab a ready-made recipe below 👇

All snippets assume db is an active Surreal connection and models are already defined.

Pagination with start, limit, and orderBy

// Fetch the next page of posts ordered by newest first
const pageSize = 10;
const posts = await Post.select(db, {
  orderBy: [{ field: 'createdAt', order: 'desc' }],
  start: 20, // skip first 2 pages
  limit: pageSize,
});

Soft Delete (isDeleted flag)

class Post extends Table.normal({
  name: 'post',
  fields: {
    title: Field.string(),
    content: Field.string(),
    isDeleted: Field.bool({ default: surql`false` }),
  },
}) {
  // Convenience helpers
  async softDelete(db: Surreal) {
    return this.update(db, {
      data: { isDeleted: true },
      mode: 'merge',
    });
  }

  static async allActive(db: Surreal) {
    return this.select(db, { where: surql`isDeleted = false` });
  }
}

Enum Helper

// Authorised values enforced in SurrealDB
export const Roles = ['admin', 'editor', 'viewer'] as const;
export type Role = (typeof Roles)[number];

class User extends Table.normal({
  name: 'user',
  fields: {
    role: Field.custom<Role>('string', {
      assert: surql`$value INSIDE ["admin", "editor", "viewer"]`,
    }),
  },
}) {}

Patch Update with merge

// Partially update fields without replacing the whole record
await Post.update(db, 'post:123', {
  data: { content: 'Updated body' },
  mode: 'merge',
});

Parameterised Full-Text Search

await Post.select(db, {
  where: surql`title ~~ $q OR content ~~ $q`,
  vars: { q: '*orm*' },
});

Type-Safe Select (Field Projection)

Select specific fields with full type inference:

import { typed } from 'unreal-orm';

// Select specific fields - return type is inferred
const posts = await Post.select(db, {
  select: { title: true, author: { name: true, email: true } },
});
// Type: { title: string; author: { name: string; email: string } }[]

// Computed fields with typed() helper
const posts = await Post.select(db, {
  select: { title: true, commentCount: typed<number>(surql`count(<-comment)`) },
});
// Type: { title: string; commentCount: number }[]

// Type-safe omit - exclude fields from result
const users = await User.select(db, {
  omit: { password: true },
});
// Type: Omit<User, 'password'>[]

---

📖 Continue exploring the Tutorial or deep-dive into the API Reference.