Unreal

const Unreal: object

Defined in: unreal.ts:65

The Unreal namespace provides a unified API for:

• Configuration: Database connection setup
• Schema: DDL generation and application
• AST: Schema parsing, comparison, and migration

Type Declaration

applySchema()

applySchema: (db, definables, method) => Promise<void>

Apply schema definitions to the database. Creates/updates tables, fields, and indexes.

Generates and applies the full SurrealQL schema to a SurrealDB instance.

Parameters

db

Surreal

The SurrealDB instance to apply the schema to.

definables

Definable[]

An array of Definable entities (model classes and index definitions).

method

The method to use for schema application if a table already exists.

"IF NOT EXISTS" | "OVERWRITE" | "error"

Returns

Promise<void>

Example

await Unreal.applySchema(db, [User, Post, idx_user_email]);

ast

readonly ast: object

AST utilities for schema parsing, comparison, and migration.

ast.areEqual()

readonly areEqual: (source, target) => boolean = schemasAreEqual

Check if two schemas are equal.

Checks if two schemas are identical (no changes).

Parameters

source

SchemaAST

First schema

target

SchemaAST

Second schema

Returns

boolean

true if schemas are semantically identical

ast.compare()

readonly compare: (source, target, isPush) => SchemaChange[] = compareSchemas

Compare two schemas and return the differences.

Compares two SchemaAST objects and returns structured changes. This enables semantic diffing instead of string comparison.

Parameters

source

SchemaAST

The “source of truth” schema (what we want to apply)

target

SchemaAST

The “target” schema (what currently exists)

isPush

boolean = false

If true, source=code, target=database (pushing code to DB) If false, source=database, target=code (pulling DB to code)

Returns

SchemaChange[]

Array of schema changes

Example

const codeSchema = extractSchemaFromDefinables([User, Post]);
const dbSchema = await introspectDatabase(db);

// Find what needs to change in DB to match code
const changes = compareSchemas(codeSchema, dbSchema, true);

// Find what needs to change in code to match DB
const changes = compareSchemas(dbSchema, codeSchema, false);

ast.extractIndex()

readonly extractIndex: (indexDef) => object = extractIndexFromDefinition

Extract IndexAST from an index definition.

Extracts an IndexAST from a runtime index definition.

Parameters

indexDef

IndexDefinition

The index definition to extract from

Returns

object

Object containing the IndexAST and associated table name

index

index: IndexAST

tableName

tableName: string

Example

const { index, tableName } = extractIndexFromDefinition(emailIndex);
// { index: { name: "email_idx", columns: ["email"], unique: true }, tableName: "user" }

ast.extractSchema()

readonly extractSchema: (definables) => SchemaAST = extractSchemaFromDefinables

Extract SchemaAST from model classes and index definitions.

Extracts a complete SchemaAST from an array of definables (models and indexes).

Parameters

definables

Definable[]

Array of model classes and index definitions

Returns

SchemaAST

Complete SchemaAST

Example

import { User, Post, emailIndex } from "./tables";

const schema = extractSchemaFromDefinables([User, Post, emailIndex]);
// { tables: [{ name: "user", ... }, { name: "post", ... }] }

ast.extractTable()

readonly extractTable: (modelClass) => TableAST = extractTableFromModel

Extract TableAST from a model class.

Extracts a TableAST from a runtime model class.

Parameters

modelClass

AnyModelClass

The model class to extract from

Returns

TableAST

Complete TableAST (indexes populated separately)

Example

const tableAST = extractTableFromModel(User);
// { name: "user", type: "NORMAL", fields: [...], ... }

ast.extractTableName()

extractTableName: (ql) => string | undefined

Extract table name from a DEFINE TABLE statement.

Extracts the table name from a DEFINE FIELD or DEFINE INDEX statement.

Parameters

ql

string

The raw SurrealQL statement

Returns

string | undefined

The table name or undefined

ast.filterByType()

readonly filterByType: (changes, types) => SchemaChange[] = filterChangesByType

Filter changes by type (added, removed, modified).

Filters changes to only include specific types.

Parameters

changes

SchemaChange[]

Array of schema changes

types

ChangeType[]

Change types to include

Returns

SchemaChange[]

Filtered array of changes

ast.generateMigration()

readonly generateMigration: (changes, schema?) => string = generateMigrationSurql

Generate migration SurrealQL from schema changes.

Generates only the DEFINE/REMOVE statements needed for specific changes. This is used for generating migrations from schema diffs.

Parameters

changes

SchemaChange[]

Array of schema changes from compareSchemas

schema?

SchemaAST

Optional source schema for full table definitions

Returns

string

SurrealQL migration statements

Example

const changes = compareSchemas(codeSchema, dbSchema, true);
const migration = generateMigrationSurql(changes, codeSchema);
await db.query(migration);

ast.generateSurql()

readonly generateSurql: (schema, method) => string = generateSurqlFromAST

Generate SurrealQL from SchemaAST.

Generates a complete SurrealQL schema from SchemaAST.

Parameters

