@remix-run/data-table 0.1.0 → 0.2.0

package/src/lib/column.ts

@@ -0,0 +1,384 @@
+import type { ColumnDefinition, ForeignKeyAction, IdentityOptions } from './adapter.ts'
+import { toTableRef } from './migrations/helpers.ts'
+
+/**
+ * Chainable builder used to describe physical column definitions.
+ */
+export class ColumnBuilder<output = unknown> {
+  #definition: ColumnDefinition
+
+  constructor(definition: ColumnDefinition) {
+    this.#definition = definition
+  }
+
+  /**
+   * Marks the column as nullable.
+   * @returns The column builder with `null` added to its output type.
+   */
+  nullable(): ColumnBuilder<output | null> {
+    this.#definition.nullable = true
+    return this as unknown as ColumnBuilder<output | null>
+  }
+
+  /**
+   * Marks the column as non-nullable.
+   * @returns The column builder with `null` removed from its output type.
+   */
+  notNull(): ColumnBuilder<Exclude<output, null>> {
+    this.#definition.nullable = false
+    return this as unknown as ColumnBuilder<Exclude<output, null>>
+  }
+
+  /**
+   * Sets a literal default value for the column.
+   * @param value Default value to apply when the column is omitted.
+   * @returns The column builder.
+   */
+  default(value: unknown): ColumnBuilder<output> {
+    this.#definition.default = {
+      kind: 'literal',
+      value,
+    }
+    return this
+  }
+
+  /**
+   * Sets the column default to the current timestamp at write time.
+   * @returns The column builder.
+   */
+  defaultNow(): ColumnBuilder<output> {
+    this.#definition.default = {
+      kind: 'now',
+    }
+    return this
+  }
+
+  /**
+   * Sets a raw SQL expression as the column default.
+   * @param expression SQL expression used as the default value.
+   * @returns The column builder.
+   */
+  defaultSql(expression: string): ColumnBuilder<output> {
+    this.#definition.default = {
+      kind: 'sql',
+      expression,
+    }
+    return this
+  }
+
+  /**
+   * Marks the column as part of the primary key.
+   * @returns The column builder.
+   */
+  primaryKey(): ColumnBuilder<output> {
+    this.#definition.primaryKey = true
+    return this
+  }
+
+  /**
+   * Marks the column as unique.
+   * @param name Optional constraint name.
+   * @returns The column builder.
+   */
+  unique(name?: string): ColumnBuilder<output> {
+    this.#definition.unique = name ? { name } : true
+    return this
+  }
+
+  /**
+   * Adds a foreign-key reference for the column.
+   * @param table Referenced table name.
+   * @param name Constraint name.
+   * @returns The column builder.
+   */
+  references(table: string, name: string): ColumnBuilder<output>
+  /**
+   * Adds a foreign-key reference for the column.
+   * @param table Referenced table name.
+   * @param columns Referenced column list.
+   * @param name Constraint name.
+   * @returns The column builder.
+   */
+  references(table: string, columns: string | string[], name: string): ColumnBuilder<output>
+  references(
+    table: string,
+    columnsOrName: string | string[],
+    maybeName?: string,
+  ): ColumnBuilder<output> {
+    let columns = maybeName === undefined ? 'id' : columnsOrName
+    let name = maybeName === undefined ? String(columnsOrName) : maybeName
+
+    this.#definition.references = {
+      table: toTableRef(table),
+      columns: Array.isArray(columns) ? [...columns] : [columns],
+      onDelete: this.#definition.references?.onDelete,
+      onUpdate: this.#definition.references?.onUpdate,
+      name,
+    }
+    return this
+  }
+
+  /**
+   * Sets the foreign-key action used when the referenced row is deleted.
+   * @param action Delete action to apply.
+   * @returns The column builder.
+   */
+  onDelete(action: ForeignKeyAction): ColumnBuilder<output> {
+    if (!this.#definition.references) {
+      throw new Error('onDelete() requires references() to be set first')
+    }
+
+    this.#definition.references.onDelete = action
+    return this
+  }
+
+  /**
+   * Sets the foreign-key action used when the referenced row is updated.
+   * @param action Update action to apply.
+   * @returns The column builder.
+   */
+  onUpdate(action: ForeignKeyAction): ColumnBuilder<output> {
+    if (!this.#definition.references) {
+      throw new Error('onUpdate() requires references() to be set first')
+    }
+
+    this.#definition.references.onUpdate = action
+    return this
+  }
+
+  /**
+   * Adds a check constraint for the column.
+   * @param expression SQL check expression.
+   * @param name Constraint name.
+   * @returns The column builder.
+   */
+  check(expression: string, name: string): ColumnBuilder<output> {
+    let checks = this.#definition.checks ?? []
+    checks.push({ expression, name })
+    this.#definition.checks = checks
+    return this
+  }
+
+  /**
+   * Adds a database comment for the column.
+   * @param text Comment text.
+   * @returns The column builder.
+   */
+  comment(text: string): ColumnBuilder<output> {
+    this.#definition.comment = text
+    return this
+  }
+
+  /**
+   * Marks the column as computed from a SQL expression.
+   * @param expression SQL expression for the computed value.
+   * @param options Computed-column options.
+   * @param options.stored Whether the computed column should be stored instead of virtual.
+   * @returns The column builder.
+   */
+  computed(expression: string, options?: { stored?: boolean }): ColumnBuilder<output> {
+    this.#definition.computed = {
+      expression,
+      stored: options?.stored ?? true,
+    }
+    return this
+  }
+
+  /**
+   * Marks the column as unsigned when the dialect supports it.
+   * @returns The column builder.
+   */
+  unsigned(): ColumnBuilder<output> {
+    this.#definition.unsigned = true
+    return this
+  }
+
+  /**
+   * Marks the column as auto-incrementing when the dialect supports it.
+   * @returns The column builder.
+   */
+  autoIncrement(): ColumnBuilder<output> {
+    this.#definition.autoIncrement = true
+    return this
+  }
+
+  /**
+   * Configures an identity column strategy when the dialect supports it.
+   * @param options Identity sequence options.
+   * @returns The column builder.
+   */
+  identity(options?: IdentityOptions): ColumnBuilder<output> {
+    this.#definition.identity = options ?? {}
+    return this
+  }
+
+  /**
+   * Sets the collation for the column.
+   * @param name Collation name.
+   * @returns The column builder.
+   */
+  collate(name: string): ColumnBuilder<output> {
+    this.#definition.collate = name
+    return this
+  }
+
+  /**
+   * Sets the character set for the column.
+   * @param name Character set name.
+   * @returns The column builder.
+   */
+  charset(name: string): ColumnBuilder<output> {
+    this.#definition.charset = name
+    return this
+  }
+
+  /**
+   * Sets the column length.
+   * @param value Maximum length value.
+   * @returns The column builder.
+   */
+  length(value: number): ColumnBuilder<output> {
+    this.#definition.length = value
+    return this
+  }
+
+  /**
+   * Sets numeric precision and optional scale for the column.
+   * @param value Precision value.
+   * @param scale Optional scale value.
+   * @returns The column builder.
+   */
+  precision(value: number, scale?: number): ColumnBuilder<output> {
+    this.#definition.precision = value
+
+    if (scale !== undefined) {
+      this.#definition.scale = scale
+    }
+
+    return this
+  }
+
+  /**
+   * Sets numeric scale for the column.
+   * @param value Scale value.
+   * @returns The column builder.
+   */
+  scale(value: number): ColumnBuilder<output> {
+    this.#definition.scale = value
+    return this
+  }
+
+  /**
+   * Enables or disables timezone support for time-based columns.
+   * @param enabled Whether timezone support should be enabled.
+   * @returns The column builder.
+   */
+  timezone(enabled = true): ColumnBuilder<output> {
+    this.#definition.withTimezone = enabled
+    return this
+  }
+
+  /**
+   * Builds the immutable column definition.
+   * @returns A normalized column definition.
+   */
+  build(): ColumnDefinition {
+    return {
+      ...this.#definition,
+      checks: this.#definition.checks ? [...this.#definition.checks] : undefined,
+    }
+  }
+}
+
+/** Resolves the runtime output type from a column builder. */
+export type ColumnOutput<column extends ColumnBuilder<any>> =
+  column extends ColumnBuilder<infer output> ? output : never
+
+/** Input type accepted when writing values for a column builder. */
+export type ColumnInput<column extends ColumnBuilder<any>> = ColumnOutput<column>
+
+/**
+ * Public constructor namespace for column builders.
+ */
+export type ColumnNamespace = {
+  varchar(length: number): ColumnBuilder<string>
+  text(): ColumnBuilder<string>
+  integer(): ColumnBuilder<number>
+  bigint(): ColumnBuilder
+  decimal(precision: number, scale: number): ColumnBuilder<number>
+  boolean(): ColumnBuilder<boolean>
+  uuid(): ColumnBuilder<string>
+  date(): ColumnBuilder
+  time(options?: { precision?: number; withTimezone?: boolean }): ColumnBuilder
+  timestamp(options?: { precision?: number; withTimezone?: boolean }): ColumnBuilder
+  json(): ColumnBuilder
+  binary(length?: number): ColumnBuilder
+  enum<values extends readonly string[]>(values: values): ColumnBuilder<values[number]>
+}
+
+function createColumnBuilder<output = unknown>(
+  type: ColumnDefinition['type'],
+): ColumnBuilder<output> {
+  return new ColumnBuilder({ type })
+}
+
+/**
+ * Chainable column builder namespace.
+ * @example
+ * ```ts
+ * import { column as c } from 'remix/data-table'
+ *
+ * let email = c.varchar(255).notNull().unique('users_email_uq')
+ * ```
+ */
+export const column: ColumnNamespace = {
+  varchar(length: number) {
+    return new ColumnBuilder({ type: 'varchar', length })
+  },
+  text() {
+    return createColumnBuilder<string>('text')
+  },
+  integer() {
+    return createColumnBuilder<number>('integer')
+  },
+  bigint() {
+    return createColumnBuilder('bigint')
+  },
+  decimal(precision: number, scale: number) {
+    return new ColumnBuilder({ type: 'decimal', precision, scale })
+  },
+  boolean() {
+    return createColumnBuilder<boolean>('boolean')
+  },
+  uuid() {
+    return createColumnBuilder<string>('uuid')
+  },
+  date() {
+    return createColumnBuilder('date')
+  },
+  time(options?: { precision?: number; withTimezone?: boolean }) {
+    return new ColumnBuilder({
+      type: 'time',
+      precision: options?.precision,
+      withTimezone: options?.withTimezone,
+    })
+  },
+  timestamp(options?: { precision?: number; withTimezone?: boolean }) {
+    return new ColumnBuilder({
+      type: 'timestamp',
+      precision: options?.precision,
+      withTimezone: options?.withTimezone,
+    })
+  },
+  json() {
+    return createColumnBuilder('json')
+  },
+  binary(length?: number) {
+    return new ColumnBuilder({ type: 'binary', length })
+  },
+  enum<values extends readonly string[]>(values: values) {
+    return new ColumnBuilder({ type: 'enum', enumValues: [...values] }) as ColumnBuilder<
+      values[number]
+    >
+  },
+}

