@remix-run/data-table 0.2.1 → 0.4.0

package/src/lib/migrations-node.ts

@@ -1,16 +1,18 @@
-import { createHash } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
-import { pathToFileURL } from 'node:url'
-import type { Migration, MigrationDescriptor } from './migrations.ts'
-import { parseMigrationFilename } from './migrations/filename.ts'
+
+import type { MigrationDescriptor, Seed } from './migrations.ts'
+import { parseMigrationDirectoryName } from './migrations/directory-name.ts'
 
 /**
- * Loads migration modules from a directory on Node.js.
+ * Loads SQL-file migrations from a directory on Node.js.
+ *
+ * Each migration is a directory named `YYYYMMDDHHmmss_<slug>` containing:
+ * - `up.sql` (required)
+ * - `down.sql` (optional; omit for irreversible migrations)
  *
- * Filenames are used to infer migration `id` and `name`.
- * Each file must default-export `createMigration(...)`.
- * @param directory Absolute or relative directory containing migration files.
+ * `id` and `name` are inferred from the directory name.
+ * @param directory Absolute or relative directory containing migration directories.
  * @returns A sorted list of loaded migration descriptors.
  * @example
  * ```ts
@@ -20,52 +22,92 @@ import { parseMigrationFilename } from './migrations/filename.ts'
  * ```
  */
 export async function loadMigrations(directory: string): Promise<MigrationDescriptor[]> {
-  let allFiles = (await fs.readdir(directory, { withFileTypes: true }))
-    .filter((entry) => entry.isFile())
+  let entries = await fs.readdir(directory, { withFileTypes: true })
+  let directories = entries
+    .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name)
     .sort((left, right) => left.localeCompare(right))
-  let files: Array<{ file: string; id: string; name: string }> = []
-
-  for (let file of allFiles) {
-    if (!/\.(?:m?ts|m?js|cts|cjs)$/.test(file)) {
-      continue
-    }
-
-    let parsed = parseMigrationFilename(file)
-    files.push({ file, id: parsed.id, name: parsed.name })
-  }
 
   let migrations: MigrationDescriptor[] = []
   let seenIds = new Set<string>()
 
-  for (let entry of files) {
-    if (seenIds.has(entry.id)) {
+  for (let directoryName of directories) {
+    let parsed = parseMigrationDirectoryName(directoryName)
+
+    if (seenIds.has(parsed.id)) {
       throw new Error(
-        'Duplicate migration id "' + entry.id + '" inferred from filename "' + entry.file + '"',
+        'Duplicate migration id "' +
+          parsed.id +
+          '" inferred from directory "' +
+          directoryName +
+          '"',
       )
     }
 
-    seenIds.add(entry.id)
-    let fullPath = path.join(directory, entry.file)
-    let source = await fs.readFile(fullPath, 'utf8')
-    let checksum = createHash('sha256').update(source).digest('hex')
-    let module = (await import(pathToFileURL(fullPath).href)) as { default?: Migration }
-    let migration = module.default
+    seenIds.add(parsed.id)
 
-    if (!migration || typeof migration.up !== 'function' || typeof migration.down !== 'function') {
-      throw new Error(
-        'Migration file "' + entry.file + '" must default-export createMigration(...)',
-      )
+    let directoryPath = path.join(directory, directoryName)
+    let upPath = path.join(directoryPath, 'up.sql')
+    let downPath = path.join(directoryPath, 'down.sql')
+
+    let up: string
+    try {
+      up = await fs.readFile(upPath, 'utf8')
+    } catch (error) {
+      if (isNodeFileNotFoundError(error)) {
+        throw new Error('Migration directory "' + directoryName + '" is missing up.sql')
+      }
+      throw error
+    }
+
+    let down: string | undefined
+    try {
+      down = await fs.readFile(downPath, 'utf8')
+    } catch (error) {
+      if (!isNodeFileNotFoundError(error)) {
+        throw error
+      }
     }
 
     migrations.push({
-      id: entry.id,
-      name: entry.name,
-      path: fullPath,
-      checksum,
-      migration,
+      id: parsed.id,
+      name: parsed.name,
+      up,
+      down,
+      path: directoryPath,
     })
   }
 
   return migrations
 }
+
+/**
+ * Loads a SQL seed file on Node.js.
+ *
+ * The file may contain multiple SQL statements. Seeds that must be safe to
+ * run against an already-seeded database should use idempotent statements
+ * (for example, `insert or ignore` on SQLite).
+ *
+ * @param filename Absolute or relative path to a SQL seed file.
+ * @returns A seed function that executes the file's SQL script.
+ * @example
+ * ```ts
+ * import { loadSeed } from 'remix/data-table/migrations/node'
+ *
+ * let seed = await loadSeed('./app/data/seed.sql')
+ * await db.reset({ migrations, seed })
+ * ```
+ */
+export async function loadSeed(filename: string): Promise<Seed> {
+  let sql = await fs.readFile(filename, 'utf8')
+  return (db) => db.executeScript(sql)
+}
+
+function isNodeFileNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as { code?: unknown }).code === 'ENOENT'
+  )
+}