schema

SchemaAST

The schema AST

method

SchemaApplicationMethod = "error"

Schema application method

Returns

string

Complete SurrealQL schema as a string

Example

const schema = extractSchemaFromDefinables([User, Post]);
const sql = generateSurqlFromAST(schema, "OVERWRITE");
await db.query(sql);

ast.groupByTable()

readonly groupByTable: (changes) => Map<string, SchemaChange[]> = groupChangesByTable

Group schema changes by table name.

Groups schema changes by table for easier processing.

Parameters

changes

SchemaChange[]

Array of schema changes

Returns

Map<string, SchemaChange[]>

Map of table name to changes for that table

ast.isIndexDefinition()

isIndexDefinition: (value) => value is IndexDefinition

Check if a value is an index definition.

Type guard to check if a value is an index definition.

Parameters

value

unknown

Returns

value is IndexDefinition

ast.isModelClass()

isModelClass: (value) => value is AnyModelClass

Check if a value is a model class.

Type guard to check if a value is a model class.

Parameters

value

unknown

Returns

value is AnyModelClass

ast.parseField()

readonly parseField: (ql) => FieldAST = parseFieldDefinition

Parse a DEFINE FIELD statement into AST.

Parses a DEFINE FIELD statement into a FieldAST.

Parameters

ql

string

The raw SurrealQL DEFINE FIELD statement

Returns

FieldAST

Complete FieldAST

Example

const field = parseFieldDefinition("DEFINE FIELD email ON TABLE user TYPE string");
// { name: "email", type: "string", flex: false, ... }

ast.parseIndex()

readonly parseIndex: (ql) => IndexAST = parseIndexDefinition

Parse a DEFINE INDEX statement into AST.

Parses a DEFINE INDEX statement into an IndexAST.

Parameters

ql

string

The raw SurrealQL DEFINE INDEX statement

Returns

IndexAST

Complete IndexAST

Example

const index = parseIndexDefinition("DEFINE INDEX email_idx ON TABLE user FIELDS email UNIQUE");
// { name: "email_idx", columns: ["email"], unique: true }

ast.parseTable()

readonly parseTable: (ql) => Partial<TableAST> = parseTableDefinition

Parse a DEFINE TABLE statement into AST.

Parses a DEFINE TABLE statement into a partial TableAST.

Parameters

ql

string

The raw SurrealQL DEFINE TABLE statement

Returns

Partial<TableAST>

Partial TableAST (fields, indexes, events are populated separately)

Example

const table = parseTableDefinition("DEFINE TABLE user SCHEMAFULL");
// { name: "user", type: "NORMAL", schemafull: true, ... }

clearConfig()

clearConfig: () => void

Clear the global database configuration. Useful for testing or switching connections.

Clears the global database configuration. Useful for testing or when switching connections.

Returns

void

configure()

configure: (options) => void

Configure the global database connection. After calling this, ORM methods can be used without passing db explicitly.

Configures the global database connection for the ORM.

After calling configure(), you can use ORM methods without passing db:

// Before: always pass db
const users = await User.select(db, { limit: 10 });

// After: db is optional
const users = await User.select({ limit: 10 });

Parameters

options

ConfigureOptions

Configuration options

Returns

void

Example

// Option 1: Pass a pre-connected database
const db = new Surreal();
await db.connect("ws://localhost:8000");
configure({ database: db });

// Option 2: Use a factory function (lazy initialization)
configure({
  getDatabase: async () => {
    const db = new Surreal();
    await db.connect(process.env.SURREAL_URL);
    return db;
  }
});

Example

// With factory function (recommended)
Unreal.configure({ getDatabase: () => connectToDatabase() });

// With pre-connected instance
Unreal.configure({ database: db });

generateSchema()

readonly generateSchema: (definables, method) => string = generateFullSchemaQl

Generate full SurrealQL schema from definitions.

Generates the full SurrealQL schema for all provided definable entities (tables and indexes).

Parameters

definables

Definable[]

An array of Definable entities (model classes and index definitions).

method

The method to use for schema application if a table already exists.

"IF NOT EXISTS" | "OVERWRITE" | "error"

Returns

string

A string containing the complete SurrealQL schema.

Example

const ddl = Unreal.generateSchema([User, Post]);
console.log(ddl);
// DEFINE TABLE user SCHEMAFULL;
// DEFINE FIELD email ON user TYPE string;
// ...

getDatabase()

getDatabase: () => Promise<SurrealLike>

Get the configured database instance.

Gets the configured database instance. If a factory was provided, it will be called and the result cached.

Returns

Promise<SurrealLike>

The database instance

Throws

Error if no database is configured

Example

// In a custom model method
class User extends Table.normal(...) {
  async customMethod() {
    const db = await getDatabase();
    return db.query(surql`SELECT * FROM user WHERE active = true`);
  }
}

Throws

Error if no database is configured

hasDatabase()

hasDatabase: () => boolean

Check if a database is configured.

Checks if a database is configured (either directly or via factory).

Returns

boolean

true if a database is configured