@remix-run/data-table 0.1.0 → 0.2.0

package/src/lib/adapter.ts

@@ -33,7 +33,7 @@ export type ReturningSelection = '*' | string[]
 /**
  * Canonical select statement shape consumed by adapters.
  */
-export type SelectStatement<table extends AnyTable = AnyTable> = {
+export type SelectOperation<table extends AnyTable = AnyTable> = {
   kind: 'select'
   table: table
   select: '*' | SelectColumn[]
@@ -50,7 +50,7 @@ export type SelectStatement<table extends AnyTable = AnyTable> = {
 /**
  * Canonical count statement shape consumed by adapters.
  */
-export type CountStatement<table extends AnyTable = AnyTable> = {
+export type CountOperation<table extends AnyTable = AnyTable> = {
   kind: 'count'
   table: table
   joins: JoinClause[]
@@ -62,7 +62,7 @@ export type CountStatement<table extends AnyTable = AnyTable> = {
 /**
  * Canonical exists statement shape consumed by adapters.
  */
-export type ExistsStatement<table extends AnyTable = AnyTable> = {
+export type ExistsOperation<table extends AnyTable = AnyTable> = {
   kind: 'exists'
   table: table
   joins: JoinClause[]
@@ -74,7 +74,7 @@ export type ExistsStatement<table extends AnyTable = AnyTable> = {
 /**
  * Canonical insert statement shape consumed by adapters.
  */
-export type InsertStatement<table extends AnyTable = AnyTable> = {
+export type InsertOperation<table extends AnyTable = AnyTable> = {
   kind: 'insert'
   table: table
   values: Record<string, unknown>
@@ -84,7 +84,7 @@ export type InsertStatement<table extends AnyTable = AnyTable> = {
 /**
  * Canonical bulk-insert statement shape consumed by adapters.
  */
-export type InsertManyStatement<table extends AnyTable = AnyTable> = {
+export type InsertManyOperation<table extends AnyTable = AnyTable> = {
   kind: 'insertMany'
   table: table
   values: Record<string, unknown>[]
@@ -94,7 +94,7 @@ export type InsertManyStatement<table extends AnyTable = AnyTable> = {
 /**
  * Canonical update statement shape consumed by adapters.
  */
-export type UpdateStatement<table extends AnyTable = AnyTable> = {
+export type UpdateOperation<table extends AnyTable = AnyTable> = {
   kind: 'update'
   table: table
   changes: Record<string, unknown>
@@ -105,7 +105,7 @@ export type UpdateStatement<table extends AnyTable = AnyTable> = {
 /**
  * Canonical delete statement shape consumed by adapters.
  */
-export type DeleteStatement<table extends AnyTable = AnyTable> = {
+export type DeleteOperation<table extends AnyTable = AnyTable> = {
   kind: 'delete'
   table: table
   where: Predicate[]
@@ -115,7 +115,7 @@ export type DeleteStatement<table extends AnyTable = AnyTable> = {
 /**
  * Canonical upsert statement shape consumed by adapters.
  */
-export type UpsertStatement<table extends AnyTable = AnyTable> = {
+export type UpsertOperation<table extends AnyTable = AnyTable> = {
   kind: 'upsert'
   table: table
   values: Record<string, unknown>
@@ -127,24 +127,427 @@ export type UpsertStatement<table extends AnyTable = AnyTable> = {
 /**
  * Raw SQL statement execution descriptor.
  */
-export type RawStatement = {
+export type RawOperation = {
   kind: 'raw'
   sql: SqlStatement
 }
 
 /**
- * Union of all canonical statement shapes.
+ * Union of all data-manipulation statement shapes.
  */
-export type AdapterStatement =
-  | SelectStatement
-  | CountStatement
-  | ExistsStatement
-  | InsertStatement
-  | InsertManyStatement
-  | UpdateStatement
-  | DeleteStatement
-  | UpsertStatement
-  | RawStatement
+export type DataManipulationOperation =
+  | SelectOperation
+  | CountOperation
+  | ExistsOperation
+  | InsertOperation
+  | InsertManyOperation
+  | UpdateOperation
+  | DeleteOperation
+  | UpsertOperation
+  | RawOperation
+
+/**
+ * Qualified table reference used in migration operations.
+ */
+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
+}
+
+/**
+ * Primary key constraint definition.
+ */
+export type PrimaryKeyConstraint = {
+  columns: string[]
+  name: string
+}
+
+/**
+ * Unique constraint definition.
+ */
+export type UniqueConstraint = {
+  columns: string[]
+  name: string
+}
+
+/**
+ * Check constraint definition.
+ */
+export type CheckConstraint = {
+  expression: string
+  name: string
+}
+
+/**
+ * Foreign key constraint definition.
+ */
+export type ForeignKeyConstraint = {
+  columns: string[]
+  references: {
+    table: TableRef
+    columns: string[]
+  }
+  name: string
+  onDelete?: ForeignKeyAction
+  onUpdate?: ForeignKeyAction
+}
+
+/**
+ * Index method used when creating an index.
+ */
+export type IndexMethod = 'btree' | 'hash' | 'gin' | 'gist' | 'fulltext' | (string & {})
+
+/**
+ * Index definition used in schema operations.
+ */
+export type IndexDefinition = {
+  table: TableRef
+  name: string
+  columns: string[]
+  unique?: boolean
+  where?: string
+  using?: IndexMethod
+}
+
+/**
+ * Operation that creates a new table.
+ */
+export type CreateTableOperation = {
+  kind: 'createTable'
+  table: TableRef
+  ifNotExists?: boolean
+  columns: Record<string, ColumnDefinition>
+  primaryKey?: PrimaryKeyConstraint
+  uniques?: UniqueConstraint[]
+  checks?: CheckConstraint[]
+  foreignKeys?: ForeignKeyConstraint[]
+  comment?: string
+}
+
+/**
+ * Alter-table change that adds a column.
+ */
+export type AddColumnChange = {
+  kind: 'addColumn'
+  column: string
+  definition: ColumnDefinition
+}
+
+/**
+ * Alter-table change that replaces a column definition.
+ */
+export type ChangeColumnChange = {
+  kind: 'changeColumn'
+  column: string
+  definition: ColumnDefinition
+}
+
+/**
+ * Alter-table change that renames a column.
+ */
+export type RenameColumnChange = {
+  kind: 'renameColumn'
+  from: string
+  to: string
+}
+
+/**
+ * Alter-table change that drops a column.
+ */
+export type DropColumnChange = {
+  kind: 'dropColumn'
+  column: string
+  ifExists?: boolean
+}
+
+/**
+ * Alter-table change that adds a primary key.
+ */
+export type AddPrimaryKeyChange = {
+  kind: 'addPrimaryKey'
+  constraint: PrimaryKeyConstraint
+}
+
+/**
+ * Alter-table change that drops a primary key.
+ */
+export type DropPrimaryKeyChange = {
+  kind: 'dropPrimaryKey'
+  name: string
+}
+
+/**
+ * Alter-table change that adds a unique constraint.
+ */
+export type AddUniqueChange = {
+  kind: 'addUnique'
+  constraint: UniqueConstraint
+}
+
+/**
+ * Alter-table change that drops a unique constraint.
+ */
+export type DropUniqueChange = {
+  kind: 'dropUnique'
+  name: string
+}
+
+/**
+ * Alter-table change that adds a foreign key constraint.
+ */
+export type AddForeignKeyChange = {
+  kind: 'addForeignKey'
+  constraint: ForeignKeyConstraint
+}
+
+/**
+ * Alter-table change that drops a foreign key constraint.
+ */
+export type DropForeignKeyChange = {
+  kind: 'dropForeignKey'
+  name: string
+}
+
+/**
+ * Alter-table change that adds a check constraint.
+ */
+export type AddCheckChange = {
+  kind: 'addCheck'
+  constraint: CheckConstraint
+}
+
+/**
+ * Alter-table change that drops a check constraint.
+ */
+export type DropCheckChange = {
+  kind: 'dropCheck'
+  name: string
+}
+
+/**
+ * Alter-table change that updates a table comment.
+ */
+export type SetTableCommentChange = {
+  kind: 'setTableComment'
+  comment: string
+}
+
+/**
+ * Union of supported `alterTable` changes.
+ */
+export type AlterTableChange =
+  | AddColumnChange
+  | ChangeColumnChange
+  | RenameColumnChange
+  | DropColumnChange
+  | AddPrimaryKeyChange
+  | DropPrimaryKeyChange
+  | AddUniqueChange
+  | DropUniqueChange
+  | AddForeignKeyChange
+  | DropForeignKeyChange
+  | AddCheckChange
+  | DropCheckChange
+  | SetTableCommentChange
+
+/**
+ * Operation that applies one or more table changes.
+ */
+export type AlterTableOperation = {
+  kind: 'alterTable'
+  table: TableRef
+  changes: AlterTableChange[]
+  ifExists?: boolean
+}
+
+/**
+ * Operation that renames a table.
+ */
+export type RenameTableOperation = {
+  kind: 'renameTable'
+  from: TableRef
+  to: TableRef
+}
+
+/**
+ * Operation that drops a table.
+ */
+export type DropTableOperation = {
+  kind: 'dropTable'
+  table: TableRef
+  ifExists?: boolean
+  cascade?: boolean
+}
+
+/**
+ * Operation that creates an index.
+ */
+export type CreateIndexOperation = {
+  kind: 'createIndex'
+  index: IndexDefinition
+  ifNotExists?: boolean
+}
+
+/**
+ * Operation that drops an index.
+ */
+export type DropIndexOperation = {
+  kind: 'dropIndex'
+  table: TableRef
+  name: string
+  ifExists?: boolean
+}
+
+/**
+ * Operation that renames an index.
+ */
+export type RenameIndexOperation = {
+  kind: 'renameIndex'
+  table: TableRef
+  from: string
+  to: string
+}
+
+/**
+ * Operation that adds a table-level foreign key.
+ */
+export type AddForeignKeyOperation = {
+  kind: 'addForeignKey'
+  table: TableRef
+  constraint: ForeignKeyConstraint
+}
+
+/**
+ * Operation that drops a table-level foreign key.
+ */
+export type DropForeignKeyOperation = {
+  kind: 'dropForeignKey'
+  table: TableRef
+  name: string
+}
+
+/**
+ * Operation that adds a table-level check constraint.
+ */
+export type AddCheckOperation = {
+  kind: 'addCheck'
+  table: TableRef
+  constraint: CheckConstraint
+}
+
+/**
+ * Operation that drops a table-level check constraint.
+ */
+export type DropCheckOperation = {
+  kind: 'dropCheck'
+  table: TableRef
+  name: string
+}
+
+/**
+ * Union of schema and migration operations understood by adapters.
+ */
+export type DataMigrationOperation =
+  | CreateTableOperation
+  | AlterTableOperation
+  | RenameTableOperation
+  | DropTableOperation
+  | CreateIndexOperation
+  | DropIndexOperation
+  | RenameIndexOperation
+  | AddForeignKeyOperation
+  | DropForeignKeyOperation
+  | AddCheckOperation
+  | DropCheckOperation
+  | RawOperation
 
 /**
  * Opaque transaction handle supplied by adapters.
@@ -165,20 +568,38 @@ export type TransactionOptions = {
 /**
  * Adapter execution request payload.
  */
-export type AdapterExecuteRequest = {
-  statement: AdapterStatement
+export type DataManipulationRequest = {
+  operation: DataManipulationOperation
+  transaction?: TransactionToken
+}
+
+/**
+ * Adapter migration request payload.
+ */
+export type DataMigrationRequest = {
+  operation: DataMigrationOperation
   transaction?: TransactionToken
 }
 
 /**
- * Adapter execution result payload.
+ * Adapter data-manipulation result payload.
  */
-export type AdapterResult = {
+export type DataManipulationResult = {
   rows?: Record<string, unknown>[]
   affectedRows?: number
   insertId?: unknown
 }
 
+/**
+ * Adapter data-migration result payload.
+ */
+export type DataMigrationResult = {
+  /**
+   * Number of migration operations processed by the adapter call.
+   */
+  affectedOperations?: number
+}
+
 /**
  * Declares adapter feature support.
  */
@@ -186,6 +607,8 @@ export type AdapterCapabilities = {
   returning: boolean
   savepoints: boolean
   upsert: boolean
+  transactionalDdl: boolean
+  migrationLock: boolean
 }
 
 /**
@@ -197,13 +620,34 @@ 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
-  execute(request: AdapterExecuteRequest): Promise<AdapterResult>
+  /** Compiles a data or migration operation into executable SQL statements. */
+  compileSql(operation: DataManipulationOperation | DataMigrationOperation): SqlStatement[]
+  /** Executes a data-manipulation request. */
+  execute(request: DataManipulationRequest): Promise<DataManipulationResult>
+  /** Executes a migration request. */
+  migrate(request: DataMigrationRequest): Promise<DataMigrationResult>
+  /** 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>
+  /** 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>
 }