@zerotal/orm 1.0.0

package/src/schema/SchemaDiffer.ts

@@ -0,0 +1,137 @@
+import { SchemaInspector } from "./SchemaInspector.ts";
+import { columnDbName, type ModelSchema, type ModelColumn } from "./ModelInspector.ts";
+
+// -- Diff result types ---------------------------------------------------------
+
+export interface NewTable {
+  schema: ModelSchema;
+}
+
+export interface NewColumn {
+  table: string;
+  column: ModelColumn;
+}
+
+export interface DroppedColumn {
+  table: string;
+  column: string;
+}
+
+export interface DiffResult {
+  newTables: NewTable[];
+  newColumns: NewColumn[];
+  /**
+   * Columns that exist in the live table but are no longer declared by the model.
+   * Only ever acted on by a *disruptive* `synchronize` - additive sync and
+   * `migrate:generate` ignore these to avoid accidental data loss.
+   */
+  droppedColumns: DroppedColumn[];
+}
+
+// -- SchemaDiffer --------------------------------------------------------------
+
+/**
+ * Compares a set of model schemas against the live database and returns
+ * the deltas: tables that need to be created and columns that need to be added.
+ *
+ * Additive deltas (newTables, newColumns) are always safe to apply. Dropped
+ * columns are reported separately and only applied by a disruptive synchronize.
+ */
+export const SchemaDiffer = {
+  async diff(schemas: ModelSchema[]): Promise<DiffResult> {
+    const newTables: NewTable[] = [];
+    const newColumns: NewColumn[] = [];
+    const droppedColumns: DroppedColumn[] = [];
+
+    for (const schema of schemas) {
+      const live = await SchemaInspector.describe(schema.table);
+
+      if (live === null) {
+        // Entire table is new - generate a CREATE TABLE migration.
+        newTables.push({ schema });
+        continue;
+      }
+
+      // Table exists - find columns that the model declares but the DB doesn't have.
+      const liveNames = new Set(live.columns.map((c) => c.name));
+
+      // The full set of columns the model expects to exist: declared columns plus
+      // the framework-managed ones (primary key, timestamps, soft-deletes). Any live
+      // column outside this set is a candidate drop (disruptive sync only). Compare in
+      // snake_case (the DB convention) so camelCase model props match their real columns.
+      const expected = new Set<string>(schema.columns.map((c) => columnDbName(c.name)));
+      if (schema.primaryKey) expected.add(columnDbName(schema.primaryKey));
+      if (schema.timestamps) {
+        expected.add("created_at");
+        expected.add("updated_at");
+      }
+      if (schema.softDeletes) expected.add("deleted_at");
+
+      for (const col of live.columns) {
+        // Never drop the primary key, and never drop a still-declared column.
+        if (col.primary || expected.has(col.name)) continue;
+        droppedColumns.push({ table: schema.table, column: col.name });
+      }
+
+      for (const col of schema.columns) {
+        // The model column carries its raw (camelCase) name; the DB has it snake_cased.
+        if (!liveNames.has(columnDbName(col.name))) {
+          newColumns.push({ table: schema.table, column: col });
+        }
+      }
+
+      // Check timestamp columns that Blueprint.timestamps() would add.
+      if (schema.timestamps) {
+        if (!liveNames.has("created_at")) {
+          newColumns.push({
+            table: schema.table,
+            column: {
+              name: "created_at",
+              type: "datetime",
+              nullable: true,
+              primary: false,
+              default: undefined,
+            },
+          });
+        }
+        if (!liveNames.has("updated_at")) {
+          newColumns.push({
+            table: schema.table,
+            column: {
+              name: "updated_at",
+              type: "datetime",
+              nullable: true,
+              primary: false,
+              default: undefined,
+            },
+          });
+        }
+      }
+
+      // Check soft-delete column that Blueprint.softDeletes() would add.
+      if (schema.softDeletes && !liveNames.has("deleted_at")) {
+        newColumns.push({
+          table: schema.table,
+          column: {
+            name: "deleted_at",
+            type: "datetime",
+            nullable: true,
+            primary: false,
+            default: undefined,
+          },
+        });
+      }
+    }
+
+    return { newTables, newColumns, droppedColumns };
+  },
+
+  /**
+   * True when there is nothing *additive* to generate. Dropped columns are
+   * deliberately excluded: `migrate:generate` never emits drops, so a table with
+   * only dropped columns is still "in sync" from the generator's perspective.
+   */
+  isEmpty(diff: DiffResult): boolean {
+    return diff.newTables.length === 0 && diff.newColumns.length === 0;
+  },
+};

