tempest-db-js 0.1.0 → 0.2.0

package/dist/migrations/index.d.cts

@@ -353,6 +353,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 +426,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 +462,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 { 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

@@ -353,6 +353,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 +426,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 +462,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 { 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 };