@cleverbrush/orm 0.0.0-beta-20260424142030

package/README.md

@@ -0,0 +1,349 @@
+# `@cleverbrush/orm`
+
+EF-Core-like typed ORM layer on top of [`@cleverbrush/knex-schema`](../knex-schema).
+
+- Define entities with `defineEntity(schema)` and declare relations via
+  `.hasOne()` / `.hasMany()` / `.belongsTo()` / `.belongsToMany()`.
+- Group entities into a typed context with `createDb(knex, { todos, users })`.
+- Access `db.todos`, `db.users` as fully-typed `DbSet<TEntity>` instances.
+- Eager-load related entities with `.include(t => t.author)`.
+- Use `{ tracking: true }` for an identity map + change-tracking context.
+- Model inheritance with STI (single-table) and CTI (class-table) variants.
+- Manage schema migrations with [`@cleverbrush/orm-cli`](../orm-cli).
+
+---
+
+## Installation
+
+```sh
+npm install @cleverbrush/orm
+```
+
+`knex` is a peer dependency (install it alongside `@cleverbrush/orm`). `@cleverbrush/knex-schema` is a direct dependency and is installed automatically.
+
+---
+
+## Quick start
+
+### 1. Define a schema and entity
+
+```ts
+import { number, object, string, defineEntity } from '@cleverbrush/orm';
+
+const UserSchema = object({
+    id:    number().primaryKey(),
+    email: string().hasColumnName('email_address'),
+    name:  string(),
+}).hasTableName('users');
+
+export const UserEntity = defineEntity(UserSchema);
+```
+
+### 2. Create a `DbContext`
+
+```ts
+import knex from 'knex';
+import { createDb } from '@cleverbrush/orm';
+import { UserEntity } from './schemas.js';
+
+const knexClient = knex({ client: 'pg', connection: process.env.DATABASE_URL });
+
+const db = createDb(knexClient, { users: UserEntity });
+```
+
+### 3. Query and mutate
+
+```ts
+// Find by PK
+const alice = await db.users.find(1);
+
+// Find with WHERE clause
+const user = await db.users.where(t => t.email, 'alice@example.com').first();
+
+// Insert
+const created = await db.users.save({ email: 'bob@example.com', name: 'Bob' });
+
+// Update (PK present → UPDATE)
+const updated = await db.users.save({ id: 1, email: 'alice@example.com', name: 'Alice' });
+```
+
+---
+
+## `DbSet<TEntity>` API
+
+| Method | Description |
+|--------|-------------|
+| `.find(pk)` | Find one row by PK; returns `undefined` when not found |
+| `.findOrFail(pk)` | Like `.find`, but throws `EntityNotFoundError` when not found |
+| `.findMany([pk1, pk2, …])` | Fetch multiple rows by PK in one query |
+| `.all()` | Alias for `.execute()` — returns all rows |
+| `.first()` | Returns the first matching row or `undefined` |
+| `.where(col, value)` | Adds a `WHERE` predicate (chainable) |
+| `.include(t => t.rel)` | Eager-loads a relation (chainable) |
+| `.save(graph)` | Insert or update a row graph (transactional) |
+| `.ofVariant(key)` | Return a typed `VariantDbSet` scoped to a polymorphic variant |
+| `.query()` | Returns the underlying `EntityQuery` for advanced querying |
+| `.withTransaction(trx)` | Returns a new `DbSet` bound to an existing transaction |
+
+Any method from the underlying `SchemaQueryBuilder` (e.g. `.execute()`,
+`.where()`, `.orderBy()`, `.pluck()`, `.count()`) is also available and
+fully typed.
+
+---
+
+## Relations
+
+Declare relations on the entity using fluent builders.  Relations are optional
+by default (omit from the save-graph to skip them).
+
+```ts
+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');   // FK is on todos.user_id → users.id
+
+const UserEntity = defineEntity(UserSchema)
+    .hasMany(t => t.todos, TodoEntity, 'userId');   // FK on todos.user_id
+```
+
+### Eager-loading
+
+```ts
+const todo = await db.todos
+    .where(t => t.id, 42)
+    .include(t => t.author)
+    .first();
+
+console.log(todo?.author?.name);   // fully typed
+```
+
+### Saving with relations
+
+`db.todos.save(graph)` traverses the whole object graph and persists every
+level in the correct FK order inside a single transaction.
+
+```ts
+// Create a new user and a new todo in one call.
+const result = await db.users.save({
+    name: 'Alice',
+    todos: [
+        { title: 'Buy milk', completed: false, userId: 0 },
+    ],
+});
+```
+
+Topology rules:
+- `belongsTo` parents are inserted first; their PK feeds the child FK.
+- The root entity is then written.
+- `hasOne` / `hasMany` children inherit the root PK into their FK.
+- `belongsToMany` children may be new objects (inserted + pivot) or bare
+  `{ pk: value }` references (pivot only).
+
+---
+
+## Change-tracking context
+
+Pass `{ tracking: true }` to `createDb` to get a `TrackedDbContext`.  The
+context maintains an **identity map** (same PK → same object reference) and
+tracks every mutation automatically.
+
+```ts
+const db = createDb(knex, { users: UserEntity }, { tracking: true });
+
+// Load entity — it's now in the identity map.
+const user = await db.users.find(1);
+
+// Mutate normally.
+user.name = 'Updated';
+
+// Flush all dirty entries in a single transaction.
+const { inserted, updated, deleted } = await db.saveChanges();
+```
+
+### `TrackedDbContext` API
+
+| Method / property | Description |
+|---|---|
+| `.attach(key, entity)` | Register an existing entity as `Unchanged` |
+| `.entry(entity)` | Return the `EntityEntry` for a tracked entity |
+| `.entry(entity).state` | `'Added' \| 'Modified' \| 'Unchanged' \| 'Deleted'` |
+| `.entry(entity).isModified(field?)` | Check if a specific (or any) field changed |
+| `.entry(entity).reset()` | Revert the entity to its last snapshot |
+| `.detach(entity)` | Remove an entity from the tracker |
+| `.remove(entity)` | Mark a tracked entity as `Deleted` |
+| `.saveChanges()` | Flush all pending changes to the DB |
+| `.discardChanges()` | Roll back all in-memory changes |
+| `.reload(entity)` | Re-fetch the entity from the DB and refresh its snapshot |
+| `.onSavingChanges(hook)` | Register a pre-flush callback (e.g. for audit fields) |
+| `[Symbol.asyncDispose]()` | Usable in `await using` blocks; throws on pending changes |
+
+### Row versioning
+
+Mark any numeric or timestamp column as a row version:
+
+```ts
+const OrderSchema = object({
+    id:      number().primaryKey(),
+    status:  string(),
+    version: number().rowVersion(),   // auto-incremented by the ORM on every UPDATE
+}).hasTableName('orders');
+```
+
+`saveChanges()` appends `AND version = <snapshot>` to every `UPDATE` and throws
+`ConcurrencyError` if `rowCount === 0`.
+
+### `await using` integration
+
+```ts
+async function updateUser(userId: number) {
+    await using db = createDb(knex, { users: UserEntity }, { tracking: true });
+    const user = await db.users.find(userId);
+    if (!user) return;
+    user.name = 'Updated';
+    await db.saveChanges();
+}   // Symbol.asyncDispose fires here; throws if changes are still pending
+```
+
+---
+
+## Polymorphic entities (STI / CTI)
+
+### Single-Table Inheritance (STI)
+
+All variants share one table; a discriminator column identifies the type.
+
+```ts
+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(),
+    }));
+```
+
+### Class-Table Inheritance (CTI)
+
+The base row is in one table; each variant has its own extension table.
+
+```ts
+const AssignedExtras = defineEntity(
+    object({
+        activityId: number().hasColumnName('activity_id'),
+        assigneeId: number().hasColumnName('assignee_id'),
+    }).hasTableName('assigned_activities')
+);
+
+const ActivityEntity = defineEntity(ActivityBase)
+    .discriminator('type')
+    .ctiVariant('assigned', AssignedExtras, t => t.activityId);
+```
+
+### Querying variants
+
+Call `db.set.ofVariant('key')` to obtain a **`VariantDbSet`** — a typed view
+scoped to that variant, analogous to EF Core's `Set<DerivedType>()`.  All
+reads are pre-filtered by the discriminator; writes use the correct STI / CTI
+logic automatically.
+
+```ts
+// Insert a new variant row (discriminator is set automatically)
+const activity = await db.activities.ofVariant('assigned').insert({
+    todoId:     42,
+    assigneeId: 9,
+});
+// activity.type === 'assigned'
+// activity.assigneeId === 9
+
+// Find a single variant by PK
+const found = await db.activities.ofVariant('assigned').find(activityId);
+
+// Update matching rows  (chain .where() before .update())
+await db.activities.ofVariant('assigned').where(t => t.id, 3).update({ assigneeId: 99 });
+
+// Delete matching rows
+await db.activities.ofVariant('assigned').where(t => t.id, 3).delete();
+```
+
+### `VariantDbSet<TEntity, K>` API
+
+| Method | Description |
+|--------|-------------|
+| `.insert(payload)` | Insert a new variant row; discriminator is set automatically |
+| `.update(patch)` | Update variant columns for rows matched by the current `WHERE` clause |
+| `.delete()` | Delete rows matched by the current `WHERE` clause (CTI: atomic) |
+| `.find(pk)` | Find a single variant row by PK; `undefined` if not found |
+| `.findOrFail(pk)` | Like `.find`, but throws `EntityNotFoundError` |
+| `.findMany([pk…])` | Fetch multiple variant rows by PK in one query |
+| `.where(col, value)` | Adds a `WHERE` predicate (chainable; returns `VariantDbSet`) |
+| `.include(t => t.rel)` | Eager-loads a relation (chainable; returns `VariantDbSet`) |
+| `.withTransaction(trx)` | Returns a new `VariantDbSet` bound to an existing transaction |
+
+Calling `.insert()` / `.update()` / `.delete()` directly on the polymorphic
+base `DbSet` (without `ofVariant`) throws a runtime error — use `ofVariant`
+for all writes on polymorphic entities.
+
+---
+
+## Transactions
+
+```ts
+// One-off transaction (non-tracking context)
+await db.transaction(async trx => {
+    const user = await trx.users.save({ name: 'Alice' });
+    await trx.todos.save({ title: 'Buy milk', userId: user.id });
+});
+
+// Wrap existing transaction
+const user = await db.users.withTransaction(existingTrx).save({ name: 'Alice' });
+```
+
+---
+
+## Error classes
+
+| Class | Thrown when |
+|-------|-------------|
+| `EntityNotFoundError` | `findOrFail` can't locate the requested PK |
+| `ConcurrencyError` | `saveChanges` UPDATE/DELETE hits a row-version mismatch |
+| `InvariantViolationError` | PK or discriminator column mutated on a tracked entity |
+| `PendingChangesError` | `[Symbol.asyncDispose]` fires with unsaved changes |
+
+---
+
+## Schema migrations
+
+Use [`@cleverbrush/orm-cli`](../orm-cli) to generate and apply migration files
+from your entity definitions:
+
+```sh
+# Diff schema vs DB → emit a TypeScript migration file
+npx cb-orm migrate generate add_users_table
+
+# Apply pending migrations
+npx cb-orm migrate run
+```
+
+---
+
+## See also
+
+- [`@cleverbrush/knex-schema`](../knex-schema) — the underlying schema DSL and
+  query builder
+- [`@cleverbrush/orm-cli`](../orm-cli) — migration CLI tool
+- [API reference](https://cleverbrush.github.io/framework/api-docs/latest)

package/dist/change-tracker.d.ts

@@ -0,0 +1,118 @@
+import type { Knex } from 'knex';
+/**
+ * Entry state in the identity map. Mirrors EF Core's EntityState.
+ * @public
+ */
+export type EntryState = 'Added' | 'Unchanged' | 'Modified' | 'Deleted';
+/**
+ * Public view of a tracked entry, exposed via `db.entry(entity)`.
+ *
+ * @public
+ */
+export interface EntityEntry<T extends object> {
+    /** Current state of the entry. */
+    readonly state: EntryState;
+    /** Snapshot of the values at the time the entity was last loaded/saved. */
+    readonly originalValues: Readonly<T>;
+    /** Live object (same reference as the tracked entity). */
+    readonly currentValues: T;
+    /**
+     * Returns `true` when a specific field has changed since the last
+     * snapshot, or `true` when any field has changed when called without
+     * arguments.
+     */
+    isModified(field?: keyof T): boolean;
+    /**
+     * Reset all changes to the snapshot values and transition state back
+     * to `'Unchanged'` (or `'Added'` if the entity was never persisted).
+     */
+    reset(): void;
+}
+/** @internal Per-entity-set configuration needed by the tracker. */
+export interface EntitySetConfig {
+    /** The entity schema (used for PK resolution). */
+    schema: any;
+    /** Logical entity-set name (e.g. `'todos'`). */
+    entitySetKey: string;
+}
+/**
+ * Pre-save hook callback signature registered via
+ * `TrackedDbContext.onSavingChanges(hook)`.
+ * @public
+ */
+export type SavingChangesHook = (entry: EntityEntry<object>) => void | Promise<void>;
+/**
+ * The change-tracking core used by tracked `DbContext` instances.
+ *
+ * Consumers interact with this via the `DbContext` API methods; the
+ * `ChangeTracker` itself is not exported as part of the public API.
+ *
+ * @internal
+ */
+export declare class ChangeTracker {
+    #private;
+    /** Register an entity set so the tracker knows its schema. */
+    registerEntitySet(config: EntitySetConfig): void;
+    /** Register a pre-save hook. */
+    onSavingChanges(hook: SavingChangesHook): void;
+    /**
+     * Attach an entity to the tracker under the given entity-set key.
+     *
+     * If an entry with the same PK already exists, returns the EXISTING
+     * tracked object (identity-map guarantee). If the entity is already the
+     * same object, just updates its snapshot.
+     *
+     * @returns The tracked entity (same ref when already in the map).
+     */
+    attach<T extends object>(entitySetKey: string, entity: T, state?: EntryState): T;
+    /** Detach an entity from tracking. */
+    detach(entity: object): void;
+    /**
+     * Mark an entity for deletion on the next `saveChanges()` call.
+     * The entity must already be tracked.
+     */
+    remove(entity: object): void;
+    /** Return the public `EntityEntry` view for a tracked entity. */
+    entry<T extends object>(entity: T): EntityEntry<T>;
+    /**
+     * Discard all pending changes: reset all Modified entries to their
+     * snapshots, remove Added entries from the tracker, restore Deleted
+     * entries to Unchanged.
+     */
+    discardChanges(): void;
+    /**
+     * Refresh a tracked entity from the DB, replacing its current values
+     * and snapshot with the freshly-loaded row.
+     */
+    reload(entity: object, knex: Knex): Promise<void>;
+    /**
+     * Returns `true` when there are any pending changes (Added / Modified /
+     * Deleted entries, or silently mutated Unchanged entries).
+     */
+    hasPendingChanges(): boolean;
+    /**
+     * Flush all pending changes to the database within a single transaction.
+     *
+     * Returns the number of rows inserted, updated, and deleted.
+     *
+     * Invariants checked:
+     * - PK columns must not have changed since the snapshot (throws
+     *   `InvariantViolationError`).
+     * - Discriminator columns must not have changed (throws
+     *   `InvariantViolationError`).
+     * - For `rowVersion` columns: WHERE clause enforces the snapshot value;
+     *   zero affected rows throws `ConcurrencyError`.
+     */
+    saveChanges(knex: Knex): Promise<{
+        inserted: number;
+        updated: number;
+        deleted: number;
+    }>;
+    /**
+     * Generate a summary of pending changes for error messages.
+     * @internal
+     */
+    pendingSummary(): string;
+    /** Clear the entire identity map (used on dispose). */
+    clear(): void;
+}

package/dist/dbcontext.d.ts

@@ -0,0 +1,130 @@
+import type { Entity } from '@cleverbrush/knex-schema';
+import type { Knex } from 'knex';
+import { type EntityEntry, type SavingChangesHook } from './change-tracker.js';
+import { type DbSet } from './dbset.js';
+/**
+ * The map of entity name → entity definition passed to {@link createDb}.
+ *
+ * @public
+ */
+export type EntityMap = Record<string, Entity<any, any, any>>;
+/**
+ * The shape of the context object returned by {@link createDb}: every
+ * registered entity becomes a typed `DbSet` property.
+ *
+ * @public
+ */
+export type DbContext<TMap extends EntityMap> = {
+    readonly [K in keyof TMap]: DbSet<TMap[K]>;
+} & {
+    /**
+     * The underlying Knex instance the context was constructed with.
+     */
+    readonly knex: Knex;
+    /**
+     * Run `callback` inside a Knex transaction. The callback receives a new
+     * `DbContext` whose `DbSet`s are bound to the transaction.
+     */
+    transaction<T>(callback: (db: DbContext<TMap>) => Promise<T>): Promise<T>;
+    /**
+     * Return a new `DbContext` whose `DbSet`s are bound to `trx`. Useful
+     * when you already have a Knex transaction in scope.
+     */
+    withTransaction(trx: Knex.Transaction): DbContext<TMap>;
+};
+/**
+ * Extended context returned when `{ tracking: true }` is passed to
+ * {@link createDb}. Adds identity-map tracking, unit-of-work `saveChanges`,
+ * and `[Symbol.asyncDispose]` support for `await using` blocks.
+ *
+ * @public
+ */
+export type TrackedDbContext<TMap extends EntityMap> = DbContext<TMap> & {
+    /**
+     * Attach an entity to the identity map so its changes will be tracked.
+     * If an entity with the same primary key is already tracked, the existing
+     * tracked object is returned (identity-map guarantee).
+     *
+     * @param entitySetKey — the property name used when registering the entity
+     *   (e.g. `'todos'` for `createDb(knex, { todos: TodoEntity })`).
+     */
+    attach<T extends object>(entitySetKey: string, entity: T): T;
+    /**
+     * Remove an entity from the identity map. Any subsequent changes to the
+     * object will not be persisted by `saveChanges`.
+     */
+    detach(entity: object): void;
+    /**
+     * Mark a tracked entity for deletion on the next `saveChanges()` call.
+     */
+    remove(entity: object): void;
+    /**
+     * Get the public entry-state view for a tracked entity.
+     */
+    entry<T extends object>(entity: T): EntityEntry<T>;
+    /**
+     * Register a callback that is invoked for each changed entry just before
+     * the changes are flushed to the database. Use to apply audit fields etc.
+     */
+    onSavingChanges(hook: SavingChangesHook): void;
+    /**
+     * Reload a tracked entity from the database, overwriting its current
+     * values and refreshing the internal snapshot.
+     */
+    reload(entity: object): Promise<void>;
+    /**
+     * Discard all pending changes. Modified entries are reset to their
+     * snapshots; Added entries are detached; Deleted entries are restored
+     * to `Unchanged`.
+     */
+    discardChanges(): void;
+    /**
+     * Flush all pending changes to the database inside a single transaction.
+     *
+     * @returns Counts of inserted, updated, and deleted rows.
+     */
+    saveChanges(): Promise<{
+        inserted: number;
+        updated: number;
+        deleted: number;
+    }>;
+    /**
+     * Implements `Symbol.asyncDispose` for `await using` blocks.
+     *
+     * Throws {@link PendingChangesError} when there are unsaved changes at
+     * the time of disposal — callers must call `saveChanges()` or
+     * `discardChanges()` before the scope exits.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+};
+/**
+ * Create a typed database context.
+ *
+ * @example
+ * ```ts
+ * const TodoEntity = defineEntity(TodoSchema)
+ *     .belongsTo(t => t.author, l => l.userId, r => r.id);
+ *
+ * const UserEntity = defineEntity(UserSchema);
+ *
+ * const db = createDb(knex, { todos: TodoEntity, users: UserEntity });
+ *
+ * const todo = await db.todos
+ *     .where(t => t.id, '=', 42)
+ *     .include(t => t.author)
+ *     .first();
+ *
+ * await db.transaction(async dbTrx => {
+ *     const u = await dbTrx.users.insert({ email: 'a@b.c', role: 'user', authProvider: 'local', createdAt: new Date() });
+ *     await dbTrx.todos.insert({ title: 'Hi', userId: u.id, completed: false, createdAt: new Date(), updatedAt: new Date() });
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function createDb<TMap extends EntityMap>(knex: Knex, entities: TMap, opts: {
+    tracking: true;
+}): TrackedDbContext<TMap>;
+export declare function createDb<TMap extends EntityMap>(knex: Knex, entities: TMap, opts?: {
+    tracking?: false | undefined;
+}): DbContext<TMap>;