package/src/schema/SchemaInspector.ts

@@ -0,0 +1,164 @@
+import { _getDbConnection } from "../db/DB.ts";
+import { _getDialect } from "../model/BaseModel.ts";
+
+// ── DB column descriptor (normalised across dialects) ─────────────────────────
+
+export interface LiveColumn {
+  name: string;
+  rawType: string; // original SQL type string from the DB (uppercase)
+  nullable: boolean;
+  primary: boolean;
+}
+
+export interface LiveTable {
+  name: string;
+  columns: LiveColumn[];
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+/** Execute a no-parameter SQL query and return typed rows. */
+async function queryRaw<T>(sql: string): Promise<T[]> {
+  const conn = _getDbConnection();
+  const strings = [sql];
+  const tpl = Object.assign(strings, { raw: strings }) as TemplateStringsArray;
+  return conn<T>(tpl);
+}
+
+/** Execute a query with exactly one bound parameter and return typed rows. */
+async function queryParam<T>(sql: string, value: unknown): Promise<T[]> {
+  const conn = _getDbConnection();
+  const parts = sql.split("?");
+  const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+  return conn<T>(tpl, value);
+}
+
+// ── SchemaInspector ───────────────────────────────────────────────────────────
+
+/**
+ * Queries the live database to enumerate tables and their column definitions.
+ * Used by `migrate:generate` to compute what has changed since the last migration.
+ */
+export const SchemaInspector = {
+  /** Return all user-defined table names in the current DB. */
+  async tables(): Promise<string[]> {
+    const dialect = _getDialect();
+
+    if (dialect === "postgres") {
+      const rows = await queryRaw<{ table_name: string }>(
+        `SELECT table_name FROM information_schema.tables
+         WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+         ORDER BY table_name`,
+      );
+      return rows.map((r) => r.table_name);
+    }
+
+    if (dialect === "mysql") {
+      const rows = await queryRaw<{ table_name: string }>(
+        `SELECT TABLE_NAME AS table_name FROM INFORMATION_SCHEMA.TABLES
+         WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
+         ORDER BY TABLE_NAME`,
+      );
+      return rows.map((r) => r.table_name);
+    }
+
+    // SQLite
+    const rows = await queryRaw<{ name: string }>(
+      `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`,
+    );
+    return rows.map((r) => r.name);
+  },
+
+  /**
+   * Return column details for a single table, or null if the table doesn't exist.
+   * Table name is sanitised before use — safe against injection even for SQLite PRAGMAs.
+   */
+  async columns(table: string): Promise<LiveColumn[] | null> {
+    const dialect = _getDialect();
+    const safeName = table.replace(/[^a-zA-Z0-9_]/g, "");
+
+    if (dialect === "postgres") {
+      const exists = await queryParam<{ exists: boolean }>(
+        `SELECT EXISTS(
+           SELECT 1 FROM information_schema.tables
+           WHERE table_schema = 'public' AND table_name = ?
+         ) AS exists`,
+        table,
+      );
+      if (!exists[0]?.exists) return null;
+
+      const rows = await queryParam<{
+        column_name: string;
+        data_type: string;
+        is_nullable: string;
+      }>(
+        `SELECT column_name, data_type, is_nullable
+         FROM information_schema.columns
+         WHERE table_schema = 'public' AND table_name = ?
+         ORDER BY ordinal_position`,
+        table,
+      );
+      const pks = await queryParam<{ column_name: string }>(
+        `SELECT kcu.column_name
+         FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           USING (constraint_name, table_schema, table_name)
+         WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_name = ?`,
+        table,
+      );
+      const pkSet = new Set(pks.map((r) => r.column_name));
+      return rows.map((r) => ({
+        name: r.column_name,
+        rawType: r.data_type.toUpperCase(),
+        nullable: r.is_nullable === "YES",
+        primary: pkSet.has(r.column_name),
+      }));
+    }
+
+    if (dialect === "mysql") {
+      const rows = await queryParam<{
+        COLUMN_NAME: string;
+        DATA_TYPE: string;
+        IS_NULLABLE: string;
+        COLUMN_KEY: string;
+      }>(
+        `SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY
+         FROM INFORMATION_SCHEMA.COLUMNS
+         WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?
+         ORDER BY ORDINAL_POSITION`,
+        table,
+      );
+      if (rows.length === 0) return null;
+      return rows.map((r) => ({
+        name: r.COLUMN_NAME,
+        rawType: r.DATA_TYPE.toUpperCase(),
+        nullable: r.IS_NULLABLE === "YES",
+        primary: r.COLUMN_KEY === "PRI",
+      }));
+    }
+
+    // SQLite — PRAGMA table_info (table name must be inlined, not parameterised)
+    const tableExists = await queryParam<{ name: string }>(
+      `SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`,
+      safeName,
+    );
+    if (tableExists.length === 0) return null;
+
+    const rows = await queryRaw<{ name: string; type: string; notnull: number; pk: number }>(
+      `PRAGMA table_info(${safeName})`,
+    );
+    return rows.map((r) => ({
+      name: r.name,
+      rawType: (r.type ?? "TEXT").toUpperCase(),
+      nullable: r.notnull === 0 && r.pk === 0,
+      primary: r.pk > 0,
+    }));
+  },
+
+  /** Return a fully described LiveTable, or null if the table doesn't exist. */
+  async describe(table: string): Promise<LiveTable | null> {
+    const columns = await SchemaInspector.columns(table);
+    if (columns === null) return null;
+    return { name: table, columns };
+  },
+};

package/src/schema/__test_migrations__/001_create_test_table.ts

@@ -0,0 +1,15 @@
+import { Migration } from '../Migration.ts';
+import { Schema } from '../Schema.ts';
+
+export default class CreateTestTable extends Migration {
+  async up(): Promise<void> {
+    await Schema.create('test_from_dir', (table) => {
+      table.increments('id');
+      table.string('label');
+    });
+  }
+
+  async down(): Promise<void> {
+    await Schema.dropIfExists('test_from_dir');
+  }
+}

package/src/schema/autoMigrate.ts

@@ -0,0 +1,154 @@
+import type { ConcernDescriptor } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { ModelInspector, columnDbName } from "./ModelInspector.ts";
+import { SchemaDiffer, type DiffResult } from "./SchemaDiffer.ts";
+import { Schema } from "./Schema.ts";
+import type { ModelColumn } from "./ModelInspector.ts";
+
+// Mirrors MigrationCodegen's mapping so synchronize() produces the same schema as
+// `migrate:generate` would - but applies it directly instead of writing a migration file.
+const BLUEPRINT_METHOD: Record<string, string> = {
+  string: "string",
+  number: "integer",
+  boolean: "boolean",
+  datetime: "dateTime",
+  json: "json",
+};
+
+type ColumnBuilder = { nullable(): ColumnBuilder; default(v: unknown): ColumnBuilder };
+type TableBuilder = Record<string, (name: string) => ColumnBuilder> & {
+  increments(name: string): unknown;
+  timestamps(): void;
+  softDeletes(): void;
+  dropColumn(...names: string[]): unknown;
+};
+
+function applyColumn(table: TableBuilder, col: ModelColumn): void {
+  const method = BLUEPRINT_METHOD[col.type ?? "string"] ?? "string";
+  // Models declare columns in camelCase; the ORM reads/writes snake_case — emit snake_case
+  // so synchronize produces columns the runtime can actually read (e.g. two_factor_secret).
+  const builder = table[method]!(columnDbName(col.name));
+  if (col.nullable) builder.nullable();
+  if (col.default !== undefined) builder.default(col.default);
+}
+
+/** Options for {@link synchronizeSchema}. */
+export interface SynchronizeOptions {
+  /**
+   * When true, also DROP columns that exist in the database but are no longer
+   * declared by any model. Off by default - additive changes are always safe,
+   * drops can lose data.
+   */
+  disruptive?: boolean;
+}
+
+/**
+ * Schema sync (TypeORM-style `synchronize`): create missing tables and add missing columns
+ * to match the registered models. By default it is additive only and never drops or alters
+ * existing columns.
+ *
+ * Pass `{ disruptive: true }` to also drop columns that no model declares anymore - an
+ * explicit opt-in, since dropping a column destroys its data.
+ *
+ * Returns the diff that was applied (additive deltas are empty when already in sync;
+ * `droppedColumns` is populated but only acted on when `disruptive` is set).
+ */
+export async function synchronizeSchema(options: SynchronizeOptions = {}): Promise<DiffResult> {
+  const diff = await SchemaDiffer.diff(ModelInspector.all());
+
+  for (const { schema } of diff.newTables) {
+    await Schema.createIfNotExists(schema.table, (t) => {
+      const table = t as unknown as TableBuilder;
+      table.increments(columnDbName(schema.primaryKey));
+      for (const col of schema.columns) {
+        if (col.primary) continue; // increments() covers the PK
+        applyColumn(table, col);
+      }
+      if (schema.timestamps) table.timestamps();
+      if (schema.softDeletes) table.softDeletes();
+    });
+  }
+
+  const byTable = new Map<string, ModelColumn[]>();
+  for (const nc of diff.newColumns) {
+    const bucket = byTable.get(nc.table) ?? [];
+    bucket.push(nc.column);
+    byTable.set(nc.table, bucket);
+  }
+  for (const [table, cols] of byTable) {
+    await Schema.table(table, (t) => {
+      const tb = t as unknown as TableBuilder;
+      for (const col of cols) applyColumn(tb, col);
+    });
+  }
+
+  // Disruptive phase: drop columns the models no longer declare. Opt-in only.
+  if (options.disruptive && diff.droppedColumns.length > 0) {
+    const dropsByTable = new Map<string, string[]>();
+    for (const dc of diff.droppedColumns) {
+      const bucket = dropsByTable.get(dc.table) ?? [];
+      bucket.push(dc.column);
+      dropsByTable.set(dc.table, bucket);
+    }
+    for (const [table, names] of dropsByTable) {
+      console.warn(
+        `[Zerotal] synchronize (disruptive): dropping ${table}.{${names.join(", ")}} - data will be lost.`,
+      );
+      await Schema.table(table, (t) => {
+        (t as unknown as TableBuilder).dropColumn(...names);
+      });
+    }
+  }
+
+  return diff;
+}
+
+/** Resolved, normalised form of the `database.synchronize` config value. */
+export interface ResolvedSyncOptions {
+  enabled: boolean;
+  disruptive: boolean;
+}
+
+/**
+ * Normalise the polymorphic `database.synchronize` config into `{ enabled, disruptive }`.
+ *
+ *   false / undefined        -> { enabled: false, disruptive: false }
+ *   true                     -> { enabled: true,  disruptive: false }  (additive)
+ *   { enabled, disruptive? } -> as given (enabled defaults true when the object is present)
+ */
+export function resolveSyncOptions(raw: unknown): ResolvedSyncOptions {
+  if (raw === true) return { enabled: true, disruptive: false };
+  if (raw && typeof raw === "object") {
+    const o = raw as { enabled?: boolean; disruptive?: boolean };
+    const enabled = o.enabled !== false;
+    // Disruptive only matters when enabled — force it off otherwise.
+    return { enabled, disruptive: enabled && o.disruptive === true };
+  }
+  return { enabled: false, disruptive: false };
+}
+
+/**
+ * One-shot convention (runs after `models`, order 100). Applies `synchronizeSchema()` only when
+ * `database.synchronize` is enabled - strictly opt-in (like TypeORM), and HARD-OFF in
+ * `production` regardless (use `migrate` with generated files there).
+ *
+ * `synchronize` accepts `true` (additive) or `{ enabled, disruptive }` to also drop columns
+ * no model declares anymore.
+ */
+export const autoMigrateConcern: ConcernDescriptor = {
+  name: "auto-migrate",
+  order: 100,
+  async run(ctx) {
+    // Hard-off in production. `ctx.env` is the runtime mode (web/console/…), so the
+    // deployment name is read from APP_ENV directly.
+    if (Bun.env.APP_ENV === "production") return;
+    const config = ctx.resolve<ConfigManager>("config");
+    const { enabled, disruptive } = resolveSyncOptions(config?.get("database.synchronize"));
+    if (!enabled) return;
+    try {
+      await synchronizeSchema({ disruptive });
+    } catch (err) {
+      console.error("[Zerotal] auto-migrate (synchronize) failed:", err);
+    }
+  },
+};

package/src/schema/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @module schema
+ *
+ * Internal barrel for the schema-builder and migration subsystem: the
+ * {@link Schema} facade, the {@link Blueprint} table builder and its
+ * {@link ColumnBuilder}/{@link ForeignKeyBuilder} column API, the
+ * {@link Migration} base class and {@link MigrationRunner}, plus the introspection
+ * and diffing helpers ({@link SchemaInspector}, {@link ModelInspector},
+ * {@link SchemaDiffer}, {@link generateMigrationContent}) that power
+ * `migrate:generate` and `synchronize`.
+ *
+ * This is not a public package entry point — its members are re-exported from the
+ * package root (`@zerotal/orm`), which is where consumers should import them.
+ */
+export { Blueprint } from "./Blueprint.ts";
+export { ColumnBuilder, ForeignIdColumnBuilder, ForeignKeyBuilder } from "./ColumnDefinition.ts";
+export type { FKAction } from "./ColumnDefinition.ts";
+export { Schema } from "./Schema.ts";
+export { Migration } from "./Migration.ts";
+export { MigrationRunner } from "./MigrationRunner.ts";
+export type { MigrationEntry, MigrationRecord, MigrationStatus } from "./MigrationRunner.ts";
+export { SchemaInspector } from "./SchemaInspector.ts";
+export type { LiveColumn, LiveTable } from "./SchemaInspector.ts";
+export { ModelInspector } from "./ModelInspector.ts";
+export type { ModelColumn, ModelSchema } from "./ModelInspector.ts";
+export { SchemaDiffer } from "./SchemaDiffer.ts";
+export type { DiffResult, NewTable, NewColumn } from "./SchemaDiffer.ts";
+export { generateMigrationContent } from "./MigrationCodegen.ts";

package/src/seeding/Seeder.ts

@@ -0,0 +1,46 @@
+import { DB } from "../db/DB.ts";
+
+/**
+ * Base class for database seeders. Extend it and implement {@link run} to populate
+ * your database; use {@link call} to compose other seeders. Run seeders with the
+ * `db:seed` command.
+ *
+ * @example
+ * ```ts
+ * // database/seeders/DatabaseSeeder.ts
+ * export class DatabaseSeeder extends Seeder {
+ *   async run(): Promise<void> {
+ *     await this.call([UserSeeder, PostSeeder]);
+ *   }
+ * }
+ *
+ * export class UserSeeder extends Seeder {
+ *   async run(): Promise<void> {
+ *     await User.factory().count(10).create();
+ *   }
+ * }
+ * ```
+ */
+export abstract class Seeder {
+  /** Seed logic for this seeder. Implemented by subclasses. */
+  abstract run(): Promise<void>;
+
+  /**
+   * Run other seeder classes in sequence inside a single DB transaction.
+   * If any seeder throws, all changes are rolled back atomically.
+   * Order matters — seed dependencies before dependents (users before posts).
+   *
+   * @param seeders - Seeder classes to instantiate and run, in order.
+   * @returns Resolves once every seeder has run and the transaction commits.
+   */
+  async call(seeders: (new () => Seeder)[]): Promise<void> {
+    const execute = async (): Promise<void> => {
+      for (const SeederClass of seeders) {
+        const instance = new SeederClass();
+        await instance.run();
+      }
+    };
+
+    await DB.transaction(execute);
+  }
+}

package/src/support/identifiers.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared identifier-case helpers — the ORM's one camel/snake implementation.
+ *
+ * Before this module existed there were five copies across three files, with
+ * two different camel regexes. The divergence was live: `_keysetValue` used
+ * `/_([a-z0-9])/g` while hydration used `/_([a-z])/g`, so for a column like
+ * `user_2fa` the keyset lookup asked for `user2fa` on an instance whose
+ * property was `user_2fa` — the cursor encoded `undefined` and keyset
+ * pagination restarted from the top.
+ *
+ * The letters-only regex is canonical **because hydration uses it**: every
+ * helper that reads a property off a hydrated instance must derive the same
+ * name hydration produced.
+ */
+
+// DB schemas are static: the same names appear on every row. Caching the regex
+// result turns thousands of executions into Map lookups after the first query.
+const _camelCache = new Map<string, string>();
+const _snakeCache = new Map<string, string>();
+
+/** snake_case → camelCase, memoized. Matches BaseModel hydration exactly. */
+export function toCamelKey(s: string): string {
+  let v = _camelCache.get(s);
+  if (v === undefined) {
+    v = s.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+    _camelCache.set(s, v);
+  }
+  return v;
+}
+
+/**
+ * Convert a model property name to its database column name (camelCase →
+ * snake_case), mirroring the convention BaseModel uses on read/write. Raw
+ * expressions (anything beyond identifier/dot characters) and already-snake
+ * names pass through unchanged, so it is safe and idempotent to apply to any
+ * caller-supplied column — qualified `table.createdAt` resolves cleanly too.
+ */
+export function toSnakeColumn(s: string): string {
+  if (/[^\w.]/.test(s)) return s; // raw expression / function call — leave as-is
+  let v = _snakeCache.get(s);
+  if (v === undefined) {
+    v = s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+    _snakeCache.set(s, v);
+  }
+  return v;
+}
+
+/**
+ * The constructor prototype chain of `ctor`, base-first — so a subclass's
+ * entries override its parents' when merged in order. Terminates on
+ * `Function.prototype` (not a falsy `.name`) so anonymous mixin classes are
+ * still visited. Shared by cast collection and global-scope merging.
+ */
+export function ctorChain(ctor: Function): Function[] {
+  const chain: Function[] = [];
+  let current: Function | null = ctor;
+  while (current && current !== Function.prototype) {
+    chain.unshift(current);
+    current = Object.getPrototypeOf(current) as Function | null;
+  }
+  return chain;
+}