@remix-run/data-table 0.1.0 → 0.2.0

package/src/lib/table.ts

@@ -1,5 +1,6 @@
-import { createSchema, parseSafe } from '@remix-run/data-schema'
-import type { InferInput, InferOutput, Issue, ParseOptions, Schema } from '@remix-run/data-schema'
+import type { ColumnDefinition } from './adapter.ts'
+import { ColumnBuilder } from './column.ts'
+import type { ColumnInput as ColumnBuilderInput, ColumnOutput } from './column.ts'
 import type { Predicate, WhereInput } from './operators.ts'
 import { inferForeignKey } from './inflection.ts'
 import { normalizeWhereInput } from './operators.ts'
@@ -13,19 +14,174 @@ import type { Pretty } from './types.ts'
 export { columnMetadataKey, tableMetadataKey } from './references.ts'
 
 /**
- * Mapping of column names to schemas.
+ * Column builder map used when declaring a table.
  */
-export type ColumnSchemas = Record<string, Schema<any, any>>
+export type TableColumnsDefinition = Record<string, ColumnBuilder<any>>
 
-type ColumnNameFromColumns<columns extends ColumnSchemas> = keyof columns & string
+/**
+ * Validation lifecycle operations.
+ */
+export type TableValidationOperation = 'create' | 'update'
+/**
+ * Write lifecycle operations.
+ */
+export type TableWriteOperation = TableValidationOperation
+/**
+ * All lifecycle operations exposed by table hooks.
+ */
+export type TableLifecycleOperation = TableWriteOperation | 'delete' | 'read'
+
+/**
+ * Single validation issue reported by table hooks.
+ */
+export type ValidationIssue = {
+  message: string
+  path?: Array<string | number>
+}
+
+/**
+ * Validation failure returned from table hooks.
+ */
+export type ValidationFailure = {
+  issues: ReadonlyArray<ValidationIssue>
+}
+
+/**
+ * Context passed to the `validate` hook.
+ */
+export type TableValidationContext<row extends Record<string, unknown>> = {
+  operation: TableValidationOperation
+  tableName: string
+  value: Partial<row>
+}
+
+/**
+ * Result returned from the `validate` hook.
+ */
+export type TableValidationResult<row extends Record<string, unknown>> =
+  | { value: Partial<row> }
+  | ValidationFailure
+
+/**
+ * Validation hook that runs before writes.
+ */
+export type TableValidate<row extends Record<string, unknown>> = (
+  context: TableValidationContext<row>,
+) => TableValidationResult<row>
+
+/**
+ * Context passed to the `beforeWrite` hook.
+ */
+export type TableBeforeWriteContext<row extends Record<string, unknown>> = {
+  operation: TableWriteOperation
+  tableName: string
+  value: Partial<row>
+}
+
+/**
+ * Result returned from the `beforeWrite` hook.
+ */
+export type TableBeforeWriteResult<row extends Record<string, unknown>> =
+  | { value: Partial<row> }
+  | ValidationFailure
+
+/**
+ * Hook invoked before a row write executes.
+ */
+export type TableBeforeWrite<row extends Record<string, unknown>> = (
+  context: TableBeforeWriteContext<row>,
+) => TableBeforeWriteResult<row>
+
+/**
+ * Context passed to the `afterWrite` hook.
+ */
+export type TableAfterWriteContext<row extends Record<string, unknown>> = {
+  operation: TableWriteOperation
+  tableName: string
+  values: ReadonlyArray<Partial<row>>
+  affectedRows: number
+  insertId?: unknown
+}
+
+/**
+ * Hook invoked after a row write completes.
+ */
+export type TableAfterWrite<row extends Record<string, unknown>> = (
+  context: TableAfterWriteContext<row>,
+) => void
+
+/**
+ * Context passed to the `beforeDelete` hook.
+ */
+export type TableBeforeDeleteContext = {
+  tableName: string
+  where: ReadonlyArray<Predicate<string>>
+  orderBy: ReadonlyArray<OrderByClause>
+  limit?: number
+  offset?: number
+}
+
+/**
+ * Result returned from the `beforeDelete` hook.
+ */
+export type TableBeforeDeleteResult = void | ValidationFailure
+
+/**
+ * Hook invoked before a delete operation executes.
+ */
+export type TableBeforeDelete = (context: TableBeforeDeleteContext) => TableBeforeDeleteResult
+
+/**
+ * Context passed to the `afterDelete` hook.
+ */
+export type TableAfterDeleteContext = {
+  tableName: string
+  where: ReadonlyArray<Predicate<string>>
+  orderBy: ReadonlyArray<OrderByClause>
+  limit?: number
+  offset?: number
+  affectedRows: number
+}
+
+/**
+ * Hook invoked after a delete operation completes.
+ */
+export type TableAfterDelete = (context: TableAfterDeleteContext) => void
 
