tempest-db-js 0.1.0

package/dist/migrations/index.d.cts

@@ -0,0 +1,391 @@
+import { ColumnType, DefaultValue, ModelClass, Dialect, SyncDriver, AsyncDriver } from '../index.cjs';
+
+/**
+ * tempest-db-js — Phase 6: the Schema IR (intermediate representation).
+ *
+ * A canonical, dialect-neutral description of a database schema. Every source of
+ * truth — model reflection (here), migration replay, or DB introspection —
+ * produces the SAME `SchemaIR`, so the differ compares like with like and SQL is
+ * only ever emitted at the dialect edge (the anti-"SQL-stitching" core).
+ */
+
+/** A column's default in the IR. */
+type DefaultIR = DefaultValue | null;
+/** One column. */
+interface ColumnIR {
+    readonly name: string;
+    readonly type: ColumnType;
+    readonly notNull: boolean;
+    readonly primaryKey: boolean;
+    readonly default: DefaultIR;
+}
+/** One table. */
+interface TableIR {
+    readonly name: string;
+    readonly columns: Record<string, ColumnIR>;
+    /** Primary-key column names (composite = more than one). */
+    readonly primaryKey: readonly string[];
+}
+/** A whole schema, keyed by table name. */
+interface SchemaIR {
+    readonly tables: Record<string, TableIR>;
+}
+/** Reflect one model class into a `TableIR`. */
+declare function reflectTable(model: ModelClass): TableIR;
+/**
+ * Reflect a set of model classes into a `SchemaIR`. This is the **target** state
+ * the differ compares the current (replayed) schema against.
+ *
+ * @param models The model classes that make up the schema.
+ * @returns The reflected schema IR.
+ */
+declare function reflectSchema(models: readonly ModelClass[]): SchemaIR;
+/** An empty schema (the baseline before any migration). */
+declare function emptySchema(): SchemaIR;
+
+/**
+ * tempest-db-js — Phase 6: typed migration operations.
+ *
+ * Every schema change is a typed `Operation` with a known inverse. This is what
+ * gives autogenerated, reversible `down()` and dialect-rendered DDL — never a
+ * hand-written `.sql` blob (the anti-Drizzle core).
+ */
+
+/** A single, reversible schema operation. */
+type Operation = {
+    readonly kind: "create_table";
+    readonly table: TableIR;
+} | {
+    readonly kind: "drop_table";
+    readonly table: TableIR;
+} | {
+    readonly kind: "rename_table";
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: "add_column";
+    readonly table: string;
+    readonly column: ColumnIR;
+} | {
+    readonly kind: "drop_column";
+    readonly table: string;
+    readonly column: ColumnIR;
+} | {
+    readonly kind: "alter_column";
+    readonly table: string;
+    readonly name: string;
+    readonly from: ColumnIR;
+    readonly to: ColumnIR;
+} | {
+    readonly kind: "rename_column";
+    readonly table: string;
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: "recreate_table";
+    readonly from: TableIR;
+    readonly to: TableIR;
+} | {
+    readonly kind: "execute";
+    readonly up: string;
+    readonly down: string | null;
+};
+/** Raised when an operation has no safe inverse (e.g. a one-way `execute`). */
+declare class IrreversibleMigration extends Error {
+    constructor(message: string);
+}
+/**
+ * Compute the inverse of an operation, for autogenerated `down()`.
+ *
+ * @param op The forward operation.
+ * @returns The operation that undoes it.
+ * @throws IrreversibleMigration When `op` cannot be safely reversed.
+ */
+declare function invert(op: Operation): Operation;
+/** Invert a list of operations: reverse order, each inverted. */
+declare function invertAll(ops: readonly Operation[]): Operation[];
+
+/**
+ * tempest-db-js — Phase 6: 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.
+ */
+
+/** Map a column type to its SQL type string for the dialect. */
+declare function renderColumnType(type: ColumnType, dialect: Dialect): string;
+/** Render a default value into a SQL `DEFAULT` expression for the dialect. */
+declare function renderDefault(def: DefaultValue, dialect: Dialect): string;
+/** Render one column definition: `"name" TYPE [NOT NULL] [DEFAULT x]`. */
+declare function renderColumnDef(col: ColumnIR, dialect: Dialect): string;
+/**
+ * Render an operation to one or more SQL statements for the dialect.
+ *
+ * @param op The operation.
+ * @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).
+ */
+declare function renderOperation(op: Operation, dialect: Dialect): string[];
+
+/**
+ * tempest-db-js — Phase 6: the schema differ.
+ *
+ * Compares two `SchemaIR`s (current vs target) and emits the typed `Operation[]`
+ * that turns one into the other. Purely structural — no SQL, no DB.
+ */
+
+/**
+ * Diff `current` → `target`, returning the operations to migrate forward.
+ *
+ * Order: create new tables, then per-table column adds/alters/drops, then drop
+ * removed tables last (so nothing depends on a table being dropped first).
+ *
+ * @param current The current schema (e.g. from migration replay).
+ * @param target The desired schema (e.g. from model reflection).
+ * @returns The forward operations.
+ */
+declare function diffSchema(current: SchemaIR, target: SchemaIR): Operation[];
+
+/**
+ * tempest-db-js — Phase 6: the revision DAG.
+ *
+ * Migrations form a directed acyclic graph via `downRevision` (a list of parents,
+ * so branches and merges are first-class). This module orders them for applying
+ * (topological, deterministic) and finds heads.
+ */
+/** The minimal graph shape a migration must expose. */
+interface RevisionNode {
+    readonly revision: string;
+    readonly downRevision: readonly string[];
+}
+/** Raised when the revision graph contains a cycle. */
+declare class CyclicMigrationGraph extends Error {
+    constructor(remaining: readonly string[]);
+}
+/** Raised when a `downRevision` points at a revision that does not exist. */
+declare class UnknownRevision extends Error {
+    constructor(revision: string, parent: string);
+}
+/**
+ * Topologically order migrations so every parent precedes its children. Ties are
+ * broken by revision id for reproducible builds. Throws on cycles or dangling
+ * parents.
+ *
+ * @param migrations The migrations to order.
+ * @returns The migrations in apply order.
+ */
+declare function topoOrder<T extends RevisionNode>(migrations: readonly T[]): T[];
+/** Revisions that are nobody's parent — the current head(s) of the graph. */
+declare function heads<T extends RevisionNode>(migrations: readonly T[]): string[];
+
+/**
+ * tempest-db-js — Phase 6: migration autogeneration.
+ *
+ * Turns a diff's `Operation[]` into an editable TypeScript migration file with
+ * `up()` and an autogenerated, inverted `down()`. Operations are embedded as
+ * plain-data literals (they are JSON-serializable), so the file stays readable
+ * and hand-editable — never an opaque `.sql` blob.
+ */
+
+/** Inputs for one generated migration file. */
+interface MigrationDraft {
+    readonly revision: string;
+    readonly downRevision: readonly string[];
+    readonly label: string;
+    readonly operations: readonly Operation[];
+}
+/**
+ * Render a migration file body as TypeScript source.
+ *
+ * The generated `down()` inverts `up()`; if any operation is irreversible, the
+ * generation still succeeds but `down()` throws at run time with a clear message
+ * (so reversibility is never silently broken).
+ *
+ * @param draft The revision id, parents, label, and forward operations.
+ * @returns The migration file source.
+ */
+declare function generateMigration(draft: MigrationDraft): string;
+/** Build a short, stable revision id from a label + parent set. */
+declare function makeRevisionId(label: string, parents: readonly string[]): string;
+
+/**
+ * tempest-db-js — Phase 6: the migration runner.
+ *
+ * The `Op` facade records operations; the `MigrationRunner` renders them to SQL
+ * (per dialect) and runs them through a sync driver, tracking applied revisions
+ * in a `tempest_db_js_migrations` table. Upgrades/downgrades respect the revision DAG.
+ *
+ * SQLite execution is real (via `node:sqlite`); the same code path serves any
+ * sync driver.
+ */
+
+/**
+ * The facade injected into `up()`/`down()`. Each method records an operation;
+ * the runner renders and executes them after the function returns.
+ */
+declare class Op {
+    readonly operations: Operation[];
+    /** Record a raw operation (used by autogenerated migrations). */
+    run(operation: Operation): void;
+    createTable(table: TableIR): void;
+    dropTable(table: TableIR): void;
+    renameTable(from: string, to: string): void;
+    addColumn(table: string, column: ColumnIR): void;
+    dropColumn(table: string, column: ColumnIR): void;
+    alterColumn(table: string, name: string, from: ColumnIR, to: ColumnIR): void;
+    renameColumn(table: string, from: string, to: string): void;
+    /** Rebuild a table (SQLite batch-mode / PostgreSQL per-column alters). */
+    recreateTable(from: TableIR, to: TableIR): void;
+    /** Raw SQL escape hatch (e.g. a data migration). `down` may be `null`. */
+    execute(up: string, down?: string | null): void;
+}
+/** A migration file's shape. */
+interface Migration {
+    readonly revision: string;
+    readonly downRevision: readonly string[];
+    readonly label?: string;
+    up(op: Op): void;
+    down(op: Op): void;
+}
+/** Runs migrations against a sync driver, tracking applied revisions. */
+declare class MigrationRunner {
+    private readonly driver;
+    private readonly dialect;
+    constructor(driver: SyncDriver, dialect: Dialect);
+    /** Create the version-tracking table if it does not exist. */
+    ensureVersionTable(): void;
+    /** The set of applied revision ids. */
+    applied(): 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 (pass one in — the runtime has no
+     *   wall clock of its own here).
+     * @returns The revision ids that were applied this run.
+     */
+    upgrade(migrations: readonly Migration[], appliedAt: string): 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): string[];
+}
+
+/**
+ * tempest-db-js — Phase 6d: SQLite introspection + drift detection.
+ *
+ * Reads the live schema from a SQLite database (via `PRAGMA table_info`) into a
+ * `SchemaIR`, and compares it against the models to detect **drift** — the DB
+ * diverging from what the migrations/models say it should be. Comparison is done
+ * at SQLite's storage-affinity level, so coarse SQLite typing (every string is
+ * `TEXT`) does not produce false positives.
+ */
+
+/** SQLite's five storage classes / affinities. */
+type SqliteAffinity = "INTEGER" | "TEXT" | "REAL" | "BLOB" | "NUMERIC";
+/** Apply SQLite's affinity rules to a declared type string. */
+declare function sqliteAffinity(declared: string): SqliteAffinity;
+/**
+ * Read the current SQLite schema into a `SchemaIR`. Lossy by nature (SQLite
+ * collapses types into affinities), so types come back as the affinity's kind.
+ *
+ * @param driver A sync SQLite driver.
+ * @returns The introspected schema.
+ */
+declare function introspectSqlite(driver: SyncDriver): SchemaIR;
+/**
+ * Compare the live SQLite schema against the models and report drift. Comparison
+ * is at the affinity level (so `varchar` vs `TEXT` is not flagged), plus
+ * nullability, primary-key, and presence of tables/columns.
+ *
+ * @param driver A sync SQLite driver.
+ * @param models The model classes that define the intended schema.
+ * @returns A list of human-readable drift messages — empty means no drift.
+ */
+declare function checkDrift(driver: SyncDriver, models: readonly ModelClass[]): string[];
+/**
+ * Read the current PostgreSQL schema into a `SchemaIR` from `information_schema`.
+ *
+ * Not exercised by the in-repo test suite (no PostgreSQL in CI); mirrors
+ * {@link introspectSqlite} for the async driver.
+ *
+ * @param driver An async PostgreSQL driver.
+ * @returns The introspected schema.
+ */
+declare function introspectPostgres(driver: AsyncDriver): Promise<SchemaIR>;
+/**
+ * Drift check for PostgreSQL: compares the live schema (introspected) against the
+ * models by column kind, nullability, primary-key, and presence. Structural —
+ * not exercised in CI (no PostgreSQL).
+ *
+ * @param driver An async PostgreSQL driver.
+ * @param models The model classes that define the intended schema.
+ * @returns A list of drift messages — empty means no drift.
+ */
+declare function checkDriftPostgres(driver: AsyncDriver, models: readonly ModelClass[]): Promise<string[]>;
+
+/**
+ * tempest-db-js — Phase 6: migration replay → virtual schema IR.
+ *
+ * Applies a migration's operations to an in-memory `SchemaIR`, building the
+ * "current" schema without touching a database. This is the hybrid source of
+ * truth for autogenerate: diff the replayed schema against the reflected models.
+ */
+
+/** Apply one operation to a schema, returning the updated schema. */
+declare function applyOperation(schema: SchemaIR, op: Operation): SchemaIR;
+/**
+ * Replay migrations (in DAG order) into a virtual `SchemaIR` — the "current"
+ * schema, computed without a database.
+ *
+ * @param migrations All known migrations.
+ * @returns The schema after applying every migration's `up()`.
+ */
+declare function replaySchema(migrations: readonly Migration[]): SchemaIR;
+
+/**
+ * tempest-db-js — migration CLI (programmatic core).
+ *
+ * `runMigrationCli(argv, config)` dispatches Alembic-style commands against a
+ * driver + a set of migrations + (optionally) the models. It returns lines and
+ * an exit code rather than touching `process`, so it is fully testable; a thin
+ * `bin` wrapper just maps `process.argv`/`process.exit` onto it.
+ */
+
+/** Configuration the CLI operates against. */
+interface CliConfig {
+    readonly driver: SyncDriver;
+    readonly dialect: Dialect;
+    readonly migrations: readonly Migration[];
+    readonly models?: readonly ModelClass[];
+    /** Timestamp string stamped on applied revisions (no wall clock here). */
+    readonly appliedAt?: string;
+}
+/** The result of a CLI run. */
+interface CliResult {
+    readonly code: number;
+    readonly lines: string[];
+}
+/**
+ * Run one CLI command.
+ *
+ * Commands: `current`, `history`, `heads`, `upgrade [--sql]`, `downgrade [N]`,
+ * `check`, `revision -m <msg> [--autogenerate]`.
+ *
+ * @param argv The command and its arguments (without the program name).
+ * @param config The driver, migrations, and models to operate on.
+ * @returns Output lines and an exit code.
+ */
+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 };