@deterministic-code/migraters 0.0.0-stage → 0.0.1

package/src/abstractions/migrater.ts

@@ -0,0 +1,13 @@
+export type SetupArg = { connection: string; migrationsPath: string };
+export type UpArg = { connection: string; migrationsPath: string; one?: boolean };
+export type DownArg = { connection: string; migrationsPath: string };
+export type CreateArg = { name: string; migrationsPath: string };
+export type CreateResponse = { upName: string; downName: string };
+
+export interface IMigrater {
+  readonly name: string;
+  setup(args: SetupArg): Promise<void>;
+  up(args: UpArg): Promise<string[]>;
+  down(args: DownArg): Promise<string | null>;
+  create(args: CreateArg): Promise<CreateResponse>;
+}

package/src/abstractions/sql-dialect-base.ts

@@ -0,0 +1,36 @@
+import type { SqlDialect } from '../sql.ts';
+import type { ISqlDialect } from './sql-dialect.ts';
+
+export abstract class SqlDialectBase implements ISqlDialect {
+  abstract readonly name: SqlDialect;
+  abstract readonly connectionEnvironmentVariables: readonly string[];
+  abstract readonly migratesDdl: string;
+  abstract readonly migrateLogsDdl: string;
+  readonly usesLastInsertRowid: boolean = false;
+
+  quoteIdent(ident: string): string {
+    return `"${ident}"`;
+  }
+
+  nowExpr(): string {
+    return 'CURRENT_TIMESTAMP';
+  }
+
+  limitClause(n: number): string {
+    return `LIMIT ${n}`;
+  }
+
+  translatePlaceholders(sql: string): string {
+    return sql;
+  }
+
+  async prerequisiteError(_connection: string): Promise<string | null> {
+    return null;
+  }
+
+  async prepareSetup(_connection: string): Promise<void> {}
+
+  abstract createClient(
+    connection: string,
+  ): Promise<import('../migration-client.ts').MigrationClient>;
+}

package/src/abstractions/sql-dialect-factory.ts

@@ -0,0 +1,29 @@
+import { normalizeDialect, type SqlDialect } from '../sql.ts';
+import type { ISqlDialect } from './sql-dialect.ts';
+
+const VALID = 'sqlite, mysql, postgres, sqlserver, oracle';
+
+export class SqlDialectFactory {
+  private readonly byName: Map<SqlDialect, ISqlDialect>;
+
+  constructor(dialects: readonly ISqlDialect[]) {
+    this.byName = new Map(dialects.map((d) => [d.name, d]));
+  }
+
+  tryGet(raw: string): ISqlDialect | undefined {
+    const key = normalizeDialect(raw);
+    return key ? this.byName.get(key) : undefined;
+  }
+
+  get(raw: string): ISqlDialect {
+    const dialect = this.tryGet(raw);
+    if (!dialect) {
+      throw new Error(`Unknown SQL dialect "${raw}". Valid: ${VALID}.`);
+    }
+    return dialect;
+  }
+
+  all(): readonly ISqlDialect[] {
+    return [...this.byName.values()];
+  }
+}

package/src/abstractions/sql-dialect.ts

@@ -0,0 +1,17 @@
+import type { MigrationClient } from '../migration-client.ts';
+import type { SqlDialect } from '../sql.ts';
+
+export interface ISqlDialect {
+  readonly name: SqlDialect;
+  readonly connectionEnvironmentVariables: readonly string[];
+  readonly migratesDdl: string;
+  readonly migrateLogsDdl: string;
+  readonly usesLastInsertRowid: boolean;
+  quoteIdent(ident: string): string;
+  nowExpr(): string;
+  limitClause(n: number): string;
+  translatePlaceholders(sql: string): string;
+  prerequisiteError(connection: string): Promise<string | null>;
+  prepareSetup(connection: string): Promise<void>;
+  createClient(connection: string): Promise<MigrationClient>;
+}

