@zerotal/orm 1.0.0

package/src/schema/MigrationRunner.ts

@@ -0,0 +1,351 @@
+import type { SQLInstance } from "../db/sql-types.ts";
+import type { Migration } from "./Migration.ts";
+import { MigrationError } from "../errors/MigrationError.ts";
+import { FrameworkEvents } from "@zerotal/core";
+import { MigrationRan } from "../events.ts";
+import { dialectFor } from "../db/QueryBuilder.ts";
+import { getDialect } from "../db/dialects/index.ts";
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+export interface MigrationEntry {
+  /** Unique migration name, e.g. "2024_01_01_000000_create_users_table". */
+  name: string;
+  migration: Migration;
+}
+
+export interface MigrationRecord {
+  name: string;
+  instance: Migration;
+}
+
+export interface MigrationStatus {
+  name: string;
+  ran: boolean;
+  batch?: number;
+  ranAt?: Date;
+}
+
+interface MigrationRow {
+  id: number;
+  migration: string;
+  batch: number;
+  ran_at: string;
+}
+
+// ── MigrationRunner ───────────────────────────────────────────────────────────
+
+/**
+ * Executes and tracks migrations against a `Bun.sql` connection.
+ *
+ * Applied migrations are recorded in a tracking table (default `"migrations"`) by
+ * name and batch, so re-runs skip already-applied entries and rollbacks can undo a
+ * whole batch. Each `up()` runs inside its own transaction; a failure rolls that
+ * migration back and surfaces as a {@link MigrationError} without affecting
+ * already-committed migrations. Every run/rollback emits a `MigrationRan`
+ * framework event (success or failure) for observability.
+ *
+ * @example
+ * ```ts
+ * const runner = new MigrationRunner({ connection: sql });
+ * await runner.runFromDirectory('./database/migrations'); // apply pending
+ * await runner.rollbackFromDirectory('./database/migrations'); // undo last batch
+ * ```
+ */
+export class MigrationRunner {
+  private readonly _conn: SQLInstance;
+  private readonly _table: string;
+
+  /**
+   * @param options.connection - The `Bun.sql` connection to run DDL/DML against.
+   * @param options.table - Tracking-table name; defaults to `"migrations"`.
+   */
+  constructor(options: { connection: SQLInstance; table?: string }) {
+    this._conn = options.connection;
+    this._table = options.table ?? "migrations";
+  }
+
+  /**
+   * Run all pending migrations from the provided list.
+   *
+   * - Skips any entry whose name is already in the migrations table.
+   * - Executes pending entries in the order given; assigns them all to a new batch.
+   * - Returns the names of migrations that were actually executed.
+   */
+  async run(entries: MigrationEntry[]): Promise<string[]> {
+    await this._ensureTable();
+    const ran = await this._ranNames();
+    const batch = (await this._lastBatch()) + 1;
+
+    const pendingEntries = entries.filter((e) => !ran.has(e.name));
+    const executed: string[] = [];
+
+    for (const entry of pendingEntries) {
+      const start = performance.now();
+      try {
+        // Each migration runs in its own transaction so a failure rolls back
+        // that migration's DDL without affecting already-committed ones.
+        await this._conn.begin(async () => {
+          await entry.migration.up();
+        });
+      } catch (err) {
+        const cause = err instanceof Error ? err : new Error(String(err));
+        FrameworkEvents.emit(
+          new MigrationRan(
+            entry.name,
+            "up",
+            Math.round(performance.now() - start),
+            false,
+            cause.message,
+          ),
+        );
+        throw new MigrationError(entry.name, cause);
+      }
+      FrameworkEvents.emit(
+        new MigrationRan(entry.name, "up", Math.round(performance.now() - start), true),
+      );
+      await this._record(entry.name, batch);
+      executed.push(entry.name);
+    }
+
+    return executed;
+  }
+
+  /**
+   * Roll back the last batch of migrations in reverse order.
+   *
+   * `entries` must include all migration objects so the runner can locate
+   * the correct `down()` implementation for each name in the last batch.
+   *
+   * Returns the names of migrations that were rolled back.
+   */
+  async rollback(entries: MigrationEntry[]): Promise<string[]> {
+    await this._ensureTable();
+    const batch = await this._lastBatch();
+    if (batch === 0) return [];
+
+    const batchNames = await this._namesForBatch(batch);
+    const byName = new Map(entries.map((e) => [e.name, e]));
+
+    // A recorded migration whose file is gone has no down() to run, so the batch cannot be
+    // rolled back correctly. Refuse before touching anything: silently skipping it left the
+    // schema and the tracking table inconsistent — the batch's other migrations were undone
+    // while their records stayed — and left reset() looping forever, since the batch never
+    // emptied and _lastBatch() kept returning it.
+    const missing = batchNames.filter((name) => !byName.has(name));
+    if (missing.length > 0) {
+      throw new Error(
+        `[Zerotal ORM] Cannot roll back batch ${batch}: no migration file found for ` +
+          `${missing.map((n) => `"${n}"`).join(", ")}.\n` +
+          `Restore the file(s), or delete the row(s) from the migrations table if the ` +
+          `migration is genuinely gone and its schema change is already reversed.`,
+      );
+    }
+
+    // Reverse order — last migration is undone first
+    const toRollback = [...batchNames].reverse().map((n) => byName.get(n)!);
+    const rolledBack: string[] = [];
+
+    for (const entry of toRollback) {
+      const start = performance.now();
+      try {
+        await entry.migration.down();
+      } catch (err) {
+        const cause = err instanceof Error ? err : new Error(String(err));
+        FrameworkEvents.emit(
+          new MigrationRan(
+            entry.name,
+            "down",
+            Math.round(performance.now() - start),
+            false,
+            cause.message,
+          ),
+        );
+        throw err;
+      }
+      FrameworkEvents.emit(
+        new MigrationRan(entry.name, "down", Math.round(performance.now() - start), true),
+      );
+      await this._deleteRecord(entry.name);
+      rolledBack.push(entry.name);
+    }
+
+    return rolledBack;
+  }
+
+  /**
+   * Return names of migrations from `entries` that have not yet been run.
+   */
+  async pending(entries: MigrationEntry[]): Promise<string[]> {
+    await this._ensureTable();
+    const ran = await this._ranNames();
+    return entries.filter((e) => !ran.has(e.name)).map((e) => e.name);
+  }
+
+  /**
+   * Roll back every batch, running `down()` from newest to oldest.
+   */
+  async reset(entries: MigrationEntry[]): Promise<void> {
+    await this._ensureTable();
+    let batch = await this._lastBatch();
+    while (batch > 0) {
+      await this.rollback(entries);
+      batch = await this._lastBatch();
+    }
+  }
+
+  /**
+   * Report which migrations from `entries` have run.
+   */
+  async status(entries: MigrationEntry[]): Promise<MigrationStatus[]> {
+    await this._ensureTable();
+    const records = await this._allRecords();
+    const byName = new Map(records.map((r) => [r.migration, r]));
+
+    return entries.map((e) => {
+      const rec = byName.get(e.name);
+      return rec
+        ? {
+            name: e.name,
+            ran: true,
+            batch: rec.batch,
+            ranAt: new Date(rec.ran_at),
+          }
+        : { name: e.name, ran: false };
+    });
+  }
+
+  /**
+   * Load migration files from a directory, sort alphabetically, and run.
+   *
+   * Files must export a default class that extends Migration.
+   * Skips non-.ts files.
+   */
+  async runFromDirectory(dir: string): Promise<string[]> {
+    const entries = await this._loadDirectory(dir);
+    return this.run(entries);
+  }
+
+  /**
+   * Load migration files from a directory and roll back the last batch.
+   * @returns Names of the migrations that were rolled back.
+   */
+  async rollbackFromDirectory(dir: string): Promise<string[]> {
+    const entries = await this._loadDirectory(dir);
+    return this.rollback(entries);
+  }
+
+  // ── Private helpers ───────────────────────────────────────────────────────
+
+  private async _ensureTable(): Promise<void> {
+    // The tracking table is the very first DDL a project ever runs, so a SQLite-only
+    // `INTEGER PRIMARY KEY AUTOINCREMENT` here meant `migrate` against PostgreSQL or MySQL
+    // failed before it reached a single application migration.
+    const id = getDialect(dialectFor(this._conn)).autoIncrementColumn("id");
+    await this._ddl(`
+      CREATE TABLE IF NOT EXISTS ${this._table} (
+        ${id},
+        migration TEXT    NOT NULL UNIQUE,
+        batch     INTEGER NOT NULL,
+        ran_at    TEXT    NOT NULL
+      )
+    `);
+  }
+
+  private async _ranNames(): Promise<Set<string>> {
+    const rows = await this._select<{ migration: string }>(`SELECT migration FROM ${this._table}`);
+    return new Set(rows.map((r) => r.migration));
+  }
+
+  private async _lastBatch(): Promise<number> {
+    const rows = await this._select<{ b: number | null }>(
+      `SELECT MAX(batch) as b FROM ${this._table}`,
+    );
+    return rows[0]?.b ?? 0;
+  }
+
+  private async _namesForBatch(batch: number): Promise<string[]> {
+    const rows = await this._selectParam<{ migration: string }>(
+      `SELECT migration FROM ${this._table} WHERE batch = ? ORDER BY id ASC`,
+      batch,
+    );
+    return rows.map((r) => r.migration);
+  }
+
+  private async _allRecords(): Promise<MigrationRow[]> {
+    return this._select<MigrationRow>(
+      `SELECT id, migration, batch, ran_at FROM ${this._table} ORDER BY id ASC`,
+    );
+  }
+
+  private async _record(name: string, batch: number): Promise<void> {
+    const now = new Date().toISOString();
+    await this._exec(
+      `INSERT INTO ${this._table} (migration, batch, ran_at) VALUES (?, ?, ?)`,
+      name,
+      batch,
+      now,
+    );
+  }
+
+  private async _deleteRecord(name: string): Promise<void> {
+    await this._exec(`DELETE FROM ${this._table} WHERE migration = ?`, name);
+  }
+
+  /** Execute a DDL string with no parameters. */
+  private async _ddl(sql: string): Promise<void> {
+    const strings = [sql];
+    const tpl = Object.assign(strings, {
+      raw: strings,
+    }) as TemplateStringsArray;
+    await this._conn(tpl);
+  }
+
+  /** SELECT with no bound parameters. */
+  private async _select<T>(sql: string): Promise<T[]> {
+    return this._exec0<T>(sql);
+  }
+
+  /** SELECT with exactly one bound parameter. */
+  private async _selectParam<T>(sql: string, value: unknown): Promise<T[]> {
+    const parts = sql.split("?");
+    const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+    return this._conn<T>(tpl, value);
+  }
+
+  /** DML with N bound parameters. */
+  private async _exec(sql: string, ...values: unknown[]): Promise<void> {
+    const parts = sql.split("?");
+    const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+    await this._conn(tpl, ...values);
+  }
+
+  private async _exec0<T>(sql: string): Promise<T[]> {
+    const strings = [sql];
+    const tpl = Object.assign(strings, {
+      raw: strings,
+    }) as TemplateStringsArray;
+    return this._conn<T>(tpl);
+  }
+
+  private async _loadDirectory(dir: string): Promise<MigrationEntry[]> {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { readdirSync } = require("node:fs") as typeof import("node:fs");
+    const files = readdirSync(dir)
+      .filter((f: string) => f.endsWith(".ts") || f.endsWith(".js"))
+      .sort();
+
+    const entries: MigrationEntry[] = [];
+    for (const file of files) {
+      const fullPath = `${dir}/${file}`;
+      // Dynamic import — each migration file must have a default export
+      const mod = (await import(fullPath)) as { default: new () => Migration };
+      const Ctor = mod.default;
+      entries.push({
+        name: file.replace(/\.(ts|js)$/, ""),
+        migration: new Ctor(),
+      });
+    }
+    return entries;
+  }
+}

