kysely-ddl 0.1.0

package/dist/table/columns.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Column builders as chains, like in drizzle.
+ *
+ * The set of types is what application schemas actually need:
+ * uuid / varchar / integer / bigint / boolean / numeric / timestamp / jsonb,
+ * plus `enum`, a varchar with an automatic check constraint.
+ * Adding a type is one line at the bottom of the file.
+ *
+ * ── Why there is no `mode` ───────────────────────────────────────────────────
+ *
+ * In drizzle, `bigint({ mode: 'number' })` and `numeric({ mode: 'bigint' })` change
+ * the column's TS type. But the mode describes the behaviour of drizzle's RUNTIME:
+ * it converts the values itself. This library has no runtime, the driver does the
+ * reading, so the column type is set once and matches what `pg` returns:
+ *
+ *   int8    -> string   (no precision loss beyond 2^53)
+ *   numeric -> string   (no float error)
+ *
+ * For another type use `$type<T>()` plus an explicit conversion on your side.
+ */
+import type { Sql } from './sql.ts';
+/** Column config at the type level. */
+export interface ColumnCfg {
+    /** The explicitly set column name; `undefined` means it is taken from the property name. */
+    readonly name: string | undefined;
+    readonly data: unknown;
+    readonly notNull: boolean;
+    readonly hasDefault: boolean;
+    readonly array: boolean;
+    readonly identity: 'always' | 'byDefault' | undefined;
+    /** `enum()` values: `defineTable` builds a check from them. */
+    readonly enumValues: readonly string[] | undefined;
+    /** A jsonb column: values for writes go through `jsonb()`, see the kysely layer. */
+    readonly json: boolean;
+}
+/**
+ * A targeted config update: what U has overrides T, the rest is carried over.
+ * `Omit<T, keyof U> & U` does not work here: TypeScript cannot prove that the
+ * result is still a `ColumnCfg` when U is declared as `Partial`.
+ */
+type Update<T extends ColumnCfg, U extends Partial<ColumnCfg>> = {
+    readonly name: U extends {
+        name: infer V;
+    } ? V : T['name'];
+    readonly data: U extends {
+        data: infer V;
+    } ? V : T['data'];
+    readonly notNull: U extends {
+        notNull: infer V extends boolean;
+    } ? V : T['notNull'];
+    readonly hasDefault: U extends {
+        hasDefault: infer V extends boolean;
+    } ? V : T['hasDefault'];
+    readonly array: U extends {
+        array: infer V extends boolean;
+    } ? V : T['array'];
+    readonly identity: U extends {
+        identity: infer V;
+    } ? V : T['identity'];
+    readonly enumValues: U extends {
+        enumValues: infer V;
+    } ? V : T['enumValues'];
+    readonly json: U extends {
+        json: infer V extends boolean;
+    } ? V : T['json'];
+};
+/** A default: a literal or an SQL expression. */
+export type DefaultValue = Sql | string | number | boolean | null;
+/** Everything needed to generate DDL. */
+export interface ColumnSpec {
+    /** The base postgres type without `[]`: 'uuid', 'varchar(2)', 'numeric(10, 2)'. */
+    readonly sqlType: string;
+    readonly name: string | undefined;
+    readonly notNull: boolean;
+    readonly default: DefaultValue | undefined;
+    readonly identity: 'always' | 'byDefault' | undefined;
+    readonly array: boolean;
+    readonly enumValues: readonly string[] | undefined;
+}
+export declare class ColumnBuilder<T extends ColumnCfg = ColumnCfg> {
+    readonly spec: ColumnSpec;
+    readonly _: T;
+    constructor(spec: ColumnSpec);
+    private next;
+    notNull(): ColumnBuilder<Update<T, {
+        notNull: true;
+    }>>;
+    default(value: DefaultValue): ColumnBuilder<Update<T, {
+        hasDefault: true;
+    }>>;
+    /** Sugar for `.default(sql\`now()\`)`. */
+    defaultNow(): ColumnBuilder<Update<T, {
+        hasDefault: true;
+    }>>;
+    /** `GENERATED ALWAYS AS IDENTITY`: postgres owns the value, it cannot be inserted. */
+    generatedAlwaysAsIdentity(): ColumnBuilder<Update<T, {
+        notNull: true;
+        hasDefault: true;
+        identity: 'always';
+    }>>;
+    array(): ColumnBuilder<Update<T, {
+        data: T['data'][];
+        array: true;
+    }>>;
+    /** Narrows the value type without touching the column type in the database. */
+    $type<U>(): ColumnBuilder<Update<T, {
+        data: U;
+    }>>;
+}
+export type AnyColumn = ColumnBuilder<ColumnCfg>;
+/** A fresh column: the name is either explicit or taken from the object key. */
+type Fresh<N extends string | undefined, TData, TEnum extends readonly string[] | undefined = undefined, TJson extends boolean = false> = ColumnBuilder<{
+    name: N;
+    data: TData;
+    notNull: false;
+    hasDefault: false;
+    array: false;
+    identity: undefined;
+    enumValues: TEnum;
+    json: TJson;
+}>;
+declare function uuid<N extends string>(name: N): Fresh<N, string>;
+declare function uuid(): Fresh<undefined, string>;
+interface VarcharConfig {
+    length?: number;
+}
+declare function varchar<N extends string>(name: N, config?: VarcharConfig): Fresh<N, string>;
+declare function varchar(config?: VarcharConfig): Fresh<undefined, string>;
+/**
+ * A set of allowed values: the column stays `varchar`, and the restriction goes
+ * into a check constraint that `defineTable` builds itself:
+ *
+ * ```sql
+ * CONSTRAINT "ticket_status_check" CHECK ("status" in ('new', 'closed'))
+ * ```
+ *
+ * A native `create type ... as enum` is deliberately not used: adding a value
+ * requires `ALTER TYPE`, and the new value cannot be used in the same transaction
+ * that added it. `varchar` + check changes with a regular `ALTER TABLE`.
+ *
+ * In the types this is a union of string literals, not `string`.
+ *
+ * The function is declared as `enumColumn` because `enum` is a reserved word and
+ * cannot name a declaration. It can be an object key though, and the builders are
+ * handed out only as an object, so from the outside it is exactly `t.enum(...)`.
+ */
+declare function enumColumn<N extends string, const T extends readonly [string, ...string[]]>(name: N, values: T): Fresh<N, T[number], T>;
+declare function enumColumn<const T extends readonly [string, ...string[]]>(values: T): Fresh<undefined, T[number], T>;
+declare function integer<N extends string>(name: N): Fresh<N, number>;
+declare function integer(): Fresh<undefined, number>;
+/** int8. A string in JS: that is what `pg` returns, and no precision is lost. */
+declare function bigint<N extends string>(name: N): Fresh<N, string>;
+declare function bigint(): Fresh<undefined, string>;
+declare function boolean<N extends string>(name: N): Fresh<N, boolean>;
+declare function boolean(): Fresh<undefined, boolean>;
+interface NumericConfig {
+    precision?: number;
+    scale?: number;
+}
+/** numeric. A string in JS: no float error. */
+declare function numeric<N extends string>(name: N, config?: NumericConfig): Fresh<N, string>;
+declare function numeric(config?: NumericConfig): Fresh<undefined, string>;
+interface TimestampConfig {
+    withTimezone?: boolean;
+    precision?: number;
+}
+declare function timestamp<N extends string>(name: N, config?: TimestampConfig): Fresh<N, Date>;
+declare function timestamp(config?: TimestampConfig): Fresh<undefined, Date>;
+/**
+ * `unknown` in TS, narrow it with `$type<T>()`. Values for writes go only
+ * through `jsonb()` from `kysely-ddl/kysely`: drivers accept a raw jsonb
+ * parameter differently, and the helper evens that out.
+ */
+declare function jsonb<N extends string>(name: N): Fresh<N, unknown, undefined, true>;
+declare function jsonb(): Fresh<undefined, unknown, undefined, true>;
+/**
+ * What arrives in `columns: t => ({ ... })`.
+ *
+ * Builders are not exported one by one: the only way to declare a column is the
+ * callback. So the schema file has no import list to maintain with every new
+ * column, and there is exactly one declaration form.
+ */
+declare const columnBuilders: {
+    readonly bigint: typeof bigint;
+    readonly boolean: typeof boolean;
+    readonly integer: typeof integer;
+    readonly jsonb: typeof jsonb;
+    readonly numeric: typeof numeric;
+    readonly timestamp: typeof timestamp;
+    readonly enum: typeof enumColumn;
+    readonly uuid: typeof uuid;
+    readonly varchar: typeof varchar;
+};
+export { columnBuilders };
+export type ColumnBuilders = typeof columnBuilders;

