@remix-run/data-table 0.3.0 → 0.4.0

package/src/index.ts

@@ -1,37 +1,23 @@
 export type {
-  AdapterCapabilityOverrides,
-  AdapterCapabilities,
+  DatabaseCapabilities,
+  DatabaseDriver,
+  DataManipulationOperation,
   DataManipulationRequest,
   ColumnCheck,
   ColumnComputed,
   ColumnDefault,
   ColumnDefinition,
   ColumnTypeName,
-  CountOperation,
   DataManipulationResult,
-  DataManipulationOperation,
-  DeleteOperation,
-  DatabaseAdapter,
-  ExistsOperation,
   ForeignKeyAction,
   IdentityOptions,
-  InsertManyOperation,
-  InsertOperation,
-  JoinClause,
-  JoinType,
-  RawOperation,
-  ReturningSelection,
-  SelectColumn,
-  SelectOperation,
   TableRef,
   TransactionOptions,
   TransactionToken,
-  UpdateOperation,
-  UpsertOperation,
-} from './lib/adapter.ts'
+} from './lib/driver.ts'
 
 export {
-  DataTableAdapterError,
+  DataTableDatabaseError,
   DataTableConstraintError,
   DataTableError,
   DataTableQueryError,
@@ -145,6 +131,7 @@ export type {
   CreateResultOptions,
   CreateRowOptions,
   DeleteManyOptions,
+  DatabaseOptions,
   FindManyOptions,
   FindOneOptions,
   OrderByInput,
@@ -160,6 +147,18 @@ export type {
   WriteRowResult,
   WriteRowsResult,
 } from './lib/database.ts'
-export { createDatabase, Database } from './lib/database.ts'
+export { Database } from './lib/database.ts'
+export type {
+  DatabaseMigrateOptions,
+  DatabaseMigrationStatusOptions,
+  DatabaseResetOptions,
+  MigrateResult,
+  MigrationDescriptor,
+  MigrationRegistry,
+  Migrations,
+  MigrationStatus,
+  MigrationStatusEntry,
+  Seed,
+} from './lib/migrations.ts'
 export type { AnyQuery } from './lib/query.ts'
 export { Query, query } from './lib/query.ts'

package/src/lib/column.ts

@@ -1,4 +1,4 @@
-import type { ColumnDefinition, ForeignKeyAction, IdentityOptions, TableRef } from './adapter.ts'
+import type { ColumnDefinition, ForeignKeyAction, IdentityOptions, TableRef } from './driver.ts'
 
 function toTableRef(name: string): TableRef {
   let segments = name.split('.')

package/src/lib/database/execution-context.ts

@@ -1,15 +1,19 @@
 import type {
+  DatabaseCapabilities,
   DataManipulationOperation,
   DataManipulationResult,
-  DatabaseAdapter,
-} from '../adapter.ts'
-import type { Database } from '../database.ts'
+  TransactionOptions,
+} from '../driver.ts'
 
 export const executeOperation = Symbol('executeOperation')
+export const runInTransaction = Symbol('runInTransaction')
 
-export type QueryExecutionContext = {
-  adapter: DatabaseAdapter
+export type QueryExecutionContext<dialect extends string = string> = {
+  capabilities: DatabaseCapabilities
   now(): unknown
-  transaction<result>(callback: (database: Database) => Promise<result>): Promise<result>
   [executeOperation](operation: DataManipulationOperation): Promise<DataManipulationResult>
+  [runInTransaction]<result>(
+    callback: (database: QueryExecutionContext<dialect>) => Promise<result>,
+    options?: TransactionOptions,
+  ): Promise<result>
 }

package/src/lib/database/helpers.ts

@@ -80,7 +80,7 @@ export function resolveCreateRowWhere<table extends AnyTable>(
       throw new DataTableQueryError(
         'create({ returnRow: true }) requires primary key values for table "' +
           getTableName(table) +
-          '" when adapter does not support RETURNING',
+          '" when the database does not support RETURNING',
       )
     }
 

package/src/lib/database/query-execution.ts

@@ -9,7 +9,7 @@ import type {
   SelectOperation,
   UpdateOperation,
   UpsertOperation,
-} from '../adapter.ts'
+} from '../driver.ts'
 import { DataTableQueryError } from '../errors.ts'
 import type { ReturningInput, WriteResult, WriteRowResult, WriteRowsResult } from '../database.ts'
 import { normalizeWhereInput } from '../operators.ts'
@@ -18,7 +18,11 @@ import { cloneQueryState, querySnapshot } from '../query.ts'
 import type { AnyTable } from '../table.ts'
 import { getPrimaryKeyObject, getTableName } from '../table.ts'
 
-import { executeOperation, type QueryExecutionContext } from './execution-context.ts'
+import {
+  executeOperation,
+  runInTransaction,
+  type QueryExecutionContext,
+} from './execution-context.ts'
 import {
   buildPrimaryKeyPredicate,
   hasScopedWriteModifiers,
@@ -244,7 +248,7 @@ async function executeInsert(
   )
   let returning = options?.returning
 
-  assertReturningCapability(database.adapter, 'insert', returning)
+  assertReturningCapability(database.capabilities, 'insert', returning)
 
   if (returning) {
     let operation: InsertOperation<AnyTable> = {
@@ -314,7 +318,7 @@ async function executeInsertMany(
   }
 
   let returning = options?.returning
-  assertReturningCapability(database.adapter, 'insertMany', returning)
+  assertReturningCapability(database.capabilities, 'insertMany', returning)
 
   if (returning) {
     let operation: InsertManyOperation<AnyTable> = {
@@ -371,7 +375,7 @@ async function executeUpdate(
   options?: { returning?: ReturningInput<Record<string, unknown>>; touch?: boolean },
 ): Promise<WriteResult | WriteRowsResult<Record<string, unknown>>> {
   let returning = options?.returning
-  assertReturningCapability(database.adapter, 'update', returning)
+  assertReturningCapability(database.capabilities, 'update', returning)
   let preparedChanges = prepareUpdateValues(
     table,
     changes as never,
@@ -386,7 +390,7 @@ async function executeUpdate(
   let result: DataManipulationResult
 
   if (hasScopedWriteModifiers(state)) {
-    result = await database.transaction(async (tx) => {
+    result = await database[runInTransaction](async (tx) => {
       let primaryKeys = await loadPrimaryKeyRowsForScope(tx, table, state)
       let primaryKeyPredicate = buildPrimaryKeyPredicate(table, primaryKeys)
 
@@ -448,7 +452,7 @@ async function executeDelete(
   options?: { returning?: ReturningInput<Record<string, unknown>> },
 ): Promise<WriteResult | WriteRowsResult<Record<string, unknown>>> {
   let returning = options?.returning
-  assertReturningCapability(database.adapter, 'delete', returning)
+  assertReturningCapability(database.capabilities, 'delete', returning)
   let tableName = getTableName(table)
   let deleteContext = {
     tableName,
@@ -462,7 +466,7 @@ async function executeDelete(
   let result: DataManipulationResult
 
   if (hasScopedWriteModifiers(state)) {
-    result = await database.transaction(async (tx) => {
+    result = await database[runInTransaction](async (tx) => {
       let primaryKeys = await loadPrimaryKeyRowsForScope(tx, table, state)
       let primaryKeyPredicate = buildPrimaryKeyPredicate(table, primaryKeys)
 
@@ -527,8 +531,8 @@ async function executeUpsert(
     update?: Record<string, unknown>
   },
 ): Promise<WriteResult | WriteRowResult<Record<string, unknown>>> {
-  if (!database.adapter.capabilities.upsert) {
-    throw new DataTableQueryError('Adapter does not support upsert')
+  if (!database.capabilities.upsert) {
+    throw new DataTableQueryError('Database does not support upsert')
   }
 
   let preparedValues = prepareInsertValues(
@@ -547,7 +551,7 @@ async function executeUpsert(
       )
     : undefined
   let returning = options?.returning
-  assertReturningCapability(database.adapter, 'upsert', returning)
+  assertReturningCapability(database.capabilities, 'upsert', returning)
 
   if (returning) {
     let operation: UpsertOperation<AnyTable> = {

package/src/lib/database/write-lifecycle.ts

@@ -1,4 +1,4 @@
-import type { DatabaseAdapter, ReturningSelection } from '../adapter.ts'
+import type { DatabaseCapabilities, ReturningSelection } from '../driver.ts'
 import { DataTableQueryError, DataTableValidationError } from '../errors.ts'
 import type { ReturningInput } from '../database.ts'
 import type {
@@ -249,12 +249,12 @@ export function runAfterDeleteHook<table extends AnyTable>(
 }
 
 export function assertReturningCapability<row extends Record<string, unknown>>(
-  adapter: DatabaseAdapter,
+  capabilities: DatabaseCapabilities,
   operation: 'insert' | 'insertMany' | 'update' | 'delete' | 'upsert',
   returning: ReturningInput<row> | undefined,
 ): void {
-  if (returning && !adapter.capabilities.returning) {
-    throw new DataTableQueryError(operation + '() returning is not supported by this adapter')
+  if (returning && !capabilities.returning) {
+    throw new DataTableQueryError(operation + '() returning is not supported by this database')
   }
 }
 

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()
 }