tempest-db-js 0.1.0 → 0.3.0

package/dist/migrations/index.d.cts

@@ -1,4 +1,4 @@
-import { ColumnType, DefaultValue, ModelClass, Dialect, SyncDriver, AsyncDriver } from '../index.cjs';
+import { ColumnType, DefaultValue, ModelClass, Dialect, AsyncDriver, SyncDriver } from '../index.cjs';
 
 /**
  * tempest-db-js — Phase 6: the Schema IR (intermediate representation).
@@ -106,11 +106,11 @@ declare function invert(op: Operation): Operation;
 declare function invertAll(ops: readonly Operation[]): Operation[];
 
 /**
- * tempest-db-js — Phase 6: DDL rendering.
+ * tempest-db-js — Phase 6/9: DDL rendering.
  *
  * Renders the dialect-neutral IR + operations to concrete SQL per dialect. This
  * is the ONLY place migration SQL is produced — the same operation yields the
- * right DDL for SQLite or PostgreSQL.
+ * right DDL for SQLite, PostgreSQL or MySQL.
  */
 
 /** Map a column type to its SQL type string for the dialect. */
@@ -126,7 +126,7 @@ declare function renderColumnDef(col: ColumnIR, dialect: Dialect): string;
  * @param dialect The target dialect.
  * @returns The SQL statements (usually one).
  * @throws Error When the operation is unsupported on the dialect (e.g. SQLite
- *   `alter_column`, which needs the Phase 6e batch/table-rebuild path).
+ *   `alter_column`, which needs the table-rebuild path).
  */
 declare function renderOperation(op: Operation, dialect: Dialect): string[];
 
@@ -280,6 +280,43 @@ declare class MigrationRunner {
      */
     downgrade(migrations: readonly Migration[], steps?: number): string[];
 }
+/**
+ * Runs migrations against an **async** driver (PostgreSQL, or any async driver),
+ * tracking applied revisions. Mirrors {@link MigrationRunner} but every statement
+ * is awaited, and identifier quoting + placeholder style follow the dialect —
+ * so the version table and its bookkeeping are portable across SQLite/PG/MySQL.
+ */
+declare class AsyncMigrationRunner {
+    private readonly driver;
+    private readonly dialect;
+    private readonly vt;
+    constructor(driver: AsyncDriver, dialect: Dialect);
+    /** Create the version-tracking table if it does not exist. */
+    ensureVersionTable(): Promise<void>;
+    /** A portable "text" column type for the version table. */
+    private textType;
+    /** The set of applied revision ids. */
+    applied(): Promise<Set<string>>;
+    private runOps;
+    private record;
+    private forget;
+    /**
+     * Apply all pending migrations up to the head(s), in DAG order.
+     *
+     * @param migrations All known migrations.
+     * @param appliedAt Timestamp string to stamp on each applied revision.
+     * @returns The revision ids that were applied this run.
+     */
+    upgrade(migrations: readonly Migration[], appliedAt: string): Promise<string[]>;
+    /**
+     * Revert the last `steps` applied migrations (default 1), newest first.
+     *
+     * @param migrations All known migrations.
+     * @param steps How many applied revisions to roll back.
+     * @returns The revision ids that were reverted.
+     */
+    downgrade(migrations: readonly Migration[], steps?: number): Promise<string[]>;
+}
 
 /**
  * tempest-db-js — Phase 6d: SQLite introspection + drift detection.
@@ -353,6 +390,56 @@ declare function applyOperation(schema: SchemaIR, op: Operation): SchemaIR;
  */
 declare function replaySchema(migrations: readonly Migration[]): SchemaIR;
 
