@avelon/orm

@avelon/orm is Scrivener, Avelon's model layer. It builds serializable QueryIR and never imports a database vendor. Reach for this package when application code needs models, fluent queries, ward injection, relation loads, casts, timestamps, soft deletes, or lifecycle hooks.

Installation

bun add @avelon/orm

Basic Usage

import { Model } from '@avelon/orm'
import { defineConfig } from '@avelon/core'
import type { DatabaseDriver } from '@avelon/core'

export function boot(database: DatabaseDriver) {
  defineConfig({
    name: 'app',
    drivers: { database },
  })
}

export class Post extends Model {
  static override table = 'posts'
  static override fillable = ['title', 'body', 'user_id']
  static override casts = { published_at: 'datetime' } as const
  static override timestamps = true
  static override softDeletes = true

  declare id: string
  declare title: string
  declare body: string
  declare user_id: string
  declare published_at: Date | null

  author() {
    return this.belongsTo(User, 'user_id')
  }

  static published() {
    return this.query().whereNotNull('published_at')
  }
}

export class User extends Model {
  static override table = 'users'
  static override fillable = ['email', 'name']
}

export async function latestPublished() {
  return Post.published().with('author').latest('published_at').paginate(15)
}

Query Builder

The builder accumulates predicates, ordering, limits, relations, and wards, then emits QueryIR for the configured database driver. where('age', 20) equals where('age', '=', 20). orWhere wraps the accumulated predicates in an or node. paginate uses count mode for the total.

Models

Models declare a table, fillable attributes, optional casts, timestamps, and soft deletes. Use declare for attributes so hydration is not overwritten by emitted class fields. findOrFail raises NotFound. forActor injects the actor's ward. Scrivener.unwarded(Post).query() skips ward injection and is restricted by Bailiff to errands and seeds.

Lifecycle Hooks

Writes dispatch ModelLifecycle on the same event bus as application events. A creating listener that returns false (or calls stopPropagation) aborts the insert.

import { Events, defineListener } from '@avelon/core'
import { ModelLifecycle } from '@avelon/orm'

Events.listen(
  ModelLifecycle,
  defineListener({
    handle: (event) => {
      if (event.hook === 'creating' && event.modelName === 'Post') return false
    },
  }),
)

Method Reference

Testing

Point defineConfig at FakeDatabase from @avelon/conformance and assert on toIR() output or hydrated models.

import { defineConfig } from '@avelon/core'
import { FakeDatabase } from '@avelon/conformance'
import { Model } from '@avelon/orm'

defineConfig({ name: 'test', drivers: { database: new FakeDatabase() } })

export class User extends Model {
  static override table = 'assay_users'
  static override fillable = ['id', 'email', 'name', 'age', 'nickname']
}

await User.create({
  id: 'u1',
  email: 'one@example.test',
  name: 'One',
  age: 20,
  nickname: null,
})