uql-orm 0.46.0 → 0.47.1

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

@@ -1,4 +1,4 @@
-import type { DialectFeatures, DialectName, EntityMeta, ExtraOptions, FieldOptions, InsertIdSource, NamingStrategy, QueryOptions, QueryWhere, QueryWhereMap } from '../type/index.js';
+import type { DialectFeatures, DialectName, EntityMeta, ExtraOptions, FieldOptions, InsertIdSource, NamingStrategy, QueryGroupOp, QueryOptions, QueryWhere, QueryWhereArray, QueryWhereMap } from '../type/index.js';
 /**
  * Options for initializing a dialect.
  */
@@ -77,4 +77,38 @@ export declare abstract class AbstractDialect {
      * filters skipped. Recursion within one scope renders the returned map directly instead.
      */
     protected scopedWhereMap<E>(meta: EntityMeta<E>, where?: QueryWhere<E>, opts?: QueryOptions): QueryWhereMap<E>;
+    /**
+     * How each clause-grouping operator renders: which operator joins its clauses, and whether the
+     * group is negated afterwards - so `$not` is `NOT (a AND b)` and `$nor` is `NOT (a OR b)`. SQL
+     * negates the rendered group; MongoDB spells the same thing with its own `$nor`.
+     *
+     * Total over {@link QueryGroupOp}, so a fifth operator cannot reach a dialect without both being
+     * told how to render it.
+     */
+    protected static readonly GROUP_OPS: {
+        readonly $and: {
+            readonly join: '$and';
+            readonly negate: false;
+        };
+        readonly $or: {
+            readonly join: '$or';
+            readonly negate: false;
+        };
+        readonly $not: {
+            readonly join: '$and';
+            readonly negate: true;
+        };
+        readonly $nor: {
+            readonly join: '$or';
+            readonly negate: true;
+        };
+    };
+    /** Whether a `$where` key groups clauses, narrowing it for the renderers that read {@link GROUP_OPS}. */
+    protected static isGroupOp(key: string): key is QueryGroupOp;
+    /**
+     * A group operator's clauses, rejecting what the types do not cover: `/http` casts client JSON
+     * straight to `Query`, so a scalar can arrive where an array belongs. Shared so both backends
+     * refuse the same payload rather than one throwing and the other failing further in.
+     */
+    protected static groupClauses<E>(key: QueryGroupOp, val: QueryWhereArray<E>): QueryWhereArray<E>;
 }

package/dist/dialect/abstractDialect.js

@@ -88,4 +88,33 @@ export class AbstractDialect {
     scopedWhereMap(meta, where = {}, opts) {
         return applyFilters(meta, buildQueryWhereAsMap(meta, where), opts);
     }
+    /**
+     * How each clause-grouping operator renders: which operator joins its clauses, and whether the
+     * group is negated afterwards - so `$not` is `NOT (a AND b)` and `$nor` is `NOT (a OR b)`. SQL
+     * negates the rendered group; MongoDB spells the same thing with its own `$nor`.
+     *
+     * Total over {@link QueryGroupOp}, so a fifth operator cannot reach a dialect without both being
+     * told how to render it.
+     */
+    static GROUP_OPS = {
+        $and: { join: '$and', negate: false },
+        $or: { join: '$or', negate: false },
+        $not: { join: '$and', negate: true },
+        $nor: { join: '$or', negate: true },
+    };
+    /** Whether a `$where` key groups clauses, narrowing it for the renderers that read {@link GROUP_OPS}. */
+    static isGroupOp(key) {
+        return Object.hasOwn(AbstractDialect.GROUP_OPS, key);
+    }
+    /**
+     * A group operator's clauses, rejecting what the types do not cover: `/http` casts client JSON
+     * straight to `Query`, so a scalar can arrive where an array belongs. Shared so both backends
+     * refuse the same payload rather than one throwing and the other failing further in.
+     */
+    static groupClauses(key, val) {
+        if (val !== undefined && !Array.isArray(val)) {
+            throw TypeError(`${key} expects an array, got ${val === null ? 'null' : typeof val}`);
+        }
+        return val ?? [];
+    }
 }

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 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 QueryGroupOp, 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.
@@ -63,6 +76,15 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * shared for the same reason - see {@link SqlQueryContext}.
      */
     protected buildFragment(ctx: QueryContext, build: QueryBuildFn): string;