+/**
+ * tempest-db-js — Phase 6: rename detection.
+ *
+ * The differ ({@link diffSchema}) is deliberately conservative: a renamed column
+ * looks like a drop + add, and a renamed table like a drop + create. That is the
+ * *safe* default (never guesses), but it loses data. This module turns those
+ * add/drop pairs into rename *candidates* the CLI can confirm — interactively at
+ * a TTY, or explicitly via flags — and folds confirmed ones back into a single
+ * `rename_table` / `rename_column` operation.
+ *
+ * Everything here is pure and structural (no SQL, no DB, no I/O), so the
+ * detection and folding are fully testable; the actual prompting lives in the
+ * `tempest-db` bin.
+ */
+
+/** A possible rename the differ emitted as a drop + add/create pair. */
+type RenameCandidate = {
+    readonly kind: "table";
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: "column";
+    readonly table: string;
+    readonly from: string;
+    readonly to: string;
+};
+/**
+ * Detect rename candidates in a forward operation list.
+ *
+ * A table rename is a `create_table` + `drop_table` whose column shapes match
+ * exactly. A column rename is an `add_column` + `drop_column` on the same table
+ * whose column shapes match exactly. Only unambiguous 1:1 shape matches are
+ * reported — if two dropped columns share a shape, neither is offered (the
+ * mapping would be a guess).
+ *
+ * @param ops The forward operations from {@link diffSchema}.
+ * @returns The rename candidates found (never mutates `ops`).
+ */
+declare function detectRenames(ops: readonly Operation[]): RenameCandidate[];
+/**
+ * Fold confirmed renames into an operation list: each confirmed candidate's
+ * drop + add/create pair is removed and replaced by a single rename operation,
+ * inserted at the position of the first op it replaces (preserving order).
+ *
+ * @param ops The forward operations from {@link diffSchema}.
+ * @param confirmed The rename candidates the user accepted.
+ * @returns A new operation list with renames applied.
+ */
+declare function applyRenames(ops: readonly Operation[], confirmed: readonly RenameCandidate[]): Operation[];
+
 /**
  * tempest-db-js — migration CLI (programmatic core).
  *
@@ -376,6 +463,30 @@ interface CliResult {
     readonly code: number;
     readonly lines: string[];
 }
+/**
+ * Identity helper for authoring a typed migration config file. Gives editor
+ * autocompletion and type-checking on the object the `tempest-db` bin loads.
+ *
+ * @example
+ * ```ts
+ * // tempest-db.config.mjs
+ * import { defineMigrationConfig } from "tempest-db-js/migrations";
+ * import { NodeSqliteDriver } from "tempest-db-js";
+ * import { migrations } from "./migrations/index.js";
+ * import { User } from "./models.js";
+ *
+ * export default defineMigrationConfig({
+ *   driver: NodeSqliteDriver.open("app.db"),
+ *   dialect: "sqlite",
+ *   migrations,
+ *   models: [User],
+ * });
+ * ```
+ *
+ * @param config The migration config to pass through unchanged.
+ * @returns The same config, typed as `CliConfig`.
+ */
+declare function defineMigrationConfig(config: CliConfig): CliConfig;
 /**
  * Run one CLI command.
  *
@@ -388,4 +499,4 @@ interface CliResult {
  */
 declare function runMigrationCli(argv: readonly string[], config: CliConfig): CliResult;
 
-export { type CliConfig, type CliResult, type ColumnIR, CyclicMigrationGraph, type DefaultIR, IrreversibleMigration, type Migration, type MigrationDraft, MigrationRunner, Op, type Operation, type RevisionNode, type SchemaIR, type SqliteAffinity, type TableIR, UnknownRevision, applyOperation, checkDrift, checkDriftPostgres, diffSchema, emptySchema, generateMigration, heads, introspectPostgres, introspectSqlite, invert, invertAll, makeRevisionId, reflectSchema, reflectTable, renderColumnDef, renderColumnType, renderDefault, renderOperation, replaySchema, runMigrationCli, sqliteAffinity, topoOrder };
+export { AsyncMigrationRunner, type CliConfig, type CliResult, type ColumnIR, CyclicMigrationGraph, type DefaultIR, IrreversibleMigration, type Migration, type MigrationDraft, MigrationRunner, Op, type Operation, type RenameCandidate, type RevisionNode, type SchemaIR, type SqliteAffinity, type TableIR, UnknownRevision, applyOperation, applyRenames, checkDrift, checkDriftPostgres, defineMigrationConfig, detectRenames, diffSchema, emptySchema, generateMigration, heads, introspectPostgres, introspectSqlite, invert, invertAll, makeRevisionId, reflectSchema, reflectTable, renderColumnDef, renderColumnType, renderDefault, renderOperation, replaySchema, runMigrationCli, sqliteAffinity, topoOrder };