package/src/bin/migrate-create.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Scaffolds a new <NNNN>_<name>_{up,down}.sql pair in the migrations directory. Numbering is max(1-4-digit prefix in dir)+1; legacy timestamp prefixes are ignored.
+
+import { missingProviderMsg, requireDialect, takeFlag } from '../cli.ts';
+import { isMigrationName } from '../create-sequence.ts';
+import { fillTemplate, loadMessage } from '../infrastructure/message-templates.ts';
+import { loadHelp, Migrater } from '../index.ts';
+
+const [HELP_TEXT, unknownArgTpl, missingNameMsg, invalidNameTpl, createdTpl] = await Promise.all([
+  loadHelp('migrate-create'),
+  loadMessage('errors/unknown-arg'),
+  loadMessage('errors/missing-name'),
+  loadMessage('errors/invalid-name'),
+  loadMessage('status/created'),
+]);
+
+const parseArgs = (argv: string[]) => {
+  const args: {
+    provider: string | null;
+    name: string | null;
+    migrationsPath: string | null;
+  } = { provider: null, name: null, migrationsPath: null };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i] as string;
+    if (a === '-h' || a === '--help') {
+      process.stderr.write(HELP_TEXT);
+      process.exit(0);
+    }
+    let taken;
+    if ((taken = takeFlag(rest, i, a, '--provider'))) {
+      args.provider = taken.value;
+      i = taken.next;
+    } else if ((taken = takeFlag(rest, i, a, '--name'))) {
+      args.name = taken.value;
+      i = taken.next;
+    } else if (
+      (taken = takeFlag(rest, i, a, '--migrations-path')) ||
+      (taken = takeFlag(rest, i, a, '--migrate-path'))
+    ) {
+      args.migrationsPath = taken.value;
+      i = taken.next;
+    } else {
+      process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
+      process.exit(2);
+    }
+  }
+  return args;
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv);
+  if (!args.provider) {
+    process.stderr.write(missingProviderMsg);
+    process.exit(2);
+  }
+  const dialect = requireDialect(args.provider);
+  if (!args.name) {
+    process.stderr.write(missingNameMsg);
+    process.exit(2);
+  }
+  if (!isMigrationName(args.name)) {
+    process.stderr.write(fillTemplate(invalidNameTpl, { name: args.name }));
+    process.exit(2);
+  }
+
+  const migrationsPath = args.migrationsPath ?? `./sql/${dialect.name}/migrations`;
+  const { upName, downName } = await new Migrater(dialect).create({
+    name: args.name,
+    migrationsPath,
+  });
+  process.stdout.write(fillTemplate(createdTpl, { file: upName }));
+  process.stdout.write(fillTemplate(createdTpl, { file: downName }));
+};
+
+main().catch((e: unknown) => {
+  const err = e as Error;
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
+  process.exit(1);
+});

