uql-orm 0.45.0 → 0.46.0

package/README.md

@@ -53,7 +53,7 @@ The query is just JSON: build it dynamically, store it, diff it, or send it from
 - **One API, everywhere it runs.** PostgreSQL, PGlite, CockroachDB, MySQL, MariaDB, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB. The same code on Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser), with no native binaries on the `fetch`-based drivers.
 - **Relations without N+1.** [`$populate`](https://uql-orm.dev/querying/relations) loads a to-many with one query for all parents, not one per parent. Nothing is lazy, so nothing fires behind your back in a serializer.
 - **Migrations you read before they run.** Edit an entity, run `uql-migrate generate:entities`, review the SQL in the PR like any other file. [`drift:check`](https://uql-orm.dev/migrations) catches a database that no longer matches.
-- **Raw SQL when you want it.** [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere in a query, [virtual fields](https://uql-orm.dev/entities/virtual-fields) are sub-queries you can filter on, and a migration can be plain SQL.
+- **Raw SQL when you want it.** [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere in a query, [computed fields](https://uql-orm.dev/entities/computed-fields) are expressions you can filter on, and a migration can be plain SQL.
 - **Light.** Zero runtime dependencies, under 280 kB on the wire, every dialect included. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
 - **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [multi-tenant filters you cannot bypass by accident](https://uql-orm.dev/multi-tenancy), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/http).
 - **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), by 2.6-3x over the next closest and roughly 10x over the slowest, on Bun, Node and Deno alike. The same benchmark [scores the types](https://github.com/rogerpadilla/ts-orm-benchmark#type-safety) by writing ten ordinary mistakes in six ORMs' APIs and compiling them: UQL is the only one that catches all ten.

package/dist/dialect/abstractSqlDialect.d.ts

@@ -171,6 +171,13 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * `NOT (... <=> ...)` - instead of having to fall back to a form that takes none.
      */
     protected resolveOperandField<E>(ctx: QueryContext, entity: Type<E>, key: string, opts: QueryOptions): string;
+    /**
+     * The expression an inlined computed field stands for, or nothing when the field is a real column.
+     *
+     * Every clause that names such a field needs the expression itself, never the output alias: an
+     * alias exists only when the field was also selected, which `$where` and `$sort` cannot assume.
+     */
+    private inlinedOperand;
     compareFieldOperator<E, K extends keyof QueryWhereFieldOperatorMap<E>>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, op: K, val: QueryWhereFieldOperatorMap<E>[K], opts?: QueryOptions): void;
     /**
      * `<operand> <op> <value>` for every operator that needs nothing but its left-hand SQL, or
@@ -261,8 +268,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private collectSortTerms;
     /**
-     * The `ORDER BY` operand for one key. A key that is not a column of `meta` - a virtual field, a
-     * `raw()` projection - is an output alias, which is never table-qualified and needs no resolving.
+     * The `ORDER BY` operand for one key. A key that is not a field of `meta` - a `raw()` projection, a
+     * `$agg` alias - is an output alias, which is never table-qualified and needs no resolving.
      */
     private sortColumn;
     pager(ctx: QueryContext, opts: QueryPager): void;

package/dist/dialect/abstractSqlDialect.js

@@ -1,5 +1,6 @@
 import { getMeta, soleIdOf } from '../entity/index.js';
 import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, VECTOR_QUERY_KEYS, } from '../type/index.js';
+import { computedExpression, isInlinedExpression } from '../util/field.util.js';
 import { asSelectMap, assertNonNegativeInteger, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, columnFamily, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationSize, parseSortByCount, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { COUNT_ALIAS, DISTINCT_DERIVED_ALIAS, JSON_ELEM_ALIAS_PREFIX } from './aliases.js';
@@ -160,9 +161,9 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 const field = meta.fields[key];
                 if (!field)
                     return;
-                if (field.virtual) {
+                if (isInlinedExpression(field)) {
                     this.getRawValue(ctx, {
-                        value: field.virtual.as(key),
+                        value: computedExpression(field).as(key),
                         prefix: opts.prefix,
                         escapedPrefix,
                         autoPrefixAlias: opts.autoPrefixAlias,
@@ -485,15 +486,23 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      */
     resolveOperandField(ctx, entity, key, opts) {
         const field = getMeta(entity).fields[key];
-        const virtual = field?.virtual;
-        if (virtual) {
-            return this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, {
-                value: virtual,
-                prefix: opts.prefix,
-                escapedPrefix: this.escapeId(opts.prefix, true, true),
-            }));
-        }
-        return this.columnWithPrefix(key, field, opts.prefix);
+        return this.inlinedOperand(ctx, field, opts.prefix) ?? this.columnWithPrefix(key, field, opts.prefix);
+    }
+    /**
+     * The expression an inlined computed field stands for, or nothing when the field is a real column.
+     *
+     * Every clause that names such a field needs the expression itself, never the output alias: an
+     * alias exists only when the field was also selected, which `$where` and `$sort` cannot assume.
+     */
+    inlinedOperand(ctx, field, prefix) {
+        const inlined = field && isInlinedExpression(field) ? computedExpression(field) : undefined;
+        return inlined
+            ? this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, {
+                value: inlined,
+                prefix,
+                escapedPrefix: this.escapeId(prefix, true, true),
+            }))
+            : undefined;
     }
     compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
         const field = this.resolveOperandField(ctx, entity, key, opts);
@@ -767,17 +776,17 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                     : this.buildFragment(ctx, (fragmentCtx) => this.appendVectorSort(fragmentCtx, meta, key, value)));
                 continue;
             }
-            columns.push(this.sortColumn(meta, key, prefix) + this.resolveSortDirection(value));
+            columns.push(this.sortColumn(ctx, meta, key, prefix) + this.resolveSortDirection(value));
         }
     }
     /**
-     * The `ORDER BY` operand for one key. A key that is not a column of `meta` - a virtual field, a
-     * `raw()` projection - is an output alias, which is never table-qualified and needs no resolving.
+     * The `ORDER BY` operand for one key. A key that is not a field of `meta` - a `raw()` projection, a
+     * `$agg` alias - is an output alias, which is never table-qualified and needs no resolving.
      */
-    sortColumn(meta, key, prefix) {
+    sortColumn(ctx, meta, key, prefix) {
         const field = meta.fields[key];
         if (field) {
-            return field.virtual ? this.escapeId(key) : this.columnWithPrefix(key, field, prefix);
+            return this.inlinedOperand(ctx, field, prefix) ?? this.columnWithPrefix(key, field, prefix);
         }
         const json = this.resolveJsonDotPath(meta, key, prefix);
         return json ? this.jsonPathExpr(json.column, json.jsonPath, 'text') : this.escapeId(key);

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -32,7 +32,8 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         primaryKeyAlter: true,
-        columnComment: true,
+        generatedColumnAdd: true,
+        commentSyntax: 'inline',
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,

package/dist/dialect/pgLikeSqlDialect.js

@@ -29,7 +29,8 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         primaryKeyAlter: true,
-        columnComment: false,
+        generatedColumnAdd: true,
+        commentSyntax: 'statement',
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: true,
         supportsTimestamptz: true,

package/dist/entity/metadata/definition.js

@@ -1,4 +1,5 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
+import { isInlinedExpression } from '../../util/field.util.js';
 import { entityName, fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
@@ -16,7 +17,13 @@ function globalMap(key) {
 const metas = globalMap('uql-orm/entity/metadata/v1');
 export function defineField(entity, key, opts = {}) {
     const meta = ensureWritableMeta(entity);
-    if (!opts.type && !opts.references && !opts.virtual) {
+    if (opts.virtual !== undefined && opts.computed !== undefined) {
+        throw new TypeError(`'${entity.name}.${key}' gives both 'virtual' and 'computed'. They are one option under two names - ` +
+            "keep 'computed'; 'npx uql-codemod' rewrites the other.");
+    }
+    // A stored computed column is a real column and still needs a type; only an inlined one is exempt,
+    // its expression being spliced in rather than declared.
+    if (!opts.type && !opts.references && !isInlinedExpression(opts)) {
         throw new TypeError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
             "at another entity with 'references', which resolves the column type from its primary key.");
     }

package/dist/migrate/builder/columnBuilder.d.ts

@@ -3,6 +3,7 @@
  *
  * Fluent API for defining columns in migrations.
  */
+import type { EnumValues } from '../../schema/types.js';
 import type { CanonicalType, ForeignKeyAction } from '../../schema/types.js';
 import type { BaseColumnOptions, FullColumnDefinition, IColumnBuilder, IForeignKeyBuilder } from './types.js';
 /**
@@ -17,6 +18,8 @@ export declare class ColumnBuilder implements IColumnBuilder, IForeignKeyBuilder
     private _primaryKey;
     private _autoIncrement;
     private _unique;
+    private _enum?;
+    private _generatedAs?;
     private _comment?;
     private _index?;
     private _foreignKey?;
@@ -45,6 +48,17 @@ export declare class ColumnBuilder implements IColumnBuilder, IForeignKeyBuilder
      * Add a unique constraint.
      */
     unique(): this;
+    /**
+     * Make the column one the database computes: `GENERATED ALWAYS AS (<sql>) STORED`.
+     *
+     * Takes the SQL as text, since a `CREATE TABLE` has nowhere to bind a value into - the same reason
+     * a check expression and a partial-index predicate do.
+     */
+    computed(sql: string): this;
+    /**
+     * Constrain the column to these values, as a `CHECK (col IN (...))` - what `@Field({ enum })` emits.
+     */
+    enum(values: EnumValues): this;
     /**
      * Add a comment to the column.
      */

package/dist/migrate/builder/columnBuilder.js

@@ -15,6 +15,8 @@ export class ColumnBuilder {
     _primaryKey;
     _autoIncrement;
     _unique;
+    _enum;
+    _generatedAs;
     _comment;
     _index;
     _foreignKey;
@@ -35,8 +37,7 @@ export class ColumnBuilder {
         // Handle inline references option
         if (options.references) {
             this._foreignKey = {
-                table: options.references.table,
-                columns: [options.references.column ?? 'id'],
+                references: { table: options.references.table, columns: [options.references.column ?? 'id'] },
                 onDelete: options.references.onDelete ?? 'NO ACTION',
                 onUpdate: options.references.onUpdate ?? 'NO ACTION',
             };
@@ -85,6 +86,23 @@ export class ColumnBuilder {
         this._unique = true;
         return this;
     }
+    /**
+     * Make the column one the database computes: `GENERATED ALWAYS AS (<sql>) STORED`.
+     *
+     * Takes the SQL as text, since a `CREATE TABLE` has nowhere to bind a value into - the same reason
+     * a check expression and a partial-index predicate do.
+     */
+    computed(sql) {
+        this._generatedAs = sql;
+        return this;
+    }
+    /**
+     * Constrain the column to these values, as a `CHECK (col IN (...))` - what `@Field({ enum })` emits.
+     */
+    enum(values) {
+        this._enum = values;
+        return this;
+    }
     /**
      * Add a comment to the column.
      */
@@ -113,8 +131,7 @@ export class ColumnBuilder {
      */
     references(table, column = 'id') {
         this._foreignKey = {
-            table,
-            columns: [column],
+            references: { table, columns: [column] },
             onDelete: 'NO ACTION',
             onUpdate: 'NO ACTION',
         };
@@ -125,7 +142,7 @@ export class ColumnBuilder {
      */
     onDelete(action) {
         if (this._foreignKey) {
-            this._foreignKey.onDelete = action;
+            this._foreignKey = { ...this._foreignKey, onDelete: action };
         }
         return this;
     }
@@ -134,7 +151,7 @@ export class ColumnBuilder {
      */
     onUpdate(action) {
         if (this._foreignKey) {
-            this._foreignKey.onUpdate = action;
+            this._foreignKey = { ...this._foreignKey, onUpdate: action };
         }
         return this;
     }
@@ -147,9 +164,11 @@ export class ColumnBuilder {
             type: this._type,
             nullable: this._nullable,
             defaultValue: this._defaultValue,
-            primaryKey: this._primaryKey,
-            autoIncrement: this._autoIncrement,
-            unique: this._unique,
+            isPrimaryKey: this._primaryKey,
+            isAutoIncrement: this._autoIncrement,
+            isUnique: this._unique,
+            enum: this._enum,
+            generatedAs: this._generatedAs,
             comment: this._comment,
             index: this._index,
             foreignKey: this._foreignKey,

package/dist/migrate/builder/tableBuilder.js

@@ -5,6 +5,7 @@
  */
 import { ddlText, normalizeIndexColumn } from '../../util/index.js';
 import { derivedIndexName } from '../../util/sql.util.js';
+import { columnForeignKey, columnIndex } from '../generator/definitionToNode.js';
 import { ColumnBuilder } from './columnBuilder.js';
 import { expr } from './expressions.js';
 /**
@@ -193,18 +194,11 @@ export class TableBuilder {
     build() {
         // Build all columns from builders
         const columns = this._columnBuilders.map((cb) => cb.build());
-        // Collect column-level indexes
+        // Collect column-level indexes, skipping any a table-level one already names.
         for (const col of columns) {
-            if (col.index) {
-                const indexName = typeof col.index === 'string' ? col.index : derivedIndexName(this._name, [col.name]);
-                // Only add if not already in table-level indexes
-                if (!this._indexes.some((idx) => idx.name === indexName)) {
-                    this._indexes.push({
-                        name: indexName,
-                        entries: [{ column: col.name }],
-                        unique: col.unique,
-                    });
-                }
+            const index = columnIndex(this._name, col);
+            if (index && !this._indexes.some((idx) => idx.name === index.name)) {
+                this._indexes.push(index);
             }
         }
         // Build foreign keys
@@ -213,14 +207,9 @@ export class TableBuilder {
             .filter((fk) => fk !== undefined);
         // Collect column-level foreign keys
         for (const col of columns) {
-            if (col.foreignKey) {
-                foreignKeys.push({
-                    name: col.foreignKey.name,
-                    columns: [col.name],
-                    references: { table: col.foreignKey.table, columns: col.foreignKey.columns },
-                    onDelete: col.foreignKey.onDelete,
-                    onUpdate: col.foreignKey.onUpdate,
-                });
+            const foreignKey = columnForeignKey(col);
+            if (foreignKey) {
+                foreignKeys.push(foreignKey);
             }
         }
         return {

package/dist/migrate/builder/types.d.ts

@@ -4,7 +4,7 @@
  * Type definitions for the fluent migration builder API.
  * Enables type-safe migrations without raw SQL.
  */
-import type { CanonicalType, ForeignKeyAction } from '../../schema/types.js';
+import type { ColumnNode, EnumValues, ForeignKeyAction } from '../../schema/types.js';
 import type { IndexColumnInput, IndexOptions, IndexSchema } from '../../type/index.js';
 import type { ForeignKeySchema } from '../../type/migration.js';
 /**
@@ -68,41 +68,20 @@ export interface VectorColumnOptions extends BaseColumnOptions {
     dimensions?: number;
 }
 /**
- * Base options for a column definition.
+ * A column as the builder describes one: {@link ColumnNode} without the graph links a DTO cannot carry.
+ *
+ * Derived rather than restated, so the two cannot drift. A column gained `enum` and this shape was
+ * simply missing it, which is why a hand-written `createTable` could never constrain one. A field
+ * added to the node now reaches here, and failing to render it is a compile error rather than a
+ * column that quietly loses half its declaration.
  */
-export interface ColumnDefinition {
-    /** Column name */
-    name: string;
-    /** Canonical type */
-    type: CanonicalType;
-    /** Whether the column is nullable */
-    nullable: boolean;
-    /** Default value or expression */
-    defaultValue?: unknown;
-    /** Whether this is a primary key */
-    primaryKey: boolean;
-    /** Whether this column auto-increments */
-    autoIncrement: boolean;
-    /** Whether this column has a unique constraint */
-    unique: boolean;
-    /** Column comment */
-    comment?: string;
-}
+export type ColumnDefinition = Omit<ColumnNode, 'table' | 'referencedBy' | 'references'>;
 /**
- * Foreign key definition for a column.
+ * The foreign key a single column declares: {@link ForeignKeySchema} without the local columns, which
+ * are the column itself. Derived for the reason {@link ColumnDefinition} is - restated, the two spelled
+ * their target differently and every hand-off between them had to translate.
  */
-export interface ForeignKeyDefinition {
-    /** Constraint name */
-    name?: string;
-    /** Referenced table */
-    table: string;
-    /** Referenced column(s) */
-    columns: string[];
-    /** Action on delete */
-    onDelete: ForeignKeyAction;
-    /** Action on update */
-    onUpdate: ForeignKeyAction;
-}
+export type ForeignKeyDefinition = Omit<ForeignKeySchema, 'columns'>;
 /**
  * Full column definition including foreign key.
  */
@@ -259,6 +238,10 @@ export interface IColumnBuilder {
     autoIncrement(): this;
     /** Add unique constraint */
     unique(): this;
+    /** Constrain the column to these values, as a `CHECK (col IN (...))`. */
+    enum(values: EnumValues): this;
+    /** Make the column one the database computes, as `GENERATED ALWAYS AS (<sql>) STORED`. */
+    computed(sql: string): this;
     /** Add comment */
     comment(text: string): this;
     /** Add index */

package/dist/migrate/codegen/entityCodeGenerator.js

@@ -12,7 +12,7 @@
 import { canonicalToTypeScript } from '../../schema/canonicalType.js';
 import { DEFAULT_FOREIGN_KEY_ACTION, } from '../../schema/types.js';
 import { camelCase, pascalCase, singularize } from '../../util/string.util.js';
-import { buildFieldOptionsSource } from './fieldOptionsSource.js';
+import { buildFieldOptionsSource, fieldNeedsRaw } from './fieldOptionsSource.js';
 import { buildIndexDecoratorSource, indexNeedsRaw, isPlainFieldIndex } from './indexDecoratorSource.js';
 /**
  * Generates TypeScript entity code from SchemaAST.
@@ -75,11 +75,13 @@ export class EntityCodeGenerator {
     buildImports(table) {
         const uqlImports = new Set(['Entity', 'Field']);
         const relatedImports = [];
-        // Check for Id decorator
         for (const col of table.columns.values()) {
             if (col.isPrimaryKey) {
                 uqlImports.add('Id');
             }
+            if (fieldNeedsRaw(col)) {
+                uqlImports.add('raw');
+            }
         }
         // Check for relation decorators
         if (this.options.includeRelations) {
@@ -145,9 +147,6 @@ export class EntityCodeGenerator {
             lines.push('  /**');
             lines.push(`   * @sync-added ${new Date().toISOString().split('T')[0]}`);
             lines.push(`   * Column: ${col.name} (${this.formatTypeDescription(col.type)})`);
-            if (col.comment) {
-                lines.push(`   * ${col.comment}`);
-            }
             lines.push('   */');
         }
         // Decorator

package/dist/migrate/codegen/fieldOptionsSource.d.ts

@@ -8,3 +8,5 @@ import type { ColumnNode } from '../../schema/types.js';
  * file from scratch.
  */
 export declare function buildFieldOptionsSource(col: ColumnNode, propertyName: string, indexName?: string): string;
+/** Whether the field's decorator needs `raw` imported, the way {@link indexNeedsRaw} does for an index. */
+export declare function fieldNeedsRaw(col: ColumnNode): boolean;

package/dist/migrate/codegen/fieldOptionsSource.js

@@ -1,4 +1,41 @@
 import { canonicalToColumnType } from '../../schema/canonicalType.js';
+import { quoted, rawTag } from './sourceLiteral.js';
+/**
+ * What each field of a {@link ColumnNode} contributes to `@Field({ ... })`, in emit order, and `null`
+ * where nothing does.
+ *
+ * The `satisfies` is the point: a field the node gains cannot reach here without someone answering
+ * whether an entity generated from a database keeps it. Written as a hand-rolled `if` chain, this had
+ * already dropped `comment` - introspection reads one on Postgres and MySQL, and regenerating an
+ * entity threw it away.
+ */
+const OPTION_SOURCE = {
+    // Without this the entity maps to a column named after the property, which for anything the
+    // transformer rewrote - every `user_id` - is a column the database does not have.
+    name: (col, { propertyName }) => (propertyName === col.name ? [] : [`name: ${quoted(col.name)}`]),
+    type: (col) => {
+        const columnType = canonicalToColumnType(col.type);
+        return [
+            ...(columnType ? [`columnType: ${quoted(columnType)}`] : []),
+            ...(col.type.length && col.type.category === 'string' ? [`length: ${col.type.length}`] : []),
+            ...(col.type.precision === undefined ? [] : [`precision: ${col.type.precision}`]),
+            ...(col.type.precision !== undefined && col.type.scale !== undefined ? [`scale: ${col.type.scale}`] : []),
+        ];
+    },
+    nullable: (col) => (col.nullable ? ['nullable: true'] : []),
+    isUnique: (col) => (col.isUnique ? ['unique: true'] : []),
+    enum: (col) => col.enum ? [`enum: [${col.enum.map((it) => (typeof it === 'number' ? it : quoted(it))).join(', ')}]`] : [],
+    defaultValue: (col) => col.defaultValue === undefined ? [] : [`defaultValue: ${defaultValueSource(col.defaultValue)}`],
+    generatedAs: (col) => (col.generatedAs ? [`computed: ${rawTag(col.generatedAs)}`, 'stored: true'] : []),
+    comment: (col) => (col.comment ? [`comment: ${quoted(col.comment)}`] : []),
+    // A key is `@Id`, and a numeric one generates by that alone. Neither is an option to write out.
+    isPrimaryKey: null,
+    isAutoIncrement: null,
+    // Graph links. A foreign key becomes a relation decorator, emitted beside the field rather than in it.
+    table: null,
+    references: null,
+    referencedBy: null,
+};
 /**
  * A column's `@Field({ ... })` options as source, or `''` when it needs none.
  *
@@ -8,47 +45,26 @@ import { canonicalToColumnType } from '../../schema/canonicalType.js';
  * file from scratch.
  */
 export function buildFieldOptionsSource(col, propertyName, indexName) {
-    const options = [];
-    // Without this the entity maps to a column named after the property, which for anything the
-    // transformer rewrote - every `user_id` - is a column the database does not have.
-    if (propertyName !== col.name) {
-        options.push(`name: '${col.name}'`);
-    }
-    const columnType = canonicalToColumnType(col.type);
-    if (columnType) {
-        options.push(`columnType: '${columnType}'`);
-    }
-    if (col.type.length && col.type.category === 'string') {
-        options.push(`length: ${col.type.length}`);
-    }
-    if (col.type.precision !== undefined) {
-        options.push(`precision: ${col.type.precision}`);
-        if (col.type.scale !== undefined) {
-            options.push(`scale: ${col.type.scale}`);
-        }
-    }
-    if (col.nullable) {
-        options.push('nullable: true');
-    }
-    if (col.isUnique) {
-        options.push('unique: true');
-    }
-    if (col.defaultValue !== undefined) {
-        options.push(`defaultValue: ${formatDefaultValueSource(col.defaultValue)}`);
-    }
-    if (indexName) {
-        options.push(`index: '${indexName}'`);
-    }
+    const context = { propertyName, indexName };
+    const options = [
+        ...Object.values(OPTION_SOURCE).flatMap((source) => source?.(col, context) ?? []),
+        // Not a column field: the index is a table-level object the field only borrows.
+        ...(indexName ? [`index: ${quoted(indexName)}`] : []),
+    ];
     return options.length > 0 ? `{ ${options.join(', ')} }` : '';
 }
+/** Whether the field's decorator needs `raw` imported, the way {@link indexNeedsRaw} does for an index. */
+export function fieldNeedsRaw(col) {
+    return col.generatedAs !== undefined;
+}
 /**
  * A default value as source. Strings stay single-quoted, expressions included: `defaultValue: 'now()'`
  * is what reaches the DDL. The generator used to branch on `CURRENT_TIMESTAMP`/`NEXTVAL`/`(` first, but
  * both branches emitted a quoted string and only the fallthrough escaped embedded quotes.
  */
-function formatDefaultValueSource(value) {
+function defaultValueSource(value) {
     if (typeof value === 'string') {
-        return `'${value.replace(/'/g, "\\'")}'`;
+        return quoted(value);
     }
     if (typeof value === 'boolean' || typeof value === 'number') {
         return value.toString();

package/dist/migrate/codegen/indexDecoratorSource.js

@@ -1,3 +1,4 @@
+import { rawTag } from './sourceLiteral.js';
 /**
  * A vector index carries its metric in the operator class pgvector names after it
  * (`vector_cosine_ops`), which is the only place introspection can recover it from. `@Index` requires
@@ -94,12 +95,3 @@ function indexEntrySource(entry, propertyName) {
     }
     return `{ column: '${propertyName(entry.column)}', ${modifiers.join(', ')} }`;
 }
-/**
- * SQL as a `raw` tagged template. A database reprints an expression as arbitrary text, and exactly
- * three sequences can end or interpolate a template literal, so escaping those is the whole job.
- * Newlines need none, which keeps a multi-line expression readable in the generated entity.
- */
-function rawTag(sql) {
-    const escaped = sql.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
-    return `raw\`${escaped}\``;
-}

package/dist/migrate/codegen/sourceLiteral.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A string as single-quoted source. Introspected text is arbitrary - a comment or a default
+ * expression can hold a quote or a backslash - and only escaping both keeps the generated file
+ * parsing.
+ */
+export declare function quoted(text: string): string;
+/**
+ * SQL as a `raw` tagged template. A database reprints an expression as arbitrary text, and exactly
+ * three sequences can end or interpolate a template literal, so escaping those is the whole job.
+ * Newlines need none, which keeps a multi-line expression readable in the generated entity.
+ */
+export declare function rawTag(sql: string): string;

package/dist/migrate/codegen/sourceLiteral.js

@@ -0,0 +1,17 @@
+/**
+ * A string as single-quoted source. Introspected text is arbitrary - a comment or a default
+ * expression can hold a quote or a backslash - and only escaping both keeps the generated file
+ * parsing.
+ */
+export function quoted(text) {
+    return `'${text.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/**
+ * SQL as a `raw` tagged template. A database reprints an expression as arbitrary text, and exactly
+ * three sequences can end or interpolate a template literal, so escaping those is the whole job.
+ * Newlines need none, which keeps a multi-line expression readable in the generated entity.
+ */
+export function rawTag(sql) {
+    const escaped = sql.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+    return `raw\`${escaped}\``;
+}

package/dist/migrate/generator/definitionToNode.d.ts

@@ -1,4 +1,5 @@
 import type { ColumnNode, TableNode } from '../../schema/types.js';
+import type { ForeignKeySchema, IndexSchema } from '../../type/migration.js';
 import type { FullColumnDefinition, TableDefinition } from '../builder/types.js';
 /**
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
@@ -6,4 +7,24 @@ import type { FullColumnDefinition, TableDefinition } from '../builder/types.js'
  * not generator methods: nothing here consults the dialect.
  */
 export declare function tableDefinitionToNode(def: TableDefinition): TableNode;
+/**
+ * A builder's column as the AST node the generators render from.
+ *
+ * The shared half is spread, not copied field by field: `ColumnDefinition` *is* a `ColumnNode` minus
+ * the graph links, so spreading it and adding those back is a node by construction. Listed one by one,
+ * the copy silently dropped whatever the node gained next - `enum` first, and the type had no way to
+ * say so. The two builder-only keys are destructured off: `index` and `foreignKey` are lifted onto the
+ * table by `columnIndex`/`columnForeignKey`, which is the path that renders them.
+ *
+ * No `references` node either: `SchemaAST.addRelationship` sets that one.
+ */
 export declare function fullColumnDefinitionToNode(col: FullColumnDefinition, tableName: string): ColumnNode;
+/**
+ * The index a column-level `index` declares, or nothing.
+ *
+ * Shared with `TableBuilder.build`, which lifts these into the table it is creating: written twice,
+ * `addColumn` had no lift at all and silently emitted a column with no index.
+ */
+export declare function columnIndex(tableName: string, col: FullColumnDefinition): IndexSchema | undefined;
+/** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
+export declare function columnForeignKey(col: FullColumnDefinition): ForeignKeySchema | undefined;