package/dist/migrations/index.d.ts

@@ -1,4 +1,4 @@
-import { ColumnType, DefaultValue, ModelClass, Dialect, SyncDriver, AsyncDriver } from '../index.js';
+import { ColumnType, DefaultValue, ModelClass, Dialect, AsyncDriver, SyncDriver } from '../index.js';
 
 /**
  * tempest-db-js — Phase 6: the Schema IR (intermediate representation).
@@ -106,11 +106,11 @@ declare function invert(op: Operation): Operation;
 declare function invertAll(ops: readonly Operation[]): Operation[];
 
 /**
- * tempest-db-js — Phase 6: DDL rendering.
+ * tempest-db-js — Phase 6/9: DDL rendering.
  *
  * Renders the dialect-neutral IR + operations to concrete SQL per dialect. This
  * is the ONLY place migration SQL is produced — the same operation yields the
- * right DDL for SQLite or PostgreSQL.
+ * right DDL for SQLite, PostgreSQL or MySQL.
  */
 
 /** Map a column type to its SQL type string for the dialect. */
@@ -126,7 +126,7 @@ declare function renderColumnDef(col: ColumnIR, dialect: Dialect): string;
  * @param dialect The target dialect.
  * @returns The SQL statements (usually one).
  * @throws Error When the operation is unsupported on the dialect (e.g. SQLite
- *   `alter_column`, which needs the Phase 6e batch/table-rebuild path).
+ *   `alter_column`, which needs the table-rebuild path).
  */
 declare function renderOperation(op: Operation, dialect: Dialect): string[];
 
@@ -280,6 +280,43 @@ declare class MigrationRunner {
      */
     downgrade(migrations: readonly Migration[], steps?: number): string[];
 }
+/**
+ * Runs migrations against an **async** driver (PostgreSQL, or any async driver),
+ * tracking applied revisions. Mirrors {@link MigrationRunner} but every statement
+ * is awaited, and identifier quoting + placeholder style follow the dialect —
+ * so the version table and its bookkeeping are portable across SQLite/PG/MySQL.
+ */
+declare class AsyncMigrationRunner {
+    private readonly driver;
+    private readonly dialect;
+    private readonly vt;
+    constructor(driver: AsyncDriver, dialect: Dialect);
+    /** Create the version-tracking table if it does not exist. */
+    ensureVersionTable(): Promise<void>;
+    /** A portable "text" column type for the version table. */
+    private textType;
+    /** The set of applied revision ids. */
+    applied(): Promise<Set<string>>;
+    private runOps;
+    private record;
+    private forget;
+    /**
+     * Apply all pending migrations up to the head(s), in DAG order.
+     *
+     * @param migrations All known migrations.
+     * @param appliedAt Timestamp string to stamp on each applied revision.
+     * @returns The revision ids that were applied this run.
+     */
+    upgrade(migrations: readonly Migration[], appliedAt: string): Promise<string[]>;
+    /**
+     * Revert the last `steps` applied migrations (default 1), newest first.
+     *
+     * @param migrations All known migrations.
+     * @param steps How many applied revisions to roll back.
+     * @returns The revision ids that were reverted.
+     */
+    downgrade(migrations: readonly Migration[], steps?: number): Promise<string[]>;
+}
 
 /**
  * tempest-db-js — Phase 6d: SQLite introspection + drift detection.
@@ -353,6 +390,56 @@ declare function applyOperation(schema: SchemaIR, op: Operation): SchemaIR;
  */
 declare function replaySchema(migrations: readonly Migration[]): SchemaIR;
 
