@remix-run/data-table 0.1.0 → 0.2.0

package/src/lib/errors.ts

@@ -2,7 +2,14 @@
  * Base error for all `data-table` failures.
  */
 export class DataTableError extends Error {
+  /**
+   * Stable error code identifying the failure category.
+   */
   code: string
+
+  /**
+   * Optional structured metadata attached to the failure.
+   */
   metadata?: Record<string, unknown>
 
   constructor(
@@ -24,6 +31,9 @@ export class DataTableError extends Error {
  * Thrown when input data fails schema validation.
  */
 export class DataTableValidationError extends DataTableError {
+  /**
+   * Validation issues reported by the schema validator.
+   */
   issues: ReadonlyArray<unknown>
 
   constructor(

package/src/lib/migrations/filename.ts

@@ -0,0 +1,25 @@
+const migrationFilenamePattern = /^(\d{14})_(.+)\.(?:m?ts|m?js|cts|cjs)$/
+
+/**
+ * Parses a migration filename into `{ id, name }`.
+ *
+ * Expected format: `YYYYMMDDHHmmss_name.(ts|js|mts|mjs|cts|cjs)`.
+ * @param filename Migration file basename.
+ * @returns Parsed migration id and name.
+ */
+export function parseMigrationFilename(filename: string): { id: string; name: string } {
+  let match = filename.match(migrationFilenamePattern)
+
+  if (!match) {
+    throw new Error(
+      'Invalid migration filename "' +
+        filename +
+        '". Expected format YYYYMMDDHHmmss_name.ts (or .js/.mts/.mjs/.cts/.cjs)',
+    )
+  }
+
+  return {
+    id: match[1],
+    name: match[2],
+  }
+}

package/src/lib/migrations/helpers.ts

@@ -0,0 +1,108 @@
+import type { TableRef } from '../adapter.ts'
+import type { IndexColumns, KeyColumns } from '../migrations.ts'
+
+export function toTableRef(name: string): TableRef {
+  let segments = name.split('.')
+
+  if (segments.length === 1) {
+    return { name }
+  }
+
+  return {
+    schema: segments[0],
+    name: segments.slice(1).join('.'),
+  }
+}
+
+export function normalizeIndexColumns(columns: IndexColumns): string[] {
+  return normalizeKeyColumns(columns)
+}
+
+export function normalizeKeyColumns(columns: KeyColumns): string[] {
+  if (Array.isArray(columns)) {
+    return [...columns]
+  }
+
+  return [columns]
+}
+
+function normalizeNamePart(value: string): string {
+  let normalized = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+
+  if (normalized.length === 0) {
+    return 'item'
+  }
+
+  return normalized
+}
+
+function tableNamePart(table: TableRef): string {
+  if (table.schema) {
+    return normalizeNamePart(table.schema + '_' + table.name)
+  }
+
+  return normalizeNamePart(table.name)
+}
+
+function hashString(value: string): number {
+  let hash = 5381
+
+  for (let index = 0; index < value.length; index++) {
+    hash = ((hash << 5) + hash) ^ value.charCodeAt(index)
+  }
+
+  return hash >>> 0
+}
+
+function withNameLimit(name: string): string {
+  let limit = 63
+
+  if (name.length <= limit) {
+    return name
+  }
+
+  let suffix = hashString(name).toString(36).padStart(8, '0').slice(0, 8)
+  return name.slice(0, limit - 9) + '_' + suffix
+}
+
+function columnsNamePart(columns: string[]): string {
+  return columns.map((column) => normalizeNamePart(column)).join('_')
+}
+
+export function createPrimaryKeyName(table: TableRef): string {
+  return withNameLimit(tableNamePart(table) + '_pk')
+}
+
+export function createUniqueName(table: TableRef, columns: string[]): string {
+  return withNameLimit(tableNamePart(table) + '_' + columnsNamePart(columns) + '_uq')
+}
+
+export function createForeignKeyName(
+  table: TableRef,
+  columns: string[],
+  references: TableRef,
+  referenceColumns: string[],
+): string {
+  let base =
+    tableNamePart(table) +
+    '_' +
+    columnsNamePart(columns) +
+    '_' +
+    tableNamePart(references) +
+    '_' +
+    columnsNamePart(referenceColumns) +
+    '_fk'
+  return withNameLimit(base)
+}
+
+export function createCheckName(table: TableRef, expression: string): string {
+  let suffix = hashString(expression).toString(36)
+  return withNameLimit(tableNamePart(table) + '_chk_' + suffix)
+}
+
+export function createIndexName(table: TableRef, columns: string[]): string {
+  return withNameLimit(tableNamePart(table) + '_' + columnsNamePart(columns) + '_idx')
+}

package/src/lib/migrations/journal-store.ts

@@ -0,0 +1,122 @@
+import type { DatabaseAdapter, TransactionToken } from '../adapter.ts'
+import { rawSql } from '../sql.ts'
+import type { MigrationDescriptor, MigrationJournalRow } from '../migrations.ts'
+
+export function normalizeChecksum(migration: MigrationDescriptor): string {
+  if (migration.checksum) {
+    return migration.checksum
+  }
+
+  return migration.id + ':' + migration.name
+}
+
+export async function ensureMigrationJournal(
+  adapter: DatabaseAdapter,
+  tableName: string,
+): Promise<void> {
+  await adapter.migrate({
+    operation: {
+      kind: 'createTable',
+      table: { name: tableName },
+      ifNotExists: true,
+      columns: {
+        id: { type: 'varchar', length: 64, nullable: false, primaryKey: true },
+        name: { type: 'varchar', length: 255, nullable: false },
+        checksum: { type: 'varchar', length: 128, nullable: false },
+        batch: { type: 'integer', nullable: false },
+        applied_at: { type: 'timestamp', nullable: false, default: { kind: 'now' } },
+      },
+    },
+  })
+}
+
+export async function hasMigrationJournal(
+  adapter: DatabaseAdapter,
+  tableName: string,
+): Promise<boolean> {
+  try {
+    await adapter.execute({
+      operation: {
+        kind: 'raw',
+        sql: rawSql('select 1 from ' + tableName + ' limit 1'),
+      },
+    })
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function loadJournalRows(
+  adapter: DatabaseAdapter,
+  tableName: string,
+): Promise<MigrationJournalRow[]> {
+  let result = await adapter.execute({
+    operation: {
+      kind: 'raw',
+      sql: rawSql(
+        'select id, name, checksum, batch, applied_at from ' + tableName + ' order by id asc',
+      ),
+    },
+  })
+
+  let rows = result.rows ?? []
+
+  return rows.map((row) => ({
+    id: String(row.id),
+    name: String(row.name),
+    checksum: String(row.checksum),
+    batch: Number(row.batch),
+    appliedAt: new Date(String(row.applied_at)),
+  }))
+}
+
+export async function insertJournalRow(
+  adapter: DatabaseAdapter,
+  tableName: string,
+  row: {
+    id: string
+    name: string
+    checksum: string
+    batch: number
+  },
+  transaction?: TransactionToken,
+): Promise<void> {
+  await adapter.execute({
+    operation: {
+      kind: 'raw',
+      sql: rawSql('insert into ' + tableName + ' (id, name, checksum, batch) values (?, ?, ?, ?)', [
+        row.id,
+        row.name,
+        row.checksum,
+        row.batch,
+      ]),
+    },
+    transaction,
+  })
+}
+
+export async function deleteJournalRow(
+  adapter: DatabaseAdapter,
+  tableName: string,
+  id: string,
+  transaction?: TransactionToken,
+): Promise<void> {
+  await adapter.execute({
+    operation: {
+      kind: 'raw',
+      sql: rawSql('delete from ' + tableName + ' where id = ?', [id]),
+    },
+    transaction,
+  })
+}
+
+export function getBatch(rows: MigrationJournalRow[]): number {
+  if (rows.length === 0) {
+    return 1
+  }
+
+  let max = Math.max(...rows.map((row) => row.batch))
+  return max + 1
+}

package/src/lib/migrations/registry.ts

@@ -0,0 +1,62 @@
+import type { MigrationDescriptor, MigrationRegistry } from '../migrations.ts'
+
+/**
+ * Returns a new array of migrations ordered by migration id.
+ * @param migrations Migration descriptors to sort.
+ * @returns A newly sorted migration descriptor array.
+ */
+export function sortMigrations(migrations: MigrationDescriptor[]): MigrationDescriptor[] {
+  return [...migrations].sort((left, right) => left.id.localeCompare(right.id))
+}
+
+/**
+ * Resolves a migration source into a sorted migration list.
+ * @param input Migration list or registry.
+ * @returns A sorted migration descriptor list.
+ */
+export function resolveMigrations(
+  input: MigrationDescriptor[] | MigrationRegistry,
+): MigrationDescriptor[] {
+  if (Array.isArray(input)) {
+    return sortMigrations(input)
+  }
+
+  return input.list()
+}
+
+/**
+ * Creates an in-memory migration registry.
+ * @param initial Optional initial migration list.
+ * @returns A migration registry with duplicate-id protection.
+ * @example
+ * ```ts
+ * import { createMigrationRegistry } from 'remix/data-table/migrations'
+ *
+ * let registry = createMigrationRegistry()
+ * registry.register({ id, name, migration })
+ * ```
+ */
+export function createMigrationRegistry(initial: MigrationDescriptor[] = []): MigrationRegistry {
+  let migrations = new Map<string, MigrationDescriptor>()
+
+  for (let migration of initial) {
+    if (migrations.has(migration.id)) {
+      throw new Error('Duplicate migration id: ' + migration.id)
+    }
+
+    migrations.set(migration.id, migration)
+  }
+
+  return {
+    register(migration: MigrationDescriptor) {
+      if (migrations.has(migration.id)) {
+        throw new Error('Duplicate migration id: ' + migration.id)
+      }
+
+      migrations.set(migration.id, migration)
+    },
+    list() {
+      return sortMigrations(Array.from(migrations.values()))
+    },
+  }
+}

package/src/lib/migrations/runner.ts

@@ -0,0 +1,374 @@
+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,
+  MigrationRegistry,
+  MigrationRunner,
+  MigrationRunnerOptions,
+  MigrationStatus,
+  MigrationStatusEntry,
+} from '../migrations.ts'
+
+import {
+  deleteJournalRow,
+  ensureMigrationJournal,
+  getBatch,
+  hasMigrationJournal,
+  insertJournalRow,
+  loadJournalRows,
+  normalizeChecksum,
+} from './journal-store.ts'
+import { resolveMigrations } from './registry.ts'
+import { createMigrationSchema } from './schema-api.ts'
+
+type RunMigrationsInput = {
+  adapter: DatabaseAdapter
+  migrations: MigrationDescriptor[]
+  journalTable: string
+  direction: MigrationDirection
+  options: MigrateOptions
+}
+
+function assertStepOption(step: number | undefined): void {
+  if (step === undefined) {
+    return
+  }
+
+  if (!Number.isInteger(step) || step < 1) {
+    throw new Error('Invalid migration step option. Expected a positive integer.')
+  }
+}
+
+function assertMigrateOptions(options: MigrateOptions): 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 {
+  if (!to) {
+    return
+  }
+
+  let target = migrations.find((migration) => migration.id === to)
+
+  if (!target) {
+    throw new Error('Unknown migration target: ' + to)
+  }
+}
+
+function assertNoMigrationDrift(
+  migrations: MigrationDescriptor[],
+  journal: MigrationJournalRow[],
+): void {
+  let migrationMap = new Map(migrations.map((migration) => [migration.id, migration]))
+
+  for (let row of journal) {
+    let migration = migrationMap.get(row.id)
+
+    if (!migration) {
+      continue
+    }
+
+    let expected = normalizeChecksum(migration)
+
+    if (expected !== row.checksum) {
+      throw new Error(
+        'Migration checksum drift detected for "' +
+          row.id +
+          '" (journal=' +
+          row.checksum +
+          ', current=' +
+          expected +
+          ')',
+      )
+    }
+  }
+}
+
+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
+  }
+  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,
+  }
+
+  return createDatabase(dryRunAdapter)
+}
+
+async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult> {
+  let adapter = input.adapter
+  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)
+  assertStepOption(step)
+  assertTargetOption(migrations, target)
+
+  let sql: SqlStatement[] = []
+
+  await adapter.acquireMigrationLock?.()
+
+  try {
+    let journal: MigrationJournalRow[] = []
+
+    if (dryRun) {
+      let canReadJournal = await hasMigrationJournal(adapter, journalTable)
+
+      if (canReadJournal) {
+        journal = await loadJournalRows(adapter, journalTable)
+      }
+    } else {
+      await ensureMigrationJournal(adapter, journalTable)
+      journal = await loadJournalRows(adapter, journalTable)
+    }
+
+    let appliedMap = new Map(journal.map((row) => [row.id, row]))
+    assertNoMigrationDrift(migrations, journal)
+    let toRun: MigrationDescriptor[] = []
+
+    if (input.direction === 'up') {
+      for (let migration of migrations) {
+        if (!appliedMap.has(migration.id)) {
+          toRun.push(migration)
+        }
+      }
+
+      if (target) {
+        toRun = toRun.filter((migration) => migration.id <= target)
+      }
+
+      if (step !== undefined) {
+        toRun = toRun.slice(0, step)
+      }
+    } else {
+      let appliedMigrations = migrations
+        .filter((migration) => appliedMap.has(migration.id))
+        .reverse()
+
+      if (target) {
+        appliedMigrations = appliedMigrations.filter((migration) => migration.id >= target)
+      }
+
+      if (step !== undefined) {
+        appliedMigrations = appliedMigrations.slice(0, step)
+      }
+
+      toRun = appliedMigrations
+    }
+
+    let applied: MigrationStatusEntry[] = []
+    let reverted: MigrationStatusEntry[] = []
+    let batch = getBatch(journal)
+
+    for (let migration of toRun) {
+      if (
+        migration.migration.transaction === 'required' &&
+        !adapter.capabilities.transactionalDdl
+      ) {
+        throw new Error(
+          'Migration "' +
+            migration.id +
+            '" requires transactional DDL, but adapter does not support it',
+        )
+      }
+
+      let shouldUseTransaction =
+        !dryRun &&
+        migration.migration.transaction !== '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)
+
+          if (!dryRun) {
+            await adapter.migrate({ operation, transaction: token })
+          }
+        },
+        { transaction: token },
+      )
+      let context: MigrationContext = {
+        db,
+        schema,
+      }
+
+      try {
+        if (input.direction === 'up') {
+          await migration.migration.up(context)
+
+          if (!dryRun) {
+            await insertJournalRow(
+              adapter,
+              journalTable,
+              {
+                id: migration.id,
+                name: migration.name,
+                checksum: normalizeChecksum(migration),
+                batch,
+              },
+              token,
+            )
+          }
+
+          applied.push({
+            id: migration.id,
+            name: migration.name,
+            status: 'applied',
+          })
+        } else {
+          await migration.migration.down(context)
+
+          if (!dryRun) {
+            await deleteJournalRow(adapter, journalTable, migration.id, token)
+          }
+
+          reverted.push({
+            id: migration.id,
+            name: migration.name,
+            status: 'pending',
+          })
+        }
+
+        if (token) {
+          await adapter.commitTransaction(token)
+        }
+      } catch (error) {
+        if (token) {
+          await adapter.rollbackTransaction(token)
+        }
+
+        throw error
+      }
+    }
+
+    return {
+      applied,
+      reverted,
+      sql,
+    }
+  } finally {
+    await adapter.releaseMigrationLock?.()
+  }
+}
+
+/**
+ * Creates a migration runner for applying/reverting migrations against an adapter.
+ * @param adapter Database adapter used to compile and execute migration operations.
+ * @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,
+  migrations: MigrationDescriptor[] | MigrationRegistry,
+  options: MigrationRunnerOptions = {},
+): MigrationRunner {
+  let journalTable = options.journalTable ?? 'data_table_migrations'
+
+  return {
+    async up(runOptions: MigrateOptions = {}): Promise<MigrateResult> {
+      return runMigrations({
+        adapter,
+        migrations: resolveMigrations(migrations),
+        journalTable,
+        direction: 'up',
+        options: runOptions,
+      })
+    },
+    async down(runOptions: MigrateOptions = {}): Promise<MigrateResult> {
+      return runMigrations({
+        adapter,
+        migrations: resolveMigrations(migrations),
+        journalTable,
+        direction: 'down',
+        options: runOptions,
+      })
+    },
+    async status(): Promise<MigrationStatusEntry[]> {
+      await ensureMigrationJournal(adapter, journalTable)
+
+      let journal = await loadJournalRows(adapter, journalTable)
+      let journalMap = new Map(journal.map((row) => [row.id, row]))
+      let sortedMigrations = resolveMigrations(migrations)
+
+      return sortedMigrations.map((migration) => {
+        let journalRow = journalMap.get(migration.id)
+
+        if (!journalRow) {
+          return {
+            id: migration.id,
+            name: migration.name,
+            status: 'pending' as MigrationStatus,
+          }
+        }
+
+        let checksum = normalizeChecksum(migration)
+
+        return {
+          id: migration.id,
+          name: migration.name,
+          status:
+            checksum === journalRow.checksum
+              ? ('applied' as MigrationStatus)
+              : ('drifted' as MigrationStatus),
+          appliedAt: journalRow.appliedAt,
+          batch: journalRow.batch,
+          checksum: journalRow.checksum,
+        }
+      })
+    },
+  }
+}