uql-orm 0.46.0 → 0.47.1

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, dataKeyed, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, 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,22 +358,38 @@ 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 = {};
+        const childrenByParentId = dataKeyed();
+        // Every joined column, so two children agreeing on one column of a composite key are not
+        // gathered under the same parent. Both column lists are read once, not once per row.
+        const joinedKeys = keyColumns(joins, 'joined');
+        const parentKeys = keyColumns(joins, 'parent');
         for (const child of children) {
-            // Every joined column, so two children agreeing on one column of a composite key are not
-            // gathered under the same parent.
-            (childrenByParentId[joinedRowKey(joins, child)] ??= []).push(child);
+            (childrenByParentId[rowKey(child, joinedKeys)] ??= []).push(child);
         }
         for (const parent of parents) {
             // `[]` rather than nothing for a parent with no children: a populated to-many is a list the
             // caller asked for, so it maps and counts without a guard, and its type can say so. An
             // unpopulated one stays absent, which is what tells the two apart.
-            parent[relKey] = (childrenByParentId[parentRowKey(joins, parent)] ?? []);
+            parent[relKey] = (childrenByParentId[rowKey(parent, parentKeys)] ?? []);
         }
     }
     async insertRelations(entity, payload) {

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/querier/relationCount.js

@@ -1,7 +1,7 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { getMeta, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
-import { asSelectMap, getKeys, joinedColumns, joinedRowKey, parentJoins, parentRowKey, parentsIn, targetKeyColumns, } from '../util/index.js';
+import { asSelectMap, dataKeyed, getKeys, joinedColumns, keyColumns, parentJoins, parentsIn, rowKey, targetKeyColumns, } from '../util/index.js';
 /**
  * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
  * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
@@ -50,7 +50,7 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         return;
     }
     const meta = getMeta(entity);
-    // The tallies come back keyed by the columns *this relation* joins from, so its `joins` are kept
+    // The tallies come back keyed by the columns *this relation* joins from, so those columns are kept
     // beside them: reading the parent through `meta.ids` instead matches only where the two coincide,
     // which is a to-many and nothing else.
     const counted = new Map();
@@ -62,14 +62,19 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         }
         const where = typeof value === 'object' ? value.$where : undefined;
         const joins = parentJoins(relOpts, meta.ids.length);
-        counted.set(relKey, { joins, byParent: await countPerParent(querier, relOpts, joins, payload, where) });
+        counted.set(relKey, {
+            parentKeys: keyColumns(joins, 'parent'),
+            byParent: await countPerParent(querier, relOpts, joins, payload, where),
+        });
     }
     for (const parent of payload) {
+        // A plain object, unlike the tallies below: this one is keyed by relation names the entity
+        // declares, not by data, and it is handed to the caller - who would meet a null prototype.
         const row = {};
-        for (const [relKey, { joins, byParent }] of counted) {
+        for (const [relKey, { parentKeys, byParent }] of counted) {
             // A parent the grouped result has no row for matched nothing, which is a zero rather than a
             // gap: `_count` names what the caller asked to count, so every key it asked for is present.
-            row[relKey] = byParent[parentRowKey(joins, parent)] ?? 0;
+            row[relKey] = byParent[rowKey(parent, parentKeys)] ?? 0;
         }
         parent[COUNT_RESULT_KEY] = row;
     }
@@ -105,11 +110,12 @@ async function groupedCount(querier, entity, joins, where) {
     const $agg = { [COUNT_ALIAS]: { $count: '*' } };
     const $group = joinedColumns(joins);
     const rows = await querier.aggregate(entity, { $group, $agg, $where: where });
-    const byParent = {};
+    const byParent = dataKeyed();
+    // Keyed by every joined column, which is how a tally finds the one parent whose whole key it
+    // matches - and how the rows an over-selecting `IN` brought back find no parent at all.
+    const joinedKeys = keyColumns(joins, 'joined');
     for (const row of rows) {
-        // Keyed by every joined column, which is how a tally finds the one parent whose whole key it
-        // matches - and how the rows an over-selecting `IN` brought back find no parent at all.
-        byParent[joinedRowKey(joins, row)] = Number(row[COUNT_ALIAS]);
+        byParent[rowKey(row, joinedKeys)] = Number(row[COUNT_ALIAS]);
     }
     return byParent;
 }

package/dist/type/queryWhere.d.ts

@@ -85,6 +85,16 @@ export type QueryWhereRootOperator<E> = {
  * {@link QueryWhereRootOperator} so a rename there breaks this union at compile time.
  */
 export type QueryNegateOp = keyof Pick<QueryWhereRootOperator<unknown>, '$not' | '$nor'>;
+/**
+ * The root operators that join their clauses instead of negating them, tied back to
+ * {@link QueryWhereRootOperator} on the same terms as {@link QueryNegateOp}.
+ */
+export type QueryJoinOp = keyof Pick<QueryWhereRootOperator<unknown>, '$and' | '$or'>;
+/**
+ * Every root operator whose value is a {@link QueryWhereArray} rather than a field condition: the
+ * two that join their clauses and the two that negate the join.
+ */
+export type QueryGroupOp = QueryJoinOp | QueryNegateOp;
 /**
  * Comparison operators accepted by `$size` for range queries: {@link QueryHavingOp} plus `$between`.
  * Strips `null` from picked operators since array size is always numeric.
@@ -320,7 +330,7 @@ type IsUntypedColumn<T> = [Scalar] extends [NonNullable<T>] ? true : false;
  */
 export type QueryWhereFieldValue<T> = T | (undefined extends T ? null : never) | (IsMany<T> extends true ? never : T[]) | QueryWhereFieldOperators<T> | QueryRaw;
 /**
- * query filter array - used for `$and`, `$or`, `$not`, `$nor` operators.
+ * query filter array - the value every {@link QueryGroupOp} takes.
  */
 export type QueryWhereArray<E> = (QueryWhereMap<E> | QueryRaw)[];
 /**

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>[];
@@ -35,13 +35,16 @@ export declare function targetKeyColumns(relOpts: Pick<RelationMeta, 'references
 /** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
 export declare function joinedColumns(joins: readonly ParentJoin[]): Record<string, true>;
 /**
- * A parent row keyed by the columns a relation joins *from*, and a child or tally row keyed by the
- * columns it carries that key in. The two halves of matching children to parents: they must agree on
- * every column, so each is read through `joins` rather than through the parent's own key list - which
- * is the same set only for a to-many, and silently a different one otherwise.
+ * One side's columns: `'parent'` for the columns a parent is keyed by, `'joined'` for the ones a
+ * child or tally row carries that key in. Matching the two halves means agreeing on every column, so
+ * each side is read through `joins` rather than through the parent's own key list - the same set only
+ * for a to-many, and silently a different one otherwise. `keyof ParentJoin` is what keeps the two
+ * sides from being spelled apart.
+ *
+ * Lifted out of `joins` once per relation, not once per row: {@link rowKey} takes the list and reads
+ * each row itself, so a page of children costs one key each and nothing else.
  */
-export declare function parentRowKey(joins: readonly ParentJoin[], parent: unknown): string;
-export declare function joinedRowKey(joins: readonly ParentJoin[], row: unknown): string;
+export declare function keyColumns(joins: readonly ParentJoin[], side: keyof ParentJoin): string[];
 /**
  * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
  * children in one statement.
@@ -51,6 +54,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

@@ -1,6 +1,5 @@
 import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_NUMBER_CLAUSES, } from '../type/query.js';
 import { getKeys, someKey } from './object.util.js';
-import { rowKey } from './rowKey.util.js';
 /**
  * Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. Takes
  * the one field it reads, so it answers for a relation being declared as well as for a resolved one.
@@ -37,19 +36,20 @@ export function targetKeyColumns(relOpts, parentKeyCount) {
 }
 /** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
 export function joinedColumns(joins) {
-    return Object.fromEntries(joins.map(({ joined }) => [joined, true]));
+    return Object.fromEntries(keyColumns(joins, 'joined').map((column) => [column, true]));
 }
 /**
- * A parent row keyed by the columns a relation joins *from*, and a child or tally row keyed by the
- * columns it carries that key in. The two halves of matching children to parents: they must agree on
- * every column, so each is read through `joins` rather than through the parent's own key list - which
- * is the same set only for a to-many, and silently a different one otherwise.
+ * One side's columns: `'parent'` for the columns a parent is keyed by, `'joined'` for the ones a
+ * child or tally row carries that key in. Matching the two halves means agreeing on every column, so
+ * each side is read through `joins` rather than through the parent's own key list - the same set only
+ * for a to-many, and silently a different one otherwise. `keyof ParentJoin` is what keeps the two
+ * sides from being spelled apart.
+ *
+ * Lifted out of `joins` once per relation, not once per row: {@link rowKey} takes the list and reads
+ * each row itself, so a page of children costs one key each and nothing else.
  */
-export function parentRowKey(joins, parent) {
-    return rowKey(joins.map(({ parent: key }) => read(parent, key)));
-}
-export function joinedRowKey(joins, row) {
-    return rowKey(joins.map(({ joined }) => read(row, joined)));
+export function keyColumns(joins, side) {
+    return joins.map((join) => join[side]);
 }
 /**
  * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
@@ -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/dist/util/rowKey.util.d.ts

@@ -1,9 +1,23 @@
 /**
- * A row's key as a string, for matching rows to each other in a `Map`.
+ * A row's key as a string, for matching rows to each other in a {@link dataKeyed} lookup.
+ *
+ * Reads the columns off the row rather than taking their values, because every caller matches a
+ * whole page of rows against one fixed column list: taking an array would make each of them build
+ * one per row, which is what a page of 250 rows paid 56 KB for.
  *
  * Values are normalized before joining, not stringified: `String(date)` is locale- and
  * timezone-dependent, so two equal dates could key apart, and a `Uint8Array` stringifies to its
- * bytes with commas. Every part is included, so two rows agreeing on one column of a composite key
- * are not treated as one row.
+ * bytes with commas. Every column is included, so two rows agreeing on one column of a composite
+ * key are not treated as one row.
+ */
+export declare function rowKey(row: unknown, columns: readonly string[]): string;
+/**
+ * A lookup keyed by data rather than by a name this code chose, so a key that spells `__proto__` or
+ * `constructor` is an ordinary entry instead of the prototype: on `{}` those threw when a bucket was
+ * pushed to, and a `_count` tally under one silently read back as an object. Cheaper than a `Map`
+ * here, and faster than `{}`, which walks the prototype chain on every miss.
+ *
+ * It carries none of `Object.prototype`, which no type can say: index it and spread it, but calling
+ * `hasOwnProperty` on one type-checks and throws.
  */
-export declare function rowKey(values: readonly unknown[]): string;
+export declare function dataKeyed<V>(): Record<string, V>;

package/dist/util/rowKey.util.js

@@ -1,15 +1,39 @@
 /** Separates the parts of a composite key: a unit separator, which no column value carries. */
 const KEY_SEPARATOR = '\u001f';
 /**
- * A row's key as a string, for matching rows to each other in a `Map`.
+ * A row's key as a string, for matching rows to each other in a {@link dataKeyed} lookup.
+ *
+ * Reads the columns off the row rather than taking their values, because every caller matches a
+ * whole page of rows against one fixed column list: taking an array would make each of them build
+ * one per row, which is what a page of 250 rows paid 56 KB for.
  *
  * Values are normalized before joining, not stringified: `String(date)` is locale- and
  * timezone-dependent, so two equal dates could key apart, and a `Uint8Array` stringifies to its
- * bytes with commas. Every part is included, so two rows agreeing on one column of a composite key
- * are not treated as one row.
+ * bytes with commas. Every column is included, so two rows agreeing on one column of a composite
+ * key are not treated as one row.
+ */
+export function rowKey(row, columns) {
+    const values = row;
+    let key = '';
+    for (let i = 0; i < columns.length; i++) {
+        if (i) {
+            key += KEY_SEPARATOR;
+        }
+        key += keyPart(values[columns[i]]);
+    }
+    return key;
+}
+/**
+ * A lookup keyed by data rather than by a name this code chose, so a key that spells `__proto__` or
+ * `constructor` is an ordinary entry instead of the prototype: on `{}` those threw when a bucket was
+ * pushed to, and a `_count` tally under one silently read back as an object. Cheaper than a `Map`
+ * here, and faster than `{}`, which walks the prototype chain on every miss.
+ *
+ * It carries none of `Object.prototype`, which no type can say: index it and spread it, but calling
+ * `hasOwnProperty` on one type-checks and throws.
  */
-export function rowKey(values) {
-    return values.map(keyPart).join(KEY_SEPARATOR);
+export function dataKeyed() {
+    return Object.create(null);
 }
 function keyPart(value) {
     if (value instanceof Date) {

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.1",
   "type": "module",
   "engines": {
     "node": ">=24"