uql-orm 0.47.0 → 0.47.1

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,4 @@
-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';
@@ -76,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.
@@ -134,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

@@ -100,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);
@@ -306,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);
@@ -366,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;
         }
@@ -405,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/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/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, isBoundedPerParent, parentJoins, parentRowKey, queryChildrenOfAll, 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';
 /**
@@ -377,17 +377,19 @@ export class AbstractQuerier {
         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/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

@@ -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.

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'

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.47.0",
+  "version": "0.47.1",
   "type": "module",
   "engines": {
     "node": ">=24"