+    /**
+     * Each operand rendered into its own fragment, keeping only those that emitted SQL.
+     *
+     * Nothing reaches `ctx` until every one has rendered, because an operand that emits nothing - an
+     * empty `$and`, an `{}` entry - must leave behind neither a dangling separator nor a clause with no
+     * condition after it. How many terms really emit is also what decides the parentheses, which is why
+     * the caller counts what comes back rather than what it passed in.
+     */
+    protected renderOperands<T>(ctx: QueryContext, operands: readonly T[], render: (ctx: QueryContext, operand: T) => void): string[];
     addValue(values: unknown[], value: unknown): string;
     /**
      * Normalizes a parameter value for the database driver.
@@ -121,13 +143,12 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected selectRelationFields(ctx: QueryContext, joins: QueryJoins): void;
     protected selectRelationJoins<E>(ctx: QueryContext, meta: EntityMeta<E>, rootAlias: string, joins: QueryJoins): void;
     where<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
-    /** Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or` recursion). */
+    /** Renders a `$where` tree without applying entity filters (used for same-scope group-operator recursion). */
     protected renderWhere<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
     compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
-    protected compareLogicalOperator<E>(ctx: QueryContext, entity: Type<E>, key: '$and' | '$or' | '$not' | '$nor', val: QueryWhereArray<E>, opts: QueryComparisonOptions): void;
+    protected compareLogicalOperator<E>(ctx: QueryContext, entity: Type<E>, key: QueryGroupOp, val: QueryWhereArray<E>, opts: QueryComparisonOptions): void;
     /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
     private readonly escapedColumns;
-    private static readonly NEGATE_OP_MAP;
     private static readonly COMPARE_OP_MAP;
     /** What a `$near` says about the search itself; everything else in it is a bound. */
     private static readonly VECTOR_QUERY_KEYS;

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);
     }
@@ -72,6 +100,19 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         build(fragmentCtx);
         return fragmentCtx.sql;
     }
+    /**
+     * Each operand rendered into its own fragment, keeping only those that emitted SQL.
+     *
+     * Nothing reaches `ctx` until every one has rendered, because an operand that emits nothing - an
+     * empty `$and`, an `{}` entry - must leave behind neither a dangling separator nor a clause with no
+     * condition after it. How many terms really emit is also what decides the parentheses, which is why
+     * the caller counts what comes back rather than what it passed in.
+     */
+    renderOperands(ctx, operands, render) {
+        return operands
+            .map((operand) => this.buildFragment(ctx, (fragmentCtx) => render(fragmentCtx, operand)))
+            .filter((part) => part !== '');
+    }
     addValue(values, value) {
         values.push(this.normalizeValue(value));
         return this.placeholder(values.length);
@@ -278,40 +319,29 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // Filters are applied once, here at the scope entry point; recursion uses `renderWhere`.
         this.renderWhere(ctx, entity, this.scopedWhereMap(meta, where, opts), opts);
     }