package/src/schema/ModelInspector.ts

@@ -0,0 +1,133 @@
+import path from "node:path";
+import type { ColumnOptions } from "../model/decorators/column.ts";
+import { columnRegistry, columnsFor } from "../model/decorators/_metadata.ts";
+
+// ── Model schema descriptor ───────────────────────────────────────────────────
+
+export interface ModelColumn {
+  name: string;
+  type: ColumnOptions["type"]; // 'string' | 'number' | 'boolean' | 'datetime' | 'json'
+  nullable: boolean;
+  primary: boolean;
+  default: unknown;
+}
+
+export interface ModelSchema {
+  table: string;
+  primaryKey: string;
+  timestamps: boolean;
+  softDeletes: boolean;
+  columns: ModelColumn[];
+}
+
+/**
+ * Map a model property name to its database column name. Models declare columns in camelCase
+ * (`twoFactorSecret`) but the ORM reads/writes snake_case (`two_factor_secret`) — see
+ * BaseModel's `toSnake`. Schema generation (synchronize, migrate:generate) and schema diffing
+ * MUST use this so generated/compared column names match the runtime convention. Idempotent for
+ * names that are already snake_case.
+ */
+export function columnDbName(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+// ── Prototype-chain column collection ─────────────────────────────────────────
+
+/**
+ * Walk up the prototype chain of `ctor`, collecting `@column()` definitions
+ * from every ancestor that has an entry in `columnRegistry`.
+ *
+ * Child-class columns win over parent-class columns when names collide —
+ * the walk stops at `Function.prototype` (the top of the JS class hierarchy).
+ *
+ * This handles `AdminUser extends User extends BaseModel` correctly: columns
+ * declared on `User` appear in `AdminUser`'s schema without needing to be
+ * re-declared.
+ */
+function collectColumns(ctor: Function): Map<string, ColumnOptions> | null {
+  // columnsFor walks the prototype chain (child overrides parent) and mirrors each
+  // class's metadata into columnRegistry on first read.
+  return columnsFor(ctor);
+}
+
+function toModelColumns(fields: Map<string, ColumnOptions>): ModelColumn[] {
+  const columns: ModelColumn[] = [];
+  for (const [name, opts] of fields.entries()) {
+    columns.push({
+      name,
+      type: opts.type,
+      nullable: opts.nullable ?? false,
+      primary: opts.primary ?? false,
+      default: opts.default,
+    });
+  }
+  return columns;
+}
+
+// ── ModelInspector ────────────────────────────────────────────────────────────
+
+/**
+ * Reads model class metadata from `columnRegistry` (populated when a model's `@table`
+ * decorator drains its queued `@column` registrations at class-definition time) and
+ * returns a structured schema description for each registered model.
+ *
+ * Prototype-chain walking: columns declared on a parent class are inherited
+ * by child classes, matching normal TypeScript class semantics.
+ *
+ * Used by `migrate:generate` to compare model intent against the live DB.
+ */
+export const ModelInspector = {
+  /**
+   * Dynamically import all files matching `pattern` (relative to `cwd`).
+   * Importing a model file runs its `@table` decorator, which registers the class's
+   * columns into `columnRegistry` at definition time — so `all()` can enumerate them.
+   */
+  async load(pattern: string, cwd = process.cwd()): Promise<void> {
+    const glob = new Bun.Glob(pattern);
+    const files = await Array.fromAsync(glob.scan({ cwd }));
+    for (const file of files) {
+      await import(path.resolve(cwd, file));
+    }
+  },
+
+  /**
+   * Return a `ModelSchema` for every class registered in `columnRegistry`
+   * that has a non-empty `static table` property.
+   *
+   * Skips anonymous classes, the `BaseModel` base class, and any class that
+   * hasn't set `static table`. Walks the prototype chain so that inherited
+   * columns are included automatically.
+   */
+  all(): ModelSchema[] {
+    const schemas: ModelSchema[] = [];
+
+    for (const [ctor] of columnRegistry.entries()) {
+      const schema = ModelInspector.fromClass(ctor);
+      if (schema) schemas.push(schema);
+    }
+
+    return schemas;
+  },
+
+  /**
+   * Read the schema for a single model class.
+   * Returns null if the class has no `static table` or no `@column()` fields
+   * anywhere in its prototype chain.
+   */
+  fromClass(ctor: Function): ModelSchema | null {
+    const M = ctor as unknown as Record<string, unknown>;
+    const table = M["table"] as string | undefined;
+    if (!table) return null;
+
+    const fields = collectColumns(ctor);
+    if (!fields) return null;
+
+    return {
+      table,
+      primaryKey: (M["primaryKey"] as string | undefined) ?? "id",
+      timestamps: (M["timestamps"] as boolean | undefined) ?? true,
+      softDeletes: (M["softDeletes"] as boolean | undefined) ?? false,
+      columns: toModelColumns(fields),
+    };
+  },
+};

package/src/schema/Schema.ts

@@ -0,0 +1,140 @@
+import { _getDbConnection } from "../db/DB.ts";
+import { _getDialect } from "../model/BaseModel.ts";
+import { getDialect } from "../db/dialects/index.ts";
+import { Blueprint } from "./Blueprint.ts";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Execute a DDL statement that contains no bound parameters.
+ * Constructs a TemplateStringsArray from a plain string so we can call the
+ * Bun SQL tagged-template function without interpolating anything.
+ */
+async function ddl(sql: string): Promise<void> {
+  const conn = _getDbConnection();
+  const strings = [sql];
+  const tpl = Object.assign(strings, { raw: strings }) as TemplateStringsArray;
+  await conn(tpl);
+}
+
+/**
+ * Execute a query with bound `?` parameters, returning rows.
+ * We need this for parameterised introspection queries (hasTable, hasColumn).
+ */
+async function query<T = Record<string, unknown>>(sql: string, params: unknown[]): Promise<T[]> {
+  const conn = _getDbConnection();
+  const parts = sql.split("?");
+  const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+  return conn<T>(tpl, ...params);
+}
+
+// ── Schema facade ─────────────────────────────────────────────────────────────
+
+/**
+ * The schema-builder facade — the entry point used inside migration `up()`/`down()`
+ * methods to issue DDL against the active `Bun.sql` connection.
+ *
+ * Each mutating helper constructs a {@link Blueprint}, runs the caller's callback to
+ * record the desired columns/indexes/constraints, compiles the blueprint to SQL,
+ * and executes the statements. Introspection helpers ({@link Schema.hasTable},
+ * {@link Schema.hasColumn}) are dialect-aware and use bound parameters.
+ *
+ * @example
+ * ```ts
+ * // Create
+ * await Schema.create('users', (table) => {
+ *   table.id();
+ *   table.string('email').unique();
+ *   table.timestamps();
+ * });
+ *
+ * // Alter
+ * await Schema.table('users', (table) => {
+ *   table.string('name').nullable();
+ * });
+ *
+ * // Drop
+ * await Schema.drop('users');
+ * ```
+ */
+export const Schema = {
+  /**
+   * Create a table: `CREATE TABLE table_name ( … )`.
+   *
+   * @param table - Table name.
+   * @param callback - Receives a {@link Blueprint} to define columns/indexes/constraints.
+   * @throws Rejects if the table already exists — use {@link Schema.createIfNotExists}
+   * for idempotent runs.
+   */
+  async create(table: string, callback: (bp: Blueprint) => void): Promise<void> {
+    const bp = new Blueprint();
+    callback(bp);
+    for (const sql of bp.toCreateSQL(table, _getDialect())) {
+      await ddl(sql);
+    }
+  },
+
+  /**
+   * Idempotent create: `CREATE TABLE IF NOT EXISTS table_name ( … )` followed by
+   * each index statement. Safe to run repeatedly.
+   */
+  async createIfNotExists(table: string, callback: (bp: Blueprint) => void): Promise<void> {
+    const bp = new Blueprint();
+    callback(bp);
+    const [create, ...indexes] = bp.toCreateSQL(table, _getDialect());
+    if (create) {
+      await ddl(create.replace("CREATE TABLE ", "CREATE TABLE IF NOT EXISTS "));
+    }
+    for (const idx of indexes) await ddl(idx);
+  },
+
+  /**
+   * Modify an existing table: `ALTER TABLE ADD COLUMN / DROP COLUMN /
+   * RENAME COLUMN` plus `CREATE INDEX IF NOT EXISTS`. The blueprint is compiled
+   * for the connection's active dialect (see {@link Blueprint.toAlterSQL}).
+   */
+  async table(name: string, callback: (bp: Blueprint) => void): Promise<void> {
+    const bp = new Blueprint();
+    callback(bp);
+    for (const sql of bp.toAlterSQL(name, _getDialect())) {
+      await ddl(sql);
+    }
+  },
+
+  /** `DROP TABLE table_name` */
+  async drop(table: string): Promise<void> {
+    await ddl(`DROP TABLE ${table}`);
+  },
+
+  /** `DROP TABLE IF EXISTS table_name` */
+  async dropIfExists(table: string): Promise<void> {
+    await ddl(`DROP TABLE IF EXISTS ${table}`);
+  },
+
+  /** `ALTER TABLE from RENAME TO to` */
+  async rename(from: string, to: string): Promise<void> {
+    await ddl(`ALTER TABLE ${from} RENAME TO ${to}`);
+  },
+
+  /**
+   * Returns true if the table exists in the current schema.
+   * Dialect-aware: sqlite_master on SQLite, information_schema on
+   * PostgreSQL/MySQL.
+   */
+  async hasTable(table: string): Promise<boolean> {
+    const { sql, params } = getDialect(_getDialect()).hasTableSql(table);
+    const rows = await query(sql, params);
+    return rows.length > 0;
+  },
+
+  /**
+   * Returns true if `column` exists in `table`.
+   * Dialect-aware: pragma_table_info() on SQLite, information_schema on
+   * PostgreSQL/MySQL. All inputs are bound parameters — never inlined.
+   */
+  async hasColumn(table: string, column: string): Promise<boolean> {
+    const { sql, params } = getDialect(_getDialect()).hasColumnSql(table, column);
+    const rows = await query(sql, params);
+    return rows.length > 0;
+  },
+};