tempest-db-js 0.2.0 → 0.4.0

package/dist/migrations/index.d.cts

@@ -1,4 +1,4 @@
-import { ColumnType, DefaultValue, ModelClass, Dialect, SyncDriver, AsyncDriver } from '../index.cjs';
+import { ColumnType, DefaultValue, ForeignKeyRef, FkAction, ModelClass, Dialect, AsyncDriver, SyncDriver } from '../index.cjs';
 
 /**
  * tempest-db-js — Phase 6: the Schema IR (intermediate representation).
@@ -18,13 +18,46 @@ interface ColumnIR {
     readonly notNull: boolean;
     readonly primaryKey: boolean;
     readonly default: DefaultIR;
+    /** A column-level `UNIQUE` constraint. */
+    readonly unique: boolean;
+    /** A column-level foreign-key reference, or `null` for none. */
+    readonly references: ForeignKeyRef | null;
 }
+/** A (composite) `UNIQUE` table constraint in the IR. */
+interface UniqueConstraintIR {
+    readonly name: string;
+    readonly columns: readonly string[];
+}
+/** A (composite) foreign-key table constraint in the IR. */
+interface ForeignKeyIR {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly refTable: string;
+    readonly refColumns: readonly string[];
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
+/**
+ * A named table-level constraint, tagged by kind. Carried whole by the
+ * `add_constraint` / `drop_constraint` operations so each is reversible.
+ */
+type NamedConstraint = {
+    readonly type: "unique";
+    readonly constraint: UniqueConstraintIR;
+} | {
+    readonly type: "foreignKey";
+    readonly constraint: ForeignKeyIR;
+};
 /** One table. */
 interface TableIR {
     readonly name: string;
     readonly columns: Record<string, ColumnIR>;
     /** Primary-key column names (composite = more than one). */
     readonly primaryKey: readonly string[];
+    /** Table-level unique constraints (from `tableArgs`). */
+    readonly uniqueConstraints: readonly UniqueConstraintIR[];
+    /** Table-level foreign-key constraints (from `tableArgs`). */
+    readonly foreignKeys: readonly ForeignKeyIR[];
 }
 /** A whole schema, keyed by table name. */
 interface SchemaIR {
@@ -85,6 +118,14 @@ type Operation = {
     readonly kind: "recreate_table";
     readonly from: TableIR;
     readonly to: TableIR;
+} | {
+    readonly kind: "add_constraint";
+    readonly table: string;
+    readonly constraint: NamedConstraint;
+} | {
+    readonly kind: "drop_constraint";
+    readonly table: string;
+    readonly constraint: NamedConstraint;
 } | {
     readonly kind: "execute";
     readonly up: string;
@@ -106,18 +147,21 @@ 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. */
 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]`. */
+/**
+ * Render one column definition: `"name" TYPE [NOT NULL] [DEFAULT x] [UNIQUE]
+ * [REFERENCES ...]`.
+ */
 declare function renderColumnDef(col: ColumnIR, dialect: Dialect): string;
 /**
  * Render an operation to one or more SQL statements for the dialect.
@@ -126,7 +170,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[];
 
@@ -239,6 +283,10 @@ declare class Op {
     renameColumn(table: string, from: string, to: string): void;
     /** Rebuild a table (SQLite batch-mode / PostgreSQL per-column alters). */
     recreateTable(from: TableIR, to: TableIR): void;
+    /** Add a table-level unique / foreign-key constraint. */
+    addConstraint(table: string, constraint: NamedConstraint): void;
+    /** Drop a table-level unique / foreign-key constraint. */
+    dropConstraint(table: string, constraint: NamedConstraint): void;
     /** Raw SQL escape hatch (e.g. a data migration). `down` may be `null`. */
     execute(up: string, down?: string | null): void;
 }
@@ -280,6 +328,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.
@@ -303,15 +388,6 @@ declare function sqliteAffinity(declared: string): SqliteAffinity;
  * @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`.
@@ -462,4 +538,4 @@ declare function defineMigrationConfig(config: CliConfig): CliConfig;
  */
 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 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 };
+export { AsyncMigrationRunner, type CliConfig, type CliResult, type ColumnIR, CyclicMigrationGraph, type DefaultIR, type ForeignKeyIR, IrreversibleMigration, type Migration, type MigrationDraft, MigrationRunner, type NamedConstraint, Op, type Operation, type RenameCandidate, type RevisionNode, type SchemaIR, type SqliteAffinity, type TableIR, type UniqueConstraintIR, 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, ForeignKeyRef, FkAction, ModelClass, Dialect, AsyncDriver, SyncDriver } from '../index.js';
 
 /**
  * tempest-db-js — Phase 6: the Schema IR (intermediate representation).
@@ -18,13 +18,46 @@ interface ColumnIR {
     readonly notNull: boolean;
     readonly primaryKey: boolean;
     readonly default: DefaultIR;
+    /** A column-level `UNIQUE` constraint. */
+    readonly unique: boolean;
+    /** A column-level foreign-key reference, or `null` for none. */
+    readonly references: ForeignKeyRef | null;
 }
