turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/schema-builder.js

@@ -25,10 +25,16 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.camelToSnake = exports.column = exports.ColumnBuilder = void 0;
+exports.tsTypeTextProblem = tsTypeTextProblem;
 exports.isDocFieldIndexDef = isDocFieldIndexDef;
 exports.defineSchema = defineSchema;
 exports.table = table;
 exports.applyManyToManyRelations = applyManyToManyRelations;
+// Type-only import, erased at runtime, so it cannot introduce a circular
+// runtime dependency (the local `camelToSnakeLocal` copy avoids that for the
+// value-level helper).
+const errors_js_1 = require("./errors.js");
+const utils_js_1 = require("./query/utils.js");
 /** Maps shorthand names to actual Postgres type strings */
 const TYPE_MAP = {
     // `serial` maps to SERIAL (int4). Its values fit in a JS `number` and pg
@@ -63,16 +69,42 @@ const TYPE_MAP = {
     enum: 'ENUM',
     vector: 'VECTOR',
 };
+/** What a value is, for a message: `an array`, `null`, `a string`. */
+function describeKind(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return typeof value === 'object' ? 'an object' : `a ${typeof value}`;
+}
+/**
+ * A declared DEFAULT as the SQL text the DDL generators take. A string is raw
+ * SQL, kept as written. A finite number or a boolean is the literal it is,
+ * where it used to reach the generator as a non-string and crash it with a
+ * TypeError. `undefined` and `null` mean no default.
+ */
+function declaredDefault(value, where) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if ((typeof value === 'number' && Number.isFinite(value)) || typeof value === 'bigint')
+        return String(value);
+    throw new errors_js_1.ValidationError(`Invalid default for ${where}: received ${describeKind(value)}${typeof value === 'number' ? ` (${value})` : ''}. ` +
+        `Write it as a string of raw SQL such as 'now()' or "'active'", or as a finite number or a boolean.`);
+}
 /** Convert a user-facing ColumnDef to the internal ColumnConfig */
