@metaobjectsdev/migrate-ts 0.5.0-rc.1

package/src/sql-type.ts

@@ -0,0 +1,91 @@
+/**
+ * Canonical, dialect-neutral SQL type. Both buildExpectedSchema (metadata→snapshot)
+ * and introspect (db→snapshot) produce this shape; diff compares canonical to
+ * canonical; emit re-renders to dialect-specific SQL.
+ *
+ * Per spec §5.2.
+ */
+export type SqlType =
+  | { kind: "text"; maxLength?: number }
+  | { kind: "integer"; bits: 32 | 64 }
+  | { kind: "real" }
+  | { kind: "numeric"; precision?: number; scale?: number }
+  | { kind: "boolean" }
+  | { kind: "timestamp"; withTimezone: boolean }
+  | { kind: "date" }
+  | { kind: "json" }
+  | { kind: "blob" }
+  | { kind: "uuid" };
+
+/** Structural equality on SqlType. */
+export function sqlTypeEquals(a: SqlType, b: SqlType): boolean {
+  if (a.kind !== b.kind) return false;
+  switch (a.kind) {
+    case "text":
+      return a.maxLength === (b as Extract<SqlType, { kind: "text" }>).maxLength;
+    case "integer":
+      return a.bits === (b as Extract<SqlType, { kind: "integer" }>).bits;
+    case "numeric": {
+      const bn = b as Extract<SqlType, { kind: "numeric" }>;
+      return a.precision === bn.precision && a.scale === bn.scale;
+    }
+    case "timestamp":
+      return a.withTimezone === (b as Extract<SqlType, { kind: "timestamp" }>).withTimezone;
+    case "real":
+    case "boolean":
+    case "date":
+    case "json":
+    case "blob":
+    case "uuid":
+      return true;
+  }
+}
+
+/**
+ * Returns true if changing column type from `from` to `to` is provably non-lossy.
+ * Per spec §6.5. Conservative on purpose — false negatives just mean the user has
+ * to pass `allow.typeChange`; false positives could silently corrupt data.
+ *
+ * Returns false for identical types (caller should not emit a change-column-type
+ * in that case at all; this is defensive).
+ */
+export function isWidening(from: SqlType, to: SqlType): boolean {
+  if (sqlTypeEquals(from, to)) return false;
+  if (from.kind !== to.kind) return false;       // cross-kind: always lossy
+
+  switch (from.kind) {
+    case "text": {
+      const t = to as Extract<SqlType, { kind: "text" }>;
+      // unbounded → bounded: lossy
+      if (from.maxLength === undefined) return false;
+      // bounded → unbounded: widening
+      if (t.maxLength === undefined) return true;
+      // bounded both: widening iff new ≥ old
+      return t.maxLength >= from.maxLength;
+    }
+    case "integer": {
+      const t = to as Extract<SqlType, { kind: "integer" }>;
+      return t.bits >= from.bits;
+    }
+    case "numeric": {
+      const t = to as Extract<SqlType, { kind: "numeric" }>;
+      const fp = from.precision ?? 0;
+      const fs = from.scale ?? 0;
+      const tp = t.precision ?? 0;
+      const ts = t.scale ?? 0;
+      // widening iff p2 ≥ p1 AND s2 = s1 AND (p2 - s2) ≥ (p1 - s1)
+      return tp >= fp && ts === fs && (tp - ts) >= (fp - fs);
+    }
+    // real/boolean/date/json/blob/uuid: same kind already handled by sqlTypeEquals;
+    // any difference here means the discriminant matched but structural equality failed
+    // (impossible given SqlType has no other variants for these kinds). Defensive false.
+    case "real":
+    case "boolean":
+    case "date":
+    case "json":
+    case "blob":
+    case "uuid":
+    case "timestamp":
+      return false;
+  }
+}

package/src/types.ts