package/src/lib/database/execution-context.ts

@@ -0,0 +1,15 @@
+import type {
+  DataManipulationOperation,
+  DataManipulationResult,
+  DatabaseAdapter,
+} from '../adapter.ts'
+import type { Database } from '../database.ts'
+
+export const executeOperation = Symbol('executeOperation')
+
+export type QueryExecutionContext = {
+  adapter: DatabaseAdapter
+  now(): unknown
+  transaction<result>(callback: (database: Database) => Promise<result>): Promise<result>
+  [executeOperation](operation: DataManipulationOperation): Promise<DataManipulationResult>
+}

package/src/lib/database/helpers.ts

@@ -0,0 +1,216 @@
+import { DataTableQueryError } from '../errors.ts'
+import type {
+  OrderByInput,
+  OrderByTuple,
+  QueryColumnName,
+  QueryColumns,
+  QueryColumnTypeMap,
+  QueryTableInput,
+  SingleTableWhere,
+  TableColumnName,
+  WriteResult,
+  WriteRowsResult,
+} from '../database.ts'
+import type { Predicate } from '../operators.ts'
+import { and, eq, inList, or } from '../operators.ts'
+import { query as createQuery } from '../query.ts'
+import type { AnyTable, PrimaryKeyInput, TableName, TablePrimaryKey, TableRow } from '../table.ts'
+import { getPrimaryKeyObject, getTableName, getTablePrimaryKey } from '../table.ts'
+
+import type { QueryExecutionContext } from './execution-context.ts'
+import { loadRowsWithRelationsForQuery } from './query-execution.ts'
+
+export function asQueryTableInput<table extends AnyTable>(
+  table: table,
+): QueryTableInput<TableName<table>, TableRow<table>, TablePrimaryKey<table>> {
+  return table as unknown as QueryTableInput<
+    TableName<table>,
+    TableRow<table>,
+    TablePrimaryKey<table>
+  >
+}
+
+export function getPrimaryKeyWhere<table extends AnyTable>(
+  table: table,
+  value: PrimaryKeyInput<table>,
+): SingleTableWhere<table> {
+  return getPrimaryKeyObject(table, value as any) as SingleTableWhere<table>
+}
+
+export function getPrimaryKeyWhereFromRow<table extends AnyTable>(
+  table: table,
+  row: Record<string, unknown>,
+): SingleTableWhere<table> {
+  let where: Record<string, unknown> = {}
+
+  for (let key of getTablePrimaryKey(table) as string[]) {
+    where[key] = row[key]
+  }
+
+  return where as SingleTableWhere<table>
+}
+
+export function resolveCreateRowWhere<table extends AnyTable>(
+  table: table,
+  values: Partial<TableRow<table>>,
+  insertId: unknown,
+): SingleTableWhere<table> {
+  let primaryKey = getTablePrimaryKey(table) as string[]
+
+  if (primaryKey.length === 1) {
+    let key = primaryKey[0]
+
+    if (Object.prototype.hasOwnProperty.call(values, key)) {
+      return {
+        [key]: (values as Record<string, unknown>)[key],
+      } as SingleTableWhere<table>
+    }
+
+    if (insertId !== undefined) {
+      return {
+        [key]: insertId,
+      } as SingleTableWhere<table>
+    }
+  }
+
+  let where: Record<string, unknown> = {}
+
+  for (let key of primaryKey) {
+    if (!Object.prototype.hasOwnProperty.call(values, key)) {
+      throw new DataTableQueryError(
+        'create({ returnRow: true }) requires primary key values for table "' +
+          getTableName(table) +
+          '" when adapter does not support RETURNING',
+      )
+    }
+
+    where[key] = (values as Record<string, unknown>)[key]
+  }
+
+  return where as SingleTableWhere<table>
+}
+
+export function normalizeOrderByInput<table extends AnyTable>(
+  input: OrderByInput<table> | undefined,
+): OrderByTuple<table>[] {
+  if (!input) {
+    return []
+  }
+
+  if (input.length === 0) {
+    return []
+  }
+
+  if (Array.isArray(input[0])) {
+    return input as OrderByTuple<table>[]
+  }
+
+  return [input as OrderByTuple<table>]
+}
+
+export function toWriteResult(result: WriteResult | WriteRowsResult<unknown>): WriteResult {
+  return {
+    affectedRows: result.affectedRows,
+    insertId: result.insertId,
+  }
+}
+
+export function hasScopedWriteModifiers(state: {
+  orderBy: unknown[]
+  limit?: number
+  offset?: number
+}): boolean {
+  return state.orderBy.length > 0 || state.limit !== undefined || state.offset !== undefined
+}
+
+export async function loadPrimaryKeyRowsForScope<table extends AnyTable>(
+  database: QueryExecutionContext,
+  table: table,
+  state: {
+    where: Predicate<string>[]
+    orderBy: Array<{ column: string; direction: 'asc' | 'desc' }>
+    limit?: number
+    offset?: number
+  },
+): Promise<Record<string, unknown>[]> {
+  let query = createQuery(
+    table as unknown as QueryTableInput<TableName<table>, TableRow<table>, TablePrimaryKey<table>>,
+  )
+
+  for (let predicate of state.where) {
+    query = query.where(predicate as Predicate<QueryColumnName<table>>)
+  }
+
+  for (let clause of state.orderBy) {
+    query = query.orderBy(
+      clause.column as QueryColumns<QueryColumnTypeMap<table>>,
+      clause.direction,
+    )
+  }
+
+  if (state.limit !== undefined) {
+    query = query.limit(state.limit)
+  }
+
+  if (state.offset !== undefined) {
+    query = query.offset(state.offset)
+  }
+
+  let rows = await loadRowsWithRelationsForQuery(
+    database,
+    query.select(...(getTablePrimaryKey(table) as (keyof TableRow<table> & string)[])),
+  )
+  let primaryKeys = getTablePrimaryKey(table) as string[]
+
+  return rows.map((row) => {
+    let keyObject: Record<string, unknown> = {}
+
+    for (let key of rowKeys(row as Record<string, unknown>, primaryKeys)) {
+      keyObject[key] = (row as Record<string, unknown>)[key]
+    }
+
+    return keyObject
+  })
+}
+
+export function buildPrimaryKeyPredicate<table extends AnyTable>(
+  table: table,
+  keyObjects: Record<string, unknown>[],
+): Predicate<TableColumnName<table>> | undefined {
+  let primaryKey = getTablePrimaryKey(table)
+
+  if (keyObjects.length === 0) {
+    return undefined
+  }
+
+  if (primaryKey.length === 1) {
+    let key = primaryKey[0] as TableColumnName<table>
+    return inList(
+      key,
+      keyObjects.map((objectValue) => objectValue[key]),
+    )
+  }
+
+  let predicates = keyObjects.map((objectValue) => {
+    let comparisons = primaryKey.map((key) => {
+      let typedKey = key as TableColumnName<table>
+      return eq(typedKey, objectValue[typedKey])
+    })
+
+    return and(...comparisons)
+  })
+
+  return or(...predicates)
+}
+
+function rowKeys(row: Record<string, unknown>, keys: string[]): string[] {
+  let output: string[] = []
+
+  for (let key of keys) {
+    if (Object.prototype.hasOwnProperty.call(row, key)) {
+      output.push(key)
+    }
+  }
+
+  return output
+}