-type DefaultPrimaryKey<columns extends ColumnSchemas> =
+/**
+ * Context passed to the `afterRead` hook.
+ */
+export type TableAfterReadContext<row extends Record<string, unknown>> = {
+  tableName: string
+  /**
+   * The current row shape being returned. This may be a projection/partial row.
+   */
+  value: Partial<row>
+}
+
+/**
+ * Result returned from the `afterRead` hook.
+ */
+export type TableAfterReadResult<row extends Record<string, unknown>> =
+  | { value: Partial<row> }
+  | ValidationFailure
+
+/**
+ * Hook invoked after a row is read.
+ */
+export type TableAfterRead<row extends Record<string, unknown>> = (
+  context: TableAfterReadContext<row>,
+) => TableAfterReadResult<row>
+
+type ColumnNameFromColumns<columns extends TableColumnsDefinition> = keyof columns & string
+
+type DefaultPrimaryKey<columns extends TableColumnsDefinition> =
   'id' extends ColumnNameFromColumns<columns>
     ? readonly ['id']
     : readonly ColumnNameFromColumns<columns>[]
 
 type NormalizePrimaryKey<
-  columns extends ColumnSchemas,
+  columns extends TableColumnsDefinition,
   primaryKey extends
     | ColumnNameFromColumns<columns>
     | readonly ColumnNameFromColumns<columns>[]
@@ -36,8 +192,14 @@ type NormalizePrimaryKey<
     ? readonly [primaryKey]
     : DefaultPrimaryKey<columns>
 
+/**
+ * Timestamp configuration accepted by {@link table}.
+ */
 export type TimestampOptions = boolean | { createdAt?: string; updatedAt?: string }
 