package/dist/table/columns.js

@@ -0,0 +1,114 @@
+export class ColumnBuilder {
+    spec;
+    constructor(spec) {
+        this.spec = spec;
+    }
+    next(patch) {
+        return new ColumnBuilder({ ...this.spec, ...patch });
+    }
+    notNull() {
+        return this.next({ notNull: true });
+    }
+    default(value) {
+        return this.next({ default: value });
+    }
+    /** Sugar for `.default(sql\`now()\`)`. */
+    defaultNow() {
+        return this.next({
+            default: { kind: 'sql', chunks: ['now()'] },
+        });
+    }
+    /** `GENERATED ALWAYS AS IDENTITY`: postgres owns the value, it cannot be inserted. */
+    generatedAlwaysAsIdentity() {
+        return this.next({
+            notNull: true,
+            identity: 'always',
+        });
+    }
+    array() {
+        return this.next({ array: true });
+    }
+    /** Narrows the value type without touching the column type in the database. */
+    // oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- the type parameter is the whole point of the method
+    $type() {
+        return this;
+    }
+}
+function fresh(sqlType, name, enumValues) {
+    return new ColumnBuilder({
+        sqlType,
+        name,
+        notNull: false,
+        default: undefined,
+        identity: undefined,
+        array: false,
+        enumValues,
+    });
+}
+/** Parses `(name?, config?)`, both forms of calling a builder. */
+function args(a, b) {
+    return typeof a === 'string' ? { name: a, config: b } : { name: undefined, config: a };
+}
+function uuid(name) {
+    return fresh('uuid', name);
+}
+function varchar(a, b) {
+    const { name, config } = args(a, b);
+    const sqlType = config?.length === undefined ? 'varchar' : `varchar(${config.length})`;
+    return fresh(sqlType, name);
+}
+function enumColumn(a, b) {
+    const name = typeof a === 'string' ? a : undefined;
+    const values = typeof a === 'string' ? b : a;
+    if (values === undefined || values.length === 0) {
+        throw new Error('enum(): a non-empty list of values is required');
+    }
+    return fresh('varchar', name, values);
+}
+function integer(name) {
+    return fresh('integer', name);
+}
+function bigint(name) {
+    return fresh('bigint', name);
+}
+function boolean(name) {
+    return fresh('boolean', name);
+}
+function numeric(a, b) {
+    const { name, config } = args(a, b);
+    const sqlType = config?.precision === undefined
+        ? 'numeric'
+        : config.scale === undefined
+            ? `numeric(${config.precision})`
+            : `numeric(${config.precision}, ${config.scale})`;
+    return fresh(sqlType, name);
+}
+function timestamp(a, b) {
+    const { name, config } = args(a, b);
+    const precision = config?.precision === undefined ? '' : `(${config.precision})`;
+    const tz = config?.withTimezone === true ? ' with time zone' : '';
+    return fresh(`timestamp${precision}${tz}`, name);
+}
+function jsonb(name) {
+    return fresh('jsonb', name);
+}
+// ── the builder set for the callback form ────────────────────────────────────
+/**
+ * What arrives in `columns: t => ({ ... })`.
+ *
+ * Builders are not exported one by one: the only way to declare a column is the
+ * callback. So the schema file has no import list to maintain with every new
+ * column, and there is exactly one declaration form.
+ */
+const columnBuilders = {
+    bigint,
+    boolean,
+    integer,
+    jsonb,
+    numeric,
+    timestamp,
+    enum: enumColumn,
+    uuid,
+    varchar,
+};
+export { columnBuilders };

