@remix-run/data-table 0.2.1 → 0.4.0

package/src/lib/driver.ts

@@ -0,0 +1,333 @@
+import type { AnyTable, OrderByClause } from './table.ts'
+import type { Predicate } from './operators.ts'
+import type { SqlStatement } from './sql.ts'
+
+/**
+ * SQL join kinds supported by database drivers.
+ */
+export type JoinType = 'inner' | 'left' | 'right'
+
+/**
+ * Join configuration used in compiled select statements.
+ */
+export type JoinClause = {
+  type: JoinType
+  table: AnyTable
+  on: Predicate
+}
+
+/**
+ * Selected output column with optional alias.
+ */
+export type SelectColumn = {
+  column: string
+  alias: string
+}
+
+/**
+ * Returning selection for write statements.
+ */
+export type ReturningSelection = '*' | string[]
+
+/**
+ * Canonical select statement shape consumed by drivers.
+ */
+export type SelectOperation<table extends AnyTable = AnyTable> = {
+  kind: 'select'
+  table: table
+  select: '*' | SelectColumn[]
+  distinct: boolean
+  joins: JoinClause[]
+  where: Predicate[]
+  groupBy: string[]
+  having: Predicate[]
+  orderBy: OrderByClause[]
+  limit?: number
+  offset?: number
+}
+
+/**
+ * Canonical count statement shape consumed by drivers.
+ */
+export type CountOperation<table extends AnyTable = AnyTable> = {
+  kind: 'count'
+  table: table
+  joins: JoinClause[]
+  where: Predicate[]
+  groupBy: string[]
+  having: Predicate[]
+}
+
+/**
+ * Canonical exists statement shape consumed by drivers.
+ */
+export type ExistsOperation<table extends AnyTable = AnyTable> = {
+  kind: 'exists'
+  table: table
+  joins: JoinClause[]
+  where: Predicate[]
+  groupBy: string[]
+  having: Predicate[]
+}
+
+/**
+ * Canonical insert statement shape consumed by drivers.
+ */
+export type InsertOperation<table extends AnyTable = AnyTable> = {
+  kind: 'insert'
+  table: table
+  values: Record<string, unknown>
+  returning?: ReturningSelection
+}
+
+/**
+ * Canonical bulk-insert statement shape consumed by drivers.
+ */
+export type InsertManyOperation<table extends AnyTable = AnyTable> = {
+  kind: 'insertMany'
+  table: table
+  values: Record<string, unknown>[]
+  returning?: ReturningSelection
+}
+
+/**
+ * Canonical update statement shape consumed by drivers.
+ */
+export type UpdateOperation<table extends AnyTable = AnyTable> = {
+  kind: 'update'
+  table: table
+  changes: Record<string, unknown>
+  where: Predicate[]
+  returning?: ReturningSelection
+}
+
+/**
+ * Canonical delete statement shape consumed by drivers.
+ */
+export type DeleteOperation<table extends AnyTable = AnyTable> = {
+  kind: 'delete'
+  table: table
+  where: Predicate[]
+  returning?: ReturningSelection
+}
+
+/**
+ * Canonical upsert statement shape consumed by drivers.
+ */
+export type UpsertOperation<table extends AnyTable = AnyTable> = {
+  kind: 'upsert'
+  table: table
+  values: Record<string, unknown>
+  conflictTarget?: string[]
+  update?: Record<string, unknown>
+  returning?: ReturningSelection
+}
+
+/**
+ * Raw SQL statement execution descriptor.
+ */
+export type RawOperation = {
+  kind: 'raw'
+  sql: SqlStatement
+}
+
+/**
+ * Union of all data-manipulation statement shapes.
+ */
+export type DataManipulationOperation =
+  | SelectOperation
+  | CountOperation
+  | ExistsOperation
+  | InsertOperation
+  | InsertManyOperation
+  | UpdateOperation
+  | DeleteOperation
+  | UpsertOperation
+  | RawOperation
+
+/**
+ * Qualified table reference.
+ */
+export type TableRef = {
+  name: string
+  schema?: string
+}
+
+/**
+ * Referential actions supported by foreign key constraints.
+ */
+export type ForeignKeyAction = 'cascade' | 'restrict' | 'set null' | 'set default' | 'no action'
+
+/**
+ * Logical column type names used by schema definitions.
+ */
+export type ColumnTypeName =
+  | 'varchar'
+  | 'text'
+  | 'integer'
+  | 'bigint'
+  | 'decimal'
+  | 'boolean'
+  | 'uuid'
+  | 'date'
+  | 'time'
+  | 'timestamp'
+  | 'json'
+  | 'binary'
+  | 'enum'
+
+/**
+ * Default value definition for a column.
+ */
+export type ColumnDefault =
+  | { kind: 'literal'; value: unknown }
+  | { kind: 'now' }
+  | { kind: 'sql'; expression: string }
+
+/**
+ * Definition for a computed or generated column.
+ */
+export type ColumnComputed = {
+  expression: string
+  stored: boolean
+}
+
+/** Options for configuring identity column generation. */
+export type IdentityOptions = {
+  always?: boolean
+  start?: number
+  increment?: number
+}
+
+/** Foreign-key reference metadata declared on a column. */
+export type ColumnReference = {
+  table: TableRef
+  columns: string[]
+  name: string
+  onDelete?: ForeignKeyAction
+  onUpdate?: ForeignKeyAction
+}
+
+/**
+ * Check constraint declared on a column definition.
+ */
+export type ColumnCheck = {
+  expression: string
+  name: string
+}
+
+/**
+ * Normalized column definition used in schema operations.
+ */
+export type ColumnDefinition = {
+  type: ColumnTypeName
+  nullable?: boolean
+  primaryKey?: boolean
+  unique?: boolean | { name?: string }
+  default?: ColumnDefault
+  computed?: ColumnComputed
+  references?: ColumnReference
+  checks?: ColumnCheck[]
+  comment?: string
+  length?: number
+  precision?: number
+  scale?: number
+  unsigned?: boolean
+  withTimezone?: boolean
+  enumValues?: string[]
+  autoIncrement?: boolean
+  identity?: IdentityOptions
+  collate?: string
+  charset?: string
+}
+
+/**
+ * Opaque transaction handle supplied by database drivers.
+ */
+export type TransactionToken = {
+  id: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Transaction hints that database drivers may apply when supported by the dialect.
+ */
+export type TransactionOptions = {
+  isolationLevel?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable'
+  readOnly?: boolean
+}
+
+/**
+ * Database driver execution request payload.
+ */
+export type DataManipulationRequest = {
+  operation: DataManipulationOperation
+  transaction?: TransactionToken
+}
+
+/**
+ * Database data-manipulation result payload.
+ */
+export type DataManipulationResult = {
+  rows?: Record<string, unknown>[]
+  affectedRows?: number
+  insertId?: unknown
+}
+
+/**
+ * Declares database feature support.
+ */
+export type DatabaseCapabilities = {
+  readonly returning: boolean
+  readonly savepoints: boolean
+  readonly upsert: boolean
+  readonly transactionalDdl: boolean
+  readonly migrationLock: boolean
+}
+
+/**
+ * Low-level contract that connects a `Database` to a database engine.
+ */
+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. */
+  executeScript(sql: string, transaction?: TransactionToken): Promise<void>
+  /** 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>
+  /** 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/directive.ts

@@ -0,0 +1,38 @@
+import type { MigrationTransactionMode } from '../migrations.ts'
+
+const directivePattern = /^\s*--\s*data-table\/transaction\s*:\s*(auto|required|none)\s*$/i
+
+/**
+ * Parses an optional `-- data-table/transaction: auto|required|none` directive
+ * from any single-line SQL comment in the script.
+ *
+ * Returns `undefined` when no directive is present.
+ * @param sql SQL script contents.
+ * @returns The declared transaction mode, or `undefined` when not declared.
+ * @throws when more than one directive is present or the value is invalid.
+ */
+export function parseTransactionDirective(sql: string): MigrationTransactionMode | undefined {
+  let match: MigrationTransactionMode | undefined
+
+  for (let line of sql.split(/\r?\n/)) {
+    let trimmed = line.trim()
+
+    if (!trimmed.startsWith('--')) {
+      continue
+    }
+
+    let result = directivePattern.exec(trimmed)
+
+    if (!result) {
+      continue
+    }
+
+    if (match !== undefined) {
+      throw new Error('Migration script declares more than one transaction directive')
+    }
+
+    match = result[1].toLowerCase() as MigrationTransactionMode
+  }
+
+  return match
+}

package/src/lib/migrations/directory-name.ts

@@ -0,0 +1,23 @@
+const migrationDirectoryPattern = /^(\d{14})_(.+)$/
+
+/**
+ * Parses a migration directory name into `{ id, name }`.
+ *
+ * Expected format: `YYYYMMDDHHmmss_name`.
+ * @param name Migration directory basename.
+ * @returns Parsed migration id and name.
+ */
+export function parseMigrationDirectoryName(name: string): { id: string; name: string } {
+  let match = name.match(migrationDirectoryPattern)
+
+  if (!match) {
+    throw new Error(
+      'Invalid migration directory name "' + name + '". Expected format YYYYMMDDHHmmss_name',
+    )
+  }
+
+  return {
+    id: match[1],
+    name: match[2],
+  }
+}

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

@@ -1,41 +1,45 @@
-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'
 
-export function normalizeChecksum(migration: MigrationDescriptor): string {
-  if (migration.checksum) {
-    return migration.checksum
+export async function computeChecksum(migration: MigrationDescriptor): Promise<string> {
+  let digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(migration.up))
+  return bytesToHex(new Uint8Array(digest))
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let hex = ''
+
+  for (let byte of bytes) {
+    hex += byte.toString(16).padStart(2, '0')
   }
 
-  return migration.id + ':' + migration.name
+  return hex
 }
 
 export async function ensureMigrationJournal(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   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' } },
-      },
-    },
-  })
+  await driver.executeScript(
+    'create table if not exists ' +
+      tableName +
+      ' (' +
+      'id varchar(64) not null primary key, ' +
+      'name varchar(255) not null, ' +
+      'checksum varchar(128) not null, ' +
+      'batch integer not null, ' +
+      'applied_at timestamp not null default current_timestamp' +
+      ')',
+  )
 }
 
 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'),
@@ -44,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(
@@ -73,7 +87,7 @@ export async function loadJournalRows(
 }
 
 export async function insertJournalRow(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   tableName: string,
   row: {
     id: string
@@ -83,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 (?, ?, ?, ?)', [
@@ -98,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]),

package/src/lib/migrations/registry.ts

@@ -33,7 +33,7 @@ export function resolveMigrations(
  * import { createMigrationRegistry } from 'remix/data-table/migrations'
  *
  * let registry = createMigrationRegistry()
- * registry.register({ id, name, migration })
+ * registry.register({ id, name, up, down })
  * ```
  */
 export function createMigrationRegistry(initial: MigrationDescriptor[] = []): MigrationRegistry {