@maestro-js/db-migrate 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,307 @@
+# DbMigrations
+
+## Overview
+
+The `@maestro-js/db-migrate` package is a standalone migration runner for managing database schema changes. It discovers timestamped migration files from a directory, tracks applied migrations in a database table, and provides up/down/reset/status/scaffold operations with transaction safety and dry-run support.
+
+## Quick Setup
+
+```ts
+import { DbMigrations } from '@maestro-js/db-migrate'
+
+// Run all pending migrations against a database connection
+const results = await DbMigrations.migrate(db, './migrations')
+
+// Check current migration status
+const statuses = await DbMigrations.status(db, './migrations')
+```
+
+The `db` parameter accepts any object matching the `DbMigrations.Db` interface -- a structural subset of `Db.DbService` from `@maestro-js/db`.
+
+## Migration File Format
+
+Migration files must follow the naming pattern `{14-digit-timestamp}_{name}.[jt]s` (e.g., `20240615120000_create_users.ts`). Each file must export `up(db)` and `down(db)` functions.
+
+### Scaffolded migration structure
+
+Running `DbMigrations.scaffold({ name: 'create_users', dir: './migrations' })` creates:
+
+```
+migrations/
+  20240615120000_create_users.ts
+  sqls/
+    20240615120000_create_users-up.sql
+    20240615120000_create_users-down.sql
+```
+
+The generated `.ts` file reads companion SQL files at runtime:
+
+```ts
+import type { DbMigrations } from '@maestro-js/db-migrate'
+import { readFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export async function up(db: DbMigrations.Db) {
+  const sql = await readFile(join(__dirname, 'sqls', '20240615120000_create_users-up.sql'), 'utf-8')
+  await db.statement(sql)
+}
+
+export async function down(db: DbMigrations.Db) {
+  const sql = await readFile(join(__dirname, 'sqls', '20240615120000_create_users-down.sql'), 'utf-8')
+  await db.statement(sql)
+}
+```
+
+### Manual migration (no SQL files)
+
+Write `up` and `down` directly in the `.ts` file:
+
+```ts
+import type { DbMigrations } from '@maestro-js/db-migrate'
+
+export async function up(db: DbMigrations.Db) {
+  await db.statement(`
+    CREATE TABLE users (
+      id INT NOT NULL AUTO_INCREMENT,
+      email VARCHAR(255) NOT NULL,
+      PRIMARY KEY (id)
+    )
+  `)
+}
+
+export async function down(db: DbMigrations.Db) {
+  await db.statement('DROP TABLE users')
+}
+```
+
+## API Reference
+
+### DbMigrations.migrate(db, migrationsDir, options?)
+
+Run all pending migrations in timestamp order. Discovers migration files, compares against the tracking table, and executes each pending `up()` within a transaction.
+
+```ts
+migrate(
+  db: DbMigrations.Db,
+  migrationsDir: string,
+  options?: DbMigrations.RunOptions
+): Promise<DbMigrations.ExecutionResult[]>
+```
+
+**RunOptions:**
+- `count?: number` -- limit how many pending migrations to run
+- `dryRun?: boolean` -- preview without executing (default `false`)
+- `tableName?: string` -- tracking table name (default `'migrations'`)
+
+```ts
+// Run all pending
+const results = await DbMigrations.migrate(db, './migrations')
+
+// Run only the next 2 pending migrations
+const results = await DbMigrations.migrate(db, './migrations', { count: 2 })
+
+// Dry-run to preview what would run
+const results = await DbMigrations.migrate(db, './migrations', { dryRun: true })
+```
+
+### DbMigrations.rollback(db, migrationsDir, options?)
+
+Revert applied migrations in reverse chronological order. Defaults to rolling back a single migration when `count` is not specified.
+
+```ts
+rollback(
+  db: DbMigrations.Db,
+  migrationsDir: string,
+  options?: DbMigrations.RunOptions
+): Promise<DbMigrations.ExecutionResult[]>
+```
+
+```ts
+// Rollback the last applied migration
+const results = await DbMigrations.rollback(db, './migrations')
+
+// Rollback the last 3 migrations
+const results = await DbMigrations.rollback(db, './migrations', { count: 3 })
+```
+
+### DbMigrations.reset(db, migrationsDir, options?)
+
+Roll back ALL applied migrations. Delegates to `rollback` with the full count of applied migrations.
+
+```ts
+reset(
+  db: DbMigrations.Db,
+  migrationsDir: string,
+  options?: { dryRun?: boolean; tableName?: string }
+): Promise<DbMigrations.ExecutionResult[]>
+```
+
+```ts
+const results = await DbMigrations.reset(db, './migrations')
+```
+
+### DbMigrations.status(db, migrationsDir, options?)
+
+Return the status of every discovered migration -- whether it has been applied and when.
+
+```ts
+status(
+  db: DbMigrations.Db,
+  migrationsDir: string,
+  options?: { tableName?: string }
+): Promise<DbMigrations.MigrationStatus[]>
+```
+
+Each `MigrationStatus` contains:
+- `version: string` -- the 14-digit timestamp
+- `name: string` -- the migration name from the filename
+- `filename: string` -- full filename
+- `applied: boolean` -- whether the migration has been run
+- `run_on: string | null` -- datetime string when applied, or `null`
+
+```ts
+const statuses = await DbMigrations.status(db, './migrations')
+// [
+//   { version: '20240101000000', name: 'create_users', applied: true, run_on: '2024-01-15T10:30:00' },
+//   { version: '20240102000000', name: 'add_email_index', applied: false, run_on: null }
+// ]
+```
+
+### DbMigrations.scaffold(options)
+
+Create a new migration file and its companion SQL templates. Returns paths of all created files.
+
+```ts
+scaffold(options: DbMigrations.ScaffoldOptions): Promise<{ ts: string; upSql: string; downSql: string }>
+```
+
+**ScaffoldOptions:**
+- `name: string` -- descriptive migration name (e.g., `'create_orders'`)
+- `dir: string` -- directory to create files in
+
+```ts
+const files = await DbMigrations.scaffold({ name: 'create_orders', dir: './migrations' })
+// { ts: './migrations/20240615120000_create_orders.ts',
+//   upSql: './migrations/sqls/20240615120000_create_orders-up.sql',
+//   downSql: './migrations/sqls/20240615120000_create_orders-down.sql' }
+```
+
+### DbMigrations.discover(migrationsDir)
+
+Scan a directory for migration files matching the `{14-digit-timestamp}_{name}.[jt]s` pattern. Returns them sorted by version. Returns an empty array if the directory does not exist.
+
+```ts
+discover(migrationsDir: string): Promise<DbMigrations.Migration[]>
+```
+
+Each `Migration` contains:
+- `version: string` -- 14-digit timestamp
+- `name: string` -- migration name
+- `filename: string` -- full filename
+- `filepath: string` -- absolute path to the file
+
+## Common Patterns
+
+### Create and run a new migration
+
+```ts
+// 1. Scaffold the migration files
+const files = await DbMigrations.scaffold({ name: 'add_orders_table', dir: './migrations' })
+
+// 2. Write SQL in the generated -up.sql and -down.sql files
+
+// 3. Run pending migrations
+const results = await DbMigrations.migrate(db, './migrations')
+```
+
+### Preview before running
+
+```ts
+// Dry-run returns ExecutionResults with dryRun: true and durationMs: 0
+const preview = await DbMigrations.migrate(db, './migrations', { dryRun: true })
+for (const r of preview) {
+  console.log(`Would run: ${r.filename} (${r.direction})`)
+}
+```
+
+### Rollback and re-run during development
+
+```ts
+// Undo the last migration
+await DbMigrations.rollback(db, './migrations')
+
+// Edit the migration file, then re-apply
+await DbMigrations.migrate(db, './migrations')
+```
+
+### Use a custom tracking table
+
+```ts
+// All functions accept a tableName option (default: 'migrations')
+await DbMigrations.migrate(db, './migrations', { tableName: 'schema_migrations' })
+await DbMigrations.status(db, './migrations', { tableName: 'schema_migrations' })
+```
+
+The table name is validated against `/^[a-zA-Z_]\w*$/` to prevent SQL injection.
+
+## Key Types
+
+```ts
+declare namespace DbMigrations {
+  /** Database interface required by all migration functions. Structural subset of Db.DbService. */
+  interface Db {
+    select<T>(query: string, parameters?: any[]): Promise<T[]>
+    insert(query: string, parameters?: any[]): Promise<{ affectedRows: number; insertId: number }>
+    delete(query: string, parameters?: any[]): Promise<{ affectedRows: number }>
+    statement<T>(query: string, parameters?: any[]): Promise<T>
+    transaction: <T>(callback: () => Promise<T>) => Promise<T>
+  }
+
+  interface Migration { version: string; name: string; filename: string; filepath: string }
+  interface MigrationStatus { version: string; name: string; filename: string; applied: boolean; run_on: string | null }
+  interface ExecutionResult { version: string; name: string; filename: string; direction: 'up' | 'down'; durationMs: number; dryRun: boolean }
+  interface RunOptions { count?: number; dryRun?: boolean; tableName?: string }
+  interface ScaffoldOptions { name: string; dir: string }
+}
+```
+
+## Cross-Package Integration
+
+### Works with @maestro-js/db
+
+The `DbMigrations.Db` interface is a structural subset of `Db.DbService`. Pass a db service instance directly:
+
+```ts
+import { Db } from '@maestro-js/db'
+import { DbMigrations } from '@maestro-js/db-migrate'
+
+// The Db service satisfies DbMigrations.Db structurally
+await DbMigrations.migrate(Db, './migrations')
+```
+
+> **Note:** If migration SQL files contain multiple statements (separated by `;`), the database connection must have `multipleStatements: true` enabled in its MySQL configuration.
+
+## Internal Behavior
+
+- The tracking table (`migrations` by default) is auto-created via `CREATE TABLE IF NOT EXISTS` on every operation.
+- Each migration `up()` and `down()` runs inside `db.transaction()`. The tracking record insert/delete is part of the same transaction.
+- Migration names are stored in the tracking table as `/{version}_{name}` (prefixed with `/`).
+- The filename pattern regex is `/^(\d{14})_(.+)\.[jt]s$/` -- only `.js` and `.ts` files with exactly 14 leading digits are discovered.
+- `discover` returns an empty array (not an error) when the directory does not exist.
+- Scaffold generates a 14-digit timestamp from the current date/time: `YYYYMMDDHHmmss`.
+
+## Testing
+
+Build and test with:
+
+```bash
+pnpm --filter @maestro-js/db-migrate build
+pnpm --filter @maestro-js/db-migrate test
+pnpm --filter @maestro-js/db-migrate typecheck
+```
+
+Source: `packages/db-migrate/src/index.ts`
+Tests: `packages/db-migrate/tests/db-migrate.test.ts`

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+declare const DbMigrations: {
+    migrate: typeof migrate;
+    rollback: typeof rollback;
+    reset: typeof reset;
+    status: typeof status;
+    scaffold: typeof scaffold;
+    discover: typeof discover;
+};
+declare namespace DbMigrations {
+    /** Database interface required by all migration functions. Structural subset of `Db.DbService`. */
+    interface Db {
+        select<T>(query: string, parameters?: any[]): Promise<T[]>;
+        insert(query: string, parameters?: any[]): Promise<{
+            affectedRows: number;
+            insertId: number;
+        }>;
+        delete(query: string, parameters?: any[]): Promise<{
+            affectedRows: number;
+        }>;
+        /** If migration SQL files contain multiple statements, the connection must have `multipleStatements: true`. */
+        statement<T>(query: string, parameters?: any[]): Promise<T>;
+        transaction: <T>(callback: () => Promise<T>) => Promise<T>;
+    }
+    /** Discovered migration file metadata parsed from the filename. */
+    interface Migration {
+        version: string;
+        name: string;
+        filename: string;
+        filepath: string;
+    }
+    /** Combined discovery and applied state for a single migration. */
+    interface MigrationStatus {
+        version: string;
+        name: string;
+        filename: string;
+        applied: boolean;
+        run_on: string | null;
+    }
+    /** Result returned after executing a single migration (up or down). */
+    interface ExecutionResult {
+        version: string;
+        name: string;
+        filename: string;
+        direction: 'up' | 'down';
+        durationMs: number;
+        dryRun: boolean;
+    }
+    /** Options shared by orchestrator functions (`migrate`, `rollback`, `reset`). */
+    interface RunOptions {
+        count?: number;
+        dryRun?: boolean;
+        tableName?: string;
+    }
+    /** Options for scaffolding a new migration. */
+    interface ScaffoldOptions {
+        name: string;
+        dir: string;
+    }
+}
+/**
+ * Runs all pending migrations in timestamp order.
+ * Discovers migration files, compares against the tracking table, and executes
+ * each pending `up()` function within a transaction.
+ */
+declare function migrate(db: DbMigrations.Db, migrationsDir: string, options?: DbMigrations.RunOptions): Promise<DbMigrations.ExecutionResult[]>;
+/**
+ * Reverts applied migrations in reverse chronological order.
+ * Defaults to rolling back a single migration when `count` is not specified.
+ */
+declare function rollback(db: DbMigrations.Db, migrationsDir: string, options?: DbMigrations.RunOptions): Promise<DbMigrations.ExecutionResult[]>;
+/**
+ * Rolls back ALL applied migrations by delegating to {@link rollback} with the full count.
+ */
+declare function reset(db: DbMigrations.Db, migrationsDir: string, options?: {
+    dryRun?: boolean;
+    tableName?: string;
+}): Promise<DbMigrations.ExecutionResult[]>;
+/**
+ * Returns the status of every discovered migration — whether it has been applied and when.
+ */
+declare function status(db: DbMigrations.Db, migrationsDir: string, options?: {
+    tableName?: string;
+}): Promise<DbMigrations.MigrationStatus[]>;
+/**
+ * Creates a new migration file and its companion SQL templates.
+ * Returns the paths of all created files.
+ */
+declare function scaffold(options: DbMigrations.ScaffoldOptions): Promise<{
+    ts: string;
+    upSql: string;
+    downSql: string;
+}>;
+/** Scans a directory for `.js`/`.ts` files matching the `{14-digit-timestamp}_{name}.[jt]s` pattern. */
+declare function discover(migrationsDir: string): Promise<DbMigrations.Migration[]>;
+
+export { DbMigrations };

