uql-orm 0.46.0 → 0.47.0

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.

package/dist/dialect/abstractSqlDialect.js

@@ -1,9 +1,9 @@
 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 { 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';
@@ -55,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);
     }

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/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';
 /**
@@ -47,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/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/util/relationQuery.util.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
+import type { EntityMeta, FieldMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
 export type RelationRequestSummary<E> = {
     readonly requestedKeys: RelationKey<E>[];
     readonly joinableKeys: RelationKey<E>[];
@@ -51,6 +51,39 @@ export declare function joinedRowKey(joins: readonly ParentJoin[], row: unknown)
  * cheaper than the row-value comparison no engine spells the same way.
  */
 export declare function parentsIn(joins: readonly ParentJoin[], parents: readonly unknown[]): Record<string, unknown[]>;
+/**
+ * The parents a bounded to-many read fans out over: the rows themselves, the columns matching them to
+ * their children.
+ */
+export type ParentPartition = {
+    readonly joins: readonly ParentJoin[];
+    readonly parents: readonly unknown[];
+    /** The parent's own fields: a `LATERAL` row source has to spell its key column's type. */
+    readonly parentFields: Readonly<Record<string, FieldMeta | undefined>>;
+};
+/**
+ * Whether a to-many's own query asks for a share *per parent* rather than a slice of the whole page.
+ * Only `$limit`/`$skip` do: without one, a single flat statement over an `IN (...)` list is both
+ * correct and cheaper.
+ */
+export declare function isBoundedPerParent(query: Pick<RelationQuery, '$limit' | '$skip'>): boolean;
+/**
+ * `query` narrowed to one parent's children: what a single branch of a bounded per-parent read asks
+ * for. Shared by the backends so how the parent's filter merges into the relation's own is decided
+ * once - both spelled it out, and a rule that ever needs more than a spread would have to change twice.
+ */
+export declare function queryChildrenOf<E>(query: Query<E>, joins: readonly ParentJoin[], parent: unknown): Query<E>;
+/**
+ * `query` narrowed to the children of a whole page of parents, which is the flat read a relation with
+ * no share of its own takes. Over-selects on a composite key exactly as {@link parentsIn} does.
+ */
+export declare function queryChildrenOfAll<E>(query: Query<E>, joins: readonly ParentJoin[], parents: readonly unknown[]): Query<E>;
+/**
+ * `query` with `filter` merged into its own `$where`: the one rule for narrowing a relation's query to
+ * the parents it is being read for, whether the filter names their keys as values or, for a correlated
+ * shape, as a reference to a row source.
+ */
+export declare function queryNarrowedTo<E>(query: Query<E>, filter: Record<string, unknown>): Query<E>;
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
  * column a single key contributes, an OR of key maps for several.

package/dist/util/relationQuery.util.js

@@ -62,6 +62,45 @@ export function joinedRowKey(joins, row) {
 export function parentsIn(joins, parents) {
     return Object.fromEntries(joins.map(({ parent, joined }) => [joined, parents.map((it) => read(it, parent))]));
 }
+/**
+ * Whether a to-many's own query asks for a share *per parent* rather than a slice of the whole page.
+ * Only `$limit`/`$skip` do: without one, a single flat statement over an `IN (...)` list is both
+ * correct and cheaper.
+ */
+export function isBoundedPerParent(query) {
+    return query.$limit !== undefined || query.$skip !== undefined;
+}
+/**
+ * The `$where` naming exactly one parent's children: every joined column equal to that parent's value.
+ * What a per-parent bounded read filters each of its branches by, and the composite half of
+ * {@link childrenOf}.
+ */
+function childOf(joins, parent) {
+    return Object.fromEntries(joins.map(({ parent: key, joined }) => [joined, read(parent, key)]));
+}
+/**
+ * `query` narrowed to one parent's children: what a single branch of a bounded per-parent read asks
+ * for. Shared by the backends so how the parent's filter merges into the relation's own is decided
+ * once - both spelled it out, and a rule that ever needs more than a spread would have to change twice.
+ */
+export function queryChildrenOf(query, joins, parent) {
+    return queryNarrowedTo(query, childOf(joins, parent));
+}
+/**
+ * `query` narrowed to the children of a whole page of parents, which is the flat read a relation with
+ * no share of its own takes. Over-selects on a composite key exactly as {@link parentsIn} does.
+ */
+export function queryChildrenOfAll(query, joins, parents) {
+    return queryNarrowedTo(query, parentsIn(joins, parents));
+}
+/**
+ * `query` with `filter` merged into its own `$where`: the one rule for narrowing a relation's query to
+ * the parents it is being read for, whether the filter names their keys as values or, for a correlated
+ * shape, as a reference to a row source.
+ */
+export function queryNarrowedTo(query, filter) {
+    return { ...query, $where: { ...query.$where, ...filter } };
+}
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
  * column a single key contributes, an OR of key maps for several.
@@ -74,9 +113,7 @@ export function childrenOf(joins, parentIds) {
     if (joins.length === 1) {
         return { [first.joined]: parentIds };
     }
-    return {
-        $or: parentIds.map((id) => Object.fromEntries(joins.map(({ parent, joined }) => [joined, read(id, parent)]))),
-    };
+    return { $or: parentIds.map((id) => childOf(joins, id)) };
 }
 function read(row, key) {
     return row[key];

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "type": "module",
   "engines": {
     "node": ">=24"