sealed-migrations 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,151 @@
+//#region src/types.d.ts
+/**
+ * The subset of a database connection the runner needs. A `mysql2/promise`
+ * Connection satisfies it structurally (so a consumer can pass
+ * `mysql.createConnection(...)` with no cast), and so does any compatible
+ * driver or test fake. The consumer owns the driver, so this package has no
+ * runtime dependency on mysql2 (or any specific client).
+ *
+ * `params` and the row tuples are intentionally loose: this is the untyped
+ * driver boundary, and a stricter shape would reject real driver types through
+ * parameter contravariance. Callers narrow rows internally.
+ */
+interface MigrationConnection {
+  query: <T = any>(sql: string) => Promise<[T, any]>;
+  execute: <T = any>(sql: string, params?: any) => Promise<[T, any]>;
+  beginTransaction: () => Promise<void>;
+  commit: () => Promise<void>;
+  rollback: () => Promise<void>;
+  end?: () => Promise<void>;
+}
+type Logger = Pick<Console, 'log' | 'warn' | 'error'>;
+interface RunnerConfig {
+  /** Path to the migrations directory (absolute, or relative to `process.cwd()`). */
+  migrationsDir: string;
+  /** Opens a connection the runner owns and closes for a single command. */
+  connect: () => Promise<MigrationConnection>;
+  /** MySQL advisory lock name serialising up/down/seal/rehash. */
+  lockName?: string;
+  /** Seconds to wait for the advisory lock (default 120). */
+  lockTimeoutSec?: number;
+  /** Version treated as the baseline (default `001_baseline`). */
+  baselineVersion?: string;
+  /**
+   * Database name, used only to detect an existing schema for the baseline
+   * short-circuit. Omit to always execute the baseline SQL.
+   */
+  databaseName?: string;
+  /** Optional pre-flight assertion, e.g. refuse a non-MariaDB server. */
+  assertServer?: (conn: MigrationConnection) => Promise<void>;
+  /**
+   * Wraps retryable writes, e.g. a Galera deadlock retry. Defaults to a plain
+   * pass-through, so a single-writer setup needs no configuration.
+   */
+  withRetry?: <T>(fn: () => Promise<T>, label: string) => Promise<T>;
+  /** Recorded in `schema_migrations.app_version`. */
+  appVersion?: string | null;
+  /** Recorded in `schema_migrations.executed_by`. */
+  executedBy?: string | null;
+  /** Sink for progress messages (default `console`). */
+  logger?: Logger;
+}
+type TxMode = 'transactional' | 'non_transactional' | 'baseline_mark';
+interface ParsedMigrationName {
+  isDev: boolean;
+  sortNumber: number;
+  version: string;
+  description: string;
+}
+interface Migration extends ParsedMigrationName {
+  upSql: string;
+  downSql: string;
+  checksum: string;
+}
+interface AppliedMigration {
+  checksum: string;
+  appliedAt?: unknown;
+}
+type AppliedMap = Map<string, AppliedMigration>;
+interface ValidateOptions {
+  /** How a checksum mismatch on an applied dev migration is handled. */
+  devChecksumMismatch?: 'error' | 'warn';
+}
+interface UpOptions {
+  to?: string;
+  allowDev?: boolean;
+}
+interface DownOptions {
+  to?: string;
+}
+//#endregion
+//#region src/commands.d.ts
+declare function assertDevMigrationsAllowed(migrations: Migration[], allowDev: boolean): void;
+/** Next free number = max(numbered repo folders ∪ numbered applied versions) + 1. */
+declare function computeNextSealNumber(migrations: Migration[], appliedVersions: string[]): string;
+declare function commandCurrent(conn: MigrationConnection, migrations: Migration[], logger: Logger): Promise<void>;
+declare function commandStatus(conn: MigrationConnection, migrations: Migration[], logger: Logger): Promise<void>;
+declare function commandUp(conn: MigrationConnection, migrations: Migration[], config: RunnerConfig, options: UpOptions, logger: Logger): Promise<void>;
+declare function commandDown(conn: MigrationConnection, migrations: Migration[], options: DownOptions, logger: Logger): Promise<void>;
+declare function commandSeal(conn: MigrationConnection, migrations: Migration[], migrationsDir: string, slug: string | undefined, logger: Logger): Promise<void>;
+declare function commandRehash(conn: MigrationConnection, migrations: Migration[], slug: string | undefined, logger: Logger): Promise<void>;
+//#endregion
+//#region src/migrations.d.ts
+declare const MIGRATION_DIR_PATTERN: RegExp;
+declare const DEV_MIGRATION_DIR_PATTERN: RegExp;
+/** SHA-256 of `up.sql + "\n--down-sql--\n" + down.sql`, content only. */
+declare function hashMigration(upSql: string, downSql: string): string;
+declare function isDevVersion(version: string): boolean;
+declare function parseMigrationDirName(dirName: string): ParsedMigrationName;
+/**
+ * Normalises a `seal`/`rehash` argument into a `dev_<slug>` version. Accepts
+ * both `foo` and `dev_foo`, and refuses sealed (numbered) versions, which are
+ * immutable.
+ */
+declare function normalizeDevVersion(input: string | undefined): string;
+/**
+ * Reads every migration folder, sorted numbered-ascending then dev
+ * alphabetical. Duplicate numeric prefixes stay deterministic via the folder
+ * name tie-break.
+ */
+declare function readMigrations(migrationsDir: string): Promise<Migration[]>;
+//#endregion
+//#region src/runner.d.ts
+interface ParsedArgs {
+  args: Record<string, string | boolean>;
+  positionals: string[];
+}
+/** Minimal `--flag`, `--key=value`, `--key value` and positional parser. */
+declare function parseArgs(argv: string[]): ParsedArgs;
+interface Runner {
+  up: (options?: UpOptions) => Promise<void>;
+  down: (options: DownOptions) => Promise<void>;
+  seal: (slug: string) => Promise<void>;
+  rehash: (slug: string) => Promise<void>;
+  current: () => Promise<void>;
+  status: () => Promise<void>;
+  /** Parses `argv` (without node/script), dispatches, and throws on error. */
+  runCli: (argv: string[]) => Promise<void>;
+}
+declare function createRunner(config: RunnerConfig): Runner;
+//#endregion
+//#region src/sql.d.ts
+declare function splitSqlStatements(sqlFileContent: string): string[];
+/**
+ * Picks the transaction mode for a migration file. An explicit
+ * `-- migrate: tx | no-tx | auto` directive wins; otherwise DDL forces the
+ * non-transactional path (MySQL/MariaDB cannot roll back DDL).
+ */
+declare function resolveTxMode(sql: string, statements: string[]): 'transactional' | 'non_transactional';
+//#endregion
+//#region src/state.d.ts
+/**
+ * Checks applied state against the repo:
+ * - a dev migration applied elsewhere but missing here is only a warning
+ *   (the normal state of a shared dev DB with parallel branches),
+ * - a numbered migration missing here is a hard error (sealed history is strict),
+ * - a checksum mismatch is a hard error, except a dev mismatch in `warn` mode
+ *   (the `down` path, so the SQL-first edit loop can start).
+ */
+declare function validateAppliedState(migrations: Migration[], appliedByVersion: AppliedMap, options?: ValidateOptions, logger?: Logger): void;
+//#endregion
+export { type AppliedMap, type AppliedMigration, DEV_MIGRATION_DIR_PATTERN, type DownOptions, type Logger, MIGRATION_DIR_PATTERN, type Migration, type MigrationConnection, type ParsedArgs, type ParsedMigrationName, type Runner, type RunnerConfig, type TxMode, type UpOptions, type ValidateOptions, assertDevMigrationsAllowed, commandCurrent, commandDown, commandRehash, commandSeal, commandStatus, commandUp, computeNextSealNumber, createRunner, hashMigration, isDevVersion, normalizeDevVersion, parseArgs, parseMigrationDirName, readMigrations, resolveTxMode, splitSqlStatements, validateAppliedState };

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+//#region src/types.d.ts
+/**
+ * The subset of a database connection the runner needs. A `mysql2/promise`
+ * Connection satisfies it structurally (so a consumer can pass
+ * `mysql.createConnection(...)` with no cast), and so does any compatible
+ * driver or test fake. The consumer owns the driver, so this package has no
+ * runtime dependency on mysql2 (or any specific client).
+ *
+ * `params` and the row tuples are intentionally loose: this is the untyped
+ * driver boundary, and a stricter shape would reject real driver types through
+ * parameter contravariance. Callers narrow rows internally.
+ */
+interface MigrationConnection {
+  query: <T = any>(sql: string) => Promise<[T, any]>;
+  execute: <T = any>(sql: string, params?: any) => Promise<[T, any]>;
+  beginTransaction: () => Promise<void>;
+  commit: () => Promise<void>;
+  rollback: () => Promise<void>;
+  end?: () => Promise<void>;
+}
+type Logger = Pick<Console, 'log' | 'warn' | 'error'>;
+interface RunnerConfig {
+  /** Path to the migrations directory (absolute, or relative to `process.cwd()`). */
+  migrationsDir: string;
+  /** Opens a connection the runner owns and closes for a single command. */
+  connect: () => Promise<MigrationConnection>;
+  /** MySQL advisory lock name serialising up/down/seal/rehash. */
+  lockName?: string;
+  /** Seconds to wait for the advisory lock (default 120). */
+  lockTimeoutSec?: number;
+  /** Version treated as the baseline (default `001_baseline`). */
+  baselineVersion?: string;
+  /**
+   * Database name, used only to detect an existing schema for the baseline
+   * short-circuit. Omit to always execute the baseline SQL.
+   */
+  databaseName?: string;
+  /** Optional pre-flight assertion, e.g. refuse a non-MariaDB server. */
+  assertServer?: (conn: MigrationConnection) => Promise<void>;
+  /**
+   * Wraps retryable writes, e.g. a Galera deadlock retry. Defaults to a plain
+   * pass-through, so a single-writer setup needs no configuration.
+   */
+  withRetry?: <T>(fn: () => Promise<T>, label: string) => Promise<T>;
+  /** Recorded in `schema_migrations.app_version`. */
+  appVersion?: string | null;
+  /** Recorded in `schema_migrations.executed_by`. */
+  executedBy?: string | null;
+  /** Sink for progress messages (default `console`). */
+  logger?: Logger;
+}
+type TxMode = 'transactional' | 'non_transactional' | 'baseline_mark';
+interface ParsedMigrationName {
+  isDev: boolean;
+  sortNumber: number;
+  version: string;
+  description: string;
+}
+interface Migration extends ParsedMigrationName {
+  upSql: string;
+  downSql: string;
+  checksum: string;
+}
+interface AppliedMigration {
+  checksum: string;
+  appliedAt?: unknown;
+}
+type AppliedMap = Map<string, AppliedMigration>;
+interface ValidateOptions {
+  /** How a checksum mismatch on an applied dev migration is handled. */
+  devChecksumMismatch?: 'error' | 'warn';
+}
+interface UpOptions {
+  to?: string;
+  allowDev?: boolean;
+}
+interface DownOptions {
+  to?: string;
+}
+//#endregion
+//#region src/commands.d.ts
+declare function assertDevMigrationsAllowed(migrations: Migration[], allowDev: boolean): void;
+/** Next free number = max(numbered repo folders ∪ numbered applied versions) + 1. */
+declare function computeNextSealNumber(migrations: Migration[], appliedVersions: string[]): string;
+declare function commandCurrent(conn: MigrationConnection, migrations: Migration[], logger: Logger): Promise<void>;
+declare function commandStatus(conn: MigrationConnection, migrations: Migration[], logger: Logger): Promise<void>;
+declare function commandUp(conn: MigrationConnection, migrations: Migration[], config: RunnerConfig, options: UpOptions, logger: Logger): Promise<void>;
+declare function commandDown(conn: MigrationConnection, migrations: Migration[], options: DownOptions, logger: Logger): Promise<void>;
+declare function commandSeal(conn: MigrationConnection, migrations: Migration[], migrationsDir: string, slug: string | undefined, logger: Logger): Promise<void>;
+declare function commandRehash(conn: MigrationConnection, migrations: Migration[], slug: string | undefined, logger: Logger): Promise<void>;
+//#endregion
+//#region src/migrations.d.ts
+declare const MIGRATION_DIR_PATTERN: RegExp;
+declare const DEV_MIGRATION_DIR_PATTERN: RegExp;
+/** SHA-256 of `up.sql + "\n--down-sql--\n" + down.sql`, content only. */
+declare function hashMigration(upSql: string, downSql: string): string;
+declare function isDevVersion(version: string): boolean;
+declare function parseMigrationDirName(dirName: string): ParsedMigrationName;
+/**
+ * Normalises a `seal`/`rehash` argument into a `dev_<slug>` version. Accepts
+ * both `foo` and `dev_foo`, and refuses sealed (numbered) versions, which are
+ * immutable.
+ */
+declare function normalizeDevVersion(input: string | undefined): string;
+/**
+ * Reads every migration folder, sorted numbered-ascending then dev
+ * alphabetical. Duplicate numeric prefixes stay deterministic via the folder
+ * name tie-break.
+ */
+declare function readMigrations(migrationsDir: string): Promise<Migration[]>;
+//#endregion
+//#region src/runner.d.ts
+interface ParsedArgs {
+  args: Record<string, string | boolean>;
+  positionals: string[];
+}
+/** Minimal `--flag`, `--key=value`, `--key value` and positional parser. */
+declare function parseArgs(argv: string[]): ParsedArgs;
+interface Runner {
+  up: (options?: UpOptions) => Promise<void>;
+  down: (options: DownOptions) => Promise<void>;
+  seal: (slug: string) => Promise<void>;
+  rehash: (slug: string) => Promise<void>;
+  current: () => Promise<void>;
+  status: () => Promise<void>;
+  /** Parses `argv` (without node/script), dispatches, and throws on error. */
+  runCli: (argv: string[]) => Promise<void>;
+}
+declare function createRunner(config: RunnerConfig): Runner;
+//#endregion
+//#region src/sql.d.ts
+declare function splitSqlStatements(sqlFileContent: string): string[];
+/**
+ * Picks the transaction mode for a migration file. An explicit
+ * `-- migrate: tx | no-tx | auto` directive wins; otherwise DDL forces the
+ * non-transactional path (MySQL/MariaDB cannot roll back DDL).
+ */
+declare function resolveTxMode(sql: string, statements: string[]): 'transactional' | 'non_transactional';
+//#endregion
+//#region src/state.d.ts
+/**
+ * Checks applied state against the repo:
+ * - a dev migration applied elsewhere but missing here is only a warning
+ *   (the normal state of a shared dev DB with parallel branches),
+ * - a numbered migration missing here is a hard error (sealed history is strict),
+ * - a checksum mismatch is a hard error, except a dev mismatch in `warn` mode
+ *   (the `down` path, so the SQL-first edit loop can start).
+ */
+declare function validateAppliedState(migrations: Migration[], appliedByVersion: AppliedMap, options?: ValidateOptions, logger?: Logger): void;
+//#endregion
+export { type AppliedMap, type AppliedMigration, DEV_MIGRATION_DIR_PATTERN, type DownOptions, type Logger, MIGRATION_DIR_PATTERN, type Migration, type MigrationConnection, type ParsedArgs, type ParsedMigrationName, type Runner, type RunnerConfig, type TxMode, type UpOptions, type ValidateOptions, assertDevMigrationsAllowed, commandCurrent, commandDown, commandRehash, commandSeal, commandStatus, commandUp, computeNextSealNumber, createRunner, hashMigration, isDevVersion, normalizeDevVersion, parseArgs, parseMigrationDirName, readMigrations, resolveTxMode, splitSqlStatements, validateAppliedState };