package/dist/index.js

@@ -0,0 +1,220 @@
+// src/index.ts
+import { mkdir, readdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { pathToFileURL } from "url";
+var DbMigrations = {
+  migrate,
+  rollback,
+  reset,
+  status,
+  scaffold,
+  discover
+};
+async function migrate(db, migrationsDir, options) {
+  const tableName = options?.tableName ?? DEFAULT_TABLE;
+  const dryRun = options?.dryRun ?? false;
+  const count = options?.count;
+  await ensureTable(db, tableName);
+  const [discovered, applied] = await Promise.all([discover(migrationsDir), getApplied(db, tableName)]);
+  const appliedNames = new Set(applied.map((r) => r.name));
+  let pending = discovered.filter((m) => !appliedNames.has(dbName(m)));
+  if (count !== void 0) {
+    pending = pending.slice(0, count);
+  }
+  if (pending.length === 0) return [];
+  const results = [];
+  for (const migration of pending) {
+    const result = await runUp(db, migration, { dryRun, tableName });
+    results.push(result);
+  }
+  return results;
+}
+async function rollback(db, migrationsDir, options) {
+  const tableName = options?.tableName ?? DEFAULT_TABLE;
+  const dryRun = options?.dryRun ?? false;
+  const count = options?.count ?? 1;
+  await ensureTable(db, tableName);
+  const [discovered, applied] = await Promise.all([discover(migrationsDir), getApplied(db, tableName)]);
+  const migrationsByDbName = new Map(discovered.map((m) => [dbName(m), m]));
+  const toRevert = [...applied].reverse().slice(0, count);
+  const results = [];
+  for (const record of toRevert) {
+    const migration = migrationsByDbName.get(record.name);
+    if (!migration) {
+      throw new Error(`Migration file not found for ${record.name}`);
+    }
+    const result = await runDown(db, migration, { dryRun, tableName });
+    results.push(result);
+  }
+  return results;
+}
+async function reset(db, migrationsDir, options) {
+  const tableName = options?.tableName ?? DEFAULT_TABLE;
+  await ensureTable(db, tableName);
+  const applied = await getApplied(db, tableName);
+  if (applied.length === 0) return [];
+  return rollback(db, migrationsDir, {
+    count: applied.length,
+    dryRun: options?.dryRun,
+    tableName
+  });
+}
+async function status(db, migrationsDir, options) {
+  const tableName = options?.tableName ?? DEFAULT_TABLE;
+  await ensureTable(db, tableName);
+  const [discovered, applied] = await Promise.all([discover(migrationsDir), getApplied(db, tableName)]);
+  const appliedMap = new Map(applied.map((r) => [r.name, r]));
+  return discovered.map((m) => {
+    const record = appliedMap.get(dbName(m));
+    return {
+      version: m.version,
+      name: m.name,
+      filename: m.filename,
+      applied: !!record,
+      run_on: record?.run_on ?? null
+    };
+  });
+}
+async function runUp(db, migration, options) {
+  const tableName = options?.tableName ?? DEFAULT_TABLE;
+  const dryRun = options?.dryRun ?? false;
+  if (dryRun) {
+    return {
+      version: migration.version,
+      name: migration.name,
+      filename: migration.filename,
+      direction: "up",
+      durationMs: 0,
+      dryRun: true
+    };
+  }
+  const mod = await importMigration(migration.filepath);
+  const start = performance.now();
+  await db.transaction(async () => {
+    await mod.up(db);
+    await db.insert(`INSERT INTO ${tableName} (name, run_on) VALUES (?, NOW())`, [dbName(migration)]);
+  });
+  return {
+    version: migration.version,
+    name: migration.name,
+    filename: migration.filename,
+    direction: "up",
+    durationMs: Math.round(performance.now() - start),
+    dryRun: false
+  };
+}
+async function runDown(db, migration, options) {
+  const tableName = options?.tableName ?? DEFAULT_TABLE;
+  const dryRun = options?.dryRun ?? false;
+  if (dryRun) {
+    return {
+      version: migration.version,
+      name: migration.name,
+      filename: migration.filename,
+      direction: "down",
+      durationMs: 0,
+      dryRun: true
+    };
+  }
+  const mod = await importMigration(migration.filepath);
+  const start = performance.now();
+  await db.transaction(async () => {
+    await mod.down(db);
+    await db.delete(`DELETE FROM ${tableName} WHERE name = ?`, [dbName(migration)]);
+  });
+  return {
+    version: migration.version,
+    name: migration.name,
+    filename: migration.filename,
+    direction: "down",
+    durationMs: Math.round(performance.now() - start),
+    dryRun: false
+  };
+}
+async function scaffold(options) {
+  const { name, dir } = options;
+  const sqlsDir = join(dir, "sqls");
+  await mkdir(sqlsDir, { recursive: true });
+  const timestamp = generateTimestamp();
+  const baseName = `${timestamp}_${name}`;
+  const tsFile = join(dir, `${baseName}.ts`);
+  const upSqlFile = join(sqlsDir, `${baseName}-up.sql`);
+  const downSqlFile = join(sqlsDir, `${baseName}-down.sql`);
+  await Promise.all([writeFile(tsFile, tsTemplate(baseName)), writeFile(upSqlFile, ""), writeFile(downSqlFile, "")]);
+  return { ts: tsFile, upSql: upSqlFile, downSql: downSqlFile };
+}
+var DEFAULT_TABLE = "migrations";
+var MIGRATION_PATTERN = /^(\d{14})_(.+)\.[jt]s$/;
+var SAFE_IDENTIFIER = /^[a-zA-Z_]\w*$/;
+function validateTableName(tableName) {
+  if (!SAFE_IDENTIFIER.test(tableName)) {
+    throw new Error(`Invalid table name: "${tableName}". Must match /^[a-zA-Z_]\\w*$/.`);
+  }
+}
+async function ensureTable(db, tableName = DEFAULT_TABLE) {
+  validateTableName(tableName);
+  await db.statement(`
+    CREATE TABLE IF NOT EXISTS ${tableName} (
+      id INT NOT NULL AUTO_INCREMENT,
+      name VARCHAR(255) NOT NULL,
+      run_on DATETIME NOT NULL,
+      PRIMARY KEY (id)
+    )
+  `);
+}
+async function getApplied(db, tableName = DEFAULT_TABLE) {
+  validateTableName(tableName);
+  return db.select(`SELECT * FROM ${tableName} ORDER BY name ASC`);
+}
+async function discover(migrationsDir) {
+  let entries;
+  try {
+    entries = await readdir(migrationsDir);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  return entries.map((filename) => {
+    const match = filename.match(MIGRATION_PATTERN);
+    if (!match) return null;
+    const [, version, name] = match;
+    return { version, name, filename, filepath: join(migrationsDir, filename) };
+  }).filter((m) => m !== null).sort((a, b) => a.version.localeCompare(b.version));
+}
+async function importMigration(filepath) {
+  const mod = await import(pathToFileURL(filepath).href);
+  if (typeof mod.up !== "function" || typeof mod.down !== "function") {
+    throw new Error(`Migration ${filepath} must export up(db) and down(db) functions`);
+  }
+  return mod;
+}
+function dbName(m) {
+  return `/${m.version}_${m.name}`;
+}
+function tsTemplate(baseName) {
+  return `import type { DbMigrations } from '@maestro-js/db-migrate'
+import { readFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export async function up(db: DbMigrations.Db) {
+  const sql = await readFile(join(__dirname, 'sqls', '${baseName}-up.sql'), 'utf-8')
+  await db.statement(sql)
+}
+
+export async function down(db: DbMigrations.Db) {
+  const sql = await readFile(join(__dirname, 'sqls', '${baseName}-down.sql'), 'utf-8')
+  await db.statement(sql)
+}
+`;
+}
+function generateTimestamp() {
+  const now = /* @__PURE__ */ new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return String(now.getFullYear()) + pad(now.getMonth() + 1) + pad(now.getDate()) + pad(now.getHours()) + pad(now.getMinutes()) + pad(now.getSeconds());
+}
+export {
+  DbMigrations
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@maestro-js/db-migrate",
+  "description": "Use when working with @maestro-js/db-migrate. Standalone database migration runner with up/down support, dry-run mode, and file scaffolding. Trigger when creating, running, rolling back, or inspecting database migrations. Key capabilities include running pending migrations, rolling back applied migrations, resetting all migrations, checking migration status, scaffolding new migration files with SQL templates, and dry-run previews.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "test": "beartest ./tests/**/*",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}