package/src/bin/migrate-down.ts

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Rolls back the most recently applied migration (one step). DESTRUCTIVE: prints a random 4-letter uppercase confirmation token and refuses to proceed unless the user types it back on stdin. Pass --confirm <TOKEN> matching the printed token to bypass the interactive prompt (CI / scripted use).
+
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { missingProviderMsg, requireConnection, requireDialect, takeFlag } from '../cli.ts';
+import { fillTemplate, loadMessage } from '../infrastructure/message-templates.ts';
+import { loadHelp, Migrater } from '../index.ts';
+
+const [
+  HELP_TEXT,
+  unknownArgTpl,
+  destructiveHeaderTpl,
+  confirmMismatchTpl,
+  confirmTtyRequiredTpl,
+  confirmPromptTpl,
+  confirmTokenMismatchMsg,
+  noRollbackMsg,
+  rolledBackTpl,
+] = await Promise.all([
+  loadHelp('migrate-down'),
+  loadMessage('errors/unknown-arg'),
+  loadMessage('down/destructive-header'),
+  loadMessage('down/confirm-mismatch'),
+  loadMessage('down/confirm-tty-required'),
+  loadMessage('down/confirm-prompt'),
+  loadMessage('down/confirm-token-mismatch'),
+  loadMessage('status/no-rollback'),
+  loadMessage('status/rolled-back'),
+]);
+
+const parseArgs = (argv: string[]) => {
+  const args: {
+    provider: string | null;
+    migratePath: string | null;
+    migrateRoot: string | null;
+    connection: string | null;
+    confirm: string | null;
+  } = {
+    provider: null,
+    migratePath: null,
+    migrateRoot: null,
+    connection: null,
+    confirm: null,
+  };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i] as string;
+    if (a === '-h' || a === '--help') {
+      process.stderr.write(HELP_TEXT);
+      process.exit(0);
+    }
+    let taken;
+    if ((taken = takeFlag(rest, i, a, '--provider'))) {
+      args.provider = taken.value;
+      i = taken.next;
+    } else if (
+      (taken = takeFlag(rest, i, a, '--migrations-path')) ||
+      (taken = takeFlag(rest, i, a, '--migrate-path'))
+    ) {
+      args.migratePath = taken.value;
+      i = taken.next;
+    } else if (
+      (taken = takeFlag(rest, i, a, '--migrations-root')) ||
+      (taken = takeFlag(rest, i, a, '--migrate-root'))
+    ) {
+      args.migrateRoot = taken.value;
+      i = taken.next;
+    } else if ((taken = takeFlag(rest, i, a, '--connection'))) {
+      args.connection = taken.value;
+      i = taken.next;
+    } else if ((taken = takeFlag(rest, i, a, '--confirm'))) {
+      args.confirm = taken.value;
+      i = taken.next;
+    } else {
+      process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
+      process.exit(2);
+    }
+  }
+  return args;
+};
+
+const resolveMigratePath = (
+  args: { migratePath: string | null; migrateRoot: string | null },
+  dialect: string,
+): string => {
+  if (args.migratePath) return args.migratePath;
+  const root = args.migrateRoot ?? 'sql';
+  return `${root}/${dialect}/migrations`;
+};
+
+const randomToken = (): string => {
+  const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ';
+  const buf = new Uint8Array(4);
+  globalThis.crypto.getRandomValues(buf);
+  let out = '';
+  for (let i = 0; i < 4; i++) out += alphabet[(buf[i] as number) % alphabet.length];
+  return out;
+};
+
+const promptConfirmation = async (token: string): Promise<boolean> => {
+  if (!process.stdin.isTTY) {
+    process.stderr.write(fillTemplate(confirmTtyRequiredTpl, { token }));
+    process.exit(2);
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await rl.question(fillTemplate(confirmPromptTpl, { token }));
+    return answer.trim() === token;
+  } finally {
+    rl.close();
+  }
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv);
+  if (!args.provider) {
+    process.stderr.write(missingProviderMsg);
+    process.exit(2);
+  }
+  const dialect = requireDialect(args.provider);
+  const connection = requireConnection(dialect, args.connection);
+
+  const missing = await dialect.prerequisiteError(connection);
+  if (missing !== null) {
+    process.stderr.write(`${missing}\n`);
+    process.exit(2);
+  }
+
+  const token = randomToken();
+  process.stderr.write(
+    fillTemplate(destructiveHeaderTpl, { dialect: dialect.name, token }),
+  );
+
+  if (args.confirm !== null) {
+    if (args.confirm !== token) {
+      process.stderr.write(
+        fillTemplate(confirmMismatchTpl, { supplied: args.confirm, token }),
+      );
+      process.exit(2);
+    }
+  } else {
+    const ok = await promptConfirmation(token);
+    if (!ok) {
+      process.stderr.write(confirmTokenMismatchMsg);
+      process.exit(2);
+    }
+  }
+
+  const migratePath = resolve(resolveMigratePath(args, dialect.name));
+  const name = await new Migrater(dialect).down({
+    connection,
+    migrationsPath: migratePath,
+  });
+  if (name == null) process.stdout.write(noRollbackMsg);
+  else process.stdout.write(fillTemplate(rolledBackTpl, { name }));
+};
+
+main().catch((e: unknown) => {
+  const err = e as Error;
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
+  process.exit(1);
+});

package/src/bin/migrate-init.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { loadHelp } from '../help.ts';
+import { loadSelectedPackages, resolveInitDialects } from '../init-select.ts';
+
+const HELP_TEXT = await loadHelp('migrate-init');
+
+const takeFlag = (
+  rest: string[],
+  i: number,
+  arg: string,
+  flag: string,
+): { value: string; next: number } | undefined => {
+  const eq = `${flag}=`;
+  if (arg === flag) {
+    const value = rest[i + 1];
+    if (value === undefined) return undefined;
+    return { value, next: i + 1 };
+  }
+  if (arg.startsWith(eq)) return { value: arg.slice(eq.length), next: i };
+  return undefined;
+};
+
+const parseArgs = (argv: string[]) => {
+  const dialects: string[] = [];
+  let all = false;
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i] as string;
+    if (a === '-h' || a === '--help') {
+      process.stderr.write(HELP_TEXT);
+      process.exit(0);
+    }
+    if (a === '--all') {
+      all = true;
+      continue;
+    }
+    const taken = takeFlag(rest, i, a, '--dialect');
+    if (taken) {
+      dialects.push(taken.value);
+      i = taken.next;
+      continue;
+    }
+    process.stderr.write(`unknown arg: ${a}\n`);
+    process.exit(2);
+  }
+  return { dialects, all };
+};
+
+const npmFlags = ['--no-audit', '--no-fund', '--loglevel=error'];
+
+const npm = (args: string[]): void => {
+  const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(cmd, args, { stdio: 'inherit', cwd: process.cwd() });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv);
+  let names: string[];
+  try {
+    names = resolveInitDialects(args.dialects, args.all);
+  } catch (e) {
+    const err = e as Error;
+    process.stderr.write(`${err.message}\n`);
+    process.exit(2);
+  }
+  const selected = await loadSelectedPackages(names);
+  const specs = selected.packages.map((p) => `${p.name}@${p.version}`);
+  if (specs.length > 0) {
+    npm(['install', ...npmFlags, ...specs]);
+  }
+  const remove = selected.allDriverPackages.filter(
+    (name) => !selected.packages.some((p) => p.name === name),
+  );
+  if (remove.length > 0) {
+    npm(['uninstall', ...npmFlags, ...remove]);
+  }
+  process.stdout.write(`Enabled dialects: ${selected.names.join(', ')}\n`);
+};
+
+main().catch((e: unknown) => {
+  const err = e as Error;
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
+  process.exit(1);
+});

