uql-orm 0.45.1 → 0.47.0

package/dist/migrate/schemaGenerator.js

@@ -8,7 +8,7 @@ import { getKeys, isAutoIncrement, isSoleIdField, qualifyName } from '../util/in
 import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
 import { indexDdlFor } from './ddl/index.js';
-import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
+import { columnForeignKey, columnIndex, fullColumnDefinitionToNode, tableDefinitionToNode, } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 /**
  * Unified SQL schema generator.
@@ -61,6 +61,17 @@ export class SqlSchemaGenerator {
     serialType(type) {
         return `${this.canonicalTypeToSql(type)} ${this.dialect.autoIncrementSuffix}`;
     }
+    /**
+     * The SQL type a column is spelled with: the engine's generated-key form for an auto-increment key,
+     * the canonical type otherwise.
+     *
+     * One method because both paths that spell a column need the same answer - written twice, with a
+     * comment asking the two to stay in sync, is how the generated key and the column referencing it
+     * came to disagree in the first place.
+     */
+    columnSqlType(col) {
+        return col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type);
+    }
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
     }
@@ -142,7 +153,9 @@ export class SqlSchemaGenerator {
         // Add new columns
         if (diff.columnsToAdd?.length) {
             for (const column of diff.columnsToAdd) {
+                this.assertColumnAddable(diff.tableName, column);
                 statements.push(`ALTER TABLE ${tableName} ADD COLUMN ${this.generateColumnDefinitionFromSchema(column)};`);
+                statements.push(...this.generateColumnCommentStatement(diff.tableName, column, diff.schema));
             }
         }
         // Alter existing columns
@@ -278,6 +291,12 @@ export class SqlSchemaGenerator {
      */
     renderColumn(column) {
         let def = `${this.escapeId(column.name)} ${column.type}`;
+        // Before the constraints, which every engine here accepts and is where each documents it. The
+        // clause takes the place of a `DEFAULT`, which is mutually exclusive with it; everything else -
+        // `NOT NULL`, `UNIQUE`, an enum `CHECK`, a comment - a generated column carries like any other.
+        if (column.generatedAs) {
+            def += ` GENERATED ALWAYS AS (${column.generatedAs}) STORED`;
+        }
         if (!column.nullable && !column.isPrimaryKey) {
             def += ' NOT NULL';
         }
@@ -290,7 +309,7 @@ export class SqlSchemaGenerator {
         }
         def += this.defaultClause(column);
         if (column.comment) {
-            def += this.generateColumnComment(column.name, column.comment);
+            def += this.generateColumnComment(column.comment);
         }
         return def;
     }
@@ -349,15 +368,40 @@ export class SqlSchemaGenerator {
         }
         return [`ALTER TABLE ${table} ${this.dialect.alterColumnSyntax} ${newDefinition};`];
     }
+    /** The inline ` COMMENT '...'` a column declaration carries, where the engine takes one there. */
+    generateColumnComment(comment) {
+        return this.features.commentSyntax === 'inline' ? ` COMMENT ${this.dialect.escape(comment)}` : '';
+    }
+    /**
+     * The `COMMENT ON` statements a table and its columns need, on an engine that carries a comment
+     * that way. Empty on the others: MySQL writes them inline, SQLite has no comments at all.
+     *
+     * Emitted after the `CREATE TABLE` rather than folded into it, which is what `COMMENT ON` requires -
+     * and what makes a comment reach Postgres, where it was previously read as unsupported and dropped.
+     */
+    generateCommentStatements(table) {
+        if (this.features.commentSyntax !== 'statement') {
+            return [];
+        }
+        const tableRef = this.dialect.escapeQualifiedId(table.name, table.schema);
+        const statements = table.comment ? [`COMMENT ON TABLE ${tableRef} IS ${this.dialect.escape(table.comment)};`] : [];
+        for (const col of table.columns.values()) {
+            statements.push(...this.generateColumnCommentStatement(table.name, col, table.schema));
+        }
+        return statements;
+    }
     /**
-     * Generate column comment clause (if supported)
+     * The `COMMENT ON COLUMN` one column needs, on an engine that carries a comment that way.
+     *
+     * Shared by `CREATE TABLE` and every path that adds a column: written only for the former, a column
+     * added later reached the database undocumented, the way its enum `CHECK` used to.
      */
-    generateColumnComment(columnName, comment) {
-        if (this.features.columnComment) {
-            const escapedComment = comment.replace(/'/g, "''");
-            return ` COMMENT '${escapedComment}'`;
+    generateColumnCommentStatement(tableName, column, schema) {
+        if (!column.comment || this.features.commentSyntax !== 'statement') {
+            return [];
         }
-        return '';
+        const tableRef = this.dialect.escapeQualifiedId(tableName, schema);
+        return [`COMMENT ON COLUMN ${tableRef}.${this.escapeId(column.name)} IS ${this.dialect.escape(column.comment)};`];
     }
     /**
      * Compare an entity with a database table node and return the differences.
@@ -468,20 +512,10 @@ export class SqlSchemaGenerator {
             defaultsEqual: (expected, actual) => this.isDefaultValueEqual(actual, expected),
         };
     }
+    /** Spread, not copied field by field, so a field the node gains cannot go missing here. */
     columnNodeToSchema(col) {
-        return {
-            name: col.name,
-            // The same rule `generateColumnFromNode` renders by, so a column added to an existing table
-            // gets the type it would have had if the table were created from scratch.
-            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type),
-            nullable: col.nullable,
-            defaultValue: col.defaultValue,
-            isPrimaryKey: col.isPrimaryKey,
-            isAutoIncrement: col.isAutoIncrement,
-            isUnique: col.isUnique,
-            comment: col.comment,
-            enum: col.enum,
-        };
+        const { table: _table, referencedBy: _referencedBy, references: _references, ...column } = col;
+        return { ...column, type: this.columnSqlType(col) };
     }
     /**
      * Compare two default values for equality
@@ -540,11 +574,8 @@ export class SqlSchemaGenerator {
         });
         for (const rel of table.outgoingRelations) {
             if (rel.from.columns.length > 0) {
-                const fromCols = rel.from.columns.map((c) => this.escapeId(c.name)).join(', ');
-                const toCols = rel.to.columns.map((c) => this.escapeId(c.name)).join(', ');
-                const constraintName = rel.name ? `CONSTRAINT ${this.escapeId(rel.name)} ` : '';
-                constraints.push(`${constraintName}FOREIGN KEY (${fromCols}) REFERENCES ${this.dialect.escapeQualifiedId(rel.to.table.name, rel.to.table.schema)} (${toCols})` +
-                    ` ON DELETE ${rel.onDelete ?? this.defaultForeignKeyAction} ON UPDATE ${rel.onUpdate ?? this.defaultForeignKeyAction}`);
+                const refTable = this.dialect.escapeQualifiedId(rel.to.table.name, rel.to.table.schema);
+                constraints.push(this.foreignKeyConstraint(table.name, foreignKeyOf(rel), refTable));
             }
         }
         const ifNotExists = options.ifNotExists && this.features.ifNotExists ? 'IF NOT EXISTS ' : '';
@@ -558,6 +589,9 @@ export class SqlSchemaGenerator {
         if (this.dialect.tableOptions) {
             createSql += ` ${this.dialect.tableOptions}`;
         }
+        if (table.comment && this.features.commentSyntax === 'inline') {
+            createSql += ` COMMENT=${this.dialect.escape(table.comment)}`;
+        }
         createSql += ';';
         const statements = [];
         if (this.dialect.vectorExtension) {
@@ -567,6 +601,7 @@ export class SqlSchemaGenerator {
             }
         }
         statements.push(createSql);
+        statements.push(...this.generateCommentStatements(table));
         for (const idx of table.indexes) {
             statements.push(this.generateCreateIndexFromNode(idx));
         }
@@ -577,10 +612,7 @@ export class SqlSchemaGenerator {
      * so only a lone primary key column carries `PRIMARY KEY` inline.
      */
     generateColumnFromNode(col) {
-        return this.renderColumn({
-            ...col,
-            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type),
-        });
+        return this.renderColumn({ ...col, type: this.columnSqlType(col) });
     }
     /**
      * Generate CREATE INDEX SQL from an IndexNode.
@@ -600,9 +632,28 @@ export class SqlSchemaGenerator {
         }
         return `ALTER TABLE ${this.escapeId(oldName)} RENAME TO ${this.escapeId(newName)};`;
     }
+    /**
+     * `ADD COLUMN`, plus the constraint and index the column declares.
+     *
+     * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
+     * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
+     * dropped both without a word. Several statements in one string is what `generateAlterColumnSql`
+     * already returns, and `execute` splits them.
+     */
     generateAddColumnSql(tableName, column) {
+        this.assertColumnAddable(tableName, column);
         const colSql = this.generateColumnFromNode(fullColumnDefinitionToNode(column, tableName));
-        return `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql};`;
+        const statements = [`ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql};`];
+        const foreignKey = columnForeignKey(column);
+        if (foreignKey) {
+            statements.push(...this.addForeignKeyStatements(tableName, [foreignKey]));
+        }
+        const index = columnIndex(tableName, column);
+        if (index) {
+            statements.push(this.generateCreateIndex(tableName, index));
+        }
+        statements.push(...this.generateColumnCommentStatement(tableName, column));
+        return statements.join('\n');
     }
     generateAlterColumnSql(tableName, columnName, column) {
         const node = fullColumnDefinitionToNode(column, tableName);
@@ -614,16 +665,26 @@ export class SqlSchemaGenerator {
     generateRenameColumnSql(tableName, oldName, newName) {
         return `ALTER TABLE ${this.escapeId(tableName)} RENAME COLUMN ${this.escapeId(oldName)} TO ${this.escapeId(newName)};`;
     }
-    generateAddForeignKeySql(tableName, foreignKey) {
+    /**
+     * `CONSTRAINT <name> FOREIGN KEY (...) REFERENCES ... ON DELETE ... ON UPDATE ...`.
+     *
+     * One spelling for the two places that need it - inline in a `CREATE TABLE`, and after `ADD` in an
+     * `ALTER`. Written twice, the two drifted over which end they qualified with a schema.
+     */
+    foreignKeyConstraint(tableName, foreignKey, refTableSql) {
         const fkCols = foreignKey.columns.map((c) => this.escapeId(c)).join(', ');
         const refCols = foreignKey.references.columns.map((c) => this.escapeId(c)).join(', ');
-        const constraintName = this.escapeId(constraintNameOf(tableName, foreignKey));
+        return (`CONSTRAINT ${this.escapeId(constraintNameOf(tableName, foreignKey))} ` +
+            `FOREIGN KEY (${fkCols}) REFERENCES ${refTableSql} (${refCols}) ` +
+            `ON DELETE ${foreignKey.onDelete ?? this.defaultForeignKeyAction} ` +
+            `ON UPDATE ${foreignKey.onUpdate ?? this.defaultForeignKeyAction}`);
+    }
+    generateAddForeignKeySql(tableName, foreignKey) {
         if (!this.features.foreignKeyAlter) {
             throw new TypeError(`Dialect ${this.dialect} does not support adding foreign keys to existing tables`);
         }
-        return (`ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} ` +
-            `FOREIGN KEY (${fkCols}) REFERENCES ${this.escapeId(foreignKey.references.table)} (${refCols}) ` +
-            `ON DELETE ${foreignKey.onDelete ?? this.defaultForeignKeyAction} ON UPDATE ${foreignKey.onUpdate ?? this.defaultForeignKeyAction};`);
+        const constraint = this.foreignKeyConstraint(tableName, foreignKey, this.escapeId(foreignKey.references.table));
+        return `ALTER TABLE ${this.escapeId(tableName)} ADD ${constraint};`;
     }
     generateDropForeignKeySql(tableName, constraintName) {
         return `ALTER TABLE ${this.escapeId(tableName)} ${this.dialect.dropForeignKeySyntax} ${this.escapeId(constraintName)};`;
@@ -659,6 +720,18 @@ export class SqlSchemaGenerator {
         }
         return `ALTER TABLE ${table} DROP CONSTRAINT ${this.escapeId(constraintName)};`;
     }
+    /**
+     * A column an `ALTER` can carry. Only a generated one is ever refused, and only where the engine
+     * takes it in a `CREATE TABLE` but not afterwards.
+     */
+    assertColumnAddable(tableName, column) {
+        if (!column.generatedAs || this.features.generatedColumnAdd) {
+            return;
+        }
+        throw new TypeError(`${this.dialect}: Cannot add the computed column "${column.name}" to the existing table ` +
+            `"${tableName}" - this database only accepts one in a CREATE TABLE. Drop \`stored\` to have the ` +
+            'expression spliced into each statement instead, or recreate the table in a written migration.');
+    }
     assertPrimaryKeyAlterable(tableName) {
         if (this.features.primaryKeyAlter) {
             return;

package/dist/mongo/mongoDialect.js

@@ -17,7 +17,8 @@ export const mongoDialectFeatures = {
     renameColumn: false,
     foreignKeyAlter: false,
     primaryKeyAlter: false,
-    columnComment: false,
+    generatedColumnAdd: false,
+    commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
     supportsTimestamptz: false,

package/dist/mongo/mongodbQuerier.d.ts

@@ -1,6 +1,7 @@
 import type { Document, MongoClient } from 'mongodb';
 import { AbstractQuerier } from '../querier/index.js';
 import type { EntityData, ExtraOptions, IdValue, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import { type ParentPartition } from '../util/index.js';
 import type { MongoDialect } from './mongoDialect.js';
 export declare class MongodbQuerier extends AbstractQuerier {
     readonly dialect: MongoDialect;
@@ -10,6 +11,21 @@ export declare class MongodbQuerier extends AbstractQuerier {
     constructor(dialect: MongoDialect, conn: MongoClient, extra?: ExtraOptions | undefined);
     private execute;
     protected internalFindMany<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
+    /**
+     * Every parent's own bounded page. One `$unionWith` per parent after the first, so the whole page is
+     * one round trip - measured ~6x faster than a query each (11.0 ms -> 1.9 ms at 50 parents, 87.5 ms
+     * -> 14.1 ms at 500), because `execute` serializes on the session and a query each is N round trips
+     * rather than N concurrent ones.
+     *
+     * Both arms return documents with their own relations already filled, so this only chooses between
+     * them: leaving that to the caller once meant the arm that fills its own did it twice.
+     * [The design](../../../../architecture/populate-limits.md).
+     */
+    protected internalFindManyPerParent<E extends Document>(entity: Type<E>, q: Query<E>, { joins, parents }: ParentPartition): Promise<E[]>;
+    /** Every parent's page as one `$unionWith` pipeline. */
+    private readInOnePipeline;
+    /** A query each, for what one pipeline cannot carry. `internalFindMany` fills its own relations. */
+    private readEachInTurn;
     protected internalFindManyStream<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<E, void, unknown>;
     private buildScalarProjection;
     /** Build a MongoDB FindCursor with filter, projection, sort, skip, and limit from the query. */

package/dist/mongo/mongodbQuerier.js

@@ -2,7 +2,7 @@ import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { getMeta, idOf, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, queryChildrenOf, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
 /**
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
  * as *unlimited*, so a read that passed it straight to the driver came back with the whole
@@ -11,6 +11,12 @@ import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys,
 function asksForNoRows(q) {
     return q.$limit === 0;
 }
+/**
+ * What MongoDB accepts in one pipeline. Bisected against a real server: 1000 top-level stages are
+ * accepted and 1001 refused (`Pipeline length must be no longer than 1000 stages`), and a
+ * `$unionWith`'s own sub-pipeline stages do not count toward it.
+ */
+const MAX_PIPELINE_STAGES = 1000;
 export class MongodbQuerier extends AbstractQuerier {
     dialect;
     conn;
@@ -63,6 +69,49 @@ export class MongodbQuerier extends AbstractQuerier {
             return documents;
         });
     }
+    /**
+     * Every parent's own bounded page. One `$unionWith` per parent after the first, so the whole page is
+     * one round trip - measured ~6x faster than a query each (11.0 ms -> 1.9 ms at 50 parents, 87.5 ms
+     * -> 14.1 ms at 500), because `execute` serializes on the session and a query each is N round trips
+     * rather than N concurrent ones.
+     *
+     * Both arms return documents with their own relations already filled, so this only chooses between
+     * them: leaving that to the caller once meant the arm that fills its own did it twice.
+     * [The design](../../../../architecture/populate-limits.md).
+     */
+    async internalFindManyPerParent(entity, q, { joins, parents }) {
+        const queries = parents.map((parent) => queryChildrenOf(q, joins, parent));
+        // A vector sort needs a pipeline of its own shape, which only `internalFindMany` builds.
+        if (this.dialect.extractVectorSort(q.$sort)) {
+            return this.readEachInTurn(entity, queries);
+        }
+        const pipelines = queries.map((it) => this.dialect.aggregationPipeline(entity, it));
+        // Counted, not estimated: the leading branch's own length grows with every `$lookup` a populate
+        // adds, so a fixed parent budget would let a richer query overflow at the server instead.
+        const stages = (pipelines[0]?.length ?? 0) + pipelines.length - 1;
+        return stages > MAX_PIPELINE_STAGES
+            ? this.readEachInTurn(entity, queries)
+            : this.readInOnePipeline(entity, q, pipelines);
+    }
+    /** Every parent's page as one `$unionWith` pipeline. */
+    async readInOnePipeline(entity, q, pipelines) {
+        const meta = getMeta(entity);
+        const [first, ...rest] = pipelines;
+        const documents = await this.runPipeline(entity, meta, [
+            ...first,
+            ...rest.map((pipeline) => ({ $unionWith: { coll: meta.name, pipeline } })),
+        ]);
+        await this.fillToManyRelations(entity, documents, q.$populate);
+        return documents;
+    }
+    /** A query each, for what one pipeline cannot carry. `internalFindMany` fills its own relations. */
+    async readEachInTurn(entity, queries) {
+        const documents = [];
+        for (const query of queries) {
+            documents.push(...(await this.internalFindMany(entity, query)));
+        }
+        return documents;
+    }
     async *internalFindManyStream(entity, q, opts) {
         if (asksForNoRows(q)) {
             return;

package/dist/querier/abstractQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
-import { LoggerWrapper, type ParentJoin } from '../util/index.js';
+import { LoggerWrapper, type ParentJoin, type ParentPartition } from '../util/index.js';
 /**
  * Base class for all database queriers.
  * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
@@ -64,6 +64,14 @@ export declare abstract class AbstractQuerier implements Querier {
         $entity: Type<E>;
     }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
     findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryStreamProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
+    /**
+     * The children of every parent in `parents`, at most `$limit` each after `$skip` - what a to-many
+     * `$populate` carrying either one means. One statement, not one per parent.
+     *
+     * Abstract rather than defaulted: a default would be N queries, which is the N+1 that batched
+     * population exists to prevent, and it would be invisible to whichever backend forgot to override.
+     */
+    protected abstract internalFindManyPerParent<E extends object>(entity: Type<E>, q: Query<E>, partition: ParentPartition): Promise<E[]>;
     protected abstract internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncIterable<E>;
     /**
      * Find multiple records and return both the records and total count.
@@ -137,6 +145,15 @@ export declare abstract class AbstractQuerier implements Querier {
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
     private fillToManyThroughRelation;
     private fillToManyOneToMany;
+    /**
+     * The children of a whole page of parents, however the relation asked for them: one bounded branch
+     * per parent when it wants a share of its own, otherwise a single flat statement over an `IN (...)`
+     * list, which is both correct and cheaper.
+     *
+     * The one place that decision is made - a one-to-many and the junction of a many-to-many differ in
+     * what they query, never in how the page is spread over its parents.
+     */
+    private findChildrenOf;
     protected putChildrenInParents<E>(parents: E[], children: RawRow[], joins: readonly ParentJoin[], relKey: keyof E & string): void;
     protected insertRelations<E extends object>(entity: Type<E>, payload: E[]): Promise<void>;
     protected updateRelations<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<void>;

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
 import { assertSoleId, getMeta, idOf, soleIdOf } from '../entity/index.js';
-import { asSelectMap, augmentWhere, childrenOf, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, joinedRowKey, LoggerWrapper, parentJoins, parentRowKey, parentsIn, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, augmentWhere, childrenOf, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, joinedRowKey, LoggerWrapper, isBoundedPerParent, parentJoins, parentRowKey, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
@@ -299,22 +299,44 @@ export class AbstractQuerier {
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
         const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === targetColumn));
-        // A relation query names the target's columns, not the join table's, so the projection and the
-        // filter belong on the populate below - resolved there against the entity that has them. Spread
-        // onto the through query they asked `ItemTag` for `Tag`'s columns: `$where`/`$sort` failed with
-        // "no such column", and `$exclude` collided with the `$select` this builds.
-        const { $select: _select, $exclude: _exclude, $where: _where, ...throughQuery } = relationQuery;
-        const throughFounds = await this.findMany(throughEntity, {
-            ...throughQuery,
+        if (!targetRelKey) {
+            // Asserted rather than assumed: used as a key regardless, it spells the literal string
+            // `undefined`, and the statement asks the junction for a relation of that name.
+            throw new TypeError(`'${meta.name}.${relKey}' goes through '${throughMeta.name}', which declares no relation on its ` +
+                `'${targetColumn}' column. Give it one, so the target's rows can be read through it.`);
+        }
+        // A relation query names the target's columns, not the junction's, so its projection and filter
+        // belong on the populate below, resolved against the entity that has them. Spread onto the
+        // junction query instead they asked `ItemTag` for `Tag`'s columns and failed with "no such
+        // column".
+        //
+        // Ordering and paging split the other way: they describe the statement with one row per pairing,
+        // which is the junction's. Left on the populate they reached a to-one join, which rejects all
+        // four by name - so a many-to-many carrying any of them threw rather than paging.
+        //
+        // Those four are not a coincidence: they are exactly the clauses a joined relation rejects, for
+        // the same reason - each needs a statement with many rows per parent, which only the junction's
+        // is. The `satisfies` ties the two lists together, so a fifth clause added there fails to compile
+        // here rather than quietly staying on the populate and throwing again.
+        const { $sort, $limit, $skip, $distinct, ...targetQuery } = relationQuery;
+        const junctionClauses = {
+            $limit,
+            $skip,
+            $distinct,
+            // Qualified by the relation that reaches them, since the columns it names are the target's.
+            $sort: $sort && { [targetRelKey]: $sort },
+        };
+        const junctionQuery = {
             $select: joinedColumns(joins),
+            ...junctionClauses,
             $populate: {
                 [targetRelKey]: {
-                    ...relationQuery,
+                    ...targetQuery,
                     $required: true,
                 },
             },
-            $where: parentsIn(joins, payload),
-        });
+        };
+        const throughFounds = await this.findChildrenOf(throughEntity, junctionQuery, joins, payload, meta.fields);
         // The junction's own columns carried onto the target's row, which is where `putChildrenInParents`
         // reads them back from - a junction row holds the parent's key under `joined`, not under `parent`.
         const founds = throughFounds.map((it) => ({
@@ -336,9 +358,23 @@ export class AbstractQuerier {
             }
             delete exclude?.[joined];
         }
-        relationQuery.$where = { ...relationQuery.$where, ...parentsIn(joins, payload) };
-        const founds = await this.findMany(relEntity, relationQuery);
-        this.putChildrenInParents(payload, founds, joins, relKey);
+        this.putChildrenInParents(payload, await this.findChildrenOf(relEntity, relationQuery, joins, payload, meta.fields), joins, relKey);
+    }
+    /**
+     * The children of a whole page of parents, however the relation asked for them: one bounded branch
+     * per parent when it wants a share of its own, otherwise a single flat statement over an `IN (...)`
+     * list, which is both correct and cheaper.
+     *
+     * The one place that decision is made - a one-to-many and the junction of a many-to-many differ in
+     * what they query, never in how the page is spread over its parents.
+     */
+    async findChildrenOf(entity, query, joins, parents, parentFields) {
+        const founds = isBoundedPerParent(query)
+            ? await this.internalFindManyPerParent(entity, query, { joins, parents, parentFields })
+            : await this.findMany(entity, queryChildrenOfAll(query, joins, parents));
+        // Read back as rows rather than as the entity they hydrate to: what follows regroups them by the
+        // join columns, which a projected entity type does not carry.
+        return founds;
     }
     putChildrenInParents(parents, children, joins, relKey) {
         const childrenByParentId = {};

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,6 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import { type ParentPartition } from '../util/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
@@ -57,6 +58,19 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     private applyVectorTuning;
     protected internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
+    /**
+     * One bounded subquery per parent, concatenated with `UNION ALL`, so each parent gets its own
+     * `$limit` rather than a share of one. 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: SQLite rejects `ORDER BY`/`LIMIT` on a bare parenthesised
+     * compound branch, and the wrapper costs nothing elsewhere.
+     *
+     * Unlike {@link selectRows} this asserts no lock and tunes no vector search: `$lock` and
+     * `$candidates` describe the statement, and `parseRelationQueryValue` refuses both on a relation
+     * query, so neither can reach here.
+     */
+    protected internalFindManyPerParent<E extends object>(entity: Type<E>, q: Query<E>, partition: ParentPartition): Promise<E[]>;
     /**
      * One statement for both: the page carries its own unpaged total in an extra column. An empty page
      * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past

package/dist/querier/abstractSqlQuerier.js

@@ -104,6 +104,23 @@ export class AbstractSqlQuerier extends AbstractQuerier {
     async internalFindMany(entity, q, opts) {
         return this.hydrateRows(entity, q, await this.selectRows(entity, q, opts));
     }
+    /**
+     * One bounded subquery per parent, concatenated with `UNION ALL`, so each parent gets its own
+     * `$limit` rather than a share of one. 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: SQLite rejects `ORDER BY`/`LIMIT` on a bare parenthesised
+     * compound branch, and the wrapper costs nothing elsewhere.
+     *
+     * Unlike {@link selectRows} this asserts no lock and tunes no vector search: `$lock` and
+     * `$candidates` describe the statement, and `parseRelationQueryValue` refuses both on a relation
+     * query, so neither can reach here.
+     */
+    async internalFindManyPerParent(entity, q, partition) {
+        const ctx = this.dialect.createContext();
+        this.dialect.findPerParent(ctx, entity, q, partition);
+        return this.hydrateRows(entity, q, await this.all(ctx.sql, ctx.values));
+    }
     /**
      * One statement for both: the page carries its own unpaged total in an extra column. An empty page
      * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past

package/dist/schema/schemaAST.d.ts

@@ -150,7 +150,38 @@ export declare class SchemaAST implements ISchemaAST {
         indexCount: number;
     };
     /**
-     * Convert schema to a plain object for serialization/debugging.
-     */
-    toJSON(): object;
+     * The schema as a plain object, for serialization and debugging. The graph links are what is left
+     * out - they are cycles, and nothing else is: listing the fields to keep instead dropped every
+     * option a column had gained since, `defaultValue` and `enum` included.
+     */
+    toJSON(): {
+        tables: {
+            name: string;
+            columns: {
+                name: string;
+                type: import("./types.js").CanonicalType;
+                nullable: boolean;
+                defaultValue?: unknown;
+                isPrimaryKey: boolean;
+                isAutoIncrement: boolean;
+                isUnique: boolean;
+                enum?: import("./types.js").EnumValues;
+                generatedAs?: string;
+                comment?: string;
+            }[];
+            indexes: {
+                name: string;
+                columns: string[];
+                unique: boolean;
+            }[];
+        }[];
+        relationships: {
+            name: string;
+            type: RelationshipType;
+            from: string;
+            to: string;
+            onDelete: import("./types.js").ForeignKeyAction | undefined;
+            onUpdate: import("./types.js").ForeignKeyAction | undefined;
+        }[];
+    };
 }

package/dist/schema/schemaAST.js

@@ -385,20 +385,15 @@ export class SchemaAST {
         };
     }
     /**
-     * Convert schema to a plain object for serialization/debugging.
+     * The schema as a plain object, for serialization and debugging. The graph links are what is left
+     * out - they are cycles, and nothing else is: listing the fields to keep instead dropped every
+     * option a column had gained since, `defaultValue` and `enum` included.
      */
     toJSON() {
         return {
             tables: Array.from(this.tables.values()).map((t) => ({
                 name: t.name,
-                columns: Array.from(t.columns.values()).map((c) => ({
-                    name: c.name,
-                    type: c.type,
-                    nullable: c.nullable,
-                    isPrimaryKey: c.isPrimaryKey,
-                    isAutoIncrement: c.isAutoIncrement,
-                    isUnique: c.isUnique,
-                })),
+                columns: Array.from(t.columns.values()).map(({ table: _table, referencedBy: _referencedBy, references: _references, ...column }) => column),
                 indexes: t.indexes.map((i) => ({
                     name: i.name,
                     columns: i.entries.map((entry) => entry.column),

package/dist/schema/schemaASTBuilder.js

@@ -6,6 +6,8 @@
  * - Database introspection results (TableSchema[])
  */
 import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
+import { ddlText } from '../util/ddlExpression.util.js';
+import { computedExpression, isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
@@ -82,8 +84,8 @@ function addTableFromEntity(ctx, meta) {
         const field = fields[key];
         if (!field)
             continue;
-        // Skip virtual fields
-        if (field.virtual)
+        // An inlined expression has no column; a stored one is a column like any other.
+        if (isInlinedExpression(field))
             continue;
         const columnName = ctx.resolveColumnName(key, field);
         const type = resolveColumnCanonicalType(field);
@@ -99,6 +101,7 @@ function addTableFromEntity(ctx, meta) {
             isPrimaryKey,
             isAutoIncrement: isAutoIncrement(field, isSoleKey),
             isUnique: field.unique ?? false,
+            generatedAs: ddlText(computedExpression(field), `the computed column '${columnName}'`),
             comment: field.comment,
             enum: field.enum,
             table,