package/src/lib/migrations.ts

@@ -1,98 +1,37 @@
 import type { Database } from './database.ts'
-import type { ColumnDefinition, ForeignKeyAction, IndexDefinition } from './adapter.ts'
-import type { ColumnBuilder } from './column.ts'
-import type { SqlStatement } from './sql.ts'
-import type { AnyTable } from './table.ts'
 
 /**
  * Controls how each migration is wrapped in transactions.
- */
-export type MigrationTransactionMode = 'auto' | 'required' | 'none'
-
-/**
- * Runtime context passed to migration `up`/`down` handlers.
- */
-export type MigrationContext = {
-  /**
-   * Immediate data runtime (`query/create/update/exec/transaction`).
-   */
-  db: Database
-  /**
-   * Migration schema runtime (`createTable/alterTable/createIndex/...`).
-   */
-  schema: MigrationSchema
-}
-
-/**
- * Authoring shape for `createMigration(...)`.
- */
-export type CreateMigrationInput = {
-  up: (context: MigrationContext) => Promise<void> | void
-  down: (context: MigrationContext) => Promise<void> | void
-  transaction?: MigrationTransactionMode
-}
-
-/**
- * Normalized migration object consumed by the registry/runner.
- */
-export type Migration = {
-  up: CreateMigrationInput['up']
-  down: CreateMigrationInput['down']
-  transaction: MigrationTransactionMode
-}
-
-/**
- * Creates a migration descriptor with normalized defaults.
- * @param input Migration handlers and transaction mode.
- * @returns A normalized migration object.
- * @example
- * ```ts
- * import { createMigration, column as c } from 'remix/data-table/migrations'
- * import { table } from 'remix/data-table'
- *
- * let users = table({
- *   name: 'users',
- *   columns: {
- *     id: c.integer().primaryKey().autoIncrement(),
- *     email: c.varchar(255).notNull().unique(),
- *   },
- * })
  *
- * export default createMigration({
- *   async up({ db, schema }) {
- *     await schema.createTable(users)
- *
- *     if (db.adapter.dialect === 'sqlite') {
- *       await db.exec('pragma foreign_keys = on')
- *     }
- *   },
- *   async down({ schema }) {
- *     await schema.dropTable('users', { ifExists: true })
- *   },
- * })
- * ```
+ * - `auto` (default): wrap when the database supports transactional DDL.
+ * - `required`: wrap; throws when the database does not support transactional DDL.
+ * - `none`: never wrap.
  */
-export function createMigration(input: CreateMigrationInput): Migration {
-  return {
-    up: input.up,
-    down: input.down,
-    transaction: input.transaction ?? 'auto',
-  }
-}
+export type MigrationTransactionMode = 'auto' | 'required' | 'none'
 
 /**
- * Migration metadata stored in registries and returned by loaders.
+ * Migration metadata and SQL consumed by `Database.migrate()`.
  */
 export type MigrationDescriptor = {
+  /** Migration id (typically a `YYYYMMDDHHmmss` timestamp). */
   id: string
+  /** Human-readable migration slug. */
   name: string
+  /** SQL executed when applying the migration. May contain multiple statements. */
+  up: string
+  /**
+   * SQL executed when reverting the migration. May contain multiple statements.
+   * Omit (or pass `undefined`) for irreversible migrations.
+   */
+  down?: string
+  /** Transaction wrapping mode. Defaults to `auto`. */
+  transaction?: MigrationTransactionMode
+  /** Optional source path used in error messages. */
   path?: string
-  checksum?: string
-  migration: Migration
 }
 
 /**
- * Direction used by migration runner operations.
+ * Direction used by `Database.migrate()`.
  */
 export type MigrationDirection = 'up' | 'down'
 