package/src/bin/migrate-setup.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// Idempotent migrate-setup — creates the migrates + migrate_logs tracking tables per dialect.
+
+import { missingProviderMsg, requireConnection, requireDialect, takeFlag } from '../cli.ts';
+import { fillTemplate, loadMessage } from '../infrastructure/message-templates.ts';
+import { loadHelp, Migrater } from '../index.ts';
+
+const [HELP_TEXT, unknownArgTpl, setupCompleteTpl] = await Promise.all([
+  loadHelp('migrate-setup'),
+  loadMessage('errors/unknown-arg'),
+  loadMessage('setup-complete'),
+]);
+
+const parseArgs = (argv: string[]) => {
+  const args: {
+    provider: string | null;
+    connection: string | null;
+    migrationsPath: string | null;
+    andUp: boolean;
+  } = {
+    provider: null,
+    connection: null,
+    migrationsPath: null,
+    andUp: false,
+  };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i] as string;
+    if (a === '-h' || a === '--help') {
+      process.stderr.write(HELP_TEXT);
+      process.exit(0);
+    }
+    if (a === '--and-up') {
+      args.andUp = true;
+      continue;
+    }
+    let taken;
+    if ((taken = takeFlag(rest, i, a, '--provider'))) {
+      args.provider = taken.value;
+      i = taken.next;
+    } else if ((taken = takeFlag(rest, i, a, '--connection'))) {
+      args.connection = taken.value;
+      i = taken.next;
+    } else if (
+      (taken = takeFlag(rest, i, a, '--migrations-path')) ||
+      (taken = takeFlag(rest, i, a, '--migrate-path'))
+    ) {
+      args.migrationsPath = taken.value;
+      i = taken.next;
+    } else {
+      process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
+      process.exit(2);
+    }
+  }
+  return args;
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv);
+  if (!args.provider) {
+    process.stderr.write(missingProviderMsg);
+    process.exit(2);
+  }
+  const dialect = requireDialect(args.provider);
+  const connection = requireConnection(dialect, args.connection);
+
+  const migrationsPath = args.migrationsPath ?? `./sql/${dialect.name}/migrations`;
+  const migrater = new Migrater(dialect);
+  await migrater.setup({ connection, migrationsPath });
+  process.stdout.write(
+    fillTemplate(setupCompleteTpl, {
+      dialect: dialect.name,
+      migrationsPath,
+      createExample: `  migrate-create --provider ${dialect.name} --name add_users`,
+      upExample: `  migrate-up --provider ${dialect.name} --connection ${connection}`,
+    }),
+  );
+
+  if (args.andUp) {
+    const names = await migrater.up({ connection, migrationsPath });
+    const [noPendingMsg, noMorePendingMsg, appliedTpl] = await Promise.all([
+      loadMessage('status/no-pending'),
+      loadMessage('status/no-more-pending'),
+      loadMessage('status/applied'),
+    ]);
+    if (names.length === 0) process.stdout.write(noPendingMsg);
+    else {
+      for (const name of names) process.stdout.write(fillTemplate(appliedTpl, { name }));
+      process.stdout.write(noMorePendingMsg);
+    }
+  }
+};
+
+main().catch((e: unknown) => {
+  const err = e as Error;
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
+  process.exit(1);
+});