@@ -0,0 +1,174 @@
+import type { SqlType } from "./sql-type.js";
+
+// ---------------------------------------------------------------------------
+// Snapshot descriptors — same shape for expected (from metadata) and actual
+// (from introspection). diff() compares two SchemaSnapshots symmetrically.
+// ---------------------------------------------------------------------------
+
+export interface SchemaSnapshot {
+  tables: TableDescriptor[];
+  /** Always empty in v0.1; populated by introspect for v0.3 future-proofing. */
+  views: ViewDescriptor[];
+  /**
+   * Dialect-specific metadata captured at introspect time. Used by emit
+   * (e.g., SQLite version → choose native ALTER vs recreate-and-copy fallback).
+   */
+  meta?: SnapshotMeta;
+}
+
+export interface SnapshotMeta {
+  sqliteVersion?: string;            // e.g., "3.44.2"; only set for SQLite snapshots
+}
+
+export interface TableDescriptor {
+  name: string;                      // resolved db name (snake_case, plural)
+  /**
+   * DB schema this table lives in. Undefined for SQLite (no schema concept).
+   * For Postgres, undefined is normalized to "public" at SnapshotMeta boundaries;
+   * the diff and emit layers treat undefined === "public" as equivalent.
+   */
+  schema?: string;
+  columns: ColumnDescriptor[];
+  indexes: IndexDescriptor[];
+  foreignKeys: FkDescriptor[];
+  primaryKey: string[];              // column names; [] if none
+}
+
+export interface ColumnDescriptor {
+  name: string;
+  sqlType: SqlType;
+  nullable: boolean;
+  default?: ColumnDefault;
+  identity?: "increment" | "uuid";
+}
+
+export interface ColumnDefault {
+  kind: "literal" | "expr";
+  value: string;
+}
+
+export interface IndexDescriptor {
+  name: string;
+  columns: string[];
+  unique: boolean;
+}
+
+export interface FkDescriptor {
+  name: string;
+  columns: string[];
+  refTable: string;
+  refColumns: string[];
+  onDelete?: FkAction;
+  onUpdate?: FkAction;
+}
+
+export type FkAction = "cascade" | "set-null" | "restrict" | "no-action";
+
+export interface ViewDescriptor {
+  name: string;
+  /** Same semantics as TableDescriptor.schema. */
+  schema?: string;
+  // structural fields deferred to v0.3
+}
+
+// ---------------------------------------------------------------------------
+// Change union — produced by diff(), consumed by emit().
+// ---------------------------------------------------------------------------
+
+/**
+ * Every variant with a `table: string` (or `table: TableDescriptor`) field also
+ * carries an optional `schema?: string`. For the descriptor-bearing variants
+ * (create-table, drop-table source is just a name) the schema is redundant with
+ * `table.schema` but kept in parallel so the emit layer has a single, uniform
+ * place to read schema regardless of variant.
+ *
+ * For Postgres, undefined is treated as equivalent to "public" by both diff
+ * (table identity normalization) and emit (qualified-name suppression).
+ * SQLite has no schema concept; the field is always undefined there.
+ */
+export type Change =
+  | { kind: "create-table"; table: TableDescriptor; schema?: string; status: ChangeStatus }
+  | { kind: "drop-table"; table: string; schema?: string; status: ChangeStatus }
+  | { kind: "rename-table"; from: string; to: string; schema?: string; status: ChangeStatus }
+  | { kind: "add-column"; table: string; schema?: string; column: ColumnDescriptor; status: ChangeStatus }
+  | { kind: "drop-column"; table: string; schema?: string; column: string; status: ChangeStatus }
+  | { kind: "rename-column"; table: string; schema?: string; from: string; to: string; status: ChangeStatus }
+  | { kind: "change-column-type"; table: string; schema?: string; column: string;
+      from: SqlType; to: SqlType; status: ChangeStatus }
+  | { kind: "change-column-nullable"; table: string; schema?: string; column: string;
+      from: boolean; to: boolean; status: ChangeStatus }
+  | { kind: "change-column-default"; table: string; schema?: string; column: string;
+      from?: ColumnDefault; to?: ColumnDefault; status: ChangeStatus }
+  | { kind: "add-index"; table: string; schema?: string; index: IndexDescriptor; status: ChangeStatus }
+  | { kind: "drop-index"; table: string; schema?: string; index: string; status: ChangeStatus }
+  | { kind: "add-fk"; table: string; schema?: string; fk: FkDescriptor; status: ChangeStatus }
+  | { kind: "drop-fk"; table: string; schema?: string; fk: string; status: ChangeStatus }
+  // Declared for v0.3, never produced in v0.1:
+  | { kind: "create-view"; view: ViewDescriptor; status: ChangeStatus }
+  | { kind: "drop-view"; view: string; status: ChangeStatus }
+  | { kind: "replace-view"; view: ViewDescriptor; status: ChangeStatus };
+
+export type ChangeKind = Change["kind"];
+
+export interface ChangeStatus {
+  state: "allowed" | "blocked";
+  blockedReason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// diff() options
+// ---------------------------------------------------------------------------
+
+export interface AllowOptions {
+  dropColumn?: boolean;
+  dropTable?: boolean;
+  /** Narrowing/lossy types only; widening always allowed regardless of this flag. */
+  typeChange?: boolean;
+  dropIndex?: boolean;
+  dropFk?: boolean;
+  /** Existing data must satisfy NOT NULL; diff cannot verify this. */
+  nullableToNotNull?: boolean;
+}
+
+export type AmbiguousChange =
+  | {
+      kind: "possible-column-rename";
+      table: string;
+      from: { name: string; sqlType: SqlType };
+      to: { name: string; sqlType: SqlType };
+    }
+  | {
+      kind: "possible-table-rename";
+      from: { name: string; columnCount: number };
+      to: { name: string; columnCount: number };
+      columnOverlap: number;          // 0..1 fraction
+    };
+
+export type AmbiguousResolution = "rename" | "drop+add" | "abort";
+
+export type AmbiguousCallback = (q: AmbiguousChange) => Promise<AmbiguousResolution>;
+
+export interface DiffResult {
+  changes: Change[];
+  /** Subset of `changes` where status.state === "blocked"; convenience for CLI error messaging. */
+  blocked: Change[];
+}
+
+// ---------------------------------------------------------------------------
+// emit() result
+// ---------------------------------------------------------------------------
+
+export interface EmitResult {
+  up: string;
+  down: string;
+  /**
+   * Tables rebuilt via the SQLite recreate-and-copy pattern. Empty for
+   * postgres (in-place ALTER). The CLI uses this to pre-drop only the
+   * views whose source tables are being recreated — SQLite's RENAME re-
+   * parses dependent view definitions and errors if any reference the
+   * mid-recreate source table.
+   */
+  recreatedTables: ReadonlySet<string>;
+}
+
+export type Dialect = "postgres" | "sqlite";

package/src/view-ddl-postgres.ts

@@ -0,0 +1,15 @@
+import type { ViewMigrationOpts } from "./view-diff.js";
+
+export { type ViewMigrationOpts } from "./view-diff.js";
+
+export function emitPostgresViewMigration(opts: ViewMigrationOpts): string {
+  switch (opts.diffClass) {
+    case "no-change": return "";
+    case "safe-append":
+    case "safe-replace":
+      // Replace CREATE VIEW with CREATE OR REPLACE VIEW.
+      return opts.createSql.replace(/^CREATE VIEW\b/i, "CREATE OR REPLACE VIEW");
+    case "breaking":
+      return `DROP VIEW IF EXISTS ${opts.viewName} CASCADE;\n${opts.createSql}`;
+  }
+}

package/src/view-ddl-sqlite.ts

@@ -0,0 +1,7 @@
+import type { ViewMigrationOpts } from "./view-diff.js";
+
+export function emitSqliteViewMigration(opts: ViewMigrationOpts): string {
+  if (opts.diffClass === "no-change") return "";
+  // SQLite has no CREATE OR REPLACE VIEW; must drop+create. Wrap in txn.
+  return `BEGIN;\nDROP VIEW IF EXISTS ${opts.viewName};\n${opts.createSql}\nCOMMIT;`;
+}

package/src/view-diff.ts

@@ -0,0 +1,55 @@
+export interface ViewShape {
+  readonly columns: readonly string[];
+  readonly columnTypes?: Readonly<Record<string, string>>;
+}
+
+export type ViewDiffClass =
+  | "no-change"
+  | "safe-append"
+  | "safe-replace"
+  | "breaking";
+
+export interface ViewMigrationOpts {
+  readonly diffClass: ViewDiffClass;
+  readonly viewName: string;
+  /** Full `CREATE VIEW <name> AS ...;` statement (semicolon included). */
+  readonly createSql: string;
+}
+
+export function classifyViewDiff(prev: ViewShape, next: ViewShape): ViewDiffClass {
+  const prevCols = prev.columns;
+  const nextCols = next.columns;
+
+  // Dropped column = breaking.
+  for (const c of prevCols) {
+    if (!nextCols.includes(c)) return "breaking";
+  }
+
+  // Type change on existing column = breaking.
+  if (prev.columnTypes && next.columnTypes) {
+    for (const c of prevCols) {
+      const pt = prev.columnTypes[c];
+      const nt = next.columnTypes[c];
+      if (pt && nt && pt !== nt) return "breaking";
+    }
+  }
+
+  if (prevCols.length === nextCols.length) {
+    // Same length, same set → either identical order or reordered.
+    let identical = true;
+    for (let i = 0; i < prevCols.length; i++) {
+      if (prevCols[i] !== nextCols[i]) { identical = false; break; }
+    }
+    return identical ? "no-change" : "safe-replace";
+  }
+
+  // Longer next, same prefix? → safe-append.
+  let prefixMatches = true;
+  for (let i = 0; i < prevCols.length; i++) {
+    if (prevCols[i] !== nextCols[i]) { prefixMatches = false; break; }
+  }
+  if (prefixMatches) return "safe-append";
+
+  // Mixed: reordered + appended → safe-replace (data shape unchanged at column level).
+  return "safe-replace";
+}

package/src/write-migration.ts

@@ -0,0 +1,64 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { EmitResult } from "./types.js";
+
+export interface WriteMigrationOptions {
+  /** Migrations root directory (e.g., ".meta/migrations"). Must already exist. */
+  dir: string;
+  /** Human-readable slug; sanitized to lowercase + hyphens. */
+  slug: string;
+  /** Override for the timestamp source (UTC). Defaults to new Date(). */
+  now?: Date;
+}
+
+export interface WriteMigrationResult {
+  /** Absolute path to the per-migration directory created. */
+  dir: string;
+  /** Path to up.sql. */
+  upPath: string;
+  /** Path to down.sql. */
+  downPath: string;
+}
+
+export async function writeMigration(
+  result: Pick<EmitResult, "up" | "down">,
+  opts: WriteMigrationOptions,
+): Promise<WriteMigrationResult> {
+  const ts = formatTimestamp(opts.now ?? new Date());
+  const slug = sanitizeSlug(opts.slug);
+  const migrationDir = join(opts.dir, `${ts}-${slug}`);
+
+  // Create only the per-migration directory (not the root) — root must exist.
+  await mkdir(migrationDir, { recursive: false });
+
+  const upPath = join(migrationDir, "up.sql");
+  const downPath = join(migrationDir, "down.sql");
+  await writeFile(upPath, ensureTrailingNewline(result.up), "utf8");
+  await writeFile(downPath, ensureTrailingNewline(result.down), "utf8");
+
+  return { dir: migrationDir, upPath, downPath };
+}
+
+function formatTimestamp(d: Date): string {
+  const pad = (n: number) => n.toString().padStart(2, "0");
+  return (
+    d.getUTCFullYear().toString() +
+    pad(d.getUTCMonth() + 1) +
+    pad(d.getUTCDate()) +
+    pad(d.getUTCHours()) +
+    pad(d.getUTCMinutes()) +
+    pad(d.getUTCSeconds())
+  );
+}
+
+function sanitizeSlug(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .substring(0, 60);                // cap length for sane filesystem use
+}
+
+function ensureTrailingNewline(s: string): string {
+  return s.endsWith("\n") ? s : s + "\n";
+}