@remix-run/data-table 0.3.0 → 0.4.0

package/src/lib/migrations/runner.ts

@@ -1,18 +1,26 @@
-import type { DatabaseAdapter, TransactionToken } from '../adapter.ts'
+import type { DatabaseDriver, TransactionToken } from '../driver.ts'
 import type {
-  MigrateOptions,
+  MigrationOperationOptions,
   MigrateResult,
   MigrationDescriptor,
   MigrationDirection,
   MigrationJournalRow,
   MigrationRegistry,
-  MigrationRunner,
-  MigrationRunnerOptions,
   MigrationStatus,
   MigrationStatusEntry,
   MigrationTransactionMode,
 } from '../migrations.ts'
 
+interface MigrationRunnerOptions {
+  journalTable?: string
+}
+
+interface MigrationRunner {
+  up(options?: MigrationOperationOptions): Promise<MigrateResult>
+  down(options?: MigrationOperationOptions): Promise<MigrateResult>
+  status(): Promise<MigrationStatusEntry[]>
+}
+
 import { parseTransactionDirective } from './directive.ts'
 import {
   deleteJournalRow,
@@ -25,12 +33,14 @@ import {
 } from './journal-store.ts'
 import { resolveMigrations } from './registry.ts'
 
+type MigrationRunnerContext = DatabaseDriver
+
 type RunMigrationsInput = {
-  adapter: DatabaseAdapter
+  driver: MigrationRunnerContext
   migrations: MigrationDescriptor[]
   journalTable: string
   direction: MigrationDirection
-  options: MigrateOptions
+  options: MigrationOperationOptions
 }
 
 function assertStepOption(step: number | undefined): void {
@@ -43,27 +53,46 @@ function assertStepOption(step: number | undefined): void {
   }
 }
 
-function assertMigrateOptions(options: MigrateOptions): void {
+function assertMigrationOperationOptions(options: MigrationOperationOptions): void {
   if (options.to !== undefined && options.step !== undefined) {
     throw new Error('Cannot combine "to" and "step" migration options in the same run')
   }
 }
 
-function assertTargetOption(migrations: MigrationDescriptor[], to: string | undefined): void {
+function resolveTargetOption(
+  migrations: MigrationDescriptor[],
+  to: string | undefined,
+): string | undefined {
   if (!to) {
-    return
+    return undefined
   }
 
-  let target = migrations.find((migration) => migration.id === to)
+  // Accept either a bare migration id or the full `id_name` directory form and
+  // normalize to the bare id so range filtering compares ids consistently.
+  let matches = migrations.filter(
+    (migration) => migration.id === to || migration.id + '_' + migration.name === to,
+  )
 
-  if (!target) {
+  if (matches.length === 0) {
     throw new Error('Unknown migration target: ' + to)
   }
+
+  if (matches.length > 1) {
+    throw new Error(
+      'Ambiguous migration target "' +
+        to +
+        '". Matches: ' +
+        matches.map((migration) => migration.id + '_' + migration.name).join(', '),
+    )
+  }
+
+  return matches[0].id
 }
 
-async function assertNoMigrationDrift(
+async function assertMigrationIntegrity(
   migrations: MigrationDescriptor[],
   journal: MigrationJournalRow[],
+  direction: MigrationDirection,
 ): Promise<void> {
   let migrationMap = new Map(migrations.map((migration) => [migration.id, migration]))
 
@@ -71,7 +100,15 @@ async function assertNoMigrationDrift(
     let migration = migrationMap.get(row.id)
 
     if (!migration) {
-      continue
+      // Rolling back must stay possible when journal rows have no matching
+      // migration files, so only forward runs hard-error on orphaned entries.
+      if (direction === 'down') {
+        continue
+      }
+
+      throw new Error(
+        'Applied migration "' + row.id + '_' + row.name + '" is missing from current migrations',
+      )
     }
 
     let expected = await computeChecksum(migration)
@@ -105,193 +142,193 @@ function resolveTransactionMode(migration: MigrationDescriptor): MigrationTransa
 }
 
 async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult> {
-  let adapter = input.adapter
+  if (input.driver.capabilities.migrationLock && !input.driver.withMigrationLock) {
+    throw new Error(
+      'Database driver reports migration lock support but does not implement withMigrationLock()',
+    )
+  }
+
+  if (input.driver.withMigrationLock) {
+    return input.driver.withMigrationLock(input.journalTable, (driver) =>
+      runMigrationsUnlocked({ ...input, driver }),
+    )
+  }
+
+  return runMigrationsUnlocked(input)
+}
+
+async function runMigrationsUnlocked(input: RunMigrationsInput): Promise<MigrateResult> {
+  let driver = input.driver
   let migrations = input.migrations
   let journalTable = input.journalTable
   let dryRun = Boolean(input.options.dryRun)
-  let target = input.options.to
   let step = input.options.step
 
-  assertMigrateOptions(input.options)
+  assertMigrationOperationOptions(input.options)
   assertStepOption(step)
-  assertTargetOption(migrations, target)
+
+  let target = resolveTargetOption(migrations, input.options.to)
 
   let sql: string[] = []
 
-  await adapter.acquireMigrationLock?.()
+  let journal: MigrationJournalRow[] = []
 
-  try {
-    let journal: MigrationJournalRow[] = []
+  if (dryRun) {
+    let canReadJournal = await hasMigrationJournal(driver, journalTable)
 
-    if (dryRun) {
-      let canReadJournal = await hasMigrationJournal(adapter, journalTable)
+    if (canReadJournal) {
+      journal = await loadJournalRows(driver, journalTable)
+    }
+  } else {
+    await ensureMigrationJournal(driver, journalTable)
+    journal = await loadJournalRows(driver, journalTable)
+  }
 
-      if (canReadJournal) {
-        journal = await loadJournalRows(adapter, journalTable)
+  let appliedMap = new Map(journal.map((row) => [row.id, row]))
+  await assertMigrationIntegrity(migrations, journal, input.direction)
+  let toRun: MigrationDescriptor[] = []
+
+  if (input.direction === 'up') {
+    for (let migration of migrations) {
+      if (!appliedMap.has(migration.id)) {
+        toRun.push(migration)
       }
-    } else {
-      await ensureMigrationJournal(adapter, journalTable)
-      journal = await loadJournalRows(adapter, journalTable)
     }
 
-    let appliedMap = new Map(journal.map((row) => [row.id, row]))
-    await assertNoMigrationDrift(migrations, journal)
-    let toRun: MigrationDescriptor[] = []
+    if (target) {
+      toRun = toRun.filter((migration) => migration.id <= target)
+    }
 
-    if (input.direction === 'up') {
-      for (let migration of migrations) {
-        if (!appliedMap.has(migration.id)) {
-          toRun.push(migration)
-        }
-      }
+    if (step !== undefined) {
+      toRun = toRun.slice(0, step)
+    }
+  } else {
+    toRun = migrations.filter((migration) => appliedMap.has(migration.id)).reverse()
 
-      if (target) {
-        toRun = toRun.filter((migration) => migration.id <= target)
-      }
+    if (target) {
+      toRun = toRun.filter((migration) => migration.id >= target)
+    }
 
-      if (step !== undefined) {
-        toRun = toRun.slice(0, step)
-      }
-    } else {
-      toRun = migrations.filter((migration) => appliedMap.has(migration.id)).reverse()
+    if (step !== undefined) {
+      toRun = toRun.slice(0, step)
+    }
 
-      if (target) {
-        toRun = toRun.filter((migration) => migration.id >= target)
+    for (let migration of toRun) {
+      if (migration.down === undefined) {
+        throw new Error('Migration "' + migration.id + '" has no down script')
       }
+    }
+  }
 
-      if (step !== undefined) {
-        toRun = toRun.slice(0, step)
-      }
+  let applied: MigrationStatusEntry[] = []
+  let reverted: MigrationStatusEntry[] = []
+  let batch = getBatch(journal)
 
-      for (let migration of toRun) {
-        if (migration.down === undefined) {
-          throw new Error('Migration "' + migration.id + '" has no down script')
-        }
-      }
+  for (let migration of toRun) {
+    let script = (input.direction === 'up' ? migration.up : migration.down) as string
+    let mode = resolveTransactionMode(migration)
+
+    if (mode === 'required' && !driver.capabilities.transactionalDdl) {
+      throw new Error(
+        'Migration "' +
+          migration.id +
+          '" requires transactional DDL, but the database does not support it',
+      )
     }
 
-    let applied: MigrationStatusEntry[] = []
-    let reverted: MigrationStatusEntry[] = []
-    let batch = getBatch(journal)
+    let shouldUseTransaction = !dryRun && mode !== 'none' && driver.capabilities.transactionalDdl
+    let token: TransactionToken | undefined
 
-    for (let migration of toRun) {
-      let script = (input.direction === 'up' ? migration.up : migration.down) as string
-      let mode = resolveTransactionMode(migration)
-
-      if (mode === 'required' && !adapter.capabilities.transactionalDdl) {
-        throw new Error(
-          'Migration "' +
-            migration.id +
-            '" requires transactional DDL, but adapter does not support it',
-        )
-      }
+    if (shouldUseTransaction) {
+      token = await driver.beginTransaction()
+    }
 
-      let shouldUseTransaction = !dryRun && mode !== 'none' && adapter.capabilities.transactionalDdl
-      let token: TransactionToken | undefined
+    sql.push(script)
 
-      if (shouldUseTransaction) {
-        token = await adapter.beginTransaction()
+    try {
+      if (!dryRun) {
+        if (script.trim().length > 0) {
+          await driver.executeScript(script, token)
+        }
       }
 
-      sql.push(script)
-
-      try {
+      if (input.direction === 'up') {
         if (!dryRun) {
-          if (script.trim().length > 0) {
-            await adapter.executeScript(script, token)
-          }
+          await insertJournalRow(
+            driver,
+            journalTable,
+            {
+              id: migration.id,
+              name: migration.name,
+              checksum: await computeChecksum(migration),
+              batch,
+            },
+            token,
+          )
         }
 
-        if (input.direction === 'up') {
-          if (!dryRun) {
-            await insertJournalRow(
-              adapter,
-              journalTable,
-              {
-                id: migration.id,
-                name: migration.name,
-                checksum: await computeChecksum(migration),
-                batch,
-              },
-              token,
-            )
-          }
-
-          applied.push({
-            id: migration.id,
-            name: migration.name,
-            status: 'applied',
-          })
-        } else {
-          if (!dryRun) {
-            await deleteJournalRow(adapter, journalTable, migration.id, token)
-          }
-
-          reverted.push({
-            id: migration.id,
-            name: migration.name,
-            status: 'pending',
-          })
+        applied.push({
+          id: migration.id,
+          name: migration.name,
+          status: 'applied',
+        })
+      } else {
+        if (!dryRun) {
+          await deleteJournalRow(driver, journalTable, migration.id, token)
         }
 
-        if (token) {
-          await adapter.commitTransaction(token)
-        }
-      } catch (error) {
-        if (token) {
-          await adapter.rollbackTransaction(token)
+        reverted.push({
+          id: migration.id,
+          name: migration.name,
+          status: 'pending',
+        })
+      }
+    } catch (error) {
+      if (token) {
+        try {
+          await driver.rollbackTransaction(token)
+        } catch (rollbackError) {
+          throw new AggregateError([error, rollbackError], 'Migration and rollback both failed', {
+            cause: error,
+          })
         }
-
-        throw error
       }
+
+      throw error
     }
 
-    return {
-      applied,
-      reverted,
-      sql,
+    if (token) {
+      await driver.commitTransaction(token)
     }
-  } finally {
-    await adapter.releaseMigrationLock?.()
+  }
+
+  return {
+    applied,
+    reverted,
+    sql,
   }
 }
 
-/**
- * Creates a migration runner for applying/reverting SQL migrations against an adapter.
- * @param adapter Database adapter used to execute migration scripts.
- * @param migrations Migration descriptors or registry.
- * @param options Optional runner configuration.
- * @returns A migration runner instance.
- * @example
- * ```ts
- * import { createMigrationRunner } from 'remix/data-table/migrations'
- *
- * let runner = createMigrationRunner(adapter, migrations, {
- *   journalTable: 'app_migrations',
- * })
- * await runner.up()
- * ```
- */
 export function createMigrationRunner(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   migrations: MigrationDescriptor[] | MigrationRegistry,
   options: MigrationRunnerOptions = {},
 ): MigrationRunner {
   let journalTable = options.journalTable ?? 'data_table_migrations'
 
   return {
-    async up(runOptions: MigrateOptions = {}): Promise<MigrateResult> {
+    async up(runOptions: MigrationOperationOptions = {}): Promise<MigrateResult> {
       return runMigrations({
-        adapter,
+        driver,
         migrations: resolveMigrations(migrations),
         journalTable,
         direction: 'up',
         options: runOptions,
       })
     },
-    async down(runOptions: MigrateOptions = {}): Promise<MigrateResult> {
+    async down(runOptions: MigrationOperationOptions = {}): Promise<MigrateResult> {
       return runMigrations({
-        adapter,
+        driver,
         migrations: resolveMigrations(migrations),
         journalTable,
         direction: 'down',
@@ -299,11 +336,12 @@ export function createMigrationRunner(
       })
     },
     async status(): Promise<MigrationStatusEntry[]> {
-      await ensureMigrationJournal(adapter, journalTable)
-
-      let journal = await loadJournalRows(adapter, journalTable)
+      let journal = (await hasMigrationJournal(driver, journalTable))
+        ? await loadJournalRows(driver, journalTable)
+        : []
       let journalMap = new Map(journal.map((row) => [row.id, row]))
       let sortedMigrations = resolveMigrations(migrations)
+      let migrationIds = new Set(sortedMigrations.map((migration) => migration.id))
 
       let statuses: MigrationStatusEntry[] = []
 
@@ -334,7 +372,22 @@ export function createMigrationRunner(
         })
       }
 
-      return statuses
+      for (let journalRow of journal) {
+        if (migrationIds.has(journalRow.id)) {
+          continue
+        }
+
+        statuses.push({
+          id: journalRow.id,
+          name: journalRow.name,
+          status: 'missing',
+          appliedAt: journalRow.appliedAt,
+          batch: journalRow.batch,
+          checksum: journalRow.checksum,
+        })
+      }
+
+      return statuses.sort((left, right) => left.id.localeCompare(right.id))
     },
   }
 }

package/src/lib/migrations-node.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 
-import type { MigrationDescriptor } from './migrations.ts'
+import type { MigrationDescriptor, Seed } from './migrations.ts'
 import { parseMigrationDirectoryName } from './migrations/directory-name.ts'
 
 /**
@@ -81,6 +81,28 @@ export async function loadMigrations(directory: string): Promise<MigrationDescri
   return migrations
 }
 
+/**
+ * Loads a SQL seed file on Node.js.
+ *
+ * The file may contain multiple SQL statements. Seeds that must be safe to
+ * run against an already-seeded database should use idempotent statements
+ * (for example, `insert or ignore` on SQLite).
+ *
+ * @param filename Absolute or relative path to a SQL seed file.
+ * @returns A seed function that executes the file's SQL script.
+ * @example
+ * ```ts
+ * import { loadSeed } from 'remix/data-table/migrations/node'
+ *
+ * let seed = await loadSeed('./app/data/seed.sql')
+ * await db.reset({ migrations, seed })
+ * ```
+ */
+export async function loadSeed(filename: string): Promise<Seed> {
+  let sql = await fs.readFile(filename, 'utf8')
+  return (db) => db.executeScript(sql)
+}
+
 function isNodeFileNotFoundError(error: unknown): boolean {
   return (
     typeof error === 'object' &&

package/src/lib/migrations.ts

@@ -1,24 +1,26 @@
+import type { Database } from './database.ts'
+
 /**
  * Controls how each migration is wrapped in transactions.
  *
- * - `auto` (default): wrap when the adapter supports transactional DDL.
- * - `required`: wrap; throws when the adapter does not support transactional DDL.
+ * - `auto` (default): wrap when the database supports transactional DDL.
+ * - `required`: wrap; throws when the database does not support transactional DDL.
  * - `none`: never wrap.
  */
 export type MigrationTransactionMode = 'auto' | 'required' | 'none'
 
 /**
- * Migration metadata + SQL consumed by the registry/runner.
+ * Migration metadata and SQL consumed by `Database.migrate()`.
  */
 export type MigrationDescriptor = {
   /** Migration id (typically a `YYYYMMDDHHmmss` timestamp). */
   id: string
   /** Human-readable migration slug. */
   name: string
-  /** SQL executed for `runner.up(...)`. May contain multiple statements. */
+  /** SQL executed when applying the migration. May contain multiple statements. */
   up: string
   /**
-   * SQL executed for `runner.down(...)`. May contain multiple statements.
+   * SQL executed when reverting the migration. May contain multiple statements.
    * Omit (or pass `undefined`) for irreversible migrations.
    */
   down?: string
@@ -29,7 +31,7 @@ export type MigrationDescriptor = {
 }
 
 /**
- * Direction used by migration runner operations.
+ * Direction used by `Database.migrate()`.
  */
 export type MigrationDirection = 'up' | 'down'
 
@@ -45,12 +47,17 @@ export type MigrationJournalRow = {
 }
 
 /**
- * Effective status for a known migration.
+ * Effective migration status.
+ *
+ * - `applied`: the current migration matches its journal entry.
+ * - `pending`: the current migration has not been applied.
+ * - `drifted`: the current migration differs from its journal entry.
+ * - `missing`: an applied journal entry has no migration in the current set.
  */
-export type MigrationStatus = 'applied' | 'pending' | 'drifted'
+export type MigrationStatus = 'applied' | 'pending' | 'drifted' | 'missing'
 
 /**
- * Status row returned by `runner.status()` and `runner.up/down(...)`.
+ * Status entry returned by database migration operations.
  */
 export type MigrationStatusEntry = {
   id: string
@@ -62,10 +69,13 @@ export type MigrationStatusEntry = {
 }
 
 /**
- * Common options for `runner.up(...)` and `runner.down(...)`.
+ * Bounds and dry-run options for a migration operation.
  * `to` and `step` are mutually exclusive.
+ *
+ * `to` accepts a bare migration id (`20260301113000`) or the full `id_name`
+ * directory form (`20260301113000_add_user_status`).
  */
-export type MigrateOptions =
+export type MigrationOperationOptions =
   | {
       to: string
       step?: never
@@ -83,7 +93,7 @@ export type MigrateOptions =
     }
 
 /**
- * Result shape returned by migration runner commands.
+ * Result returned by `Database.migrate()`.
  */
 export type MigrateResult = {
   applied: MigrationStatusEntry[]
@@ -103,9 +113,21 @@ export type MigrationRegistry = {
 }
 
 /**
- * Options for creating a migration runner.
+ * Migration collection accepted by `db.migrate(...)` and `db.migrationStatus(...)`.
+ */
+export type Migrations = MigrationDescriptor[] | MigrationRegistry
+
+/**
+ * Function that initializes application data in a database.
  */
-export type MigrationRunnerOptions = {
+export type Seed = (db: Database) => void | Promise<void>
+
+/**
+ * Options for applying or reverting migrations through `Database.migrate()`.
+ */
+export type DatabaseMigrateOptions = MigrationOperationOptions & {
+  /** Migration direction. Defaults to `up`. */
+  direction?: MigrationDirection
   /**
    * Journal table used to record applied migrations.
    * Defaults to `data_table_migrations`.
@@ -114,10 +136,27 @@ export type MigrationRunnerOptions = {
 }
 
 /**
- * Migration runner API for applying, reverting, and inspecting migration state.
+ * Options for reading migration status through `Database.migrationStatus()`.
  */
-export type MigrationRunner = {
-  up(options?: MigrateOptions): Promise<MigrateResult>
-  down(options?: MigrateOptions): Promise<MigrateResult>
-  status(): Promise<MigrationStatusEntry[]>
+export interface DatabaseMigrationStatusOptions {
+  /**
+   * Journal table used to record applied migrations.
+   * Defaults to `data_table_migrations`.
+   */
+  journalTable?: string
+}
+
+/**
+ * Options for rebuilding a database through `Database.reset()`.
+ */
+export interface DatabaseResetOptions {
+  /** Migrations to apply after wiping the database. */
+  migrations: Migrations
+  /** Function that initializes application data after migrations finish. */
+  seed?: Seed
+  /**
+   * Journal table used to record applied migrations.
+   * Defaults to `data_table_migrations`.
+   */
+  journalTable?: string
 }

package/src/lib/operators.ts

@@ -22,7 +22,7 @@ type PredicateColumn<input extends string | ColumnReferenceLike> = NormalizeColu
   string
 
 /**
- * Normalized predicate representation consumed by adapters.
+ * Normalized predicate representation consumed by drivers.
  */
 export type Predicate<column extends string = string> =
   | {

package/src/lib/query.ts

@@ -1,4 +1,4 @@
-import type { JoinClause, JoinType, SelectColumn } from './adapter.ts'
+import type { JoinClause, JoinType, SelectColumn } from './driver.ts'
 import { DataTableQueryError, DataTableValidationError } from './errors.ts'
 import type {
   MergeColumnTypeMaps,

package/src/lib/sql-helpers.ts

@@ -1,4 +1,4 @@
-import type { TableRef } from './adapter.ts'
+import type { TableRef } from './driver.ts'
 
 /**
  * Function used to quote SQL identifiers for a dialect.