@cleverbrush/orm

Quick Start

import knex from 'knex';
import { number, object, string, defineEntity, createDb } from '@cleverbrush/orm';

// 1. Define schema + entity
const UserSchema = object({
    id:    number().primaryKey(),
    email: string().hasColumnName('email_address'),
    name:  string(),
}).hasTableName('users');

const UserEntity = defineEntity(UserSchema);

// 2. Create the context
const db = createDb(
    knex({ client: 'pg', connection: process.env.DATABASE_URL }),
    { users: UserEntity }
);

// 3. Query
const alice = await db.users.find(1);

// 4. Insert / update (PK absent → INSERT, PK present → UPDATE)
const created = await db.users.save({ email: 'bob@example.com', name: 'Bob' });
const updated = await db.users.save({ id: 1, email: 'alice@example.com', name: 'Alice' });

Relations

Declare relations fluently on the entity. They are fully typed — .include() only accepts keys you have declared.

const TodoSchema = object({
    id:     number().primaryKey(),
    title:  string(),
    userId: number().hasColumnName('user_id'),
    author: object({ id: number().primaryKey(), name: string() })
                .hasTableName('users').optional(),
}).hasTableName('todos');

const TodoEntity = defineEntity(TodoSchema)
    .belongsTo(t => t.author, 'userId');

const UserEntity = defineEntity(UserSchema)
    .hasMany(t => t.todos, TodoEntity, 'userId');

const db = createDb(knex, { users: UserEntity, todos: TodoEntity });

// Eager-load the author
const todo = await db.todos
    .where(t => t.id, 42)
    .include(t => t.author)
    .first();
console.log(todo?.author?.name); // fully typed

// Save a whole graph in one transaction
const user = await db.users.save({
    name: 'Alice',
    todos: [{ title: 'Buy milk', completed: false, userId: 0 }],
});

Change Tracking

Enable tracking with { tracking: true }. The context maintains an identity map and flushes all dirty entries inside a single transaction on saveChanges().

const db = createDb(knex, { users: UserEntity }, { tracking: true });

// Load — entity enters the identity map as Unchanged.
const user = await db.users.find(1);

// Mutate normally — no special setter required.
user.name = 'Updated';

// All dirty entries are flushed in one transaction.
const { inserted, updated, deleted } = await db.saveChanges();

// Works with await using — throws PendingChangesError if not flushed.
async function handler() {
    await using db = createDb(knex, { users: UserEntity }, { tracking: true });
    const user = await db.users.find(1);
    user.name = 'Updated';
    await db.saveChanges();
}   // Symbol.asyncDispose fires here

Optimistic Concurrency (Row Versioning)

const OrderSchema = object({
    id:      number().primaryKey(),
    status:  string(),
    version: number().rowVersion(),   // auto-incremented on every UPDATE
}).hasTableName('orders');

const db = createDb(knex, { orders: OrderEntity }, { tracking: true });

const order = await db.orders.find(orderId);
order.status = 'shipped';

try {
    await db.saveChanges();
} catch (err) {
    if (err instanceof ConcurrencyError) {
        // Another process updated the row — reload and retry.
        await db.reload(order);
    }
}

Polymorphic Entities (STI / CTI)

Model discriminated unions with Single-Table Inheritance (one table, discriminator column) or Class-Table Inheritance (base table + per-variant extension tables).

// ── STI: all variants in one table ──────────────────────────────
const ActivityBase = object({
    id:     number().primaryKey(),
    type:   string(),
    todoId: number().hasColumnName('todo_id'),
}).hasTableName('activities');

const ActivityEntity = defineEntity(ActivityBase)
    .discriminator('type')
    .stiVariant('assigned', object({
        type:       string('assigned'),
        assigneeId: number().hasColumnName('assignee_id').optional(),
    }))
    .stiVariant('commented', object({
        type: string('commented'),
        body: string().optional(),
    }));

const db = createDb(knex, { activities: ActivityEntity });

// Get a typed view scoped to one variant (analogous to EF Core Set<T>())
const assigned = db.activities.ofVariant('assigned');

// Insert — discriminator is set automatically
const activity = await assigned.insert({ todoId: 42, assigneeId: 9 });
// activity.type === 'assigned', activity.assigneeId === 9

// Find by PK, typed to the variant
const found = await assigned.find(activity.id);

// Update rows matching a WHERE clause
await assigned.where(t => t.id, 3).update({ assigneeId: 99 });

// Delete rows matching a WHERE clause
await assigned.where(t => t.id, 3).delete();

Schema Migrations

Use @cleverbrush/orm-cli to diff your entity definitions against the live database and emit TypeScript migration files.

// db.config.ts — one config file, picked up automatically by cb-orm
import knex from 'knex';
import { defineConfig } from '@cleverbrush/orm-cli';
import { UserEntity, TodoEntity } from './src/db/schemas.js';

export default defineConfig({
    knex: knex({ client: 'pg', connection: process.env.DATABASE_URL }),
    entities: { users: UserEntity, todos: TodoEntity },
    migrations: { directory: './migrations' }
});

# Diff schema vs DB → emit a TS migration file
npx cb-orm migrate generate add_users_table

# Apply pending migrations
npx cb-orm migrate run

# Check migration status
npx cb-orm migrate status

# Sync in-place (dev only — no migration file)
npx cb-orm db push

API Reference

See Also

• @cleverbrush/knex-schema — the schema DSL and query builder that powers this ORM
• @cleverbrush/orm-cli — migration CLI tool
• API Reference — full TypeDoc-generated API documentation