+/**
+ * Resolved timestamp column names for a table.
+ */
 export type TimestampConfig = {
   createdAt: string
   updatedAt: string
@@ -45,94 +207,143 @@ export type TimestampConfig = {
 
 type TableMetadata<
   name extends string,
-  columns extends ColumnSchemas,
+  columns extends TableColumnsDefinition,
   primaryKey extends readonly ColumnNameFromColumns<columns>[],
 > = {
   name: name
   columns: columns
   primaryKey: primaryKey
   timestamps: TimestampConfig | null
+  columnDefinitions: {
+    [column in keyof columns & string]: ColumnDefinition
+  }
+  beforeWrite?: TableBeforeWrite<TableRowFromColumns<columns>>
+  afterWrite?: TableAfterWrite<TableRowFromColumns<columns>>
+  beforeDelete?: TableBeforeDelete
+  afterDelete?: TableAfterDelete
+  afterRead?: TableAfterRead<TableRowFromColumns<columns>>
+  validate?: TableValidate<TableRowFromColumns<columns>>
 }
 
+/**
+ * Typed reference to a table column.
+ */
 export type ColumnReference<
   tableName extends string,
   columnName extends string,
-  schema extends Schema<any, any>,
 > = ColumnReferenceLike<`${tableName}.${columnName}`> & {
   [columnMetadataKey]: {
     tableName: tableName
     columnName: columnName
     qualifiedName: `${tableName}.${columnName}`
-    schema: schema
   }
 }
 
-export type AnyColumn = ColumnReference<string, string, Schema<any, any>>
+/**
+ * Any column reference.
+ */
+export type AnyColumn = ColumnReference<string, string>
 
+/**
+ * Column reference narrowed by a qualified column name string.
+ */
 export type ColumnReferenceForQualifiedName<qualifiedName extends string> = AnyColumn & {
   [columnMetadataKey]: {
     qualifiedName: qualifiedName
   }
 }
 
-type TableColumnReferences<name extends string, columns extends ColumnSchemas> = {
-  [column in keyof columns & string]: ColumnReference<name, column, columns[column]>
+type TableColumnReferences<name extends string, columns extends TableColumnsDefinition> = {
+  [column in keyof columns & string]: ColumnReference<name, column>
 }
 
-type TableParseOutput<columns extends ColumnSchemas> = Partial<{
-  [column in keyof columns & string]: InferOutput<columns[column]>
+type TableRowFromColumns<columns extends TableColumnsDefinition> = Pretty<{
+  [column in keyof columns & string]: ColumnOutput<columns[column]>
 }>
 
+/**
+ * Fully-typed table object returned by {@link table}.
+ */
 export type Table<
   name extends string,
-  columns extends ColumnSchemas,
+  columns extends TableColumnsDefinition,
   primaryKey extends readonly ColumnNameFromColumns<columns>[],
 > = TableMetadataLike<name, columns, primaryKey, TimestampConfig | null> & {
   [tableMetadataKey]: TableMetadata<name, columns, primaryKey>
-  '~standard': Schema<unknown, TableParseOutput<columns>>['~standard']
 } & TableColumnReferences<name, columns>
 
+/**
+ * Table-like object with erased concrete column types.
+ */
 export type AnyTable = TableMetadataLike<
   string,
-  ColumnSchemas,
+  TableColumnsDefinition,
   readonly string[],
   TimestampConfig | null
 > & {
   [tableMetadataKey]: {
     name: string
-    columns: ColumnSchemas
+    columns: TableColumnsDefinition
     primaryKey: readonly string[]
     timestamps: TimestampConfig | null
+    columnDefinitions: Record<string, ColumnDefinition>
+    beforeWrite?: unknown
+    afterWrite?: unknown
+    beforeDelete?: unknown
+    afterDelete?: unknown
+    afterRead?: unknown
+    validate?: TableValidate<Record<string, unknown>>
   }
-  '~standard': Schema<unknown, Partial<Record<string, unknown>>>['~standard']
 } & Record<string, unknown>
 
+/**
+ * Name of a concrete table.
+ */
 export type TableName<table extends AnyTable> = table[typeof tableMetadataKey]['name']
 
+/**
+ * Column builder map for a concrete table.
+ */
 export type TableColumns<table extends AnyTable> = table[typeof tableMetadataKey]['columns']
 
+/**
+ * Primary-key column list for a concrete table.
+ */
 export type TablePrimaryKey<table extends AnyTable> = table[typeof tableMetadataKey]['primaryKey']
 
 export type TableTimestamps<table extends AnyTable> = table[typeof tableMetadataKey]['timestamps']
 
-export type TableRow<table extends AnyTable> = Pretty<{
-  [column in keyof TableColumns<table> & string]: InferOutput<TableColumns<table>[column]>
-}>
+/**
+ * Row shape produced by a concrete table.
+ */
+export type TableRow<table extends AnyTable> = TableRowFromColumns<TableColumns<table>>
 
+/**
+ * Row shape with loaded relations merged in.
+ */
 export type TableRowWith<
   table extends AnyTable,
   loaded extends Record<string, unknown> = {},
 > = Pretty<TableRow<table> & loaded>
 
+/**
+ * Unqualified column names for a concrete table.
+ */
 export type TableColumnName<table extends AnyTable> = keyof TableColumns<table> & string
 
 export type QualifiedTableColumnName<table extends AnyTable> =
   `${TableName<table>}.${TableColumnName<table>}`
 
+/**
+ * Column input accepted for a concrete table.
+ */
 export type TableColumnInput<table extends AnyTable> = ColumnInput<
   TableColumnName<table> | QualifiedTableColumnName<table>
 >
 
+/**
+ * Plain metadata snapshot of a table.
+ */
 export type TableReference<table extends AnyTable = AnyTable> = {
   kind: 'table'
   name: TableName<table>
@@ -168,14 +379,96 @@ export function getTableName<table extends AnyTable>(table: table): TableName<ta
 }
 
 /**
- * Returns a table's schema map.
+ * Returns a table's column builder map.
  * @param table Source table instance.
- * @returns Table schema map.
+ * @returns Table column builder map.
  */
 export function getTableColumns<table extends AnyTable>(table: table): TableColumns<table> {
   return table[tableMetadataKey].columns as TableColumns<table>
 }
 
+/**
+ * Returns a table's resolved physical column definitions.
+ * @param table Source table instance.
+ * @returns Column definition map.
+ */
+export function getTableColumnDefinitions<table extends AnyTable>(
+  table: table,
+): {
+  [column in keyof TableColumns<table> & string]: ColumnDefinition
+} {
+  return table[tableMetadataKey].columnDefinitions as {
+    [column in keyof TableColumns<table> & string]: ColumnDefinition
+  }
+}
+
+/**
+ * Returns a table's optional write validator.
+ * @param table Source table instance.
+ * @returns Validation function or `undefined`.
+ */
+export function getTableValidator<table extends AnyTable>(
+  table: table,
+): TableValidate<TableRow<table>> | undefined {
+  return table[tableMetadataKey].validate as TableValidate<TableRow<table>> | undefined
+}
+
+/**
+ * Returns a table's optional before-write lifecycle callback.
+ * @param table Source table instance.
+ * @returns Before-write callback or `undefined`.
+ */
+export function getTableBeforeWrite<table extends AnyTable>(
+  table: table,
+): TableBeforeWrite<TableRow<table>> | undefined {
+  return table[tableMetadataKey].beforeWrite as TableBeforeWrite<TableRow<table>> | undefined
+}
+
+/**
+ * Returns a table's optional after-write lifecycle callback.
+ * @param table Source table instance.
+ * @returns After-write callback or `undefined`.
+ */
+export function getTableAfterWrite<table extends AnyTable>(
+  table: table,
+): TableAfterWrite<TableRow<table>> | undefined {
+  return table[tableMetadataKey].afterWrite as TableAfterWrite<TableRow<table>> | undefined
+}
+
+/**
+ * Returns a table's optional before-delete lifecycle callback.
+ * @param table Source table instance.
+ * @returns Before-delete callback or `undefined`.
+ */
+export function getTableBeforeDelete<table extends AnyTable>(
+  table: table,
+): TableBeforeDelete | undefined {
+  return table[tableMetadataKey].beforeDelete as TableBeforeDelete | undefined
+}
+
+/**
+ * Returns a table's optional after-delete lifecycle callback.
+ * @param table Source table instance.
+ * @returns After-delete callback or `undefined`.
+ */
+export function getTableAfterDelete<table extends AnyTable>(
+  table: table,
+): TableAfterDelete | undefined {
+  return table[tableMetadataKey].afterDelete as TableAfterDelete | undefined
+}
+
+/**
+ * Returns a table's optional after-read lifecycle callback.
+ * The callback receives the current read shape, which may be a projected partial row.
+ * @param table Source table instance.
+ * @returns After-read callback or `undefined`.
+ */
+export function getTableAfterRead<table extends AnyTable>(
+  table: table,
+): TableAfterRead<TableRow<table>> | undefined {
+  return table[tableMetadataKey].afterRead as TableAfterRead<TableRow<table>> | undefined
+}
+
 /**
  * Returns a table's primary key columns.
  * @param table Source table instance.
@@ -194,15 +487,27 @@ export function getTableTimestamps<table extends AnyTable>(table: table): TableT
   return table[tableMetadataKey].timestamps as TableTimestamps<table>
 }
 
+/**
+ * Sort direction accepted by `orderBy`.
+ */
 export type OrderDirection = 'asc' | 'desc'
 
+/**
+ * Normalized `orderBy` clause.
+ */
 export type OrderByClause = {
   column: string
   direction: OrderDirection
 }
 
+/**
+ * Cardinality of a relation.
+ */
 export type RelationCardinality = 'one' | 'many'
 
+/**
+ * Supported relation kinds.
+ */
 export type RelationKind = 'hasMany' | 'hasOne' | 'belongsTo' | 'hasManyThrough'
 
 export type RelationResult<relation extends AnyRelation> =
@@ -212,6 +517,9 @@ export type RelationResult<relation extends AnyRelation> =
       : TableRowWith<target, loaded> | null
     : never
 
+/**
+ * Named relation map for a source table.
+ */
 export type RelationMapForTable<table extends AnyTable> = Record<
   string,
   Relation<table, AnyTable, RelationCardinality, any>
@@ -221,25 +529,40 @@ export type LoadedRelationMap<relations extends RelationMapForTable<any>> = Pret
   [name in keyof relations]: RelationResult<relations[name]>
 }>
 
+/**
+ * Column or column list used to join relations.
+ */
 export type KeySelector<table extends AnyTable> =
   | (keyof TableRow<table> & string)
   | readonly (keyof TableRow<table> & string)[]
 
+/**
+ * Options for defining a {@link hasMany} relation.
+ */
 export type HasManyOptions<source extends AnyTable, target extends AnyTable> = {
   foreignKey?: KeySelector<target>
   targetKey?: KeySelector<source>
 }
 
+/**
+ * Options for defining a {@link hasOne} relation.
+ */
 export type HasOneOptions<source extends AnyTable, target extends AnyTable> = {
   foreignKey?: KeySelector<target>
   targetKey?: KeySelector<source>
 }
 
+/**
+ * Options for defining a {@link belongsTo} relation.
+ */
 export type BelongsToOptions<source extends AnyTable, target extends AnyTable> = {
   foreignKey?: KeySelector<source>
   targetKey?: KeySelector<target>
 }
 
+/**
+ * Options for defining a {@link hasManyThrough} relation.
+ */
 export type HasManyThroughOptions<source extends AnyTable, target extends AnyTable> = {
   through: Relation<source, AnyTable, RelationCardinality, any>
   throughForeignKey?: KeySelector<target>
@@ -260,6 +583,9 @@ export type ThroughRelationMetadata = {
   throughTargetKey: string[]
 }
 
+/**
+ * Relation descriptor used by query loading.
+ */
 export type Relation<
   source extends AnyTable,
   target extends AnyTable,
@@ -289,11 +615,14 @@ export type Relation<
   ): Relation<source, target, cardinality, loaded & LoadedRelationMap<relations>>
 }
 
+/**
+ * Relation descriptor with erased table types.
+ */
 export type AnyRelation = Relation<AnyTable, AnyTable, RelationCardinality, any>
 
 export type CreateTableOptions<
   name extends string,
-  columns extends ColumnSchemas,
+  columns extends TableColumnsDefinition,
   primaryKey extends
     | ColumnNameFromColumns<columns>
     | readonly ColumnNameFromColumns<columns>[]
@@ -303,80 +632,68 @@ export type CreateTableOptions<
   columns: columns
   primaryKey?: primaryKey
   timestamps?: TimestampOptions
+  beforeWrite?: TableBeforeWrite<TableRowFromColumns<columns>>
+  afterWrite?: TableAfterWrite<TableRowFromColumns<columns>>
+  beforeDelete?: TableBeforeDelete
+  afterDelete?: TableAfterDelete
+  afterRead?: TableAfterRead<TableRowFromColumns<columns>>
+  validate?: TableValidate<TableRowFromColumns<columns>>
 }
 
-let defaultTimestampConfig: TimestampConfig = {
+const defaultTimestampConfig: TimestampConfig = {
   createdAt: 'created_at',
   updatedAt: 'updated_at',
 }
 
-function prefixIssuePath(issue: Issue, key: string): Issue {
-  let issuePath = issue.path ?? []
-  return {
-    ...issue,
-    path: [key, ...issuePath],
-  }
-}
-
-function validatePartialRowInput<columns extends ColumnSchemas>(
-  tableName: string,
-  columns: columns,
-  value: unknown,
-  options?: ParseOptions,
-): { value: TableParseOutput<columns> } | { issues: ReadonlyArray<Issue> } {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+/**
+ * Creates a lifecycle/validation failure result with one or more issues.
+ * @param message A single issue message.
+ * @param path Optional issue path.
+ * @returns A {@link ValidationFailure} result object for `validate` and lifecycle callbacks.
+ * @example
+ * ```ts
+ * import { column as c, fail, table } from 'remix/data-table'
+ *
+ * let users = table({
+ *   name: 'users',
+ *   columns: {
+ *     id: c.integer(),
+ *     email: c.varchar(255),
+ *   },
+ *   validate({ value }) {
+ *     if (!value.email) {
+ *       // Fail with a single issue message and optional path
+ *       return fail('Email is required', ['email'])
+ *
+ *       // Or fail with multiple issues at once
+ *       return fail([
+ *         { message: 'Id is required', path: ['id'] },
+ *         { message: 'Email is required', path: ['email'] },
+ *       ])
+ *     }
+ *
+ *     return { value }
+ *   },
+ * })
+ * ```
+ */
+export function fail(message: string, path?: Array<string | number>): ValidationFailure
+/**
+ * @param issues An array of issues.
+ */
+export function fail(issues: ReadonlyArray<ValidationIssue>): ValidationFailure
+export function fail(
+  messageOrIssues: string | ReadonlyArray<ValidationIssue>,
+  path?: Array<string | number>,
+): ValidationFailure {
+  if (typeof messageOrIssues === 'string') {
     return {
-      issues: [{ message: 'Expected object' }],
+      issues: [{ message: messageOrIssues, path }],
     }
   }
 
-  let input = value as Record<string, unknown>
-  let output: Record<string, unknown> = {}
-  let issues: Issue[] = []
-
-  for (let key in input) {
-    if (!Object.prototype.hasOwnProperty.call(input, key)) {
-      continue
-    }
-
-    if (!Object.prototype.hasOwnProperty.call(columns, key)) {
-      issues.push({
-        message: 'Unknown column "' + key + '" for table "' + tableName + '"',
-        path: [key],
-      })
-      continue
-    }
-
-    let result = parseSafe(columns[key], input[key], options)
-
-    if (!result.success) {
-      issues.push(...result.issues.map((issue) => prefixIssuePath(issue, key)))
-      continue
-    }
-
-    output[key] = result.value
-  }
-
-  if (issues.length > 0) {
-    return { issues }
-  }
-
-  return { value: output as TableParseOutput<columns> }
-}
-
-export function validatePartialRow<table extends AnyTable>(
-  table: table,
-  value: unknown,
-  options?: ParseOptions,
-): { value: Partial<TableRow<table>> } | { issues: ReadonlyArray<Issue> } {
-  let result = validatePartialRowInput(getTableName(table), getTableColumns(table), value, options)
-
-  if ('issues' in result) {
-    return result
-  }
-
   return {
-    value: result.value as Partial<TableRow<table>>,
+    issues: [...messageOrIssues],
   }
 }
 
@@ -384,10 +701,23 @@ export function validatePartialRow<table extends AnyTable>(
  * Creates a table object with symbol-backed metadata and direct column references.
  * @param options Table declaration options.
  * @returns A frozen table object.
+ * @example
+ * ```ts
+ * import { column as c, table } from 'remix/data-table'
+ *
+ * let users = table({
+ *   name: 'users',
+ *   columns: {
+ *     id: c.integer(),
+ *     email: c.varchar(255),
+ *   },
+ *   primaryKey: 'id',
+ * })
+ * ```
  */
-export function createTable<
+export function table<
   name extends string,
-  columns extends ColumnSchemas,
+  columns extends TableColumnsDefinition,
   primaryKey extends
     | ColumnNameFromColumns<columns>
     | readonly ColumnNameFromColumns<columns>[]
@@ -398,14 +728,9 @@ export function createTable<
   let tableName = options.name
   let columns = options.columns
 
-  if (Object.prototype.hasOwnProperty.call(columns, '~standard')) {
-    throw new Error(
-      'Column name "~standard" is reserved for table validation on "' + tableName + '"',
-    )
-  }
-
   let resolvedPrimaryKey = normalizePrimaryKey(tableName, columns, options.primaryKey)
   let timestampConfig = normalizeTimestampConfig(options.timestamps)
+  let columnDefinitions = resolveTableColumns(tableName, columns)
   let table = Object.create(null) as Table<name, columns, NormalizePrimaryKey<columns, primaryKey>>
 
   Object.defineProperty(table, tableMetadataKey, {
@@ -414,19 +739,15 @@ export function createTable<
       columns,
       primaryKey: resolvedPrimaryKey,
       timestamps: timestampConfig,
-    }),
-    enumerable: false,
-    writable: false,
-    configurable: false,
-  })
-
-  Object.defineProperty(table, '~standard', {
-    value: Object.freeze({
-      version: 1,
-      vendor: 'data-table',
-      validate(value: unknown, parseOptions?: ParseOptions) {
-        return validatePartialRowInput(tableName, columns, value, parseOptions)
-      },
+      columnDefinitions,
+      beforeWrite: options.beforeWrite as
+        | TableBeforeWrite<TableRowFromColumns<columns>>
+        | undefined,
+      afterWrite: options.afterWrite as TableAfterWrite<TableRowFromColumns<columns>> | undefined,
+      beforeDelete: options.beforeDelete as TableBeforeDelete | undefined,
+      afterDelete: options.afterDelete as TableAfterDelete | undefined,
+      afterRead: options.afterRead as TableAfterRead<TableRowFromColumns<columns>> | undefined,
+      validate: options.validate as TableValidate<TableRowFromColumns<columns>> | undefined,
     }),
     enumerable: false,
     writable: false,
@@ -438,8 +759,7 @@ export function createTable<
       continue
     }
 
-    let schema = columns[columnName]
-    let column = createColumnReference(tableName, columnName, schema)
+    let column = createColumnReference(tableName, columnName)
 
     Object.defineProperty(table, columnName, {
       value: column,
@@ -452,24 +772,49 @@ export function createTable<
   return Object.freeze(table) as Table<name, columns, NormalizePrimaryKey<columns, primaryKey>>
 }
 
-function createColumnReference<
-  tableName extends string,
-  columnName extends string,
-  schema extends Schema<any, any>,
->(
+function createColumnReference<tableName extends string, columnName extends string>(
   tableName: tableName,
   columnName: columnName,
-  schema: schema,
-): ColumnReference<tableName, columnName, schema> {
+): ColumnReference<tableName, columnName> {
   return Object.freeze({
     kind: 'column',
     [columnMetadataKey]: Object.freeze({
       tableName,
       columnName,
       qualifiedName: tableName + '.' + columnName,
-      schema,
     }),
-  }) as ColumnReference<tableName, columnName, schema>
+  }) as ColumnReference<tableName, columnName>
+}
+
+function resolveTableColumns<columns extends TableColumnsDefinition>(
+  tableName: string,
+  columns: columns,
+): { [column in keyof columns & string]: ColumnDefinition } {
+  let columnDefinitions: Record<string, ColumnDefinition> = {}
+
+  for (let columnName in columns) {
+    if (!Object.prototype.hasOwnProperty.call(columns, columnName)) {
+      continue
+    }
+
+    let column = columns[columnName]
+
+    if (!(column instanceof ColumnBuilder)) {
+      throw new Error(
+        'Invalid column "' +
+          columnName +
+          '" for table "' +
+          tableName +
+          '". Expected a column(...) builder',
+      )
+    }
+
+    columnDefinitions[columnName] = column.build()
+  }
+
+  return Object.freeze(columnDefinitions) as {
+    [column in keyof columns & string]: ColumnDefinition
+  }
 }
 
 /**
@@ -630,51 +975,34 @@ export function hasManyThrough<source extends AnyTable, target extends AnyTable>
   })
 }
 
-/**
- * Creates a schema that accepts `Date`, string, and numeric timestamp inputs.
- * @returns Timestamp schema for generated timestamp helpers.
- */
-export function timestampSchema(): Schema<unknown, Date | string | number> {
-  return createSchema<unknown, Date | string | number>((value) => {
-    if (value instanceof Date) {
-      return { value }
-    }
-
-    if (typeof value === 'string' || typeof value === 'number') {
-      return { value }
-    }
-
-    return {
-      issues: [{ message: 'Expected Date, string, or number' }],
-    }
-  })
-}
-
-let defaultTimestampSchema = timestampSchema()
-
 /**
  * Convenience helper for standard snake_case timestamp columns.
- * @param schema Schema used for both timestamp columns.
- * @returns Column schema map for `created_at`/`updated_at`.
+ * @returns Column-builder map for `created_at`/`updated_at`.
  */
-export function timestamps(
-  schema: Schema<any, any> = defaultTimestampSchema,
-): Record<'created_at' | 'updated_at', Schema<any, any>> {
+export function timestamps(): Record<
+  'created_at' | 'updated_at',
+  ColumnBuilder<Date | string | number>
+> {
+  let timestampColumn = () => new ColumnBuilder<Date | string | number>({ type: 'timestamp' })
+
   return {
-    created_at: schema,
-    updated_at: schema,
+    created_at: timestampColumn(),
+    updated_at: timestampColumn(),
   }
 }
 
+/**
+ * Primary-key input accepted by `find()`, `update()`, and similar helpers.
+ */
 export type PrimaryKeyInput<table extends AnyTable> =
   TablePrimaryKey<table> extends readonly [infer column extends string]
     ? column extends keyof TableColumns<table> & string
-      ? InferInput<TableColumns<table>[column]>
+      ? ColumnBuilderInput<TableColumns<table>[column]>
       : never
     : Pretty<{
-        [column in TablePrimaryKey<table>[number] & keyof TableColumns<table> & string]: InferInput<
-          TableColumns<table>[column]
-        >
+        [column in TablePrimaryKey<table>[number] &
+          keyof TableColumns<table> &
+          string]: ColumnBuilderInput<TableColumns<table>[column]>
       }>
 
 /**
@@ -757,13 +1085,13 @@ export function stableSerialize(value: unknown): string {
 
 function normalizePrimaryKey(
   tableName: string,
-  columns: ColumnSchemas,
+  columns: TableColumnsDefinition,
   primaryKey?: string | readonly string[],
 ): string[] {
   if (primaryKey === undefined) {
     if (!Object.prototype.hasOwnProperty.call(columns, 'id')) {
       throw new Error(
-        'Table "' + tableName + '" must define an "id" column or an explicit primaryKey',
+        'Table "' + tableName + '" must include an "id" column or an explicit primaryKey',
       )
     }