@remix-run/data-table 0.3.0 → 0.5.0

package/src/cli.ts

@@ -0,0 +1,179 @@
+import type { Database } from './lib/database.ts'
+import type { Migrations, Seed } from './lib/migrations.ts'
+
+interface DatabaseCommandOptions {
+  /** Database instance used by the command. */
+  db: Database
+}
+
+type RollbackBoundOptions =
+  | {
+      /**
+       * Reverts back through this migration, inclusive. Accepts a bare
+       * migration id or the full `id_name` directory form.
+       */
+      to: string
+      step?: never
+    }
+  | {
+      to?: never
+      /** Reverts this many migrations. Defaults to `1`. */
+      step?: number
+    }
+
+type RollbackCommandOptions = DatabaseCommandOptions &
+  RollbackBoundOptions & {
+    /** Reverts applied migrations, newest first. */
+    command: 'rollback'
+    /** Migrations to revert. */
+    migrations: Migrations
+    /** Reports what would be reverted without running it. */
+    dryRun?: boolean
+    /** Migration journal table. */
+    journalTable?: string
+  }
+
+/** Structured invocation options accepted by {@link runRemixDb}. */
+export type RunRemixDbOptions =
+  | (DatabaseCommandOptions & {
+      /** Applies pending migrations. */
+      command: 'migrate'
+      /** Migrations to apply. */
+      migrations: Migrations
+      /**
+       * Stops after applying this migration. Accepts a bare migration id or
+       * the full `id_name` directory form.
+       */
+      to?: string
+      /** Migration journal table. */
+      journalTable?: string
+    })
+  | RollbackCommandOptions
+  | (DatabaseCommandOptions & {
+      /** Wipes, migrates, and optionally seeds the database. */
+      command: 'reset'
+      /** Migrations to apply after wiping the database. */
+      migrations: Migrations
+      /** Initializes database data after migrations finish. */
+      seed?: Seed
+      /** Migration journal table. */
+      journalTable?: string
+    })
+  | (DatabaseCommandOptions & {
+      /** Runs the application's seed function. */
+      command: 'seed'
+      /** Initializes application database data. */
+      seed: Seed
+    })
+  | (DatabaseCommandOptions & {
+      /** Reports the status of known migrations. */
+      command: 'status'
+      /** Migrations to inspect. */
+      migrations: Migrations
+      /** Migration journal table. */
+      journalTable?: string
+    })
+  | (DatabaseCommandOptions & {
+      /** Destructively recreates the configured database. */
+      command: 'wipe'
+    })
+
+/**
+ * Runs a data-table database command from structured invocation options.
+ *
+ * @param options Database command and application database values.
+ * @returns The exit code the host CLI should use. Always resolves `0`;
+ * command failures throw.
+ */
+export async function runRemixDb(options: RunRemixDbOptions): Promise<number> {
+  if (options.command === 'migrate') {
+    let migrateOptions =
+      options.to === undefined
+        ? { journalTable: options.journalTable }
+        : { to: options.to, journalTable: options.journalTable }
+    let result = await options.db.migrate(options.migrations, migrateOptions)
+
+    if (result.applied.length === 0) {
+      console.log('no pending migrations')
+    }
+
+    for (let entry of result.applied) {
+      console.log('applied ' + entry.id + '_' + entry.name)
+    }
+
+    return 0
+  }
+
+  if (options.command === 'rollback') {
+    if (options.to !== undefined && options.step !== undefined) {
+      throw new Error('Cannot combine "to" and "step" migration options in the same run')
+    }
+
+    let result =
+      options.to === undefined
+        ? await options.db.migrate(options.migrations, {
+            direction: 'down',
+            step: options.step ?? 1,
+            dryRun: options.dryRun,
+            journalTable: options.journalTable,
+          })
+        : await options.db.migrate(options.migrations, {
+            direction: 'down',
+            to: options.to,
+            dryRun: options.dryRun,
+            journalTable: options.journalTable,
+          })
+
+    if (result.reverted.length === 0) {
+      console.log('no migrations to revert')
+    }
+
+    for (let entry of result.reverted) {
+      console.log((options.dryRun ? 'would revert ' : 'reverted ') + entry.id + '_' + entry.name)
+    }
+
+    return 0
+  }
+
+  if (options.command === 'reset') {
+    await options.db.reset({
+      migrations: options.migrations,
+      seed: options.seed,
+      journalTable: options.journalTable,
+    })
+
+    console.log('database reset')
+
+    return 0
+  }
+
+  if (options.command === 'seed') {
+    await options.seed(options.db)
+
+    console.log('database seeded')
+
+    return 0
+  }
+
+  if (options.command === 'status') {
+    let entries = await options.db.migrationStatus(options.migrations, {
+      journalTable: options.journalTable,
+    })
+
+    for (let entry of entries) {
+      console.log(entry.id + ' ' + entry.name + ' ' + entry.status)
+    }
+
+    return 0
+  }
+
+  if (options.command === 'wipe') {
+    await options.db.wipe()
+    return 0
+  }
+
+  // Guard against unchecked command strings from plain-JS callers so an
+  // unknown command can never fall through to a destructive operation.
+  let command = (options as { command: string }).command
+  throw new Error('Unknown database command: ' + command)
+}

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