package/src/bin/migrate-up.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Default: applies ALL pending migrations in sequence, each in its own transaction. Pass --one to apply only the next pending migration (legacy one-shot behavior; useful when wrapping in an external loop or when you want to inspect state between steps).
+
+import { resolve } from 'node:path';
+import { missingProviderMsg, requireConnection, requireDialect, takeFlag } from '../cli.ts';
+import { fillTemplate, loadMessage } from '../infrastructure/message-templates.ts';
+import { loadHelp, Migrater } from '../index.ts';
+
+const [HELP_TEXT, unknownArgTpl, noPendingMsg, noMorePendingMsg, appliedTpl] = await Promise.all([
+  loadHelp('migrate-up'),
+  loadMessage('errors/unknown-arg'),
+  loadMessage('status/no-pending'),
+  loadMessage('status/no-more-pending'),
+  loadMessage('status/applied'),
+]);
+
+const parseArgs = (argv: string[]) => {
+  const args: {
+    provider: string | null;
+    migratePath: string | null;
+    migrateRoot: string | null;
+    connection: string | null;
+    one: boolean;
+  } = {
+    provider: null,
+    migratePath: null,
+    migrateRoot: null,
+    connection: null,
+    one: false,
+  };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i] as string;
+    if (a === '-h' || a === '--help') {
+      process.stderr.write(HELP_TEXT);
+      process.exit(0);
+    }
+    if (a === '--one') {
+      args.one = true;
+      continue;
+    }
+    let taken;
+    if ((taken = takeFlag(rest, i, a, '--provider'))) {
+      args.provider = taken.value;
+      i = taken.next;
+    } else if (
+      (taken = takeFlag(rest, i, a, '--migrations-path')) ||
+      (taken = takeFlag(rest, i, a, '--migrate-path'))
+    ) {
+      args.migratePath = taken.value;
+      i = taken.next;
+    } else if (
+      (taken = takeFlag(rest, i, a, '--migrations-root')) ||
+      (taken = takeFlag(rest, i, a, '--migrate-root'))
+    ) {
+      args.migrateRoot = taken.value;
+      i = taken.next;
+    } else if ((taken = takeFlag(rest, i, a, '--connection'))) {
+      args.connection = taken.value;
+      i = taken.next;
+    } else {
+      process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
+      process.exit(2);
+    }
+  }
+  return args;
+};
+
+const resolveMigratePath = (
+  args: { migratePath: string | null; migrateRoot: string | null },
+  dialect: string,
+): string => {
+  if (args.migratePath) return args.migratePath;
+  const root = args.migrateRoot ?? 'sql';
+  return `${root}/${dialect}/migrations`;
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv);
+  if (!args.provider) {
+    process.stderr.write(missingProviderMsg);
+    process.exit(2);
+  }
+  const dialect = requireDialect(args.provider);
+  const connection = requireConnection(dialect, args.connection);
+
+  const missing = await dialect.prerequisiteError(connection);
+  if (missing !== null) {
+    process.stderr.write(`${missing}\n`);
+    process.exit(2);
+  }
+
+  const migratePath = resolve(resolveMigratePath(args, dialect.name));
+  const names = await new Migrater(dialect).up({
+    connection,
+    migrationsPath: migratePath,
+    one: args.one,
+  });
+  if (names.length === 0) {
+    process.stdout.write(noPendingMsg);
+    return;
+  }
+  for (const name of names) process.stdout.write(fillTemplate(appliedTpl, { name }));
+  if (!args.one) process.stdout.write(noMorePendingMsg);
+};
+
+main().catch((e: unknown) => {
+  const err = e as Error;
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
+  process.exit(1);
+});

package/src/cli-contract.ts

@@ -0,0 +1,25 @@
+export type { MigrateVerb } from './cli-spec.ts';
+export { migrateCommand, usageLine, programUsageText } from './cli-spec.ts';
+import { usageLine, type MigrateVerb } from './cli-spec.ts';
+import { fillTemplate } from './infrastructure/message-templates.ts';
+
+export const MIGRATE_VERBS = ['setup', 'up', 'down', 'create'] as const;
+
+export const verbFromCommand = (command: string): MigrateVerb => {
+  const verb = command.replace(/^migrate-/, '');
+  if (
+    verb !== 'init' &&
+    verb !== 'setup' &&
+    verb !== 'up' &&
+    verb !== 'down' &&
+    verb !== 'create'
+  ) {
+    throw new Error(`Unknown migrate command "${command}"`);
+  }
+  return verb;
+};
+
+export const fillHelpTemplate = (text: string, command: string): string => {
+  const usage = usageLine(verbFromCommand(command));
+  return fillTemplate(text, { command, usage });
+};