+/** A (composite) `UNIQUE` table constraint in the IR. */
+interface UniqueConstraintIR {
+    readonly name: string;
+    readonly columns: readonly string[];
+}
+/** A (composite) foreign-key table constraint in the IR. */
+interface ForeignKeyIR {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly refTable: string;
+    readonly refColumns: readonly string[];
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
+/**
+ * A named table-level constraint, tagged by kind. Carried whole by the
+ * `add_constraint` / `drop_constraint` operations so each is reversible.
+ */
+type NamedConstraint = {
+    readonly type: "unique";
+    readonly constraint: UniqueConstraintIR;
+} | {
+    readonly type: "foreignKey";
+    readonly constraint: ForeignKeyIR;
+};
 /** One table. */
 interface TableIR {
     readonly name: string;
     readonly columns: Record<string, ColumnIR>;
     /** Primary-key column names (composite = more than one). */
     readonly primaryKey: readonly string[];
+    /** Table-level unique constraints (from `tableArgs`). */
+    readonly uniqueConstraints: readonly UniqueConstraintIR[];
+    /** Table-level foreign-key constraints (from `tableArgs`). */
+    readonly foreignKeys: readonly ForeignKeyIR[];
 }
 /** A whole schema, keyed by table name. */
 interface SchemaIR {
@@ -85,6 +118,14 @@ type Operation = {
     readonly kind: "recreate_table";
     readonly from: TableIR;
     readonly to: TableIR;
+} | {
+    readonly kind: "add_constraint";
+    readonly table: string;
+    readonly constraint: NamedConstraint;
+} | {
+    readonly kind: "drop_constraint";
+    readonly table: string;
+    readonly constraint: NamedConstraint;
 } | {
     readonly kind: "execute";
     readonly up: string;
@@ -106,18 +147,21 @@ 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. */
 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]`. */
+/**
+ * Render one column definition: `"name" TYPE [NOT NULL] [DEFAULT x] [UNIQUE]
+ * [REFERENCES ...]`.
+ */
 declare function renderColumnDef(col: ColumnIR, dialect: Dialect): string;
 /**
  * Render an operation to one or more SQL statements for the dialect.
@@ -126,7 +170,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[];
 
@@ -239,6 +283,10 @@ declare class Op {
     renameColumn(table: string, from: string, to: string): void;
     /** Rebuild a table (SQLite batch-mode / PostgreSQL per-column alters). */
     recreateTable(from: TableIR, to: TableIR): void;
+    /** Add a table-level unique / foreign-key constraint. */
+    addConstraint(table: string, constraint: NamedConstraint): void;
+    /** Drop a table-level unique / foreign-key constraint. */
+    dropConstraint(table: string, constraint: NamedConstraint): void;
     /** Raw SQL escape hatch (e.g. a data migration). `down` may be `null`. */
     execute(up: string, down?: string | null): void;
 }
@@ -280,6 +328,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.
@@ -303,15 +388,6 @@ declare function sqliteAffinity(declared: string): SqliteAffinity;
  * @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`.
@@ -462,4 +538,4 @@ declare function defineMigrationConfig(config: CliConfig): CliConfig;
  */
 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 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 };
+export { AsyncMigrationRunner, type CliConfig, type CliResult, type ColumnIR, CyclicMigrationGraph, type DefaultIR, type ForeignKeyIR, IrreversibleMigration, type Migration, type MigrationDraft, MigrationRunner, type NamedConstraint, Op, type Operation, type RenameCandidate, type RevisionNode, type SchemaIR, type SqliteAffinity, type TableIR, type UniqueConstraintIR, 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.js

@@ -1,4 +1,4 @@
-export { CyclicMigrationGraph, IrreversibleMigration, MigrationRunner, Op, 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 } from '../chunk-QMW4NKMH.js';
-import '../chunk-AGDD7K3F.js';
+export { AsyncMigrationRunner, CyclicMigrationGraph, IrreversibleMigration, MigrationRunner, Op, 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 } from '../chunk-43XL66JG.js';
+import '../chunk-JR4MLFQN.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-db-js",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Type-safe, class-based ORM for TypeScript — SQLAlchemy 2.0 ergonomics for the JS/TS world.",
   "type": "module",
   "sideEffects": false,