@remix-run/data-table 0.3.0 → 0.4.0

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'
   }
 }
 

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

@@ -1,4 +1,4 @@
-import type { DatabaseAdapter, TransactionToken } from '../adapter.ts'
+import type { DatabaseDriver, TransactionToken } from '../driver.ts'
 import { rawSql } from '../sql.ts'
 import type { MigrationDescriptor, MigrationJournalRow } from '../migrations.ts'
 
@@ -18,10 +18,10 @@ function bytesToHex(bytes: Uint8Array): string {
 }
 
 export async function ensureMigrationJournal(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   tableName: string,
 ): Promise<void> {
-  await adapter.executeScript(
+  await driver.executeScript(
     'create table if not exists ' +
       tableName +
       ' (' +
@@ -35,11 +35,11 @@ export async function ensureMigrationJournal(
 }
 
 export async function hasMigrationJournal(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   tableName: string,
 ): Promise<boolean> {
   try {
-    await adapter.execute({
+    await driver.execute({
       operation: {
         kind: 'raw',
         sql: rawSql('select 1 from ' + tableName + ' limit 1'),
@@ -48,15 +48,25 @@ export async function hasMigrationJournal(
 
     return true
   } catch {
+    // The probe fails both when the journal table is missing and when the
+    // database itself is unreachable. Only the former means "no journal yet";
+    // rethrow connection/auth failures via a table-independent query.
+    await driver.execute({
+      operation: {
+        kind: 'raw',
+        sql: rawSql('select 1'),
+      },
+    })
+
     return false
   }
 }
 
 export async function loadJournalRows(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   tableName: string,
 ): Promise<MigrationJournalRow[]> {
-  let result = await adapter.execute({
+  let result = await driver.execute({
     operation: {
       kind: 'raw',
       sql: rawSql(
@@ -77,7 +87,7 @@ export async function loadJournalRows(
 }
 
 export async function insertJournalRow(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   tableName: string,
   row: {
     id: string
@@ -87,7 +97,7 @@ export async function insertJournalRow(
   },
   transaction?: TransactionToken,
 ): Promise<void> {
-  await adapter.execute({
+  await driver.execute({
     operation: {
       kind: 'raw',
       sql: rawSql('insert into ' + tableName + ' (id, name, checksum, batch) values (?, ?, ?, ?)', [
@@ -102,12 +112,12 @@ export async function insertJournalRow(
 }
 
 export async function deleteJournalRow(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   tableName: string,
   id: string,
   transaction?: TransactionToken,
 ): Promise<void> {
-  await adapter.execute({
+  await driver.execute({
     operation: {
       kind: 'raw',
       sql: rawSql('delete from ' + tableName + ' where id = ?', [id]),