package/dist/table/define.d.ts

@@ -0,0 +1,165 @@
+/**
+ * `defineTable`, a hybrid: columns as chains, everything else as a declarative block.
+ *
+ * The key difference from drizzle rc5: **the column name stays a literal in the type**.
+ * When a name is not set explicitly, it is derived from the property name with the
+ * same snake_case that is applied at runtime, at the type level too (see `SnakeCase`).
+ * This is exactly what rc5 lacks, where `Column['_']['name']` collapses to `string`.
+ *
+ * Index and constraint names are optional as well, see `AUTO_NAMES`.
+ */
+import { type SnakeCase } from './casing.ts';
+import { type AnyColumn, type ColumnBuilders, type ColumnCfg, type ColumnSpec } from './columns.ts';
+import { type ColumnRef, type Sql } from './sql.ts';
+/**
+ * Auto-name suffixes. The convention:
+ *
+ *   user_pk
+ *   ticket_number_uq
+ *   session_user_id_fk
+ *   ticket_status_check
+ *   user_resource_transaction_user_id_resource_idx
+ *
+ * The primary key is the only one named without columns: there is one per table.
+ */
+export declare const AUTO_NAMES: {
+    readonly primaryKey: 'pk';
+    readonly unique: 'uq';
+    readonly foreignKey: 'fk';
+    readonly check: 'check';
+    readonly index: 'idx';
+};
+/** Column config after its name has been resolved. */
+export interface ResolvedColumnCfg extends Omit<ColumnCfg, 'name'> {
+    readonly name: string;
+}
+type ResolveName<K extends string, C extends AnyColumn> = C['_']['name'] extends string ? C['_']['name'] : SnakeCase<K>;
+export type ResolveColumns<TCols extends Record<string, AnyColumn>> = {
+    readonly [K in keyof TCols & string]: {
+        readonly name: ResolveName<K, TCols[K]>;
+        readonly data: TCols[K]['_']['data'];
+        readonly notNull: TCols[K]['_']['notNull'];
+        readonly hasDefault: TCols[K]['_']['hasDefault'];
+        readonly array: TCols[K]['_']['array'];
+        readonly identity: TCols[K]['_']['identity'];
+        readonly enumValues: TCols[K]['_']['enumValues'];
+        readonly json: TCols[K]['_']['json'];
+    };
+};
+export type ReferentialAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+/** A column with its name already resolved; this is what goes into the snapshot. */
+export interface ResolvedColumn extends Omit<ColumnSpec, 'name'> {
+    readonly name: string;
+    /** The property name in the schema; needed for clear error messages. */
+    readonly key: string;
+}
+export interface TableSpec {
+    readonly name: string;
+    readonly columns: readonly ResolvedColumn[];
+    readonly primaryKey: {
+        readonly name: string;
+        readonly columns: readonly string[];
+    } | undefined;
+    readonly uniques: readonly {
+        readonly name: string;
+        readonly columns: readonly string[];
+    }[];
+    readonly indexes: readonly {
+        readonly name: string;
+        readonly unique: boolean;
+        readonly columns: readonly string[];
+        readonly where: Sql | undefined;
+    }[];
+    readonly foreignKeys: readonly {
+        readonly name: string;
+        readonly columns: readonly string[];
+        readonly refTable: string;
+        readonly refColumns: readonly string[];
+        readonly onDelete: ReferentialAction | undefined;
+        readonly onUpdate: ReferentialAction | undefined;
+    }[];
+    readonly checks: readonly {
+        readonly name: string;
+        readonly expression: Sql;
+    }[];
+}
+export interface Table<TName extends string = string, TColumns extends Record<string, ResolvedColumnCfg> = Record<string, ResolvedColumnCfg>> {
+    readonly _: {
+        readonly name: TName;
+        readonly columns: TColumns;
+    };
+    readonly spec: TableSpec;
+}
+export type AnyTable = Table<string, Record<string, ResolvedColumnCfg>>;
+/** Column references for the callbacks in checks and partial indexes. */
+type Refs<TCols> = {
+    readonly [K in keyof TCols]: ColumnRef;
+};
+export interface Reference {
+    readonly table: AnyTable;
+    readonly columns: readonly string[];
+}
+export interface ForeignKeyDef<TCols> {
+    /** When not set, built as `{table}_{columns}_fk`. */
+    readonly name?: string;
+    readonly columns: readonly (keyof TCols & string)[];
+    readonly references: Reference;
+    readonly onDelete?: ReferentialAction;
+    readonly onUpdate?: ReferentialAction;
+}
+/**
+ * A reference to another table's columns.
+ *
+ * The target table comes first, so TypeScript infers it and checks the column
+ * names. A field inside `foreignKeys` cannot do that: the array element type is
+ * fixed, and there is nothing to infer from a neighbouring field.
+ *
+ * Checking element by element is still possible, via `const` inference of the
+ * whole array intersected with a mapped type, but measurements put it at six
+ * times the cost (175k instantiations vs 30k for 64 tables) for the same errors.
+ */
+export declare function ref<T extends AnyTable>(table: T, columns: readonly (keyof T['_']['columns'] & string)[]): Reference;
+export interface TableOptions<TName extends string, TCols extends Record<string, AnyColumn>> {
+    /** The table name in the database. Inferred as a literal; the Kysely interface keys come from it. */
+    readonly tableName: TName;
+    /**
+     * Columns are declared with a callback that receives the builder set:
+     *
+     * ```ts
+     * columns: t => ({ id: t.uuid().notNull(), status: t.enum(['new']) })
+     * ```
+     *
+     * Builders are not exported one by one: there is exactly one form, and the
+     * import list in the schema file does not need editing for every new column.
+     *
+     * Type inference is unaffected: TypeScript infers `TCols` from the callback's
+     * return type BEFORE it starts checking the rest of the literal, so `indexes`,
+     * `uniques`, `foreignKeys` and `checks` are typed as usual.
+     */
+    readonly columns: (t: ColumnBuilders) => TCols;
+    readonly primaryKey?: {
+        /** When not set, built as `{table}_pk`. */
+        readonly name?: string;
+        readonly columns: readonly (keyof TCols & string)[];
+    };
+    readonly uniques?: readonly {
+        /** When not set, built as `{table}_{columns}_uq`. */
+        readonly name?: string;
+        readonly columns: readonly (keyof TCols & string)[];
+    }[];
+    readonly indexes?: readonly {
+        /** When not set, built as `{table}_{columns}_idx`. */
+        readonly name?: string;
+        readonly unique?: boolean;
+        readonly columns: readonly (keyof TCols & string)[];
+        readonly where?: (c: Refs<TCols>) => Sql;
+    }[];
+    readonly foreignKeys?: readonly ForeignKeyDef<TCols>[];
+    readonly checks?: readonly {
+        /** When not set, built as `{table}_{expression columns}_check`. */
+        readonly name?: string;
+        readonly expression: (c: Refs<TCols>) => Sql;
+    }[];
+}
+export declare function defineTable<TName extends string, TCols extends Record<string, AnyColumn>>(options: TableOptions<TName, TCols>): Table<TName, ResolveColumns<TCols>>;
+export {};

