@remix-run/data-table 0.3.0 → 0.5.0

package/src/lib/database.ts

@@ -2,13 +2,19 @@ import type {
   ColumnDefinition,
   DataManipulationOperation,
   DataManipulationResult,
-  DatabaseAdapter,
+  DatabaseCapabilities,
+  DatabaseDriver,
+  TableRef,
   TransactionOptions,
   TransactionToken,
-} from './adapter.ts'
+} from './driver.ts'
 import type { ColumnBuilder } from './column.ts'
-import { DataTableAdapterError, DataTableQueryError } from './errors.ts'
-import { executeOperation, type QueryExecutionContext } from './database/execution-context.ts'
+import { DataTableDatabaseError, DataTableQueryError } from './errors.ts'
+import {
+  executeOperation,
+  runInTransaction,
+  type QueryExecutionContext,
+} from './database/execution-context.ts'
 import {
   asQueryTableInput,
   getPrimaryKeyWhere,
@@ -26,6 +32,15 @@ import type {
 } from './query.ts'
 import { bindQueryRuntime, query as createQuery } from './query.ts'
 import type { ColumnInput, NormalizeColumnInput, TableMetadataLike } from './references.ts'
+import type {
+  DatabaseMigrateOptions,
+  DatabaseMigrationStatusOptions,
+  DatabaseResetOptions,
+  MigrateResult,
+  Migrations,
+  MigrationStatusEntry,
+} from './migrations.ts'
+import { createMigrationRunner } from './migrations/runner.ts'
 import type { SqlStatement } from './sql.ts'
 import { isSqlStatement, rawSql } from './sql.ts'
 import type {
@@ -327,7 +342,9 @@ type SavepointCounter = {
   value: number
 }
 
-type DatabaseOptions = {
+/** Options shared by database instances. */
+export interface DatabaseOptions {
+  /** Clock function used for auto-managed timestamps. */
   now?: () => unknown
 }
 
@@ -336,39 +353,168 @@ type DatabaseInternalState = {
   savepointCounter: SavepointCounter
 }
 
-const createInternalDatabase = Symbol('createInternalDatabase')
-
 /**
- * High-level database runtime used to build and execute data manipulation operations.
+ * High-level database runtime used to query and manage a database.
  *
- * Create instances directly with `new Database(adapter, options)` or use
- * `createDatabase(adapter, options)` as a thin wrapper.
+ * Database dialects extend this class and provide a {@link DatabaseDriver} to the constructor.
+ * The driver owns SQL execution, transactions, and connection lifecycle while this class provides
+ * the shared query, persistence, and migration APIs.
  */
-export class Database implements QueryExecutionContext {
-  #adapter: DatabaseAdapter
+export class Database<dialect extends string = string> {
+  #driver: DatabaseDriver<dialect>
+  #executionContext: QueryExecutionContext<dialect>
   #token?: TransactionToken
   #now: () => unknown
   #savepointCounter: SavepointCounter
 
-  constructor(adapter: DatabaseAdapter, options?: DatabaseOptions) {
-    this.#adapter = adapter
+  /**
+   * Creates a database backed by a driver.
+   * @param driver Low-level database engine integration.
+   * @param options Database runtime options.
+   */
+  constructor(driver: DatabaseDriver<dialect>, options?: DatabaseOptions) {
+    this.#driver = driver
     this.#now = options?.now ?? defaultNow
     this.#savepointCounter = { value: 0 }
+
+    let database = this
+    this.#executionContext = {
+      get capabilities() {
+        return database.capabilities
+      },
+      now() {
+        return database.now()
+      },
+      [executeOperation](operation) {
+        return database.#executeOperation(operation)
+      },
+      [runInTransaction](callback, transactionOptions) {
+        return database.#runInTransaction(
+          (transactionDatabase) => callback(transactionDatabase.#executionContext),
+          transactionOptions,
+        )
+      },
+    }
   }
 
-  static [createInternalDatabase](
-    adapter: DatabaseAdapter,
+  static #createInternalDatabase<dialect extends string>(
+    driver: DatabaseDriver<dialect>,
     options: DatabaseOptions | undefined,
     internal: DatabaseInternalState,
-  ): Database {
-    let database = new Database(adapter, options)
+  ): Database<dialect> {
+    let database = new Database(driver, options)
     database.#token = internal.token
     database.#savepointCounter = internal.savepointCounter
     return database
   }
 
-  get adapter(): DatabaseAdapter {
-    return this.#adapter
+  /** Stable identifier for the SQL dialect. */
+  get dialect(): dialect {
+    return this.#driver.dialect
+  }
+
+  /** Immutable feature flags used by shared query and migration behavior. */
+  get capabilities(): DatabaseCapabilities {
+    return this.#driver.capabilities
+  }
+
+  /**
+   * Executes a migration or raw multi-statement SQL script.
+   * @param sql SQL script to execute.
+   * @returns A promise that resolves when execution completes.
+   */
+  executeScript(sql: string): Promise<void> {
+    return this.#driver.executeScript(sql, this.#token)
+  }
+
+  /**
+   * Reports whether a table exists.
+   * @param table Table to inspect.
+   * @returns A promise that resolves to `true` when the table exists.
+   */
+  hasTable(table: TableRef): Promise<boolean> {
+    return this.#driver.hasTable(table, this.#token)
+  }
+
+  /**
+   * Reports whether a column exists on a table.
+   * @param table Table to inspect.
+   * @param column Column name to inspect.
+   * @returns A promise that resolves to `true` when the column exists.
+   */
+  hasColumn(table: TableRef, column: string): Promise<boolean> {
+    return this.#driver.hasColumn(table, column, this.#token)
+  }
+
+  /**
+   * Closes resources owned by this database.
+   * @returns A promise that resolves when owned resources have been released.
+   */
+  async close(): Promise<void> {
+    this.#assertLifecycleOperationAllowed('close')
+    await this.#driver.close()
+  }
+
+  /**
+   * Destructively recreates the configured database.
+   * @returns A promise that resolves when the database is ready for use.
+   */
+  async wipe(): Promise<void> {
+    this.#assertLifecycleOperationAllowed('wipe')
+    await this.#driver.wipe()
+  }
+
+  /**
+   * Applies or reverts migrations in order.
+   *
+   * @param migrations Migration descriptors or registry to apply.
+   * @param options Migration direction, bound, dry-run, and journal configuration.
+   * @returns The migrations applied or reverted by this run and their SQL scripts.
+   */
+  async migrate(migrations: Migrations, options?: DatabaseMigrateOptions): Promise<MigrateResult> {
+    this.#assertLifecycleOperationAllowed('migrate')
+    let { direction = 'up', journalTable, ...migrateOptions } = options ?? {}
+    let runner = createMigrationRunner(this.#driver, migrations, { journalTable })
+    return direction === 'up' ? runner.up(migrateOptions) : runner.down(migrateOptions)
+  }
+
+  /**
+   * Reports the current state of the provided migrations.
+   *
+   * @param migrations Migration descriptors or registry to inspect.
+   * @param options Migration journal configuration.
+   * @returns Status entries for the provided migrations.
+   */
+  async migrationStatus(
+    migrations: Migrations,
+    options: DatabaseMigrationStatusOptions = {},
+  ): Promise<MigrationStatusEntry[]> {
+    this.#assertLifecycleOperationAllowed('migrationStatus')
+    let runner = createMigrationRunner(this.#driver, migrations, options)
+    return runner.status()
+  }
+
+  /**
+   * Wipes the database, applies migrations, and optionally seeds data.
+   *
+   * @param options Migrations and optional seed function used to rebuild the database.
+   * @returns A promise that resolves when the database has been rebuilt.
+   */
+  async reset(options: DatabaseResetOptions): Promise<void> {
+    this.#assertLifecycleOperationAllowed('reset')
+    await this.wipe()
+    await this.migrate(options.migrations, { journalTable: options.journalTable })
+    await options.seed?.(this)
+  }
+
+  #assertLifecycleOperationAllowed(
+    method: 'close' | 'migrate' | 'migrationStatus' | 'reset' | 'wipe',
+  ): void {
+    if (this.#token) {
+      throw new DataTableQueryError(
+        'Cannot call ' + method + '() from a transaction-scoped database',
+      )
+    }
   }
 
   now(): unknown {
@@ -423,7 +569,7 @@ export class Database implements QueryExecutionContext {
       return toWriteResult(result)
     }
 
-    if (this.#adapter.capabilities.returning) {
+    if (this.capabilities.returning) {
       let result = (await query.insert(values, {
         returning: '*',
         touch,
@@ -485,9 +631,9 @@ export class Database implements QueryExecutionContext {
     let query: QueryForTable<table> = this.query(asQueryTableInput(table))
 
     if (options?.returnRows === true) {
-      if (!this.#adapter.capabilities.returning) {
+      if (!this.capabilities.returning) {
         throw new DataTableQueryError(
-          'createMany({ returnRows: true }) is not supported by this adapter',
+          'createMany({ returnRows: true }) is not supported by this database',
         )
       }
 
@@ -616,7 +762,7 @@ export class Database implements QueryExecutionContext {
   ): Promise<TableRowWith<table, LoadedRelationMap<relations>>> {
     let where = getPrimaryKeyWhere(table, value)
 
-    if (this.#adapter.capabilities.returning) {
+    if (this.capabilities.returning) {
       let updateResult = (await this.query(asQueryTableInput(table)).where(where).update(changes, {
         touch: options?.touch,
         returning: '*',
@@ -729,23 +875,30 @@ export class Database implements QueryExecutionContext {
         ? statementOrInput
         : rawSql(statementOrInput, values)
 
-      return this[executeOperation]({
+      return this.#executeOperation({
         kind: 'raw',
         sql: sqlStatement,
       })
     }
 
-    return executeQuery(this, statementOrInput)
+    return executeQuery(this.#executionContext, statementOrInput)
   }
 
   async transaction<result>(
-    callback: (database: Database) => Promise<result>,
+    callback: (database: Database<dialect>) => Promise<result>,
+    options?: TransactionOptions,
+  ): Promise<result> {
+    return this.#runInTransaction(callback, options)
+  }
+
+  async #runInTransaction<result>(
+    callback: (database: Database<dialect>) => Promise<result>,
     options?: TransactionOptions,
   ): Promise<result> {
     if (!this.#token) {
-      let token = await this.#adapter.beginTransaction(options)
-      let tx = Database[createInternalDatabase](
-        this.#adapter,
+      let token = await this.#driver.beginTransaction(options)
+      let tx = Database.#createInternalDatabase(
+        this.#driver,
         { now: this.#now },
         {
           token,
@@ -753,47 +906,71 @@ export class Database implements QueryExecutionContext {
         },
       )
 
+      let result: result
       try {
-        let result = await callback(tx)
-        await this.#adapter.commitTransaction(token)
-        return result
+        result = await callback(tx)
       } catch (error) {
-        await this.#adapter.rollbackTransaction(token)
+        try {
+          await this.#driver.rollbackTransaction(token)
+        } catch (rollbackError) {
+          throw new AggregateError(
+            [error, rollbackError],
+            'Database transaction and rollback both failed',
+            { cause: error },
+          )
+        }
         throw error
       }
+
+      await this.#driver.commitTransaction(token)
+      return result
     }
 
-    if (!this.#adapter.capabilities.savepoints) {
-      throw new DataTableQueryError('Nested transactions require adapter savepoint support')
+    if (!this.capabilities.savepoints) {
+      throw new DataTableQueryError('Nested transactions require database savepoint support')
     }
 
     let savepointName = 'sp_' + String(this.#savepointCounter.value)
     this.#savepointCounter.value += 1
 
-    await this.#adapter.createSavepoint(this.#token, savepointName)
+    await this.#driver.createSavepoint(this.#token, savepointName)
 
+    let result: result
     try {
-      let result = await callback(this)
-      await this.#adapter.releaseSavepoint(this.#token, savepointName)
-      return result
+      result = await callback(this)
     } catch (error) {
-      await this.#adapter.rollbackToSavepoint(this.#token, savepointName)
-      await this.#adapter.releaseSavepoint(this.#token, savepointName)
+      let failures: unknown[] = [error]
+      try {
+        await this.#driver.rollbackToSavepoint(this.#token, savepointName)
+      } catch (rollbackError) {
+        failures.push(rollbackError)
+      }
+      try {
+        await this.#driver.releaseSavepoint(this.#token, savepointName)
+      } catch (releaseError) {
+        failures.push(releaseError)
+      }
+      if (failures.length > 1) {
+        throw new AggregateError(failures, 'Nested transaction cleanup failed', { cause: error })
+      }
       throw error
     }
+
+    await this.#driver.releaseSavepoint(this.#token, savepointName)
+    return result
   }
 
-  async [executeOperation](operation: DataManipulationOperation): Promise<DataManipulationResult> {
+  async #executeOperation(operation: DataManipulationOperation): Promise<DataManipulationResult> {
     try {
-      return await this.#adapter.execute({
+      return await this.#driver.execute({
         operation,
         transaction: this.#token,
       })
     } catch (error) {
-      throw new DataTableAdapterError('Adapter execution failed', {
+      throw new DataTableDatabaseError('Database execution failed', {
         cause: error,
         metadata: {
-          dialect: this.#adapter.dialect,
+          dialect: this.dialect,
           operationKind: operation.kind,
         },
       })
@@ -801,56 +978,6 @@ export class Database implements QueryExecutionContext {
   }
 }
 
-/**
- * Creates a database runtime from an adapter.
- * Thin wrapper around `new Database(adapter, options)`.
- * @param adapter Adapter implementation responsible for SQL execution.
- * @param options Optional runtime options.
- * @param options.now Clock function used for auto-managed timestamps.
- * @returns A {@link Database} API instance.
- * @example
- * ```ts
- * import { column as c, createDatabase, table } from 'remix/data-table'
- *
- * let users = table({
- *   name: 'users',
- *   columns: {
- *     id: c.integer(),
- *     email: c.varchar(255),
- *   },
- * })
- *
- * let db = createDatabase(adapter)
- * let rows = await db.query(users).where({ id: 1 }).all()
- * ```
- */
-export function createDatabase(
-  adapter: DatabaseAdapter,
-  options?: { now?: () => unknown },
-): Database {
-  return new Database(adapter, options)
-}
-
-/**
- * Creates a database runtime bound to an existing adapter transaction token.
- * This is an internal helper used by the migration runner.
- * @param adapter Adapter implementation responsible for SQL execution.
- * @param token Active adapter transaction token.
- * @param options Optional runtime options.
- * @param options.now Clock function used for auto-managed timestamps.
- * @returns A {@link Database} API instance bound to the provided transaction.
- */
-export function createDatabaseWithTransaction(
-  adapter: DatabaseAdapter,
-  token: TransactionToken,
-  options?: { now?: () => unknown },
-): Database {
-  return Database[createInternalDatabase](adapter, options, {
-    token,
-    savepointCounter: { value: 0 },
-  })
-}
-
 function defaultNow(): Date {
   return new Date()
 }

package/src/lib/{adapter.ts → driver.ts}

@@ -1,10 +1,9 @@
 import type { AnyTable, OrderByClause } from './table.ts'
 import type { Predicate } from './operators.ts'
 import type { SqlStatement } from './sql.ts'
-import type { Pretty } from './types.ts'
 
 /**
- * Supported SQL join kinds.
+ * SQL join kinds supported by database drivers.
  */
 export type JoinType = 'inner' | 'left' | 'right'
 
@@ -31,7 +30,7 @@ export type SelectColumn = {
 export type ReturningSelection = '*' | string[]
 
 /**
- * Canonical select statement shape consumed by adapters.
+ * Canonical select statement shape consumed by drivers.
  */
 export type SelectOperation<table extends AnyTable = AnyTable> = {
   kind: 'select'
@@ -48,7 +47,7 @@ export type SelectOperation<table extends AnyTable = AnyTable> = {
 }
 
 /**
- * Canonical count statement shape consumed by adapters.
+ * Canonical count statement shape consumed by drivers.
  */
 export type CountOperation<table extends AnyTable = AnyTable> = {
   kind: 'count'
@@ -60,7 +59,7 @@ export type CountOperation<table extends AnyTable = AnyTable> = {
 }
 
 /**
- * Canonical exists statement shape consumed by adapters.
+ * Canonical exists statement shape consumed by drivers.
  */
 export type ExistsOperation<table extends AnyTable = AnyTable> = {
   kind: 'exists'
@@ -72,7 +71,7 @@ export type ExistsOperation<table extends AnyTable = AnyTable> = {
 }
 
 /**
- * Canonical insert statement shape consumed by adapters.
+ * Canonical insert statement shape consumed by drivers.
  */
 export type InsertOperation<table extends AnyTable = AnyTable> = {
   kind: 'insert'
@@ -82,7 +81,7 @@ export type InsertOperation<table extends AnyTable = AnyTable> = {
 }
 
 /**
- * Canonical bulk-insert statement shape consumed by adapters.
+ * Canonical bulk-insert statement shape consumed by drivers.
  */
 export type InsertManyOperation<table extends AnyTable = AnyTable> = {
   kind: 'insertMany'
@@ -92,7 +91,7 @@ export type InsertManyOperation<table extends AnyTable = AnyTable> = {
 }
 
 /**
- * Canonical update statement shape consumed by adapters.
+ * Canonical update statement shape consumed by drivers.
  */
 export type UpdateOperation<table extends AnyTable = AnyTable> = {
   kind: 'update'
@@ -103,7 +102,7 @@ export type UpdateOperation<table extends AnyTable = AnyTable> = {
 }
 
 /**
- * Canonical delete statement shape consumed by adapters.
+ * Canonical delete statement shape consumed by drivers.
  */
 export type DeleteOperation<table extends AnyTable = AnyTable> = {
   kind: 'delete'
@@ -113,7 +112,7 @@ export type DeleteOperation<table extends AnyTable = AnyTable> = {
 }
 
 /**
- * Canonical upsert statement shape consumed by adapters.
+ * Canonical upsert statement shape consumed by drivers.
  */
 export type UpsertOperation<table extends AnyTable = AnyTable> = {
   kind: 'upsert'
@@ -243,7 +242,7 @@ export type ColumnDefinition = {
 }
 
 /**
- * Opaque transaction handle supplied by adapters.
+ * Opaque transaction handle supplied by database drivers.
  */
 export type TransactionToken = {
   id: string
@@ -251,7 +250,7 @@ export type TransactionToken = {
 }
 
 /**
- * Transaction hints that adapters may apply when supported by the dialect.
+ * Transaction hints that database drivers may apply when supported by the dialect.
  */
 export type TransactionOptions = {
   isolationLevel?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable'
@@ -259,7 +258,7 @@ export type TransactionOptions = {
 }
 
 /**
- * Adapter execution request payload.
+ * Database driver execution request payload.
  */
 export type DataManipulationRequest = {
   operation: DataManipulationOperation
@@ -267,7 +266,7 @@ export type DataManipulationRequest = {
 }
 
 /**
- * Adapter data-manipulation result payload.
+ * Database data-manipulation result payload.
  */
 export type DataManipulationResult = {
   rows?: Record<string, unknown>[]
@@ -276,58 +275,59 @@ export type DataManipulationResult = {
 }
 
 /**
- * Declares adapter feature support.
+ * Declares database feature support.
  */
-export type AdapterCapabilities = {
-  returning: boolean
-  savepoints: boolean
-  upsert: boolean
-  transactionalDdl: boolean
-  migrationLock: boolean
+export type DatabaseCapabilities = {
+  readonly returning: boolean
+  readonly savepoints: boolean
+  readonly upsert: boolean
+  readonly transactionalDdl: boolean
+  readonly migrationLock: boolean
 }
 
 /**
- * Partial capabilities used to override adapter defaults.
+ * Low-level contract that connects a `Database` to a database engine.
  */
-export type AdapterCapabilityOverrides = Pretty<Partial<AdapterCapabilities>>
-
-/**
- * Runtime contract implemented by concrete database adapters.
- */
-export interface DatabaseAdapter {
-  /** Database dialect name exposed by the adapter. */
-  dialect: string
-  /** Feature flags describing the adapter's supported behaviors. */
-  capabilities: AdapterCapabilities
-  /** Compiles a data-manipulation operation into executable SQL statements. */
-  compileSql(operation: DataManipulationOperation): SqlStatement[]
+export interface DatabaseDriver<dialect extends string = string> {
+  /** Stable identifier for the SQL dialect. */
+  readonly dialect: dialect
+  /** Immutable feature flags used by shared query and migration behavior. */
+  readonly capabilities: DatabaseCapabilities
   /** Executes a data-manipulation request. */
   execute(request: DataManipulationRequest): Promise<DataManipulationResult>
-  /**
-   * Executes a raw SQL script that may contain multiple statements.
-   *
-   * Drivers must be configured to accept multi-statement scripts where required
-   * (for example, mysql2 needs `multipleStatements: true`).
-   */
+  /** Executes a raw SQL script that may contain multiple statements. */
   executeScript(sql: string, transaction?: TransactionToken): Promise<void>
-  /** Checks whether a table exists. */
-  hasTable(table: TableRef, transaction?: TransactionToken): Promise<boolean>
-  /** Checks whether a column exists on a table. */
-  hasColumn(table: TableRef, column: string, transaction?: TransactionToken): Promise<boolean>
   /** Starts a new database transaction. */
   beginTransaction(options?: TransactionOptions): Promise<TransactionToken>
   /** Commits an open transaction. */
   commitTransaction(token: TransactionToken): Promise<void>
   /** Rolls back an open transaction. */
   rollbackTransaction(token: TransactionToken): Promise<void>
+  /** Checks whether a table exists. */
+  hasTable(table: TableRef, transaction?: TransactionToken): Promise<boolean>
+  /** Checks whether a column exists on a table. */
+  hasColumn(table: TableRef, column: string, transaction?: TransactionToken): Promise<boolean>
   /** Creates a savepoint inside an open transaction. */
   createSavepoint(token: TransactionToken, name: string): Promise<void>
   /** Rolls back to a previously created savepoint. */
   rollbackToSavepoint(token: TransactionToken, name: string): Promise<void>
   /** Releases a previously created savepoint. */
   releaseSavepoint(token: TransactionToken, name: string): Promise<void>
-  /** Acquires the adapter's migration lock when supported. */
-  acquireMigrationLock?(): Promise<void>
-  /** Releases the adapter's migration lock when supported. */
-  releaseMigrationLock?(): Promise<void>
+  /** Destructively recreates the configured database. */
+  wipe(): Promise<void>
+  /** Releases connection handles owned by the driver. Must be safe to call repeatedly. */
+  close(): void | Promise<void>
+  /**
+   * Runs migration work while holding a driver-specific lock.
+   *
+   * The callback receives a driver bound to the connection that owns the lock. Drivers must
+   * release the lock when the callback rejects as well as when it resolves.
+   * @param name Logical migration lock name.
+   * @param run Migration work to run with the connection-bound driver.
+   * @returns The callback result.
+   */
+  withMigrationLock?<result>(
+    name: string,
+    run: (driver: DatabaseDriver<dialect>) => Promise<result>,
+  ): Promise<result>
 }

package/src/lib/errors.ts

@@ -77,9 +77,9 @@ export class DataTableQueryError extends DataTableError {
 }
 
 /**
- * Thrown when adapter execution fails.
+ * Thrown when database execution fails.
  */
-export class DataTableAdapterError extends DataTableError {
+export class DataTableDatabaseError extends DataTableError {
   constructor(
     message: string,
     options?: {
@@ -88,12 +88,12 @@ export class DataTableAdapterError extends DataTableError {
     },
   ) {
     super(message, {
-      code: 'DATA_TABLE_ADAPTER_ERROR',
+      code: 'DATA_TABLE_DATABASE_ERROR',
       cause: options?.cause,
       metadata: options?.metadata,
     })
 
-    this.name = 'DataTableAdapterError'
+    this.name = 'DataTableDatabaseError'
   }
 }