-function resolveColumn(def) {
-    if (!(def.type in TYPE_MAP)) {
-        throw new Error(`Invalid column type "${def.type}". Valid types: ${Object.keys(TYPE_MAP).join(', ')}`);
+function resolveColumn(def, where = 'a column') {
+    if (!Object.hasOwn(TYPE_MAP, def.type)) {
+        throw new errors_js_1.ValidationError(`Invalid column type "${def.type}". Valid types: ${Object.keys(TYPE_MAP).join(', ')}`);
     }
     if (def.type === 'enum' && !def.enumName) {
-        throw new Error(`Column of type "enum" requires an "enumName" (the CREATE TYPE name).`);
+        throw new errors_js_1.ValidationError(`Column of type "enum" requires an "enumName" (the CREATE TYPE name).`);
     }
     if (def.type === 'vector' && (def.dimensions == null || def.dimensions <= 0)) {
-        throw new Error(`Column of type "vector" requires a positive "dimensions" count.`);
+        throw new errors_js_1.ValidationError(`Column of type "vector" requires a positive "dimensions" count.`);
     }
     // `references` is either the "table.column" string or a { target, onDelete, onUpdate } object.
     let referencesTarget = null;
@@ -81,7 +113,11 @@ function resolveColumn(def) {
     if (typeof def.references === 'string') {
         referencesTarget = def.references;
     }
-    else if (def.references) {
+    else if (def.references !== undefined && def.references !== null) {
+        if (typeof def.references !== 'object' || typeof def.references.target !== 'string') {
+            throw new errors_js_1.ValidationError(`defineSchema: ${where} has a "references" that is neither a "table.column" string nor ` +
+                `{ target: "table.column", onDelete?, onUpdate? }.`);
+        }
         referencesTarget = def.references.target;
         onDelete = def.references.onDelete ?? null;
         onUpdate = def.references.onUpdate ?? null;
@@ -92,7 +128,7 @@ function resolveColumn(def) {
         isNotNull: def.notNull ?? false,
         isNullable: def.nullable ?? false,
         isUnique: def.unique ?? false,
-        defaultValue: def.default ?? null,
+        defaultValue: declaredDefault(def.default, where),
         referencesTarget,
         maxLength: def.maxLength ?? null,
         onDelete,
@@ -103,15 +139,306 @@ function resolveColumn(def) {
         check: def.check ?? null,
         pii: def.pii ?? false,
         updatedAt: def.updatedAt ?? false,
+        tsType: checkedTsType(def.tsType),
     };
 }
+/** Characters a declared type may not contain (the generator refuses the same set). */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: refusing control characters is this pattern's purpose
+const UNSAFE_TS_TYPE_TEXT = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+/** Characters a type expression uses outside a string literal and a bracket. */
+const TS_TYPE_CHAR = /^[\p{L}\p{N}_$.:?|&!+\-= \t]$/u;
+const TS_TYPE_CLOSER = { '(': ')', '[': ']', '{': '}', '<': '>' };
+/**
+ * Why `text` cannot be written into a generated file as a TypeScript type, or
+ * null when it can. The text lands verbatim as a member type or an alias body,
+ * so what has to hold is that it stays ONE type: brackets balance, nothing at
+ * the top level ends the member (`;` or `,`), and it holds no comment, template
+ * literal or character a type does not use. A `//` would swallow the rest of the
+ * line and a stray `}` would close the interface and start a statement.
+ *
+ * It does not check that the type is well formed or that its names exist; the
+ * compiler of the generated file does that.
+ */
+function tsTypeTextProblem(text) {
+    if (text.trim() === '')
+        return 'it is empty';
+    if (UNSAFE_TS_TYPE_TEXT.test(text))
+        return 'it contains a control or line-separator character';
+    const chars = Array.from(text);
+    const open = [];
+    for (let i = 0; i < chars.length; i++) {
+        const c = chars[i];
+        if (c === "'" || c === '"') {
+            let end = i + 1;
+            while (end < chars.length && chars[end] !== c)
+                end += chars[end] === '\\' ? 2 : 1;
+            if (end >= chars.length)
+                return `a ${c} string literal is not closed`;
+            if (chars.slice(i, end).join('').includes('*/'))
+                return 'a string literal contains "*/"';
+            i = end;
+        }
+        else if (c === '=' && chars[i + 1] === '>') {
+            i++;
+        }
+        else if (TS_TYPE_CLOSER[c] !== undefined) {
+            open.push(TS_TYPE_CLOSER[c]);
+        }
+        else if (c === ')' || c === ']' || c === '}' || c === '>') {
+            if (open.pop() !== c)
+                return `"${c}" closes a bracket that was never opened`;
+        }
+        else if (c === ';' || c === ',') {
+            if (open.length === 0)
+                return `"${c}" outside any brackets would end the type`;
+        }
+        else if (c === '`') {
+            return 'a template literal type is not supported here, name it with a type alias and use import()';
+        }
+        else if (!TS_TYPE_CHAR.test(c)) {
+            return `"${c}" cannot appear in a type${c === '/' ? ' (no comments)' : ''}`;
+        }
+    }
+    return open.length > 0 ? 'a bracket is not closed' : null;
+}
+/**
+ * A `tsType` is emitted verbatim into generated source, so it must be one type
+ * on one line (see {@link tsTypeTextProblem}).
+ */
+function checkedTsType(tsType) {
+    if (tsType === undefined)
+        return null;
+    const problem = typeof tsType === 'string' ? tsTypeTextProblem(tsType) : 'it is not a string';
+    if (problem !== null) {
+        throw new errors_js_1.ValidationError(`Invalid column "tsType" ${JSON.stringify(tsType)}: ${problem}. ` +
+            `Give one TypeScript type on one line, for example '{ theme: string }' or "import('../src/types.js').Settings".`);
+    }
+    return tsType;
+}
 /** Type guard: is this index declaration a doc-field expression index? */
 function isDocFieldIndexDef(idx) {
     return 'docField' in idx && typeof idx.docField === 'string';
 }
-/** Check if a value is a TableDef (from legacy table() builder) */
+// ---------------------------------------------------------------------------
+// Known keys: one table per declaration shape
+// ---------------------------------------------------------------------------
+//
+// A schema is static code, and a key `defineSchema` does not know is not
+// harmless: it is an option the caller meant and did not get (`defaultValue`
+// for `default` emits a column with no DEFAULT, `uniq` for `unique` a
+// non-unique index). So an unknown key is refused, at compile time in a
+// literal and at runtime for JSON or plain JS.
+//
+// Each table is a `Record<keyof Shape, true>`: adding an option to the shape
+// without listing it here fails the build, and listing a key the shape does
+// not have fails as an excess property. The compile-time check types below
+// and the runtime refusal both read these, so they cannot disagree.
+const COLUMN_KEYS = {
+    type: true,
+    primaryKey: true,
+    notNull: true,
+    nullable: true,
+    unique: true,
+    default: true,
+    references: true,
+    maxLength: true,
+    enumName: true,
+    dimensions: true,
+    array: true,
+    check: true,
+    pii: true,
+    updatedAt: true,
+    tsType: true,
+};
+const REFERENCE_KEYS = { target: true, onDelete: true, onUpdate: true };
+const CHECK_KEYS = { name: true, expression: true };
+const MANY_TO_MANY_KEYS = {
+    name: true,
+    target: true,
+    through: true,
+    sourceKey: true,
+    targetKey: true,
+    references: true,
+};
+const INDEX_KEYS = {
+    columns: true,
+    docField: true,
+    path: true,
+    unique: true,
+    name: true,
+};
+const TABLE_OPTION_KEYS = {
+    primaryKey: true,
+    manyToMany: true,
+    checks: true,
+    indexes: true,
+};
+const SCHEMA_OPTION_KEYS = { enums: true };
+/**
+ * Refuse every key of `value` that `known` does not list (E003), naming where
+ * it sits and the key it most likely meant.
+ */
+function assertKnownKeys(value, known, where) {
+    for (const key of Object.keys(value)) {
+        if (Object.hasOwn(known, key))
+            continue;
+        // suggestKey covers typos and the metadata spellings (`defaultValue`,
+        // `isUnique`) alike: the second pass matches a key that adds words.
+        const suggestion = (0, utils_js_1.suggestKey)(key, Object.keys(known));
+        throw new errors_js_1.ValidationError(`defineSchema: unknown key "${key}" in ${where}.` +
+            (suggestion ? ` Did you mean "${suggestion}"?` : '') +
+            ` Valid keys: ${Object.keys(known).join(', ')}.`);
+    }
+}
+/** Each element of an option array, checked as `what` (non-objects are left to the consumer's own checks). */
+function assertKnownElementKeys(list, known, where) {
+    list.forEach((item, i) => {
+        if (typeof item === 'object' && item !== null)
+            assertKnownKeys(item, known, `${where}[${i}]`);
+    });
+}
+/**
+ * Refuse `__proto__` as a table or column name. `JSON.parse` can produce it as
+ * an own key, but assigning to it on a record sets the record's prototype
+ * instead of adding a key, so the column would vanish without a word.
+ */
+function assertOrdinaryName(name, what) {
+    if (name === '__proto__') {
+        throw new errors_js_1.ValidationError(`defineSchema: ${what} is named "__proto__", which JavaScript treats as the prototype setter rather than a ` +
+            `property name, so it could not be stored or queried. Rename it.`);
+    }
+}
+/**
+ * An index is either a column index (`columns`) or a document-field index
+ * (`docField` and `path`), never both. A declaration carrying both was taken
+ * for the document-field kind, which only PowDB creates, so the SQL engines
+ * skipped it without saying so.
+ */
+function assertIndexKinds(list, accessor) {
+    list.forEach((item, i) => {
+        if (typeof item === 'object' && item !== null && 'columns' in item && 'docField' in item) {
+            throw new errors_js_1.ValidationError(`defineSchema: index ${i} of table "${accessor}" declares both "columns" and "docField". ` +
+                `Use "columns" for a column index, or "docField" with "path" for an index into a json document. ` +
+                `Declare two indexes if you need both.`);
+        }
+    });
+}
+/**
+ * Is this value a TableDef (the legacy `table()` builder's output)?
+ *
+ * A TableDef carries a STRING `name` and a `columns` record of column configs.
+ * In the object format a key called `name` or `columns` is a column, and a
+ * column definition is an object, so the string is what tells the two apart: a
+ * table with columns named `name` and `columns` used to be read as a TableDef
+ * and emitted as a different table. A table that has a string `name` but is not
+ * a TableDef falls through to the object format, which refuses the string.
+ */
 function isTableDef(v) {
-    return typeof v === 'object' && v !== null && 'columns' in v && 'name' in v;
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return false;
+    const t = v;
+    if (typeof t.name !== 'string')
+        return false;
+    const columns = t.columns;
+    if (typeof columns !== 'object' || columns === null || Array.isArray(columns))
+        return false;
+    return Object.values(columns).every((c) => typeof c === 'object' && c !== null);
+}
+/** A name list for a message: `a, b, c`, or `(none)`. */
+function nameList(names) {
+    const list = [...names];
+    return list.length > 0 ? list.join(', ') : '(none)';
+}
+/** The DDL column name of a field: what `CREATE TABLE` and every index write for it. */
+const ddlColumnName = camelToSnakeLocal;
+/**
+ * Refuse a schema that names something it does not contain. Every one of these
+ * used to be accepted and then went wrong somewhere else, or nowhere:
+ *
+ * - `userId` and `user_id` in one table are the SAME column to the database, so
+ *   the DDL declared it twice.
+ * - A `references` that is not `table.column` was dropped (no foreign key, no
+ *   error), and one naming a column its target table does not have became a
+ *   `REFERENCES` clause the database rejects at push time. A target table that
+ *   is not in this schema is left alone, since it may be owned elsewhere.
+ * - An index on a column the table does not have failed the same way.
+ *
+ * It runs once, after every table is built, because a reference may name a
+ * table declared later.
+ */
+function assertSchemaIntegrity(tables) {
+    const byDdlName = new Map();
+    const byName = new Map();
+    for (const [accessor, table] of Object.entries(tables)) {
+        const owner = byDdlName.get(table.name);
+        if (owner !== undefined) {
+            throw new errors_js_1.ValidationError(`defineSchema: tables "${owner}" and "${accessor}" are both the table "${table.name}" in the database ` +
+                `(a camelCase name is written in snake_case). Keep one, or rename one.`);
+        }
+        byDdlName.set(table.name, accessor);
+        byName.set(accessor, table);
+        byName.set(table.name, table);
+    }
+    for (const [accessor, table] of Object.entries(tables)) {
+        const columnOf = new Map();
+        for (const field of Object.keys(table.columns)) {
+            const ddl = ddlColumnName(field);
+            const other = columnOf.get(ddl);
+            if (other !== undefined) {
+                throw new errors_js_1.ValidationError(`defineSchema: table "${accessor}" has columns "${other}" and "${field}", which are the same column ` +
+                    `"${ddl}" in the database. Keep one.`);
+            }
+            columnOf.set(ddl, field);
+        }
+        const hasColumn = (name) => Object.hasOwn(table.columns, name) || columnOf.has(name);
+        const columnNames = () => Object.keys(table.columns);
+        for (const [i, idx] of (table.indexes ?? []).entries()) {
+            if (!isDocFieldIndexDef(idx) && !Array.isArray(idx.columns)) {
+                throw new errors_js_1.ValidationError(`defineSchema: index ${i} of table "${accessor}" declares neither "columns" (an array of column names) ` +
+                    `nor "docField" with "path".`);
+            }
+            const named = isDocFieldIndexDef(idx) ? [idx.docField] : idx.columns;
+            for (const name of named) {
+                if (typeof name === 'string' && hasColumn(name))
+                    continue;
+                const suggestion = typeof name === 'string' ? (0, utils_js_1.suggestKey)(name, columnNames()) : null;
+                throw new errors_js_1.ValidationError(`defineSchema: index ${i} of table "${accessor}" names ${typeof name === 'string' ? `column "${name}"` : `a ${describeKind(name)} instead of a column name`}, ` +
+                    `which the table does not have.${suggestion ? ` Did you mean "${suggestion}"?` : ''} ` +
+                    `Columns: ${nameList(columnNames())}.`);
+            }
+        }
+        for (const [field, config] of Object.entries(table.columns)) {
+            if (config.referencesTarget === null || config.referencesTarget === undefined)
+                continue;
+            const where = `column "${accessor}.${field}"`;
+            const target = config.referencesTarget;
+            const parts = typeof target === 'string' ? target.split('.') : [];
+            if (parts.length !== 2 || !parts[0] || !parts[1]) {
+                throw new errors_js_1.ValidationError(`defineSchema: ${where} has references ${JSON.stringify(target)}, which is not in "table.column" form, so no foreign ` +
+                    `key would be created. Write it as "users.id".` +
+                    (parts.length > 2 ? ' A schema-qualified name ("auth.users.id") is not supported.' : ''));
+            }
+            const [refTable, refColumn] = parts;
+            // A table outside this schema is allowed, since something else may own
+            // it. Its columns cannot be checked here.
+            const targetTable = byName.get(refTable);
+            if (!targetTable)
+                continue;
+            const targetDdl = new Set(Object.keys(targetTable.columns).map(ddlColumnName));
+            const isField = Object.hasOwn(targetTable.columns, refColumn);
+            if (!isField && !targetDdl.has(refColumn)) {
+                const suggestion = (0, utils_js_1.suggestKey)(refColumn, Object.keys(targetTable.columns));
+                throw new errors_js_1.ValidationError(`defineSchema: ${where} references "${target}", but table "${refTable}" has no column "${refColumn}".` +
+                    (suggestion ? ` Did you mean "${suggestion}"?` : '') +
+                    ` Columns: ${nameList(Object.keys(targetTable.columns))}.`);
+            }
+            // The DDL names the column as written, so a field name (`displayName`)
+            // becomes the column it is (`display_name`) here, where the table is known.
+            if (isField && ddlColumnName(refColumn) !== refColumn) {
+                config.referencesTarget = `${refTable}.${ddlColumnName(refColumn)}`;
+            }
+        }
+    }
 }
 /**
  * Define the full database schema using plain objects.
@@ -134,7 +461,10 @@ function isTableDef(v) {
  */
 function defineSchema(input, options) {
     const tables = {};
+    if (options !== undefined)
+        assertKnownKeys(options, SCHEMA_OPTION_KEYS, 'the defineSchema options');
     for (const [accessor, value] of Object.entries(input)) {
+        assertOrdinaryName(accessor, `table "${accessor}"`);
         // The user-facing key is the camelCase JS accessor; the DDL-facing
         // table name is its snake_case form (e.g. `postTags` → `post_tags`).
         const dbName = camelToSnakeLocal(accessor);
@@ -157,8 +487,10 @@ function defineSchema(input, options) {
                 if (fieldName === 'indexes') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
-                            throw new Error(`Table "${accessor}": "indexes" must be an array of index declarations`);
+                            throw new errors_js_1.ValidationError(`Table "${accessor}": "indexes" must be an array of index declarations`);
                         }
+                        assertKnownElementKeys(def, INDEX_KEYS, `table "${accessor}" indexes`);
+                        assertIndexKinds(def, accessor);
                         indexes = def;
                     }
                     continue;
@@ -166,8 +498,9 @@ function defineSchema(input, options) {
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
-                            throw new Error(`Table "${accessor}": "manyToMany" must be an array of relation declarations`);
+                            throw new errors_js_1.ValidationError(`Table "${accessor}": "manyToMany" must be an array of relation declarations`);
                         }
+                        assertKnownElementKeys(def, MANY_TO_MANY_KEYS, `table "${accessor}" manyToMany`);
                         m2m = def;
                     }
                     continue;
@@ -175,8 +508,9 @@ function defineSchema(input, options) {
                 if (fieldName === 'checks') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
-                            throw new Error(`Table "${accessor}": "checks" must be an array of { name?, expression } objects`);
+                            throw new errors_js_1.ValidationError(`Table "${accessor}": "checks" must be an array of { name?, expression } objects`);
                         }
+                        assertKnownElementKeys(def, CHECK_KEYS, `table "${accessor}" checks`);
                         checks = def;
                     }
                     continue;
@@ -185,14 +519,35 @@ function defineSchema(input, options) {
                     // Top-level composite primary key declaration
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
-                            throw new Error(`Table "${accessor}": top-level "primaryKey" must be an array of column names (string[])`);
+                            throw new errors_js_1.ValidationError(`Table "${accessor}": top-level "primaryKey" must be an array of column names (string[])`);
                         }
                         pk = def;
                     }
                     continue;
                 }
-                // Anything else is a ColumnDef
-                columns[fieldName] = resolveColumn(def);
+                // Anything else is a ColumnDef. An array here is a table option under a
+                // name defineSchema does not know (`primarykey`, `index`): refuse it by
+                // that name rather than as a column with no type.
+                if (Array.isArray(def)) {
+                    const suggestion = (0, utils_js_1.suggestKey)(fieldName, Object.keys(TABLE_OPTION_KEYS));
+                    throw new errors_js_1.ValidationError(`defineSchema: table "${accessor}" has an array under "${fieldName}", which is not a table option ` +
+                        `(${Object.keys(TABLE_OPTION_KEYS).join(', ')}) and cannot be a column.` +
+                        (suggestion ? ` Did you mean "${suggestion}"?` : ''));
+                }
+                assertOrdinaryName(fieldName, `column "${accessor}.${fieldName}"`);
+                // An `undefined` column is absent, like an `undefined` option anywhere else.
+                if (def === undefined)
+                    continue;
+                if (typeof def !== 'object' || def === null) {
+                    throw new errors_js_1.ValidationError(`defineSchema: column "${accessor}.${fieldName}" must be an object such as { type: 'text' }, ` +
+                        `received ${describeKind(def)}.`);
+                }
+                assertKnownKeys(def, COLUMN_KEYS, `column "${accessor}.${fieldName}"`);
+                const ref = def.references;
+                if (typeof ref === 'object' && ref !== null) {
+                    assertKnownKeys(ref, REFERENCE_KEYS, `the references of column "${accessor}.${fieldName}"`);
+                }
+                columns[fieldName] = resolveColumn(def, `column "${accessor}.${fieldName}"`);
             }
             // Validate composite PK references real columns and clear column-level PKs
             // for those columns so we don't double-emit `PRIMARY KEY` clauses.
@@ -201,7 +556,7 @@ function defineSchema(input, options) {
             if (pk && pk.length > 0) {
                 for (const colName of pk) {
                     if (!(colName in columns)) {
-                        throw new Error(`Table "${accessor}": composite primaryKey references unknown column "${colName}". ` +
+                        throw new errors_js_1.ValidationError(`Table "${accessor}": composite primaryKey references unknown column "${colName}". ` +
                             `Known columns: ${Object.keys(columns).join(', ') || '(none)'}`);
                     }
                     // A composite PK at the table level supersedes any column-level
@@ -226,6 +581,7 @@ function defineSchema(input, options) {
             };
         }
     }
+    assertSchemaIntegrity(tables);
     return { tables, ...(options?.enums ? { enums: options.enums } : {}) };
 }
 /**
@@ -258,6 +614,7 @@ class ColumnBuilder {
             check: null,
             pii: false,
             updatedAt: false,
+            tsType: null,
         };
     }
     serial() {
@@ -351,10 +708,12 @@ class ColumnBuilder {
         return this;
     }
     default(val) {
-        this._config.defaultValue = val;
+        this._config.defaultValue = declaredDefault(val, 'ColumnBuilder.default()');
         return this;
     }
     references(target, opts) {
+        if (opts !== undefined)
+            assertKnownKeys(opts, { onDelete: true, onUpdate: true }, `references("${target}") options`);
         this._config.referencesTarget = target;
         this._config.onDelete = opts?.onDelete ?? null;
         this._config.onUpdate = opts?.onUpdate ?? null;
@@ -373,6 +732,11 @@ class ColumnBuilder {
         this._config.updatedAt = true;
         return this;
     }
+    /** The TypeScript type `turbine generate` emits for this column. See {@link ColumnDef.tsType}. */
+    tsType(type) {
+        this._config.tsType = checkedTsType(type);
+        return this;
+    }
     array() {
         this._config.isArray = true;
         return this;
@@ -414,7 +778,7 @@ exports.column = new Proxy({}, {
             };
         }
         return () => {
-            throw new Error(`Unknown column type: ${prop}`);
+            throw new errors_js_1.ValidationError(`Unknown column type: ${prop}`);
         };
     },
 });

package/dist/cjs/schema-metadata.d.ts

@@ -45,7 +45,27 @@
  * ```
  */
 import { type SchemaMetadata } from './schema.js';
-import { type SchemaDef } from './schema-builder.js';
+import { type ColumnConfig, type SchemaDef } from './schema-builder.js';
+/** The code-first-only flags a column can declare. */
+export interface CodeFirstColumnTags {
+    pii?: true;
+    updatedAt?: true;
+    maxLength?: number;
+    /**
+     * The declared TypeScript type, WITHOUT nullability. On metadata built by
+     * {@link schemaDefToMetadata} it is the column's `declaredTsType`, never its
+     * `tsType`; `turbine generate` passes it to the generator as a `columnTypes`
+     * entry.
+     */
+    tsType?: string;
+}
+/**
+ * The tags a column declares, as the fields they take on {@link ColumnMetadata}.
+ * The one place the tag set is listed, so `schemaDefToMetadata` and the CLI's
+ * overlay of these tags onto an introspected schema (`cli/code-first-tags.ts`)
+ * cannot disagree about what counts as one.
+ */
+export declare function declaredTagsOf(config: ColumnConfig): CodeFirstColumnTags;
 /**
  * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
  *

package/dist/cjs/schema-metadata.js

@@ -46,6 +46,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.declaredTagsOf = declaredTagsOf;
 exports.schemaDefToMetadata = schemaDefToMetadata;
 const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
@@ -160,6 +161,20 @@ function mapIndexes(tableDef, declared) {
     }
     return out;
 }
+/**
+ * The tags a column declares, as the fields they take on {@link ColumnMetadata}.
+ * The one place the tag set is listed, so `schemaDefToMetadata` and the CLI's
+ * overlay of these tags onto an introspected schema (`cli/code-first-tags.ts`)
+ * cannot disagree about what counts as one.
+ */
+function declaredTagsOf(config) {
+    return {
+        ...(config.pii ? { pii: true } : {}),
+        ...(config.updatedAt ? { updatedAt: true } : {}),
+        ...(config.maxLength != null ? { maxLength: config.maxLength } : {}),
+        ...(config.tsType != null ? { tsType: config.tsType } : {}),
+    };
+}
 // ---------------------------------------------------------------------------
 // The converter
 // ---------------------------------------------------------------------------
@@ -328,23 +343,30 @@ function schemaDefToMetadata(def) {
             const serial = isSerialType(config.type);
             // PK members and serials are NOT NULL in Postgres regardless of flags.
             const nullable = !(config.isPrimaryKey || config.isNotNull || serial);
+            const { tsType: declaredTsType, ...declaredTags } = declaredTagsOf(config);
             const col = {
                 name,
                 field,
                 dialectType: wireType,
                 pgType: wireType,
-                tsType: (0, schema_js_1.pgTypeToTs)(wireType, nullable),
                 nullable,
                 hasDefault: config.defaultValue != null || serial,
+                // The expression itself, as written in the schema (`now()`, `'draft'`).
+                // Engines with no column defaults (PowDB) apply it client-side on
+                // create, which they cannot do from `hasDefault` alone.
+                ...(config.defaultValue != null ? { defaultValue: config.defaultValue } : {}),
                 isArray: config.isArray,
                 arrayType: (0, schema_js_1.pgArrayType)(base),
                 pgArrayType: (0, schema_js_1.pgArrayType)(base),
                 ...(serial ? { isGenerated: true } : {}),
-                // PII is a code-first declaration; carry it through so query-layer
-                // default-projection exclusion and Studio redaction can honor it.
-                // Only set when true, keeping output byte-stable for untagged schemas.
-                ...(config.pii ? { pii: true } : {}),
-                ...(config.maxLength != null ? { maxLength: config.maxLength } : {}),
+                // PII, updatedAt and maxLength are code-first declarations; carry them
+                // through so query-layer projection, the updatedAt stamp and Studio
+                // redaction can honor them. Only set when declared, keeping output
+                // byte-stable for untagged schemas.
+                ...declaredTags,
+                // Always the mapped type. A declared `tsType` rides along separately.
+                tsType: (0, schema_js_1.pgTypeToTs)(wireType, nullable),
+                ...(declaredTsType !== undefined ? { declaredTsType } : {}),
             };
             columns.push(col);
             columnMap[field] = name;
@@ -373,7 +395,7 @@ function schemaDefToMetadata(def) {
             allColumns,
             primaryKey: pk,
             uniqueColumns,
-            relations: relationsByTable.get(tableDef.name) ?? {},
+            relations: { ...relationsByTable.get(tableDef.name) },
             // Declared `indexes` (plain column + doc-field expression) carry through;
             // an undeclared table gets `[]`, which keeps schemaHasIndexInfo() false so
             // the index advisor stays silent. Doc-field (docPath) indexes are ignored