@stravigor/core 0.1.0

package/src/database/migration/differ.ts

@@ -0,0 +1,308 @@
+import type {
+  DatabaseRepresentation,
+  TableDefinition,
+  ColumnDefinition,
+  ForeignKeyConstraint,
+  UniqueConstraint,
+  IndexDefinition,
+  DefaultValue,
+} from '../../schema/database_representation.ts'
+import type { PostgreSQLType } from '../../schema/postgres.ts'
+import type {
+  SchemaDiff,
+  EnumDiff,
+  TableDiff,
+  ColumnDiff,
+  ConstraintDiff,
+  IndexDiff,
+} from './types.ts'
+
+/**
+ * Compares two {@link DatabaseRepresentation} objects and produces a
+ * structured {@link SchemaDiff} describing the operations needed to
+ * transform `actual` into `desired`.
+ */
+export default class SchemaDiffer {
+  diff(desired: DatabaseRepresentation, actual: DatabaseRepresentation): SchemaDiff {
+    const enums = this.diffEnums(desired, actual)
+    const { tables, constraints, indexes } = this.diffTablesAndDeps(desired, actual)
+    return { enums, tables, constraints, indexes }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Enums
+  // ---------------------------------------------------------------------------
+
+  private diffEnums(desired: DatabaseRepresentation, actual: DatabaseRepresentation): EnumDiff[] {
+    const diffs: EnumDiff[] = []
+    const actualMap = new Map(actual.enums.map(e => [e.name, e]))
+    const desiredMap = new Map(desired.enums.map(e => [e.name, e]))
+
+    // Creates and modifications
+    for (const [name, desiredEnum] of desiredMap) {
+      const actualEnum = actualMap.get(name)
+      if (!actualEnum) {
+        diffs.push({ kind: 'create', name, values: desiredEnum.values })
+      } else {
+        const addedValues = desiredEnum.values.filter(v => !actualEnum.values.includes(v))
+        if (addedValues.length > 0) {
+          diffs.push({ kind: 'modify', name, addedValues })
+        }
+      }
+    }
+
+    // Drops
+    for (const [name, actualEnum] of actualMap) {
+      if (!desiredMap.has(name)) {
+        diffs.push({ kind: 'drop', name, values: actualEnum.values })
+      }
+    }
+
+    return diffs
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tables, Constraints, Indexes
+  // ---------------------------------------------------------------------------
+
+  private diffTablesAndDeps(
+    desired: DatabaseRepresentation,
+    actual: DatabaseRepresentation
+  ): { tables: TableDiff[]; constraints: ConstraintDiff[]; indexes: IndexDiff[] } {
+    const tables: TableDiff[] = []
+    const constraints: ConstraintDiff[] = []
+    const indexes: IndexDiff[] = []
+
+    const actualMap = new Map(actual.tables.map(t => [t.name, t]))
+    const desiredMap = new Map(desired.tables.map(t => [t.name, t]))
+
+    // Creates and modifications
+    for (const [name, desiredTable] of desiredMap) {
+      const actualTable = actualMap.get(name)
+      if (!actualTable) {
+        tables.push({ kind: 'create', table: desiredTable })
+        // All constraints and indexes from a new table are additions
+        this.extractConstraintAdds(name, desiredTable, constraints)
+        this.extractIndexAdds(name, desiredTable, indexes)
+      } else {
+        // Column diff
+        const columnDiffs = this.diffColumns(desiredTable, actualTable)
+        if (columnDiffs.length > 0) {
+          tables.push({ kind: 'modify', tableName: name, columns: columnDiffs })
+        }
+        // Constraint diff
+        this.diffConstraints(name, desiredTable, actualTable, constraints)
+        // Index diff
+        this.diffIndexes(name, desiredTable, actualTable, indexes)
+      }
+    }
+
+    // Drops
+    for (const [name, actualTable] of actualMap) {
+      if (!desiredMap.has(name)) {
+        tables.push({ kind: 'drop', table: actualTable })
+        // All constraints and indexes from a dropped table
+        this.extractConstraintDrops(name, actualTable, constraints)
+        this.extractIndexDrops(name, actualTable, indexes)
+      }
+    }
+
+    return { tables, constraints, indexes }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Column diff
+  // ---------------------------------------------------------------------------
+
+  private diffColumns(desired: TableDefinition, actual: TableDefinition): ColumnDiff[] {
+    const diffs: ColumnDiff[] = []
+    const actualMap = new Map(actual.columns.map(c => [c.name, c]))
+    const desiredMap = new Map(desired.columns.map(c => [c.name, c]))
+
+    for (const [name, desiredCol] of desiredMap) {
+      const actualCol = actualMap.get(name)
+      if (!actualCol) {
+        diffs.push({ kind: 'add', column: desiredCol })
+      } else {
+        const alter = this.diffSingleColumn(name, desiredCol, actualCol)
+        if (alter) diffs.push(alter)
+      }
+    }
+
+    for (const [name, actualCol] of actualMap) {
+      if (!desiredMap.has(name)) {
+        diffs.push({ kind: 'drop', column: actualCol })
+      }
+    }
+
+    return diffs
+  }
+
+  private diffSingleColumn(
+    name: string,
+    desired: ColumnDefinition,
+    actual: ColumnDefinition
+  ): ColumnDiff | null {
+    const typeChanged = !pgTypesEqual(desired.pgType, actual.pgType)
+    const nullableChanged = desired.notNull !== actual.notNull
+    const defaultChanged = !defaultsEqual(desired.defaultValue, actual.defaultValue)
+
+    if (!typeChanged && !nullableChanged && !defaultChanged) return null
+
+    return {
+      kind: 'alter',
+      columnName: name,
+      typeChange: typeChanged ? { from: actual.pgType, to: desired.pgType } : undefined,
+      nullableChange: nullableChanged ? { from: actual.notNull, to: desired.notNull } : undefined,
+      defaultChange: defaultChanged
+        ? { from: actual.defaultValue, to: desired.defaultValue }
+        : undefined,
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Constraint diff
+  // ---------------------------------------------------------------------------
+
+  private diffConstraints(
+    tableName: string,
+    desired: TableDefinition,
+    actual: TableDefinition,
+    out: ConstraintDiff[]
+  ): void {
+    // Foreign keys — match by (columns, referencedTable, referencedColumns)
+    const actualFKs = new Set(actual.foreignKeys.map(fkKey))
+    const desiredFKs = new Set(desired.foreignKeys.map(fkKey))
+
+    for (const fk of desired.foreignKeys) {
+      if (!actualFKs.has(fkKey(fk))) {
+        out.push({ kind: 'add_fk', tableName, constraint: fk })
+      }
+    }
+    for (const fk of actual.foreignKeys) {
+      if (!desiredFKs.has(fkKey(fk))) {
+        out.push({ kind: 'drop_fk', tableName, constraint: fk })
+      }
+    }
+
+    // Unique constraints — match by sorted columns
+    const actualUqs = new Set(actual.uniqueConstraints.map(uqKey))
+    const desiredUqs = new Set(desired.uniqueConstraints.map(uqKey))
+
+    for (const uq of desired.uniqueConstraints) {
+      if (!actualUqs.has(uqKey(uq))) {
+        out.push({ kind: 'add_unique', tableName, constraint: uq })
+      }
+    }
+    for (const uq of actual.uniqueConstraints) {
+      if (!desiredUqs.has(uqKey(uq))) {
+        out.push({ kind: 'drop_unique', tableName, constraint: uq })
+      }
+    }
+  }
+
+  private extractConstraintAdds(
+    tableName: string,
+    table: TableDefinition,
+    out: ConstraintDiff[]
+  ): void {
+    for (const fk of table.foreignKeys) {
+      out.push({ kind: 'add_fk', tableName, constraint: fk })
+    }
+    for (const uq of table.uniqueConstraints) {
+      out.push({ kind: 'add_unique', tableName, constraint: uq })
+    }
+  }
+
+  private extractConstraintDrops(
+    tableName: string,
+    table: TableDefinition,
+    out: ConstraintDiff[]
+  ): void {
+    for (const fk of table.foreignKeys) {
+      out.push({ kind: 'drop_fk', tableName, constraint: fk })
+    }
+    for (const uq of table.uniqueConstraints) {
+      out.push({ kind: 'drop_unique', tableName, constraint: uq })
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Index diff
+  // ---------------------------------------------------------------------------
+
+  private diffIndexes(
+    tableName: string,
+    desired: TableDefinition,
+    actual: TableDefinition,
+    out: IndexDiff[]
+  ): void {
+    const actualIdxs = new Set(actual.indexes.map(idxKey))
+    const desiredIdxs = new Set(desired.indexes.map(idxKey))
+
+    for (const idx of desired.indexes) {
+      if (!actualIdxs.has(idxKey(idx))) {
+        out.push({ kind: 'add', tableName, index: idx })
+      }
+    }
+    for (const idx of actual.indexes) {
+      if (!desiredIdxs.has(idxKey(idx))) {
+        out.push({ kind: 'drop', tableName, index: idx })
+      }
+    }
+  }
+
+  private extractIndexAdds(tableName: string, table: TableDefinition, out: IndexDiff[]): void {
+    for (const idx of table.indexes) {
+      out.push({ kind: 'add', tableName, index: idx })
+    }
+  }
+
+  private extractIndexDrops(tableName: string, table: TableDefinition, out: IndexDiff[]): void {
+    for (const idx of table.indexes) {
+      out.push({ kind: 'drop', tableName, index: idx })
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Comparison helpers
+// ---------------------------------------------------------------------------
+
+function fkKey(fk: ForeignKeyConstraint): string {
+  return `${fk.columns.join(',')}->${fk.referencedTable}(${fk.referencedColumns.join(',')})`
+}
+
+function uqKey(uq: UniqueConstraint): string {
+  return [...uq.columns].sort().join(',')
+}
+
+function idxKey(idx: IndexDefinition): string {
+  return `${[...idx.columns].sort().join(',')}_${idx.unique ? 'unique' : 'non_unique'}`
+}
+
+/** Deep-compare two PostgreSQL types. */
+export function pgTypesEqual(a: PostgreSQLType, b: PostgreSQLType): boolean {
+  if (typeof a === 'string' && typeof b === 'string') return a === b
+  if (typeof a !== typeof b) return false
+  if (typeof a === 'object' && typeof b === 'object') {
+    if (a.type !== (b as any).type) return false
+    if (a.type === 'custom' && (b as any).type === 'custom') {
+      return a.name === (b as any).name
+    }
+    if (a.type === 'array' && (b as any).type === 'array') {
+      return pgTypesEqual(a.element as PostgreSQLType, (b as any).element as PostgreSQLType)
+    }
+  }
+  return false
+}
+
+/** Compare two default values for equality. */
+export function defaultsEqual(a: DefaultValue | undefined, b: DefaultValue | undefined): boolean {
+  if (a === undefined && b === undefined) return true
+  if (a === undefined || b === undefined) return false
+  if (a.kind !== b.kind) return false
+  if (a.kind === 'literal' && b.kind === 'literal') return a.value === b.value
+  if (a.kind === 'expression' && b.kind === 'expression') return a.sql === b.sql
+  return false
+}

package/src/database/migration/file_generator.ts

@@ -0,0 +1,125 @@
+import { join } from 'node:path'
+import type {
+  SchemaDiff,
+  GeneratedSql,
+  MigrationManifest,
+  MigrationSummary,
+  TableDiff,
+} from './types.ts'
+
+/**
+ * Creates the migration directory structure and writes SQL files + manifest.
+ *
+ * @example
+ * const fileGen = new MigrationFileGenerator('database/migrations')
+ * await fileGen.generate(version, 'initial', generatedSql, diff)
+ */
+export default class MigrationFileGenerator {
+  constructor(private basePath: string) {}
+
+  async generate(
+    version: string,
+    message: string,
+    sql: GeneratedSql,
+    diff: SchemaDiff,
+    tableOrder?: string[]
+  ): Promise<string> {
+    const migrationDir = join(this.basePath, version)
+
+    // Build file list and execution order
+    const upOrder: string[] = []
+    const downOrder: string[] = []
+
+    // 1. Enums
+    if (sql.enumsUp.trim()) {
+      await Bun.write(join(migrationDir, 'enums', 'up.sql'), sql.enumsUp + '\n')
+      await Bun.write(join(migrationDir, 'enums', 'down.sql'), sql.enumsDown + '\n')
+      upOrder.push('enums/up.sql')
+      downOrder.unshift('enums/down.sql')
+    }
+
+    // 2. Tables — in dependency order for up, reverse for down
+    const tableNames = this.resolveTableOrder(diff.tables, tableOrder)
+    for (const name of tableNames) {
+      const tableSql = sql.tables.get(name)
+      if (!tableSql) continue
+      await Bun.write(join(migrationDir, 'tables', name, 'up.sql'), tableSql.up + '\n')
+      await Bun.write(join(migrationDir, 'tables', name, 'down.sql'), tableSql.down + '\n')
+      upOrder.push(`tables/${name}/up.sql`)
+      downOrder.unshift(`tables/${name}/down.sql`)
+    }
+
+    // 3. Constraints
+    if (sql.constraintsUp.trim()) {
+      await Bun.write(join(migrationDir, 'constraints', 'up.sql'), sql.constraintsUp + '\n')
+      await Bun.write(join(migrationDir, 'constraints', 'down.sql'), sql.constraintsDown + '\n')
+      upOrder.push('constraints/up.sql')
+      downOrder.unshift('constraints/down.sql')
+    }
+
+    // 4. Indexes
+    if (sql.indexesUp.trim()) {
+      await Bun.write(join(migrationDir, 'indexes', 'up.sql'), sql.indexesUp + '\n')
+      await Bun.write(join(migrationDir, 'indexes', 'down.sql'), sql.indexesDown + '\n')
+      upOrder.push('indexes/up.sql')
+      downOrder.unshift('indexes/down.sql')
+    }
+
+    // Build manifest
+    const manifest: MigrationManifest = {
+      version,
+      message,
+      generatedAt: new Date().toISOString(),
+      summary: this.buildSummary(diff),
+      executionOrder: { up: upOrder, down: downOrder },
+    }
+
+    await Bun.write(join(migrationDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
+
+    return migrationDir
+  }
+
+  private resolveTableOrder(tableDiffs: TableDiff[], tableOrder?: string[]): string[] {
+    const tableNames = tableDiffs.map(t => (t.kind === 'modify' ? t.tableName : t.table.name))
+
+    if (!tableOrder) return tableNames
+
+    // Sort based on provided dependency order, keeping unknown tables at the end
+    const orderIndex = new Map(tableOrder.map((name, i) => [name, i]))
+    return [...tableNames].sort((a, b) => {
+      const ai = orderIndex.get(a) ?? Infinity
+      const bi = orderIndex.get(b) ?? Infinity
+      return ai - bi
+    })
+  }
+
+  private buildSummary(diff: SchemaDiff): MigrationSummary {
+    let tablesToCreate = 0
+    let tablesToDrop = 0
+    let tablesToModify = 0
+    let enumsToCreate = 0
+    let enumsToModify = 0
+    let enumsToDrop = 0
+
+    for (const t of diff.tables) {
+      if (t.kind === 'create') tablesToCreate++
+      else if (t.kind === 'drop') tablesToDrop++
+      else if (t.kind === 'modify') tablesToModify++
+    }
+
+    for (const e of diff.enums) {
+      if (e.kind === 'create') enumsToCreate++
+      else if (e.kind === 'modify') enumsToModify++
+      else if (e.kind === 'drop') enumsToDrop++
+    }
+
+    return {
+      tablesToCreate,
+      tablesToDrop,
+      tablesToModify,
+      enumsToCreate,
+      enumsToModify,
+      enumsToDrop,
+    }
+  }
+}

package/src/database/migration/index.ts

@@ -0,0 +1,18 @@
+export { default as SchemaDiffer } from './differ.ts'
+export { default as SqlGenerator } from './sql_generator.ts'
+export { default as MigrationFileGenerator } from './file_generator.ts'
+export { default as MigrationRunner } from './runner.ts'
+export { default as MigrationTracker } from './tracker.ts'
+export type {
+  SchemaDiff,
+  EnumDiff,
+  TableDiff,
+  ColumnDiff,
+  ConstraintDiff,
+  IndexDiff,
+  GeneratedSql,
+  MigrationManifest,
+  MigrationSummary,
+  MigrationRecord,
+} from './types.ts'
+export type { RunResult, RollbackResult } from './runner.ts'

package/src/database/migration/runner.ts

@@ -0,0 +1,133 @@
+import { join } from 'node:path'
+import { readdirSync } from 'node:fs'
+import type Database from '../database.ts'
+import type MigrationTracker from './tracker.ts'
+import type { MigrationManifest } from './types.ts'
+import { DatabaseError } from '../../exceptions/errors.ts'
+
+export interface RunResult {
+  applied: string[]
+  batch: number
+}
+
+export interface RollbackResult {
+  rolledBack: string[]
+  batch: number
+}
+
+/**
+ * Executes migration SQL files against the database.
+ *
+ * Each migration version is run inside a transaction so a failure
+ * rolls back the entire version (not just the failing file).
+ */
+export default class MigrationRunner {
+  constructor(
+    private db: Database,
+    private tracker: MigrationTracker,
+    private migrationsPath: string
+  ) {}
+
+  /** Apply all pending migrations. */
+  async run(): Promise<RunResult> {
+    await this.tracker.ensureTable()
+
+    const allVersions = this.listVersions()
+    const pending = await this.tracker.getPendingVersions(allVersions)
+
+    if (pending.length === 0) return { applied: [], batch: 0 }
+
+    const batch = (await this.tracker.getLastBatch()) + 1
+
+    for (const version of pending) {
+      await this.applyMigration(version, batch)
+    }
+
+    return { applied: pending, batch }
+  }
+
+  /** Rollback the latest batch, or a specific batch if provided. */
+  async rollback(batch?: number): Promise<RollbackResult> {
+    await this.tracker.ensureTable()
+
+    const targetBatch = batch ?? (await this.tracker.getLastBatch())
+    if (targetBatch === 0) return { rolledBack: [], batch: 0 }
+
+    const records = await this.tracker.getMigrationsByBatch(targetBatch)
+    if (records.length === 0) return { rolledBack: [], batch: targetBatch }
+
+    // Records are already ordered DESC by version from the tracker
+    const rolledBack: string[] = []
+    for (const record of records) {
+      await this.rollbackMigration(record.version)
+      rolledBack.push(record.version)
+    }
+
+    return { rolledBack, batch: targetBatch }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private async applyMigration(version: string, batch: number): Promise<void> {
+    const manifest = await this.readManifest(version)
+    const files = manifest.executionOrder.up
+
+    try {
+      await this.db.sql.begin(async tx => {
+        for (const file of files) {
+          const sqlContent = await Bun.file(join(this.migrationsPath, version, file)).text()
+          if (sqlContent.trim()) {
+            await tx.unsafe(sqlContent)
+          }
+        }
+        await tx.unsafe(`INSERT INTO _strav_migrations (version, batch) VALUES ($1, $2)`, [
+          version,
+          batch,
+        ])
+      })
+    } catch (err) {
+      throw new DatabaseError(`Migration ${version} failed: ${err instanceof Error ? err.message : err}`)
+    }
+  }
+
+  private async rollbackMigration(version: string): Promise<void> {
+    const manifest = await this.readManifest(version)
+    const files = manifest.executionOrder.down
+
+    try {
+      await this.db.sql.begin(async tx => {
+        for (const file of files) {
+          const sqlContent = await Bun.file(join(this.migrationsPath, version, file)).text()
+          if (sqlContent.trim()) {
+            await tx.unsafe(sqlContent)
+          }
+        }
+        await tx.unsafe(`DELETE FROM _strav_migrations WHERE version = $1`, [version])
+      })
+    } catch (err) {
+      throw new DatabaseError(
+        `Rollback of migration ${version} failed: ${err instanceof Error ? err.message : err}`
+      )
+    }
+  }
+
+  private async readManifest(version: string): Promise<MigrationManifest> {
+    const manifestPath = join(this.migrationsPath, version, 'manifest.json')
+    return await Bun.file(manifestPath).json()
+  }
+
+  /** List all migration version directories sorted numerically. */
+  private listVersions(): string[] {
+    try {
+      const entries = readdirSync(this.migrationsPath, { withFileTypes: true })
+      return entries
+        .filter(e => e.isDirectory() && /^\d+$/.test(e.name))
+        .map(e => e.name)
+        .sort()
+    } catch {
+      return []
+    }
+  }
+}