-    /** Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or` recursion). */
+    /** Renders a `$where` tree without applying entity filters (used for same-scope group-operator recursion). */
     renderWhere(ctx, entity, where = {}, opts = {}) {
         const meta = getMeta(entity);
         const { clause = 'WHERE' } = opts;
-        where = buildQueryWhereAsMap(meta, where);
+        const whereMap = buildQueryWhereAsMap(meta, where);
         // An `undefined` value emits nothing, so it must not count towards the terms either: it decides
-        // both where the `AND`s go and whether this fragment needs parentheses.
-        const whereKeys = getKeys(where).filter((key) => where[key] !== undefined);
-        if (!whereKeys.length) {
+        // whether the keys below render as operands of an `AND`.
+        const whereKeys = getKeys(whereMap).filter((key) => whereMap[key] !== undefined);
+        // Each key is an operand of the `AND` joining them; a lone key emits this fragment verbatim, so
+        // it inherits this one's position instead.
+        const childOperand = whereKeys.length > 1 || opts.operand || clause === 'AND';
+        const childOpts = opts.operand === childOperand ? opts : { ...opts, operand: childOperand };
+        const parts = this.renderOperands(ctx, whereKeys, (fragmentCtx, key) => this.compare(fragmentCtx, entity, key, whereMap[key], childOpts));
+        if (!parts.length) {
             return;
         }
         if (clause) {
             ctx.append(` ${clause} `);
         }
-        const multipleKeys = whereKeys.length > 1;
         // This fragment joins its own keys with `AND`, so appending it after one (a JOIN's `ON`) needs no
         // parentheses - but anything nested in it is still an operand, since that may be an `OR`.
-        const parenthesize = multipleKeys && opts.operand;
-        if (parenthesize) {
-            ctx.append('(');
-        }
-        // Each key is an operand of the `AND` joining them; a lone key emits this fragment verbatim, so
-        // it inherits this one's position instead.
-        const childOperand = multipleKeys || opts.operand || clause === 'AND';
-        const childOpts = opts.operand === childOperand ? opts : { ...opts, operand: childOperand };
-        whereKeys.forEach((key, index) => {
-            if (index > 0) {
-                ctx.append(' AND ');
-            }
-            this.compare(ctx, entity, key, where[key], childOpts);
-        });
-        if (parenthesize) {
-            ctx.append(')');
-        }
+        const body = parts.join(' AND ');
+        ctx.append(parts.length > 1 && opts.operand ? `(${body})` : body);
     }
     compare(ctx, entity, key, val, opts = {}) {
         const meta = getMeta(entity);
@@ -338,7 +368,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             this.appendTextSearch(ctx, entity, meta, val);
             return;
         }
-        if (key === '$and' || key === '$or' || key === '$not' || key === '$nor') {
+        if (AbstractSqlDialect.isGroupOp(key)) {
             this.compareLogicalOperator(ctx, entity, key, val, opts);
             return;
         }
@@ -377,43 +407,29 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
     }
     compareLogicalOperator(ctx, entity, key, val, opts) {
-        const op = AbstractSqlDialect.NEGATE_OP_MAP.get(key) ?? key;
-        const negate = AbstractSqlDialect.NEGATE_OP_MAP.has(key);
-        if (val !== undefined && !Array.isArray(val)) {
-            // Not covered by the types: `/http` casts client JSON straight to `Query`, so this arrives untyped.
-            throw TypeError(`${key} expects an array, got ${val === null ? 'null' : typeof val}`);
-        }
-        const items = val ?? [];
+        const { join, negate } = AbstractSqlDialect.GROUP_OPS[key];
+        const items = AbstractSqlDialect.groupClauses(key, val);
         // With more than one item each is an operand of the operator joining them, so a compound item
         // parenthesizes itself and precedence never applies; a lone item is this group verbatim, so it
         // inherits the group's own position. A negation always makes its subject an operand.
         const childOperand = items.length > 1 || negate || opts.operand;
-        // Rendered before anything is appended, because an item that contributes no SQL (`{}`, an
-        // `undefined` entry) must leave no dangling separator behind, and how many terms this fragment
-        // really emits is what decides whether it needs parentheses.
-        const parts = items
-            .map((entry) => this.buildFragment(ctx, (fragmentCtx) => {
+        const parts = this.renderOperands(ctx, items, (fragmentCtx, entry) => {
             if (entry instanceof QueryRaw) {
                 this.getRawValue(fragmentCtx, { value: entry });
             }
             else if (entry) {
                 this.renderWhere(fragmentCtx, entity, entry, { prefix: opts.prefix, operand: childOperand, clause: false });
             }
-        }))
-            .filter((part) => part !== '');
+        });
         if (!parts.length) {
             return;
         }
-        const body = parts.join(op === '$or' ? ' OR ' : ' AND ');
+        const body = parts.join(join === '$or' ? ' OR ' : ' AND ');
         const parenthesize = parts.length > 1 && (opts.operand || negate);
         ctx.append((negate ? 'NOT ' : '') + (parenthesize ? `(${body})` : body));
     }
     /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
     escapedColumns = new WeakMap();
-    static NEGATE_OP_MAP = new Map([
-        ['$not', '$and'],
-        ['$nor', '$or'],
-    ]);
     static COMPARE_OP_MAP = new Map([
         ['$gt', ' > '],
         ['$gte', ' >= '],

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

@@ -43,11 +43,21 @@ export declare class MongoDialect extends AbstractDialect {
     /** Whether a `$where` constrains any relation, and so needs the aggregation path rather than a cursor. */
     constrainsRelations<E extends Document>(entity: Type<E>, where: QueryWhere<E> | undefined): boolean;
     /**
-     * Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or`
+     * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
      * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
      * given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
     private renderFilter;
+    /**
+     * Renders `$and`/`$or`/`$not`/`$nor` into `filter`. MongoDB has no root-level `$not`, so both
+     * negating operators become its `$nor`, which is exactly `NOT (a OR b)` - and by De Morgan that
+     * makes a `$nor` list its clauses directly while a `$not` wraps them in one `$and` first.
+     *
+     * Clauses that render to nothing are dropped and an empty operator emits no key at all: MongoDB
+     * rejects an empty `$and`/`$or`/`$nor` outright, where the SQL dialects contribute no term.
+     * Negations accumulate into the one `$nor`, since `NOT a AND NOT b` is `$nor: [a, b]`.
+     */
+    private appendLogicalOperator;
     /**
      * Emits the correlated `$lookup` for one relation condition and returns the condition that tests its
      * result: presence of a row for a plain relation filter, a comparison against the row count for

package/dist/mongo/mongoDialect.js

@@ -83,12 +83,12 @@ export class MongoDialect extends AbstractDialect {
         }
         const meta = getMeta(entity);
         const whereMap = buildQueryWhereAsMap(meta, where);
-        return someKey(whereMap, (key) => key === '$and' || key === '$or'
-            ? whereMap[key].some((it) => this.constrainsRelations(entity, it))
+        return someKey(whereMap, (key) => MongoDialect.isGroupOp(key)
+            ? (whereMap[key] ?? []).some((it) => this.constrainsRelations(entity, it))
             : Boolean(meta.relations[key]));
     }
     /**
-     * Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or`
+     * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
      * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
      * given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
@@ -99,13 +99,8 @@ export class MongoDialect extends AbstractDialect {
         for (const [rawKey, rawVal] of Object.entries(whereMap)) {
             let key = rawKey;
             let val = rawVal;
-            if (key === '$and' || key === '$or') {
-                filter[key] = val.map((filterIt) => {
-                    // A `QueryRaw` here would recurse forever: `buildQueryWhereAsMap` re-wraps it as
-                    // `{ $and: [raw] }`, which lands back on this branch.
-                    this.assertNoRaw(filterIt);
-                    return this.renderFilter(entity, filterIt, opts, lookups);
-                });
+            if (MongoDialect.isGroupOp(key)) {
+                this.appendLogicalOperator(filter, entity, key, val, opts, lookups);
             }
             else if (key === '$text') {
                 // MongoDB's text index declares which fields it covers, so `$fields` cannot narrow the search
@@ -137,6 +132,35 @@ export class MongoDialect extends AbstractDialect {
         }
         return filter;
     }
+    /**
+     * Renders `$and`/`$or`/`$not`/`$nor` into `filter`. MongoDB has no root-level `$not`, so both
+     * negating operators become its `$nor`, which is exactly `NOT (a OR b)` - and by De Morgan that
+     * makes a `$nor` list its clauses directly while a `$not` wraps them in one `$and` first.
+     *
+     * Clauses that render to nothing are dropped and an empty operator emits no key at all: MongoDB
+     * rejects an empty `$and`/`$or`/`$nor` outright, where the SQL dialects contribute no term.
+     * Negations accumulate into the one `$nor`, since `NOT a AND NOT b` is `$nor: [a, b]`.
+     */
+    appendLogicalOperator(filter, entity, key, val, opts, lookups) {
+        const { join, negate } = MongoDialect.GROUP_OPS[key];
+        const parts = MongoDialect.groupClauses(key, val)
+            .map((filterIt) => {
+            // A `QueryRaw` here would recurse forever: `buildQueryWhereAsMap` re-wraps it as
+            // `{ $and: [raw] }`, which lands back on this branch.
+            this.assertNoRaw(filterIt);
+            return this.renderFilter(entity, filterIt, opts, lookups);
+        })
+            .filter((part) => Object.keys(part).length > 0);
+        if (!parts.length) {
+            return;
+        }
+        if (!negate) {
+            filter[key] = parts;
+            return;
+        }
+        const negated = join === '$and' && parts.length > 1 ? [{ $and: parts }] : parts;
+        filter['$nor'] = [...(filter['$nor'] ?? []), ...negated];
+    }
     /**
      * Emits the correlated `$lookup` for one relation condition and returns the condition that tests its
      * result: presence of a row for a plain relation filter, a comparison against the row count for

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. */