package/dist/table/define.js

@@ -0,0 +1,198 @@
+/**
+ * `defineTable`, a hybrid: columns as chains, everything else as a declarative block.
+ *
+ * The key difference from drizzle rc5: **the column name stays a literal in the type**.
+ * When a name is not set explicitly, it is derived from the property name with the
+ * same snake_case that is applied at runtime, at the type level too (see `SnakeCase`).
+ * This is exactly what rc5 lacks, where `Column['_']['name']` collapses to `string`.
+ *
+ * Index and constraint names are optional as well, see `AUTO_NAMES`.
+ */
+import { toSnakeCase } from './casing.js';
+import { columnBuilders } from './columns.js';
+import { assertIdentifier, autoName } from './identifier.js';
+import { collectColumns, inArray } from './sql.js';
+/**
+ * Auto-name suffixes. The convention:
+ *
+ *   user_pk
+ *   ticket_number_uq
+ *   session_user_id_fk
+ *   ticket_status_check
+ *   user_resource_transaction_user_id_resource_idx
+ *
+ * The primary key is the only one named without columns: there is one per table.
+ */
+export const AUTO_NAMES = {
+    primaryKey: 'pk',
+    unique: 'uq',
+    foreignKey: 'fk',
+    check: 'check',
+    index: 'idx',
+};
+/**
+ * A reference to another table's columns.
+ *
+ * The target table comes first, so TypeScript infers it and checks the column
+ * names. A field inside `foreignKeys` cannot do that: the array element type is
+ * fixed, and there is nothing to infer from a neighbouring field.
+ *
+ * Checking element by element is still possible, via `const` inference of the
+ * whole array intersected with a mapped type, but measurements put it at six
+ * times the cost (175k instantiations vs 30k for 64 tables) for the same errors.
+ */
+export function ref(table, columns) {
+    return { table, columns };
+}
+// ── defineTable ──────────────────────────────────────────────────────────────
+export function defineTable(options) {
+    const name = options.tableName;
+    assertIdentifier(name, 'table');
+    const columns = [];
+    const dbName = {};
+    const refs = {};
+    for (const [key, builder] of Object.entries(options.columns(columnBuilders))) {
+        const resolved = builder.spec.name ?? toSnakeCase(key);
+        assertIdentifier(resolved, `${name}.${key}`);
+        if (builder.spec.enumValues !== undefined && builder.spec.array) {
+            throw new Error(`${name}.${key}: enum().array() is not supported yet: a check for an array ` +
+                'is written with `<@ ARRAY[...]`, add it by hand.');
+        }
+        columns.push({ ...builder.spec, name: resolved, key });
+        dbName[key] = resolved;
+        refs[key] = { kind: 'column', name: resolved };
+    }
+    const seenColumns = new Set();
+    for (const column of columns) {
+        if (seenColumns.has(column.name)) {
+            throw new Error(`${name}: column name "${column.name}" is used twice`);
+        }
+        seenColumns.add(column.name);
+    }
+    const toDb = (keys) => keys.map(key => {
+        const resolved = dbName[key];
+        if (resolved === undefined) {
+            throw new Error(`${name}: no column ${key}`);
+        }
+        return resolved;
+    });
+    /** An explicit name is checked against the limit; a missing one is built and shortened. */
+    const resolveName = (explicit, parts, suffix, what) => {
+        if (explicit !== undefined) {
+            assertIdentifier(explicit, `${name}: ${what}`);
+            return explicit;
+        }
+        return autoName([name, ...parts], suffix);
+    };
+    const typedRefs = refs;
+    // ── indexes ────────────────────────────────────────────────────────────────
+    const indexes = (options.indexes ?? []).map(index => {
+        const indexColumns = toDb(index.columns);
+        return {
+            name: resolveName(index.name, indexColumns, AUTO_NAMES.index, 'index'),
+            unique: index.unique ?? false,
+            columns: indexColumns,
+            where: index.where !== undefined ? index.where(typedRefs) : undefined,
+        };
+    });
+    // ── primary key ────────────────────────────────────────────────────────────
+    const primaryKey = options.primaryKey !== undefined
+        ? {
+            // the only one named without columns: there is one per table
+            name: resolveName(options.primaryKey.name, [], AUTO_NAMES.primaryKey, 'primary key'),
+            columns: toDb(options.primaryKey.columns),
+        }
+        : undefined;
+    // ── unique constraints ─────────────────────────────────────────────────────
+    const uniques = (options.uniques ?? []).map(unique => {
+        const uniqueColumns = toDb(unique.columns);
+        return {
+            name: resolveName(unique.name, uniqueColumns, AUTO_NAMES.unique, 'unique'),
+            columns: uniqueColumns,
+        };
+    });
+    // ── foreign keys ───────────────────────────────────────────────────────────
+    const foreignKeys = (options.foreignKeys ?? []).map(foreignKey => {
+        const fkColumns = toDb(foreignKey.columns);
+        return {
+            name: resolveName(foreignKey.name, fkColumns, AUTO_NAMES.foreignKey, 'foreign key'),
+            columns: fkColumns,
+            refTable: foreignKey.references.table.spec.name,
+            refColumns: foreignKey.references.columns.map(key => {
+                const target = foreignKey.references.table.spec.columns.find(c => c.key === key);
+                if (target === undefined) {
+                    throw new Error(`${name}: table ${foreignKey.references.table.spec.name} has no column ${key}`);
+                }
+                return target.name;
+            }),
+            onDelete: foreignKey.onDelete,
+            onUpdate: foreignKey.onUpdate,
+        };
+    });
+    // ── checks: automatic ones from enum() first, then the declared ones ───────
+    const checks = [];
+    for (const column of columns) {
+        if (column.enumValues === undefined) {
+            continue;
+        }
+        checks.push({
+            name: autoName([name, column.name], AUTO_NAMES.check),
+            expression: inArray({ kind: 'column', name: column.name }, column.enumValues),
+        });
+    }
+    for (const check of options.checks ?? []) {
+        const expression = check.expression(typedRefs);
+        const referenced = collectColumns(expression);
+        if (check.name === undefined && referenced.length === 0) {
+            throw new Error(`${name}: a check without a name must reference at least one column, ` +
+                'otherwise there is nothing to build the name from. Set the name explicitly.');
+        }
+        checks.push({
+            name: resolveName(check.name, referenced, AUTO_NAMES.check, 'check'),
+            expression,
+        });
+    }
+    // ── name uniqueness ────────────────────────────────────────────────────────
+    // Constraint names are unique within a table, index names within the schema.
+    // The overlap is checked only where it really conflicts: PRIMARY KEY and
+    // UNIQUE create an index under their own name.
+    const constraintNames = new Map();
+    const claim = (kind, constraintName) => {
+        const owner = constraintNames.get(constraintName);
+        if (owner !== undefined) {
+            const who = owner === kind ? `twice as ${kind}` : `as ${owner} and as ${kind}`;
+            throw new Error(`${name}: name "${constraintName}" is taken twice, ${who}. ` +
+                'Auto-names are built from the table and columns, so two objects on the same ' +
+                'columns collide: set an explicit name for at least one of them.');
+        }
+        constraintNames.set(constraintName, kind);
+    };
+    if (primaryKey !== undefined) {
+        claim('primary key', primaryKey.name);
+    }
+    for (const unique of uniques) {
+        claim('unique', unique.name);
+    }
+    for (const foreignKey of foreignKeys) {
+        claim('foreign key', foreignKey.name);
+    }
+    for (const check of checks) {
+        claim('check', check.name);
+    }
+    const indexNames = new Set();
+    for (const index of indexes) {
+        if (indexNames.has(index.name)) {
+            throw new Error(`${name}: index name "${index.name}" is used twice. ` +
+                'Two indexes on the same columns get the same auto-name: set an explicit name.');
+        }
+        // PRIMARY KEY and UNIQUE create an index under their own name, so this would conflict
+        const owner = constraintNames.get(index.name);
+        if (owner === 'primary key' || owner === 'unique') {
+            throw new Error(`${name}: index "${index.name}" has the same name as the ${owner}, ` +
+                'which already creates an index with that name.');
+        }
+        indexNames.add(index.name);
+    }
+    const spec = { name, columns, primaryKey, uniques, indexes, foreignKeys, checks };
+    return { _: { name, columns: {} }, spec };
+}