@remix-run/data-table 0.2.0 → 0.3.0

package/src/lib/migrations/runner.ts

@@ -1,11 +1,7 @@
-import { createDatabase, createDatabaseWithTransaction } from '../database.ts'
-import type { Database } from '../database.ts'
 import type { DatabaseAdapter, TransactionToken } from '../adapter.ts'
-import type { SqlStatement } from '../sql.ts'
 import type {
   MigrateOptions,
   MigrateResult,
-  MigrationContext,
   MigrationDescriptor,
   MigrationDirection,
   MigrationJournalRow,
@@ -14,8 +10,10 @@ import type {
   MigrationRunnerOptions,
   MigrationStatus,
   MigrationStatusEntry,
+  MigrationTransactionMode,
 } from '../migrations.ts'
 
+import { parseTransactionDirective } from './directive.ts'
 import {
   deleteJournalRow,
   ensureMigrationJournal,
@@ -23,10 +21,9 @@ import {
   hasMigrationJournal,
   insertJournalRow,
   loadJournalRows,
-  normalizeChecksum,
+  computeChecksum,
 } from './journal-store.ts'
 import { resolveMigrations } from './registry.ts'
-import { createMigrationSchema } from './schema-api.ts'
 
 type RunMigrationsInput = {
   adapter: DatabaseAdapter
@@ -64,10 +61,10 @@ function assertTargetOption(migrations: MigrationDescriptor[], to: string | unde
   }
 }
 
-function assertNoMigrationDrift(
+async function assertNoMigrationDrift(
   migrations: MigrationDescriptor[],
   journal: MigrationJournalRow[],
-): void {
+): Promise<void> {
   let migrationMap = new Map(migrations.map((migration) => [migration.id, migration]))
 
   for (let row of journal) {
@@ -77,7 +74,7 @@ function assertNoMigrationDrift(
       continue
     }
 
-    let expected = normalizeChecksum(migration)
+    let expected = await computeChecksum(migration)
 
     if (expected !== row.checksum) {
       throw new Error(
@@ -93,34 +90,18 @@ function assertNoMigrationDrift(
   }
 }
 
-function createDryRunDatabase(adapter: DatabaseAdapter): Database {
-  let error = new Error('Cannot execute data operations while running migrations with dryRun')
-  let throwDryRunError = async (): Promise<never> => {
-    throw error
+function resolveTransactionMode(migration: MigrationDescriptor): MigrationTransactionMode {
+  if (migration.transaction) {
+    return migration.transaction
   }
-  let dryRunAdapter: DatabaseAdapter = {
-    dialect: adapter.dialect,
-    capabilities: adapter.capabilities,
-    compileSql(operation) {
-      return adapter.compileSql(operation)
-    },
-    async hasTable(table) {
-      return adapter.hasTable(table)
-    },
-    async hasColumn(table, column) {
-      return adapter.hasColumn(table, column)
-    },
-    execute: throwDryRunError,
-    migrate: throwDryRunError,
-    beginTransaction: throwDryRunError,
-    commitTransaction: throwDryRunError,
-    rollbackTransaction: throwDryRunError,
-    createSavepoint: throwDryRunError,
-    rollbackToSavepoint: throwDryRunError,
-    releaseSavepoint: throwDryRunError,
+
+  let directive = parseTransactionDirective(migration.up)
+
+  if (directive) {
+    return directive
   }
 
-  return createDatabase(dryRunAdapter)
+  return 'auto'
 }
 
 async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult> {
@@ -135,7 +116,7 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
   assertStepOption(step)
   assertTargetOption(migrations, target)
 
-  let sql: SqlStatement[] = []
+  let sql: string[] = []
 
   await adapter.acquireMigrationLock?.()
 
@@ -154,7 +135,7 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
     }
 
     let appliedMap = new Map(journal.map((row) => [row.id, row]))
-    assertNoMigrationDrift(migrations, journal)
+    await assertNoMigrationDrift(migrations, journal)
     let toRun: MigrationDescriptor[] = []
 
     if (input.direction === 'up') {
@@ -172,19 +153,21 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
         toRun = toRun.slice(0, step)
       }
     } else {
-      let appliedMigrations = migrations
-        .filter((migration) => appliedMap.has(migration.id))
-        .reverse()
+      toRun = migrations.filter((migration) => appliedMap.has(migration.id)).reverse()
 
       if (target) {
-        appliedMigrations = appliedMigrations.filter((migration) => migration.id >= target)
+        toRun = toRun.filter((migration) => migration.id >= target)
       }
 
       if (step !== undefined) {
-        appliedMigrations = appliedMigrations.slice(0, step)
+        toRun = toRun.slice(0, step)
       }
 
-      toRun = appliedMigrations
+      for (let migration of toRun) {
+        if (migration.down === undefined) {
+          throw new Error('Migration "' + migration.id + '" has no down script')
+        }
+      }
     }
 
     let applied: MigrationStatusEntry[] = []
@@ -192,10 +175,10 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
     let batch = getBatch(journal)
 
     for (let migration of toRun) {
-      if (
-        migration.migration.transaction === 'required' &&
-        !adapter.capabilities.transactionalDdl
-      ) {
+      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 +
@@ -203,43 +186,23 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
         )
       }
 
-      let shouldUseTransaction =
-        !dryRun &&
-        migration.migration.transaction !== 'none' &&
-        adapter.capabilities.transactionalDdl
+      let shouldUseTransaction = !dryRun && mode !== 'none' && adapter.capabilities.transactionalDdl
       let token: TransactionToken | undefined
 
       if (shouldUseTransaction) {
         token = await adapter.beginTransaction()
       }
 
-      let db = dryRun
-        ? createDryRunDatabase(adapter)
-        : token
-          ? createDatabaseWithTransaction(adapter, token)
-          : createDatabase(adapter)
-
-      let schema = createMigrationSchema(
-        db,
-        async (operation) => {
-          let compiled = adapter.compileSql(operation)
-          sql.push(...compiled)
+      sql.push(script)
 
-          if (!dryRun) {
-            await adapter.migrate({ operation, transaction: token })
+      try {
+        if (!dryRun) {
+          if (script.trim().length > 0) {
+            await adapter.executeScript(script, token)
           }
-        },
-        { transaction: token },
-      )
-      let context: MigrationContext = {
-        db,
-        schema,
-      }
+        }
 
-      try {
         if (input.direction === 'up') {
-          await migration.migration.up(context)
-
           if (!dryRun) {
             await insertJournalRow(
               adapter,
@@ -247,7 +210,7 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
               {
                 id: migration.id,
                 name: migration.name,
-                checksum: normalizeChecksum(migration),
+                checksum: await computeChecksum(migration),
                 batch,
               },
               token,
@@ -260,8 +223,6 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
             status: 'applied',
           })
         } else {
-          await migration.migration.down(context)
-
           if (!dryRun) {
             await deleteJournalRow(adapter, journalTable, migration.id, token)
           }
@@ -296,8 +257,8 @@ async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult>
 }
 
 /**
- * Creates a migration runner for applying/reverting migrations against an adapter.
- * @param adapter Database adapter used to compile and execute migration operations.
+ * 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.
@@ -344,20 +305,23 @@ export function createMigrationRunner(
       let journalMap = new Map(journal.map((row) => [row.id, row]))
       let sortedMigrations = resolveMigrations(migrations)
 
-      return sortedMigrations.map((migration) => {
+      let statuses: MigrationStatusEntry[] = []
+
+      for (let migration of sortedMigrations) {
         let journalRow = journalMap.get(migration.id)
 
         if (!journalRow) {
-          return {
+          statuses.push({
             id: migration.id,
             name: migration.name,
             status: 'pending' as MigrationStatus,
-          }
+          })
+          continue
         }
 
-        let checksum = normalizeChecksum(migration)
+        let checksum = await computeChecksum(migration)
 
-        return {
+        statuses.push({
           id: migration.id,
           name: migration.name,
           status:
@@ -367,8 +331,10 @@ export function createMigrationRunner(
           appliedAt: journalRow.appliedAt,
           batch: journalRow.batch,
           checksum: journalRow.checksum,
-        }
-      })
+        })
+      }
+
+      return statuses
     },
   }
 }

package/src/lib/migrations-node.ts

@@ -1,16 +1,18 @@
-import { createHash } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
-import { pathToFileURL } from 'node:url'
-import type { Migration, MigrationDescriptor } from './migrations.ts'
-import { parseMigrationFilename } from './migrations/filename.ts'
+
+import type { MigrationDescriptor } from './migrations.ts'
+import { parseMigrationDirectoryName } from './migrations/directory-name.ts'
 
 /**
- * Loads migration modules from a directory on Node.js.
+ * Loads SQL-file migrations from a directory on Node.js.
+ *
+ * Each migration is a directory named `YYYYMMDDHHmmss_<slug>` containing:
+ * - `up.sql` (required)
+ * - `down.sql` (optional; omit for irreversible migrations)
  *
- * Filenames are used to infer migration `id` and `name`.
- * Each file must default-export `createMigration(...)`.
- * @param directory Absolute or relative directory containing migration files.
+ * `id` and `name` are inferred from the directory name.
+ * @param directory Absolute or relative directory containing migration directories.
  * @returns A sorted list of loaded migration descriptors.
  * @example
  * ```ts
@@ -20,52 +22,70 @@ import { parseMigrationFilename } from './migrations/filename.ts'
  * ```
  */
 export async function loadMigrations(directory: string): Promise<MigrationDescriptor[]> {
-  let allFiles = (await fs.readdir(directory, { withFileTypes: true }))
-    .filter((entry) => entry.isFile())
+  let entries = await fs.readdir(directory, { withFileTypes: true })
+  let directories = entries
+    .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name)
     .sort((left, right) => left.localeCompare(right))
-  let files: Array<{ file: string; id: string; name: string }> = []
-
-  for (let file of allFiles) {
-    if (!/\.(?:m?ts|m?js|cts|cjs)$/.test(file)) {
-      continue
-    }
-
-    let parsed = parseMigrationFilename(file)
-    files.push({ file, id: parsed.id, name: parsed.name })
-  }
 
   let migrations: MigrationDescriptor[] = []
   let seenIds = new Set<string>()
 
-  for (let entry of files) {
-    if (seenIds.has(entry.id)) {
+  for (let directoryName of directories) {
+    let parsed = parseMigrationDirectoryName(directoryName)
+
+    if (seenIds.has(parsed.id)) {
       throw new Error(
-        'Duplicate migration id "' + entry.id + '" inferred from filename "' + entry.file + '"',
+        'Duplicate migration id "' +
+          parsed.id +
+          '" inferred from directory "' +
+          directoryName +
+          '"',
       )
     }
 
-    seenIds.add(entry.id)
-    let fullPath = path.join(directory, entry.file)
-    let source = await fs.readFile(fullPath, 'utf8')
-    let checksum = createHash('sha256').update(source).digest('hex')
-    let module = (await import(pathToFileURL(fullPath).href)) as { default?: Migration }
-    let migration = module.default
+    seenIds.add(parsed.id)
 
-    if (!migration || typeof migration.up !== 'function' || typeof migration.down !== 'function') {
-      throw new Error(
-        'Migration file "' + entry.file + '" must default-export createMigration(...)',
-      )
+    let directoryPath = path.join(directory, directoryName)
+    let upPath = path.join(directoryPath, 'up.sql')
+    let downPath = path.join(directoryPath, 'down.sql')
+
+    let up: string
+    try {
+      up = await fs.readFile(upPath, 'utf8')
+    } catch (error) {
+      if (isNodeFileNotFoundError(error)) {
+        throw new Error('Migration directory "' + directoryName + '" is missing up.sql')
+      }
+      throw error
+    }
+
+    let down: string | undefined
+    try {
+      down = await fs.readFile(downPath, 'utf8')
+    } catch (error) {
+      if (!isNodeFileNotFoundError(error)) {
+        throw error
+      }
     }
 
     migrations.push({
-      id: entry.id,
-      name: entry.name,
-      path: fullPath,
-      checksum,
-      migration,
+      id: parsed.id,
+      name: parsed.name,
+      up,
+      down,
+      path: directoryPath,
     })
   }
 
   return migrations
 }
+
+function isNodeFileNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as { code?: unknown }).code === 'ENOENT'
+  )
+}

package/src/lib/migrations.ts

@@ -1,94 +1,31 @@
-import type { Database } from './database.ts'
-import type { ColumnDefinition, ForeignKeyAction, IndexDefinition } from './adapter.ts'
-import type { ColumnBuilder } from './column.ts'
-import type { SqlStatement } from './sql.ts'
-import type { AnyTable } from './table.ts'
-
 /**
  * Controls how each migration is wrapped in transactions.
- */
-export type MigrationTransactionMode = 'auto' | 'required' | 'none'
-
-/**
- * Runtime context passed to migration `up`/`down` handlers.
- */
-export type MigrationContext = {
-  /**
-   * Immediate data runtime (`query/create/update/exec/transaction`).
-   */
-  db: Database
-  /**
-   * Migration schema runtime (`createTable/alterTable/createIndex/...`).
-   */
-  schema: MigrationSchema
-}
-
-/**
- * Authoring shape for `createMigration(...)`.
- */
-export type CreateMigrationInput = {
-  up: (context: MigrationContext) => Promise<void> | void
-  down: (context: MigrationContext) => Promise<void> | void
-  transaction?: MigrationTransactionMode
-}
-
-/**
- * Normalized migration object consumed by the registry/runner.
- */
-export type Migration = {
-  up: CreateMigrationInput['up']
-  down: CreateMigrationInput['down']
-  transaction: MigrationTransactionMode
-}
-
-/**
- * Creates a migration descriptor with normalized defaults.
- * @param input Migration handlers and transaction mode.
- * @returns A normalized migration object.
- * @example
- * ```ts
- * import { createMigration, column as c } from 'remix/data-table/migrations'
- * import { table } from 'remix/data-table'
- *
- * let users = table({
- *   name: 'users',
- *   columns: {
- *     id: c.integer().primaryKey().autoIncrement(),
- *     email: c.varchar(255).notNull().unique(),
- *   },
- * })
  *
- * export default createMigration({
- *   async up({ db, schema }) {
- *     await schema.createTable(users)
- *
- *     if (db.adapter.dialect === 'sqlite') {
- *       await db.exec('pragma foreign_keys = on')
- *     }
- *   },
- *   async down({ schema }) {
- *     await schema.dropTable('users', { ifExists: true })
- *   },
- * })
- * ```
+ * - `auto` (default): wrap when the adapter supports transactional DDL.
+ * - `required`: wrap; throws when the adapter does not support transactional DDL.
+ * - `none`: never wrap.
  */
-export function createMigration(input: CreateMigrationInput): Migration {
-  return {
-    up: input.up,
-    down: input.down,
-    transaction: input.transaction ?? 'auto',
-  }
-}
+export type MigrationTransactionMode = 'auto' | 'required' | 'none'
 
 /**
- * Migration metadata stored in registries and returned by loaders.
+ * Migration metadata + SQL consumed by the registry/runner.
  */
 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. */
+  up: string
+  /**
+   * SQL executed for `runner.down(...)`. May contain multiple statements.
+   * Omit (or pass `undefined`) for irreversible migrations.
+   */
+  down?: string
+  /** Transaction wrapping mode. Defaults to `auto`. */
+  transaction?: MigrationTransactionMode
+  /** Optional source path used in error messages. */
   path?: string
-  checksum?: string
-  migration: Migration
 }
 
 /**
@@ -152,151 +89,9 @@ export type MigrateResult = {
   applied: MigrationStatusEntry[]
   reverted: MigrationStatusEntry[]
   /**
-   * Compiled SQL statements for operations processed during this run.
-   * Includes planned SQL when running with `dryRun: true`.
-   */
-  sql: SqlStatement[]
-}
-
-/**
- * Options for `schema.createTable(...)` migration operations.
- */
-export type CreateTableOptions = { ifNotExists?: boolean }
-/**
- * Options for `schema.alterTable(...)` migration operations.
- */
-export type AlterTableOptions = { ifExists?: boolean }
-/**
- * Options for `schema.dropTable(...)` migration operations.
- */
-export type DropTableOptions = { ifExists?: boolean; cascade?: boolean }
-/**
- * Accepts either one index column or multiple (compound index).
- */
-export type IndexColumns = string | string[]
-
-/**
- * Accepts either one key column or multiple (compound key).
- */
-export type KeyColumns = string | string[]
-
-/**
- * Accepts either a SQL table name or a `table(...)` object.
- */
-export type TableInput = string | AnyTable
-
-/**
- * Optional name override for constraints and indexes.
- */
-export type NamedConstraintOptions = {
-  name?: string
-}
-
-/**
- * Foreign key options for migration APIs.
- */
-export type ForeignKeyOptions = NamedConstraintOptions & {
-  onDelete?: ForeignKeyAction
-  onUpdate?: ForeignKeyAction
-}
-
-/**
- * Index options for migration APIs.
- */
-export type CreateIndexOptions = NamedConstraintOptions &
-  Omit<IndexDefinition, 'table' | 'name' | 'columns'> & {
-    ifNotExists?: boolean
-  }
-
-/**
- * Builder API available inside `schema.alterTable(name, table => ...)`.
- */
-export interface AlterTableBuilder {
-  /** Adds a column during an `alterTable` migration. */
-  addColumn(name: string, definition: ColumnDefinition | ColumnBuilder): void
-  /** Changes an existing column during an `alterTable` migration. */
-  changeColumn(name: string, definition: ColumnDefinition | ColumnBuilder): void
-  /** Renames a column during an `alterTable` migration. */
-  renameColumn(from: string, to: string): void
-  /** Drops a column during an `alterTable` migration. */
-  dropColumn(name: string, options?: { ifExists?: boolean }): void
-  /** Adds a primary key during an `alterTable` migration. */
-  addPrimaryKey(columns: KeyColumns, options?: NamedConstraintOptions): void
-  /** Drops a primary key during an `alterTable` migration. */
-  dropPrimaryKey(name: string): void
-  /** Adds a unique constraint during an `alterTable` migration. */
-  addUnique(columns: KeyColumns, options?: NamedConstraintOptions): void
-  /** Drops a unique constraint during an `alterTable` migration. */
-  dropUnique(name: string): void
-  /** Adds a foreign key during an `alterTable` migration. */
-  addForeignKey(
-    columns: KeyColumns,
-    refTable: TableInput,
-    refColumns?: KeyColumns,
-    options?: ForeignKeyOptions,
-  ): void
-  /** Drops a foreign key during an `alterTable` migration. */
-  dropForeignKey(name: string): void
-  /** Adds a check constraint during an `alterTable` migration. */
-  addCheck(expression: string, options?: NamedConstraintOptions): void
-  /** Drops a check constraint during an `alterTable` migration. */
-  dropCheck(name: string): void
-  /** Adds an index during an `alterTable` migration. */
-  addIndex(columns: IndexColumns, options?: CreateIndexOptions): void
-  /** Drops an index during an `alterTable` migration. */
-  dropIndex(name: string): void
-  /** Sets the table comment during an `alterTable` migration. */
-  comment(text: string): void
-}
-
-/**
- * DDL-focused operations mixed into the migration `db` object.
- */
-export interface MigrationSchema {
-  /** Creates a table in the migration schema. */
-  createTable<table extends AnyTable>(table: table, options?: CreateTableOptions): Promise<void>
-  /** Alters an existing table in the migration schema. */
-  alterTable(
-    table: TableInput,
-    migrate: (table: AlterTableBuilder) => void,
-    options?: AlterTableOptions,
-  ): Promise<void>
-  /** Renames a table in the migration schema. */
-  renameTable(from: TableInput, to: string): Promise<void>
-  /** Drops a table from the migration schema. */
-  dropTable(table: TableInput, options?: DropTableOptions): Promise<void>
-  /** Creates an index in the migration schema. */
-  createIndex(table: TableInput, columns: IndexColumns, options?: CreateIndexOptions): Promise<void>
-  /** Drops an index from the migration schema. */
-  dropIndex(table: TableInput, name: string, options?: { ifExists?: boolean }): Promise<void>
-  /** Renames an index in the migration schema. */
-  renameIndex(table: TableInput, from: string, to: string): Promise<void>
-  /** Adds a foreign key in the migration schema. */
-  addForeignKey(
-    table: TableInput,
-    columns: KeyColumns,
-    refTable: TableInput,
-    refColumns?: KeyColumns,
-    options?: ForeignKeyOptions,
-  ): Promise<void>
-  /** Drops a foreign key in the migration schema. */
-  dropForeignKey(table: TableInput, name: string): Promise<void>
-  /** Adds a check constraint in the migration schema. */
-  addCheck(table: TableInput, expression: string, options?: NamedConstraintOptions): Promise<void>
-  /** Drops a check constraint in the migration schema. */
-  dropCheck(table: TableInput, name: string): Promise<void>
-  /**
-   * Adds raw SQL to the migration plan as a migration operation.
-   */
-  plan(sql: string | SqlStatement): Promise<void>
-  /**
-   * Returns `true` when the table exists in the current database.
-   */
-  hasTable(table: TableInput): Promise<boolean>
-  /**
-   * Returns `true` when the column exists on the given table.
+   * SQL scripts that were (or, for `dryRun`, would have been) executed.
    */
-  hasColumn(table: TableInput, column: string): Promise<boolean>
+  sql: string[]
 }
 
 /**