uql-orm 0.45.1 → 0.47.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/bunSql/bunSqlQuerier.d.ts

@@ -2,6 +2,13 @@ import type { ReservedSQL, SQL } from 'bun';
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import type { ExtraOptions } from '../type/index.js';
+/**
+ * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB, CockroachDB and SQLite.
+ *
+ * @remarks Deliberately does not override `internalStream`, which every other SQL driver here does:
+ * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API, so `findManyStream` falls back
+ * to the base class buffering the whole result, as `PgliteQuerier` does for the same reason.
+ */
 export declare class BunSqlQuerier extends AbstractPoolQuerier<ReservedSQL> {
     readonly sql: SQL;
     readonly extra?: ExtraOptions | undefined;

package/dist/bunSql/bunSqlQuerier.js

@@ -1,5 +1,12 @@
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import { getAffectedRows, getInsertId, isReservedConnection, normalizeRows } from './bunSql.util.js';
+/**
+ * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB, CockroachDB and SQLite.
+ *
+ * @remarks Deliberately does not override `internalStream`, which every other SQL driver here does:
+ * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API, so `findManyStream` falls back
+ * to the base class buffering the whole result, as `PgliteQuerier` does for the same reason.
+ */
 export class BunSqlQuerier extends AbstractPoolQuerier {
     sql;
     extra;

package/dist/bunSql/bunSqlQuerierPool.d.ts

@@ -7,6 +7,7 @@ export declare class BunSqlQuerierPool extends AbstractSqlQuerierPool<BunSqlQuer
     readonly config: SQL.Options;
     readonly sql: SQL;
     readonly sqlDialectName: SqlDialectName;
+    private foreignKeysOn?;
     constructor(config: SQL.Options, extra?: ExtraOptions);
     /**
      * Provides a pg-compatible interface for libraries like connect-pg-simple.

package/dist/bunSql/bunSqlQuerierPool.js

@@ -19,6 +19,7 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     config;
     sql;
     sqlDialectName;
+    foreignKeysOn;
     constructor(config, extra) {
         const dialectName = inferDialectName(config);
         super(new DialectMap[dialectName](dialectOptionsFrom(extra)), extra);
@@ -44,8 +45,12 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     }
     async getQuerier() {
         const connFactory = async () => {
-            // Bun's SQLite adapter does not support connection reservation (it's unpooled).
+            // Bun's SQLite adapter does not support connection reservation (it's unpooled), and leaves
+            // `foreign_keys` off as `bun:sqlite` does, so without the pragma the constraints uql emits in
+            // its own DDL are decorative. One connection means one pragma, issued on the first acquisition.
             if (!isPoolableDialect(this.sqlDialectName)) {
+                this.foreignKeysOn ??= this.sql.unsafe('PRAGMA foreign_keys = ON');
+                await this.foreignKeysOn;
                 return this.sql;
             }
             return this.sql.reserve();

package/dist/bunSql/index.d.ts

@@ -1,4 +1,5 @@
 export * from './bunSqliteDialect.js';
+export * from './bunSqlCockroachDialect.js';
 export * from './bunSqlPostgresDialect.js';
 export * from './bunSqlQuerier.js';
 export * from './bunSqlQuerierPool.js';

package/dist/bunSql/index.js

@@ -1,4 +1,5 @@
 export * from './bunSqliteDialect.js';
+export * from './bunSqlCockroachDialect.js';
 export * from './bunSqlPostgresDialect.js';
 export * from './bunSqlQuerier.js';
 export * from './bunSqlQuerierPool.js';

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,4 +1,5 @@
 import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type ParentPartition } from '../util/index.js';
 import type { HydrateKind } from './hydrateColumn.js';
 import { type JsonAccessMode } from './jsonSql.js';
 import { type QueryJoins, type QuerySortOptions } from './queryJoins.js';
@@ -52,6 +53,18 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     readonly maxBindValues: number;
     getBeginTransactionStatements(isolationLevel?: IsolationLevel): string[];
+    /**
+     * Every parent's own bounded page in one statement: a subquery per parent, each filtered to that
+     * parent alone and carrying its own `ORDER BY`, `LIMIT` and `OFFSET`. Universal, and reads
+     * `parents x (skip + limit)` rows where a `ROW_NUMBER` window reads every matching child.
+     * [The design](../../../../architecture/populate-limits.md).
+     *
+     * Each branch is a wrapped derived table rather than a bare parenthesised select: SQLite rejects
+     * `ORDER BY`/`LIMIT` on the latter, and the wrapper costs nothing elsewhere.
+     */
+    findPerParent<E extends object>(ctx: QueryContext, entity: Type<E>, q: Query<E>, partition: ParentPartition): void;
+    /** The shape {@link findPerParent} emits, which the Postgres family replaces with a `LATERAL` join. */
+    protected appendPerParent<E extends object>(ctx: QueryContext, entity: Type<E>, q: Query<E>, { joins, parents }: ParentPartition): void;
     createContext(): QueryContext;
     /**
      * Builds SQL text in isolation via `build`, so the caller can embed it inline (e.g.
@@ -171,6 +184,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 +281,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,8 +1,9 @@
 import { getMeta, soleIdOf } from '../entity/index.js';
 import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, VECTOR_QUERY_KEYS, } from '../type/index.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 { 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, queryChildrenOf, 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';
+import { COUNT_ALIAS, DISTINCT_DERIVED_ALIAS, JSON_ELEM_ALIAS_PREFIX, PER_PARENT_BRANCH_ALIAS } from './aliases.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { isJsonbOp, jsonCompareMode, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
@@ -54,6 +55,34 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // 'set-before' - MySQL/MariaDB pattern
         return [`SET TRANSACTION ISOLATION LEVEL ${level}`, this.beginTransactionCommand];
     }
+    /**
+     * Every parent's own bounded page in one statement: a subquery per parent, each filtered to that
+     * parent alone and carrying its own `ORDER BY`, `LIMIT` and `OFFSET`. Universal, and reads
+     * `parents x (skip + limit)` rows where a `ROW_NUMBER` window reads every matching child.
+     * [The design](../../../../architecture/populate-limits.md).
+     *
+     * Each branch is a wrapped derived table rather than a bare parenthesised select: SQLite rejects
+     * `ORDER BY`/`LIMIT` on the latter, and the wrapper costs nothing elsewhere.
+     */
+    findPerParent(ctx, entity, q, partition) {
+        if (!partition.parents.length) {
+            // Guarded on the contract rather than in either shape: this is the end that would otherwise
+            // append nothing and hand the driver an empty statement, and both shapes owe the same promise.
+            throw new TypeError('cannot read a bounded relation for no parents at all');
+        }
+        this.appendPerParent(ctx, entity, q, partition);
+    }
+    /** The shape {@link findPerParent} emits, which the Postgres family replaces with a `LATERAL` join. */
+    appendPerParent(ctx, entity, q, { joins, parents }) {
+        parents.forEach((parent, index) => {
+            if (index) {
+                ctx.append(' UNION ALL ');
+            }
+            ctx.append('SELECT * FROM (');
+            this.find(ctx, entity, queryChildrenOf(q, joins, parent));
+            ctx.append(`) ${this.escapeId(ctx.nextAlias(PER_PARENT_BRANCH_ALIAS))}`);
+        });
+    }
     createContext() {
         return new SqlQueryContext(this);
     }
@@ -160,9 +189,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 +514,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 +804,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/aliases.d.ts

@@ -14,6 +14,10 @@ export declare const COUNT_ALIAS = "_uql_count";
 export declare const TOTAL_ALIAS = "_uql_total";
 /** The derived table a `$distinct` count wraps its deduplicated set in. MySQL requires the alias. */
 export declare const DISTINCT_DERIVED_ALIAS = "_uql_distinct";
+/** Prefix for the derived table each branch of a per-parent bounded read is wrapped in. */
+export declare const PER_PARENT_BRANCH_ALIAS = "_uql_p";
+/** The row source a `LATERAL` per-parent read correlates each of its branches against. */
+export declare const PER_PARENT_KEYS_ALIAS = "_uql_keys";
 /** Prefix for the alias an exploded JSON array element is read through. */
 export declare const JSON_ELEM_ALIAS_PREFIX = "_uql_elem";
 /** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS_PREFIX}. */

package/dist/dialect/aliases.js

@@ -14,6 +14,10 @@ export const COUNT_ALIAS = '_uql_count';
 export const TOTAL_ALIAS = '_uql_total';
 /** The derived table a `$distinct` count wraps its deduplicated set in. MySQL requires the alias. */
 export const DISTINCT_DERIVED_ALIAS = '_uql_distinct';
+/** Prefix for the derived table each branch of a per-parent bounded read is wrapped in. */
+export const PER_PARENT_BRANCH_ALIAS = '_uql_p';
+/** The row source a `LATERAL` per-parent read correlates each of its branches against. */
+export const PER_PARENT_KEYS_ALIAS = '_uql_keys';
 /** Prefix for the alias an exploded JSON array element is read through. */
 export const JSON_ELEM_ALIAS_PREFIX = '_uql_elem';
 /** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS_PREFIX}. */

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.d.ts

@@ -1,4 +1,5 @@
 import { type DialectFeatures, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type Type, type VectorDistance, type VectorOperatorMetric } from '../type/index.js';
+import { type ParentPartition } from '../util/relationQuery.util.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
@@ -21,6 +22,19 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     readonly commitTransactionCommand = "COMMIT";
     readonly rollbackTransactionCommand = "ROLLBACK";
     readonly alterColumnStrategy = "separate-clauses";
+    /**
+     * One `LATERAL` branch correlated against an array of the parent keys, in place of the base
+     * `UNION ALL` of a subquery per parent. Same rows and the same `parents x (skip + limit)` read, but
+     * the planner sees one correlated index loop rather than N branches to plan: flat in page size where
+     * `UNION ALL` is linear, and the statement's text stops changing with the number of parents, so one
+     * prepared statement serves every page.
+     *
+     * Postgres, CockroachDB, PGlite, Neon and bun-sql inherit it together. **MySQL has `LATERAL` and must
+     * not use it** - it does not plan this as a correlated index loop and measured slower than both its
+     * own `UNION ALL` and a query per parent, which is why this is an override rather than a capability
+     * flag. [The design](../../../../architecture/populate-limits.md).
+     */
+    protected appendPerParent<E extends object>(ctx: QueryContext, entity: Type<E>, q: Query<E>, { joins, parents, parentFields }: ParentPartition): void;
     /** `$N` placeholders carry their own index, so the upsert's assignments need no scratch context. */
     protected readonly upsertUpdateBindsInPlace = true;
     readonly insertIdSource = "returning";

package/dist/dialect/pgLikeSqlDialect.js

@@ -1,8 +1,11 @@
+import { canonicalToSql, fieldOptionsToCanonical } from '../schema/canonicalType.js';
 import { QueryRaw, } from '../type/index.js';
 import { hasVectorNear } from '../util/dialect.util.js';
+import { raw } from '../util/raw.js';
+import { queryNarrowedTo } from '../util/relationQuery.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
-import { JSON_PULL_ALIAS } from './aliases.js';
+import { JSON_PULL_ALIAS, PER_PARENT_BRANCH_ALIAS, PER_PARENT_KEYS_ALIAS } from './aliases.js';
 import { jsonSetTarget } from './jsonSql.js';
 import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
 /**
@@ -29,7 +32,8 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         primaryKeyAlter: true,
-        columnComment: false,
+        generatedColumnAdd: true,
+        commentSyntax: 'statement',
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: true,
         supportsTimestamptz: true,
@@ -46,6 +50,42 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     commitTransactionCommand = 'COMMIT';
     rollbackTransactionCommand = 'ROLLBACK';
     alterColumnStrategy = 'separate-clauses';
+    /**
+     * One `LATERAL` branch correlated against an array of the parent keys, in place of the base
+     * `UNION ALL` of a subquery per parent. Same rows and the same `parents x (skip + limit)` read, but
+     * the planner sees one correlated index loop rather than N branches to plan: flat in page size where
+     * `UNION ALL` is linear, and the statement's text stops changing with the number of parents, so one
+     * prepared statement serves every page.
+     *
+     * Postgres, CockroachDB, PGlite, Neon and bun-sql inherit it together. **MySQL has `LATERAL` and must
+     * not use it** - it does not plan this as a correlated index loop and measured slower than both its
+     * own `UNION ALL` and a query per parent, which is why this is an override rather than a capability
+     * flag. [The design](../../../../architecture/populate-limits.md).
+     */
+    appendPerParent(ctx, entity, q, { joins, parents, parentFields }) {
+        const keys = this.escapeId(ctx.nextAlias(PER_PARENT_KEYS_ALIAS));
+        const branch = this.escapeId(ctx.nextAlias(PER_PARENT_BRANCH_ALIAS));
+        const column = (index) => `${keys}.k${index}`;
+        // `unnest` resolves an uncast parameter to `unknown` and refuses it ("function unnest(unknown) is
+        // not unique"), so the array says its type. It comes from the parent's key column, which always
+        // declares one, rather than the child's foreign key, which would have to be resolved through the
+        // reference it takes its own type from.
+        const sources = joins.map(({ parent }) => {
+            const field = parentFields[parent];
+            if (!field) {
+                throw new TypeError(`cannot page a relation per parent: '${parent}' is not a field of the parent entity`);
+            }
+            const values = parents.map((it) => it[parent]);
+            return `${this.addValue(ctx.values, values)}::${canonicalToSql(fieldOptionsToCanonical(field), this)}[]`;
+        });
+        const rowSource = `unnest(${sources.join(', ')}) AS ${keys}(${joins.map((_, index) => `k${index}`).join(', ')})`;
+        // The keys come from the row source rather than as values, which is the whole point of correlating:
+        // one branch, planned once, instead of one per parent.
+        const correlated = Object.fromEntries(joins.map(({ joined }, index) => [joined, raw(({ ctx: inner }) => inner.append(column(index)))]));
+        ctx.append(`SELECT ${branch}.* FROM ${rowSource} JOIN LATERAL (`);
+        this.find(ctx, entity, queryNarrowedTo(q, correlated));
+        ctx.append(`) ${branch} ON TRUE`);
+    }
     /** `$N` placeholders carry their own index, so the upsert's assignments need no scratch context. */
     upsertUpdateBindsInPlace = true;
     insertIdSource = 'returning';

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 {