@@ -108,12 +47,17 @@ export type MigrationJournalRow = {
 }
 
 /**
- * Effective status for a known migration.
+ * Effective migration status.
+ *
+ * - `applied`: the current migration matches its journal entry.
+ * - `pending`: the current migration has not been applied.
+ * - `drifted`: the current migration differs from its journal entry.
+ * - `missing`: an applied journal entry has no migration in the current set.
  */
-export type MigrationStatus = 'applied' | 'pending' | 'drifted'
+export type MigrationStatus = 'applied' | 'pending' | 'drifted' | 'missing'
 
 /**
- * Status row returned by `runner.status()` and `runner.up/down(...)`.
+ * Status entry returned by database migration operations.
  */
 export type MigrationStatusEntry = {
   id: string
@@ -125,10 +69,13 @@ export type MigrationStatusEntry = {
 }
 
 /**
- * Common options for `runner.up(...)` and `runner.down(...)`.
+ * Bounds and dry-run options for a migration operation.
  * `to` and `step` are mutually exclusive.
+ *
+ * `to` accepts a bare migration id (`20260301113000`) or the full `id_name`
+ * directory form (`20260301113000_add_user_status`).
  */
-export type MigrateOptions =
+export type MigrationOperationOptions =
   | {
       to: string
       step?: never
@@ -146,171 +93,52 @@ export type MigrateOptions =
     }
 
 /**
- * Result shape returned by migration runner commands.
+ * Result returned by `Database.migrate()`.
  */
 export type MigrateResult = {
   applied: MigrationStatusEntry[]
   reverted: MigrationStatusEntry[]
   /**
-   * Compiled SQL statements for operations processed during this run.
-   * Includes planned SQL when running with `dryRun: true`.
+   * SQL scripts that were (or, for `dryRun`, would have been) executed.
    */
-  sql: SqlStatement[]
+  sql: string[]
 }
 
 /**
- * Options for `schema.createTable(...)` migration operations.
- */
-export type CreateTableOptions = { ifNotExists?: boolean }
-/**
- * Options for `schema.alterTable(...)` migration operations.
- */
-export type AlterTableOptions = { ifExists?: boolean }
-/**
- * Options for `schema.dropTable(...)` migration operations.
- */
-export type DropTableOptions = { ifExists?: boolean; cascade?: boolean }
-/**
- * Accepts either one index column or multiple (compound index).
- */
-export type IndexColumns = string | string[]
-
-/**
- * Accepts either one key column or multiple (compound key).
- */
-export type KeyColumns = string | string[]
-
-/**
- * Accepts either a SQL table name or a `table(...)` object.
- */
-export type TableInput = string | AnyTable
-
-/**
- * Optional name override for constraints and indexes.
- */
-export type NamedConstraintOptions = {
-  name?: string
-}
-
-/**
- * Foreign key options for migration APIs.
+ * Runtime-agnostic migration registry abstraction.
  */
-export type ForeignKeyOptions = NamedConstraintOptions & {
-  onDelete?: ForeignKeyAction
-  onUpdate?: ForeignKeyAction
+export type MigrationRegistry = {
+  register(migration: MigrationDescriptor): void
+  list(): MigrationDescriptor[]
 }
 
 /**
- * Index options for migration APIs.
+ * Migration collection accepted by `db.migrate(...)` and `db.migrationStatus(...)`.
  */
-export type CreateIndexOptions = NamedConstraintOptions &
-  Omit<IndexDefinition, 'table' | 'name' | 'columns'> & {
-    ifNotExists?: boolean
-  }
+export type Migrations = MigrationDescriptor[] | MigrationRegistry
 
 /**
- * Builder API available inside `schema.alterTable(name, table => ...)`.
+ * Function that initializes application data in a database.
  */
-export interface AlterTableBuilder {
-  /** Adds a column during an `alterTable` migration. */
-  addColumn(name: string, definition: ColumnDefinition | ColumnBuilder): void
-  /** Changes an existing column during an `alterTable` migration. */
-  changeColumn(name: string, definition: ColumnDefinition | ColumnBuilder): void
-  /** Renames a column during an `alterTable` migration. */
-  renameColumn(from: string, to: string): void
-  /** Drops a column during an `alterTable` migration. */
-  dropColumn(name: string, options?: { ifExists?: boolean }): void
-  /** Adds a primary key during an `alterTable` migration. */
-  addPrimaryKey(columns: KeyColumns, options?: NamedConstraintOptions): void
-  /** Drops a primary key during an `alterTable` migration. */
-  dropPrimaryKey(name: string): void
-  /** Adds a unique constraint during an `alterTable` migration. */
-  addUnique(columns: KeyColumns, options?: NamedConstraintOptions): void
-  /** Drops a unique constraint during an `alterTable` migration. */
-  dropUnique(name: string): void
-  /** Adds a foreign key during an `alterTable` migration. */
-  addForeignKey(
-    columns: KeyColumns,
-    refTable: TableInput,
-    refColumns?: KeyColumns,
-    options?: ForeignKeyOptions,
-  ): void
-  /** Drops a foreign key during an `alterTable` migration. */
-  dropForeignKey(name: string): void
-  /** Adds a check constraint during an `alterTable` migration. */
-  addCheck(expression: string, options?: NamedConstraintOptions): void
-  /** Drops a check constraint during an `alterTable` migration. */
-  dropCheck(name: string): void
-  /** Adds an index during an `alterTable` migration. */
-  addIndex(columns: IndexColumns, options?: CreateIndexOptions): void
-  /** Drops an index during an `alterTable` migration. */
-  dropIndex(name: string): void
-  /** Sets the table comment during an `alterTable` migration. */
-  comment(text: string): void
-}
+export type Seed = (db: Database) => void | Promise<void>
 
 /**
- * DDL-focused operations mixed into the migration `db` object.
+ * Options for applying or reverting migrations through `Database.migrate()`.
  */
-export interface MigrationSchema {
-  /** Creates a table in the migration schema. */
-  createTable<table extends AnyTable>(table: table, options?: CreateTableOptions): Promise<void>
-  /** Alters an existing table in the migration schema. */
-  alterTable(
-    table: TableInput,
-    migrate: (table: AlterTableBuilder) => void,
-    options?: AlterTableOptions,
-  ): Promise<void>
-  /** Renames a table in the migration schema. */
-  renameTable(from: TableInput, to: string): Promise<void>
-  /** Drops a table from the migration schema. */
-  dropTable(table: TableInput, options?: DropTableOptions): Promise<void>
-  /** Creates an index in the migration schema. */
-  createIndex(table: TableInput, columns: IndexColumns, options?: CreateIndexOptions): Promise<void>
-  /** Drops an index from the migration schema. */
-  dropIndex(table: TableInput, name: string, options?: { ifExists?: boolean }): Promise<void>
-  /** Renames an index in the migration schema. */
-  renameIndex(table: TableInput, from: string, to: string): Promise<void>
-  /** Adds a foreign key in the migration schema. */
-  addForeignKey(
-    table: TableInput,
-    columns: KeyColumns,
-    refTable: TableInput,
-    refColumns?: KeyColumns,
-    options?: ForeignKeyOptions,
-  ): Promise<void>
-  /** Drops a foreign key in the migration schema. */
-  dropForeignKey(table: TableInput, name: string): Promise<void>
-  /** Adds a check constraint in the migration schema. */
-  addCheck(table: TableInput, expression: string, options?: NamedConstraintOptions): Promise<void>
-  /** Drops a check constraint in the migration schema. */
-  dropCheck(table: TableInput, name: string): Promise<void>
-  /**
-   * Adds raw SQL to the migration plan as a migration operation.
-   */
-  plan(sql: string | SqlStatement): Promise<void>
+export type DatabaseMigrateOptions = MigrationOperationOptions & {
+  /** Migration direction. Defaults to `up`. */
+  direction?: MigrationDirection
   /**
-   * Returns `true` when the table exists in the current database.
-   */
-  hasTable(table: TableInput): Promise<boolean>
-  /**
-   * Returns `true` when the column exists on the given table.
+   * Journal table used to record applied migrations.
+   * Defaults to `data_table_migrations`.
    */
-  hasColumn(table: TableInput, column: string): Promise<boolean>
-}
-
-/**
- * Runtime-agnostic migration registry abstraction.
- */
-export type MigrationRegistry = {
-  register(migration: MigrationDescriptor): void
-  list(): MigrationDescriptor[]
+  journalTable?: string
 }
 
 /**
- * Options for creating a migration runner.
+ * Options for reading migration status through `Database.migrationStatus()`.
  */
-export type MigrationRunnerOptions = {
+export interface DatabaseMigrationStatusOptions {
   /**
    * Journal table used to record applied migrations.
    * Defaults to `data_table_migrations`.
@@ -319,10 +147,16 @@ export type MigrationRunnerOptions = {
 }
 
 /**
- * Migration runner API for applying, reverting, and inspecting migration state.
+ * Options for rebuilding a database through `Database.reset()`.
  */
-export type MigrationRunner = {
-  up(options?: MigrateOptions): Promise<MigrateResult>
-  down(options?: MigrateOptions): Promise<MigrateResult>
-  status(): Promise<MigrationStatusEntry[]>
+export interface DatabaseResetOptions {
+  /** Migrations to apply after wiping the database. */
+  migrations: Migrations
+  /** Function that initializes application data after migrations finish. */
+  seed?: Seed
+  /**
+   * Journal table used to record applied migrations.
+   * Defaults to `data_table_migrations`.
+   */
+  journalTable?: string
 }

package/src/lib/operators.ts

@@ -22,7 +22,7 @@ type PredicateColumn<input extends string | ColumnReferenceLike> = NormalizeColu
   string
 
 /**
- * Normalized predicate representation consumed by adapters.
+ * Normalized predicate representation consumed by drivers.
  */
 export type Predicate<column extends string = string> =
   | {

package/src/lib/query.ts

@@ -1,4 +1,4 @@
-import type { JoinClause, JoinType, SelectColumn } from './adapter.ts'
+import type { JoinClause, JoinType, SelectColumn } from './driver.ts'
 import { DataTableQueryError, DataTableValidationError } from './errors.ts'
 import type {
   MergeColumnTypeMaps,
@@ -143,6 +143,11 @@ type QueryResultMap<row extends Record<string, unknown>, loaded extends Record<s
   upsert: WriteResult | WriteRowResult<row>
 }
 
+/**
+ * Convenience alias for any {@link Query} regardless of its source, columns,
+ * row shape, loaded relations, or execution phase. Use this in helper APIs
+ * that accept a query but don't care about the specific generic parameters.
+ */
 export type AnyQuery = Query<any, any, any, any, any>
 
 type QuerySource<input extends AnyQuery> =
@@ -212,6 +217,17 @@ export const querySnapshot = Symbol('querySnapshot')
 
 declare const queryTypeBrand: unique symbol
 
+/**
+ * Type-safe query builder for `@remix-run/data-table` sources. Construct via
+ * {@link query} and chain calls (`select`, `where`, `orderBy`, etc.) to build
+ * up a plan; run it by `await`-ing on a runtime-bound query, or by passing an
+ * unbound one to a runtime.
+ *
+ * The five generic parameters track, in order: the source/table, the column
+ * type map, the projected row shape, any loaded relations, and the
+ * binding/execution-mode phase. Most consumers do not need to spell them out
+ * — `query(table)` infers everything.
+ */
 export class Query<
   source extends AnyQuerySource,
   columnTypes extends Record<string, unknown> = QuerySourceColumnTypes<source>,
@@ -684,6 +700,23 @@ export class Query<
   }
 }
 
+/**
+ * Begin a {@link Query} against a `@remix-run/data-table` source. The returned
+ * builder is in `'all'` execution mode and unbound; chain `select`, `where`,
+ * `orderBy`, etc. to refine the plan, and `await` it after binding it to a
+ * runtime to materialize results.
+ *
+ * @param table The table or source to query.
+ * @returns An unbound {@link Query} builder rooted at `table`.
+ *
+ * @example
+ * ```ts
+ * let activeUsers = await query(users)
+ *   .where({ status: 'active' })
+ *   .orderBy('createdAt', 'desc')
+ *   .select(['id', 'email'])
+ * ```
+ */
 export function query<
   tableName extends string,
   row extends Record<string, unknown>,

package/src/lib/sql-helpers.ts

@@ -1,31 +1,10 @@
-import type { DataManipulationOperation, DataMigrationOperation, TableRef } from './adapter.ts'
+import type { TableRef } from './driver.ts'
 
 /**
  * Function used to quote SQL identifiers for a dialect.
  */
 export type QuoteIdentifier = (value: string) => string
 
-/**
- * Type guard that narrows an operation to the data-manipulation union.
- * @param operation Operation to inspect.
- * @returns `true` when the operation is a data-manipulation operation.
- */
-export function isDataManipulationOperation(
-  operation: DataManipulationOperation | DataMigrationOperation,
-): operation is DataManipulationOperation {
-  return (
-    operation.kind === 'select' ||
-    operation.kind === 'count' ||
-    operation.kind === 'exists' ||
-    operation.kind === 'insert' ||
-    operation.kind === 'insertMany' ||
-    operation.kind === 'update' ||
-    operation.kind === 'delete' ||
-    operation.kind === 'upsert' ||
-    operation.kind === 'raw'
-  )
-}
-
 /**
  * Normalizes an arbitrary join type string into `inner`, `left`, or `right`.
  * @param type Input join type.

package/src/lib/sql.ts

@@ -69,7 +69,7 @@ export function isSqlStatement(value: unknown): value is SqlStatement {
 
 /**
  * Creates a SQL statement from raw text and values.
- * @param text SQL text containing placeholders expected by the target adapter.
+ * @param text SQL text containing placeholders expected by the target database.
  * @param values Placeholder values.
  * @returns A normalized SQL statement.
  * @example

package/src/lib/table.ts

@@ -1,4 +1,4 @@
-import type { ColumnDefinition } from './adapter.ts'
+import type { ColumnDefinition } from './driver.ts'
 import { ColumnBuilder } from './column.ts'
 import type { ColumnInput as ColumnBuilderInput, ColumnOutput } from './column.ts'
 import type { Predicate, WhereInput } from './operators.ts'

package/src/migrations/node.ts

@@ -1 +1 @@
-export { loadMigrations } from '../lib/migrations-node.ts'
+export { loadMigrations, loadSeed } from '../lib/migrations-node.ts'

package/src/migrations.ts

@@ -1,26 +1,15 @@
 export type {
-  AlterTableBuilder,
-  CreateMigrationInput,
-  Migration,
-  MigrationContext,
+  DatabaseMigrateOptions,
+  DatabaseMigrationStatusOptions,
+  DatabaseResetOptions,
+  MigrateResult,
   MigrationDescriptor,
   MigrationDirection,
   MigrationJournalRow,
-  MigrationSchema,
   MigrationRegistry,
-  MigrationRunner,
-  MigrationRunnerOptions,
   MigrationStatus,
   MigrationStatusEntry,
   MigrationTransactionMode,
-  MigrateOptions,
-  MigrateResult,
-  KeyColumns,
-  TableInput,
 } from './lib/migrations.ts'
-export { createMigration } from './lib/migrations.ts'
-export type { ColumnNamespace } from './lib/column.ts'
-export { ColumnBuilder, column } from './lib/column.ts'
 export { createMigrationRegistry } from './lib/migrations/registry.ts'
-export { createMigrationRunner } from './lib/migrations/runner.ts'
-export { parseMigrationFilename } from './lib/migrations/filename.ts'
+export { parseMigrationDirectoryName } from './lib/migrations/directory-name.ts'