+/**
+ * tempest-db-js — Phase 6: rename detection.
+ *
+ * The differ ({@link diffSchema}) is deliberately conservative: a renamed column
+ * looks like a drop + add, and a renamed table like a drop + create. That is the
+ * *safe* default (never guesses), but it loses data. This module turns those
+ * add/drop pairs into rename *candidates* the CLI can confirm — interactively at
+ * a TTY, or explicitly via flags — and folds confirmed ones back into a single
+ * `rename_table` / `rename_column` operation.
+ *
+ * Everything here is pure and structural (no SQL, no DB, no I/O), so the
+ * detection and folding are fully testable; the actual prompting lives in the
+ * `tempest-db` bin.
+ */
+
+/** A possible rename the differ emitted as a drop + add/create pair. */
+type RenameCandidate = {
+    readonly kind: "table";
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: "column";
+    readonly table: string;
+    readonly from: string;
+    readonly to: string;
+};
+/**
+ * Detect rename candidates in a forward operation list.
+ *
+ * A table rename is a `create_table` + `drop_table` whose column shapes match
+ * exactly. A column rename is an `add_column` + `drop_column` on the same table
+ * whose column shapes match exactly. Only unambiguous 1:1 shape matches are
+ * reported — if two dropped columns share a shape, neither is offered (the
+ * mapping would be a guess).
+ *
+ * @param ops The forward operations from {@link diffSchema}.
+ * @returns The rename candidates found (never mutates `ops`).
+ */
+declare function detectRenames(ops: readonly Operation[]): RenameCandidate[];
+/**
+ * Fold confirmed renames into an operation list: each confirmed candidate's
+ * drop + add/create pair is removed and replaced by a single rename operation,
+ * inserted at the position of the first op it replaces (preserving order).
+ *
+ * @param ops The forward operations from {@link diffSchema}.
+ * @param confirmed The rename candidates the user accepted.
+ * @returns A new operation list with renames applied.
+ */
+declare function applyRenames(ops: readonly Operation[], confirmed: readonly RenameCandidate[]): Operation[];
+
 /**
  * tempest-db-js — migration CLI (programmatic core).
  *
@@ -376,6 +463,30 @@ interface CliResult {
     readonly code: number;
     readonly lines: string[];
 }
+/**
+ * Identity helper for authoring a typed migration config file. Gives editor
+ * autocompletion and type-checking on the object the `tempest-db` bin loads.
+ *
+ * @example
+ * ```ts
+ * // tempest-db.config.mjs
+ * import { defineMigrationConfig } from "tempest-db-js/migrations";
+ * import { NodeSqliteDriver } from "tempest-db-js";
+ * import { migrations } from "./migrations/index.js";
+ * import { User } from "./models.js";
+ *
+ * export default defineMigrationConfig({
+ *   driver: NodeSqliteDriver.open("app.db"),
+ *   dialect: "sqlite",
+ *   migrations,
+ *   models: [User],
+ * });
+ * ```
+ *
+ * @param config The migration config to pass through unchanged.
+ * @returns The same config, typed as `CliConfig`.
+ */
+declare function defineMigrationConfig(config: CliConfig): CliConfig;
 /**
  * Run one CLI command.
  *
@@ -388,4 +499,4 @@ interface CliResult {
  */
 declare function runMigrationCli(argv: readonly string[], config: CliConfig): CliResult;
 
-export { type CliConfig, type CliResult, type ColumnIR, CyclicMigrationGraph, type DefaultIR, IrreversibleMigration, type Migration, type MigrationDraft, MigrationRunner, Op, type Operation, type RevisionNode, type SchemaIR, type SqliteAffinity, type TableIR, UnknownRevision, applyOperation, checkDrift, checkDriftPostgres, diffSchema, emptySchema, generateMigration, heads, introspectPostgres, introspectSqlite, invert, invertAll, makeRevisionId, reflectSchema, reflectTable, renderColumnDef, renderColumnType, renderDefault, renderOperation, replaySchema, runMigrationCli, sqliteAffinity, topoOrder };
+export { AsyncMigrationRunner, type CliConfig, type CliResult, type ColumnIR, CyclicMigrationGraph, type DefaultIR, IrreversibleMigration, type Migration, type MigrationDraft, MigrationRunner, Op, type Operation, type RenameCandidate, type RevisionNode, type SchemaIR, type SqliteAffinity, type TableIR, UnknownRevision, applyOperation, applyRenames, checkDrift, checkDriftPostgres, defineMigrationConfig, detectRenames, diffSchema, emptySchema, generateMigration, heads, introspectPostgres, introspectSqlite, invert, invertAll, makeRevisionId, reflectSchema, reflectTable, renderColumnDef, renderColumnType, renderDefault, renderOperation, replaySchema, runMigrationCli, sqliteAffinity, topoOrder };