Introduction

Documentation • GitHub • GitHub Discussions • Buy Me a Coffee

What’s UnrealORM?

UnrealORM is a modern, type-safe ORM for SurrealDB that gives you native SurrealDB power, full TypeScript safety, and zero abstraction—no decorators, no magic, just classes and functions. Designed for developers who want direct control, advanced schema features, and a frictionless experience.

Why UnrealORM? I created this package because I wanted something like it for my own projects. Building UnrealORM gave me the perfect excuse to spend more time crafting an even better, reusable solution for the community.

Note: UnrealORM is not at version 1.0 yet. While the API is stabilizing and major breaking changes are unlikely, please be aware that some changes may still occur before the 1.0 release.

Core Philosophy

UnrealORM aims to provide a powerful and intuitive way to interact with SurrealDB in TypeScript projects. Our goal is to leverage TypeScript’s type safety and developer ergonomics without abstracting away the underlying power and flexibility of SurrealDB. We believe in a “native first” approach, ensuring that you can always access SurrealDB’s full feature set.

Key Features

• Native First: Exposes SurrealDB’s native features and SurrealQL directly. No heavy abstractions.
• Type Safety: Comprehensive TypeScript types for SurrealDB features, tables, fields, and query results.
• Modern JavaScript: Designed with ESNext features and module systems in mind.
• Schema Definition: Intuitive API for defining tables, fields, indexes, and relationships that map directly to SurrealDB’s schema capabilities.
• Query Building (Lightweight): Supports direct SurrealQL with type-safe parameters.
• Developer Experience: Aims to make working with SurrealDB in TypeScript a pleasant and productive experience.
• SurrealDB Feature Support: For a detailed breakdown of supported SurrealDB 2.x schema features, please see our CAPABILITIES.md document.

unreal-orm vs. surrealdb package

A direct comparison between unreal-orm and the official surrealdb Node.js driver:

	unreal-orm	surrealdb package
Type Safety	✅ Strong TypeScript types for models/queries	⚠️ Partial (manual, not enforced)
Schema Sync	✅ Models and schema stay in sync	❌ No schema management
Model Logic	✅ Add type-safe instance/static methods to models	❌ No model abstraction
Migrations	✅ Easy schema DDL/apply from code	❌ Manual DDL, risk of drift
Relations	✅ Fully typed, hydrated relations	⚠️ Supported, manual type-safety
Query Ergonomics	✅ Type-safe, object-oriented, and SurrealQL support	⚠️ Raw SurrealQL or data objects—not type-safe
Raw SurrealQL Support	✅ Use raw SurrealQL when needed	✅ Full SurrealQL access
Error Handling	✅ Native SurrealDB errors, no ORM wrappers	✅ Native SurrealDB errors

UnrealORM builds on top of the official surrealdb package, providing a modern TypeScript ORM experience while preserving full access to SurrealDB’s native features.

Installation

Install unreal-orm using your favorite package manager:

# Using pnpm
pnpm add unreal-orm surrealdb typescript

# Using npm
npm install unreal-orm surrealdb typescript

# Using yarn
yarn add unreal-orm surrealdb typescript

# Using bun
bun add unreal-orm surrealdb typescript

Note: surrealdb and typescript are peer dependencies.

Quick Start

1. Define a Model

import { Table, Field } from 'unreal-orm';

class User extends Table.normal({
  name: 'user',
  fields: {
    name: Field.string({ assert: '$value.length > 2' }),
    email: Field.string({ value: 'string::lowercase($value)' }),
    age: Field.option(Field.number()),
  }
}) {
  isAdult() {
    return (this.age ?? 0) >= 18;
  }
}

2. Create and Query Data

import { Surreal } from 'surrealdb';

async function main() {
  const db = new Surreal();
  await db.connect({ ... });
  await db.use({ ns: 'test', db: 'test' });

  // Create a user
  const user = await User.create(db, { name: 'Jane', email: 'Jane@Email.com', age: 30 });

  // Query users
  const users = await User.select(db);
  console.log(users[0].isAdult()); // true

  await db.close();
}
main();

See below for field patterns, relationships, schema generation, and advanced usage.

Field Patterns & Schema Generation

const User = Table.normal({
  name: 'user',
  fields: {
    name: Field.string({ assert: '$value.length > 2', comment: 'User name' }),
    tags: Field.array(Field.string(), { max: 10 }),
    posts: Field.array(Field.record((): any => Post)),
    createdAt: Field.datetime({ value: 'time::now()' }),
    customField: Field.custom<number>('duration'),
  }
});

// Generate and apply schema
import { applySchema, generateTableSchemaQl } from 'unreal-orm';
// Generate
const ddl = generateTableSchemaQl(User);
// Or automatically generate & apply
await applySchema(db, [User, Post]);

See Capabilities for all supported field options, validation, and SurrealDB mappings.

Documentation

For more detailed information, API reference, and advanced usage, visit the UnrealORM documentation.

• Getting Started
• Capabilities
• Contributing Guide
• Design Principles
• API Reference

Contributing

We welcome contributions of all kinds!
Please read our Contributing Guide for how to get started, coding standards, and guidelines.

If you have questions, ideas, or want to discuss improvements, join our GitHub Discussions.

Author & Support

unreal-orm is created and maintained by Jimpex.

If you find this project useful, please consider:

• ⭐ Starring the repository on GitHub
• ☕ Supporting the development via Ko-fi

Your support helps keep this project active and improving!

Community & Help

• 💬 Questions or Ideas? Join the conversation on our GitHub Discussions
• 🐛 Found a bug? Open an issue
• 🤝 Want to contribute? See our Contributing Guidelines
• 💡 Feature requests and feedback are welcome!
• 📣 Share your story or project! Post in Discussions, ping @jimpex on SurrealDB’s Discord, or email: contact@jimpex.dev

License

This project is licensed under the ISC License.