uql-orm 0.56.0 → 0.57.0

package/dist/mongo/mongodbQuerier.js

@@ -2,7 +2,7 @@ import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { fieldOf, getMeta, idOf, namesKey, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, queryChildrenOf, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, 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,12 +11,6 @@ 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;
@@ -34,109 +28,20 @@ export class MongodbQuerier extends AbstractQuerier {
         });
     }
     async internalFindMany(entity, q, opts) {
-        this.dialect.assertNoLock(q);
         if (asksForNoRows(q)) {
             return [];
         }
         return this.timed('internalFindMany', undefined, async () => {
-            const meta = getMeta(entity);
-            const vectorSort = this.dialect.extractVectorSort(q.$sort);
-            let documents;
-            if (vectorSort) {
-                const pipeline = this.buildVectorPipeline(entity, q, vectorSort, opts);
-                documents = await this.runPipeline(entity, meta, pipeline);
-                // to-many relations need their own query, exactly as in the non-vector path
-                await this.fillToManyRelations(entity, documents, q.$populate);
-            }
-            else {
-                // A relation condition needs `$lookup`, so it forces the aggregation path just like populating
-                // one does - and so does ordering by a relation, which reads what a lookup produced, and
-                // `$distinct`, which is a `$group`. A plain `find` cursor can express none of the four.
-                if (q.$distinct ||
-                    populatesRelations(meta, q.$populate) ||
-                    this.dialect.constrainsRelations(entity, q.$where) ||
-                    this.dialect.sortsRelations(entity, q.$sort)) {
-                    const pipeline = this.dialect.aggregationPipeline(entity, q, opts);
-                    documents = await this.runPipeline(entity, meta, pipeline);
-                    await this.fillToManyRelations(entity, documents, q.$populate);
-                }
-                else {
-                    const cursor = this.buildFindCursor(entity, q, opts);
-                    documents = await this.execute(() => cursor.toArray());
-                    documents = this.dialect.normalizeIds(meta, documents);
-                }
-            }
-            return documents;
+            const cursor = this.readCursor(entity, q, opts);
+            return this.dialect.normalizeIds(getMeta(entity), await this.execute(() => cursor.toArray()));
         });
     }
-    /**
-     * 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 is not a degraded fallback here, it is the only expressible form: `$vectorSearch`
-        // has to be the first stage of a pipeline, so it cannot be one of N `$unionWith` branches. Read a
-        // parent at a time it stays correct, because `buildVectorSearchStage` passes the query's `$where`
-        // - which carries this parent's key - into the search as its filter, so each parent gets its own
-        // nearest rather than a share of the collection's.
-        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 + 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;
         }
         const meta = getMeta(entity);
-        const { joinableKeys, toManyKeys } = getRelationRequestSummary(meta, q.$populate);
-        if (joinableKeys.length || toManyKeys.length) {
-            const parts = [];
-            if (joinableKeys.length)
-                parts.push(`joinable: ${joinableKeys.join(', ')}`);
-            if (toManyKeys.length)
-                parts.push(`toMany: ${toManyKeys.join(', ')}`);
-            throw new TypeError(`findManyStream does not load relations on MongoDB (${parts.join('; ')}). Use findMany with $populate (or legacy relation keys in $select) so aggregation and fill logic can run.`);
-        }
-        // An ordering that names a relation reads a field only a `$lookup` produces, and a stream has no
-        // pipeline to add one: MongoDB ranks every document equal and hands back natural order. `findMany`
-        // takes the aggregation path for exactly this case, so it is the one that can honor the clause.
-        if (this.dialect.sortsRelations(entity, q.$sort)) {
-            throw new TypeError('findManyStream does not order by a relation on MongoDB. Use findMany, whose aggregation pipeline adds the $lookup the ordering reads.');
-        }
-        const cursor = this.buildFindCursor(entity, q, opts);
+        const cursor = this.readCursor(entity, q, opts);
         try {
             for await (const doc of cursor) {
                 const [normalized] = this.dialect.normalizeIds(meta, [doc]);
@@ -147,6 +52,32 @@ export class MongodbQuerier extends AbstractQuerier {
             throw enrichError(err, this.logger, 'internalFindManyStream');
         }
     }
+    /**
+     * The cursor a read runs on: the aggregation pipeline for a clause only a stage can express - a
+     * lookup, a grouping, a vector search - and the plain `find` cursor for everything else. One routing
+     * for a read and a stream alike, so both load the same relations.
+     */
+    readCursor(entity, q, opts) {
+        this.dialect.assertNoLock(q);
+        const vectorSort = this.dialect.extractVectorSort(q.$sort);
+        const pipeline = vectorSort
+            ? this.buildVectorPipeline(entity, q, vectorSort, opts)
+            : this.readsThroughPipeline(entity, q) && this.dialect.aggregationPipeline(entity, q, opts);
+        return pipeline
+            ? this.collection(entity).aggregate(pipeline, { session: this.session })
+            : this.buildFindCursor(entity, q, opts);
+    }
+    /**
+     * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter
+     * or order by a relation, and the grouping `$distinct` is.
+     */
+    readsThroughPipeline(entity, q) {
+        return (!!q.$distinct ||
+            hasKeys(q.$count) ||
+            populatesRelations(getMeta(entity), q.$populate) ||
+            this.dialect.constrainsRelations(entity, q.$where) ||
+            this.dialect.sortsRelations(entity, q.$sort));
+    }
     buildScalarProjection(entity, q) {
         return this.dialect.select(entity, q.$select, q.$exclude);
     }
@@ -174,11 +105,6 @@ export class MongodbQuerier extends AbstractQuerier {
         }
         return cursor;
     }
-    /** Execute an aggregation pipeline and normalize `_id` → `id`. */
-    async runPipeline(entity, meta, pipeline) {
-        const documents = await this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
-        return this.dialect.normalizeIds(meta, documents);
-    }
     /**
      * Build an aggregation pipeline for vector similarity search.
      * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
@@ -191,7 +117,7 @@ export class MongodbQuerier extends AbstractQuerier {
             // that follow treat it like any other - and a query with no projection keeps its own columns.
             ...(scoreAlias ? [{ $addFields: { [scoreAlias]: { $meta: 'vectorSearchScore' } } }] : []),
             // `$vectorSearch` has already applied `$limit`, so the pager is its own.
-            ...this.dialect.readStages(entity, q, opts, {
+            ...this.dialect.readStages(entity, q, {
                 sort: this.dialect.sort(entity, vectorSort.regularSort, q.$populate),
                 project: scoreAlias ? { [scoreAlias]: 1 } : undefined,
             }),

package/dist/mssql/mssqlDialect.d.ts

@@ -1,3 +1,4 @@
+import { type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
 import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, Query, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, Type, VectorDistance, VectorMetric } from '../type/index.js';
 /**
@@ -65,6 +66,21 @@ export declare class MsSqlDialect extends MergeSqlDialect {
      * with room for the sign and the point.
      */
     protected selectFieldExpr(escapedColumn: string, field: FieldOptions): string;
+    /**
+     * The rows read as they are, `FOR JSON PATH` making the array. It nests a dotted key and leaves a
+     * null out, which is what unflattening a row with a joined column does, so a row with none keeps its
+     * nulls. `JSON_QUERY` keeps the array JSON inside a parent's own `FOR JSON`.
+     */
+    protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
+    /**
+     * What JSON would round or misread crosses it as text: a number exactly, style 3 keeping a float's
+     * 17 digits, bytes as hex, and a date in UTC with its offset, which is how `tedious` reads one.
+     */
+    protected readonly carriedFields: {
+        numeric: (expr: string) => string;
+        blob: (expr: string) => string;
+        date: (expr: string) => string;
+    };
     /** Named parameters, which `tedious` binds by name rather than by position. */
     placeholder(index: number): string;
     /** `OUTPUT` reads the written row out of the `INSERTED` pseudo-table rather than `RETURNING` it. */

package/dist/mssql/mssqlDialect.js

@@ -1,4 +1,6 @@
-import { COUNT_ALIAS, JSON_ELEM_ALIAS_PREFIX } from '../dialect/aliases.js';
+import { relationTermKey } from '../dialect/abstractSqlDialect.js';
+import { COUNT_ALIAS, JSON_ELEM_ALIAS } from '../dialect/aliases.js';
+import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
@@ -127,6 +129,26 @@ export class MsSqlDialect extends MergeSqlDialect {
         const exactDecimal = field.type === String && fieldOptionsToCanonical(field).category === 'decimal';
         return exactDecimal ? `CONVERT(NVARCHAR(41), ${escapedColumn})` : escapedColumn;
     }
+    /**
+     * The rows read as they are, `FOR JSON PATH` making the array. It nests a dotted key and leaves a
+     * null out, which is what unflattening a row with a joined column does, so a row with none keeps its
+     * nulls. `JSON_QUERY` keeps the array JSON inside a parent's own `FOR JSON`.
+     */
+    appendRelationArray(ctx, rows) {
+        const rowsCtx = ctx.createFragment();
+        const { terms } = this.read(rowsCtx, rows.entity, rows.query, { alias: rows.alias, json: true }, rows.joins);
+        const nulls = terms.some((term) => relationTermKey(term).includes('.')) ? '' : ', INCLUDE_NULL_VALUES';
+        ctx.append(`JSON_QUERY(COALESCE((${rowsCtx.sql} FOR JSON PATH${nulls}), '[]'))`);
+    }
+    /**
+     * What JSON would round or misread crosses it as text: a number exactly, style 3 keeping a float's
+     * 17 digits, bytes as hex, and a date in UTC with its offset, which is how `tedious` reads one.
+     */
+    carriedFields = {
+        numeric: (expr) => `CONVERT(VARCHAR(40), ${expr}, 3)`,
+        blob: (expr) => `${this.escape(BYTES_PREFIX)} + CONVERT(VARCHAR(MAX), ${expr}, 2)`,
+        date: (expr) => `CONVERT(VARCHAR(33), CAST(${expr} AS DATETIMEOFFSET), 127)`,
+    };
     /** Named parameters, which `tedious` binds by name rather than by position. */
     placeholder(index) {
         return `@p${index}`;
@@ -293,12 +315,12 @@ export class MsSqlDialect extends MergeSqlDialect {
             : `JSON_VALUE(${alias}.${this.#elem.value}, ${jsonPath(field)})`;
     }
     jsonAll(ctx, jsonField, value) {
-        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
         const conditions = value.map((val) => `EXISTS (SELECT 1 FROM OPENJSON(${jsonField}) ${alias} WHERE ${alias}.${this.#elem.value} = ${this.jsonScalarParam(ctx, val)})`);
         return `(${conditions.join(' AND ')})`;
     }
     jsonSize(ctx, jsonField, value) {
-        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
         return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`(SELECT COUNT(*) FROM OPENJSON(${jsonField}) ${alias})`), value));
     }
     /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
@@ -323,7 +345,7 @@ export class MsSqlDialect extends MergeSqlDialect {
      * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string.
      */
     jsonPullKey(ctx, expr, escapedCol, key, value) {
-        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
         const val = `${alias}.${this.#elem.value}`;
         // `OPENJSON` hands back a string element unquoted and a null one as SQL NULL, so each survivor is
         // re-encoded from its reported `type` before the array is put back together - concatenated raw,

package/dist/mysql/mysqlDialect.d.ts

@@ -6,4 +6,6 @@ export declare class MySqlDialect extends MysqlLikeSqlDialect {
      * "subject to removal in a future version"; aliasing the inserted row (8.0.19+) is its replacement.
      */
     protected readonly upsertNewRowAlias = "_uql_new";
+    /** A `SET_VAR` hint, which MySQL reads only in a statement's first `SELECT`. */
+    protected applySettings(sql: string, settings: readonly string[]): string;
 }

package/dist/mysql/mysqlDialect.js

@@ -7,4 +7,8 @@ export class MySqlDialect extends MysqlLikeSqlDialect {
      * "subject to removal in a future version"; aliasing the inserted row (8.0.19+) is its replacement.
      */
     upsertNewRowAlias = UPSERT_NEW_ROW_ALIAS;
+    /** A `SET_VAR` hint, which MySQL reads only in a statement's first `SELECT`. */
+    applySettings(sql, settings) {
+        return sql.replace('SELECT ', `SELECT /*+ ${settings.map((setting) => `SET_VAR(${setting})`).join(' ')} */ `);
+    }
 }

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, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
-import { LoggerWrapper, type ParentJoin, type ParentPartition } from '../util/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import { LoggerWrapper } from '../util/index.js';
 /** Base class for all database queriers. */
 export declare abstract class AbstractQuerier implements Querier {
     readonly extra?: ExtraOptions | undefined;
@@ -44,31 +44,20 @@ export declare abstract class AbstractQuerier implements Querier {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
     findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
-    protected abstract internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
     /**
-     * Stream records as an async iterable.
-     * Supports both entity-as-argument and entity-as-field patterns.
-     *
-     * **SQL:** Joinable relations (e.g. m1 / one-to-one) are still emitted in the streamed SQL; **to-many**
-     * relations are not filled (no second query) - requesting them throws a clear `TypeError`.
-     *
-     * **MongoDB:** Relation loading uses aggregation + follow-up queries in `findMany`; **streams use a plain
-     * find cursor**, so any requested relation keys in `$select` / `$populate` throw a `TypeError`.
-     *
-     * No `afterLoad` hooks on streamed rows.
+     * The rows matching `q`, each populated relation and `$count` read with them in the same statement
+     * or pipeline. [The design](../../../../architecture/relations-in-one-statement.md).
      */
-    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>(q: QueryStreamProjected<E, S, V, X, P> & {
-        $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>>;
+    protected abstract internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
     /**
-     * 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.
+     * Stream records as an async iterable, in both the entity-as-argument and entity-as-field patterns.
+     * Each row streams with its populated relations and counts, read by the same statement or pipeline
+     * `findMany` runs. No `afterLoad` hooks on streamed rows.
      */
-    protected abstract internalFindManyPerParent<E extends object>(entity: Type<E>, q: Query<E>, partition: ParentPartition): Promise<E[]>;
+    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, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
+        $entity: Type<E>;
+    }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
+    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, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
     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.
@@ -157,19 +146,6 @@ export declare abstract class AbstractQuerier implements Querier {
      * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
      */
     saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
-    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>;
     /**
@@ -207,6 +183,14 @@ export declare abstract class AbstractQuerier implements Querier {
     transaction<T>(callback: () => Promise<T>, opts?: TransactionOptions): Promise<T>;
     /** Whether anything at all - a global listener or the entity itself - handles `event`. */
     private hasHook;
+    /** Whether an `afterLoad` listens on the entity a read returns or on any relation it populated. */
+    private listensForLoad;
+    /**
+     * `afterLoad` for every row a read loaded, a populated relation's before the rows holding them, so a
+     * parent's hook sees its children as their own hooks left them. Rows are walked only where a hook
+     * listens.
+     */
+    private emitLoaded;
     /**
      * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
      * not report them in payload order. A row that no read row matches, or that two do, keeps

package/dist/querier/abstractQuerier.js

@@ -1,7 +1,6 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf, soleIdOf } from '../entity/index.js';
-import { asSelectMap, childrenOf, clone, dataKeyed, entityName, fillOnFields, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { childrenOf, clone, entityName, fillOnFields, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
-import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
  * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
  * `{ $where: { id } }`, and a key compared to `undefined` is *no filter*, so an unchecked one
@@ -130,14 +129,11 @@ export class AbstractQuerier {
     async findMany(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
         this.validateProjectionQuery(entity, q);
-        const founds = await this.internalFindMany(entity, withIdForCounts(entity, q), opts);
+        const founds = await this.internalFindMany(entity, q, opts);
         // Guarded here rather than only inside: awaiting a call that returns at once still costs every read
-        // a promise and a turn of the microtask queue, and most reads count nothing and hook nothing.
-        if (q.$count) {
-            await fillRelationCounts(this, entity, founds, q.$count);
-        }
-        if (this.hasHook(entity, 'afterLoad')) {
-            await this.emitHook(entity, 'afterLoad', founds);
+        // a promise and a turn of the microtask queue, and most reads hook nothing.
+        if (this.listensForLoad(entity, q.$populate)) {
+            await this.emitLoaded(entity, founds, q.$populate);
         }
         return founds;
     }
@@ -149,9 +145,10 @@ export class AbstractQuerier {
     async findManyAndCount(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
         this.validateProjectionQuery(entity, q);
-        const [founds, count] = await this.internalFindManyAndCount(entity, withIdForCounts(entity, q), opts);
-        await fillRelationCounts(this, entity, founds, q.$count);
-        await this.emitHook(entity, 'afterLoad', founds);
+        const [founds, count] = await this.internalFindManyAndCount(entity, q, opts);
+        if (this.listensForLoad(entity, q.$populate)) {
+            await this.emitLoaded(entity, founds, q.$populate);
+        }
         return [founds, count];
     }
     /**
@@ -342,123 +339,6 @@ export class AbstractQuerier {
         await (toInsert.length && toUpsert.length ? this.transaction(write) : write());
         return ids;
     }
-    async fillToManyRelations(entity, payload, populate) {
-        if (!payload.length) {
-            return;
-        }
-        const meta = getMeta(entity);
-        const relKeys = getRelationRequestSummary(meta, populate).toManyKeys;
-        for (const relKey of relKeys) {
-            const relOpts = relationOf(meta, relKey);
-            const relEntity = relOpts.entity();
-            const relationQuery = clone(parseRelationAtKey(relKey, populate).query);
-            if (relOpts.through) {
-                await this.fillToManyThroughRelation(payload, meta, relKey, relOpts, relationQuery);
-            }
-            else if (relOpts.cardinality === '1m') {
-                await this.fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity);
-            }
-        }
-    }
-    async fillToManyThroughRelation(payload, meta, relKey, relOpts, relationQuery) {
-        const joins = parentJoins(relOpts, meta.ids.length);
-        const [targetColumn] = targetKeyColumns(relOpts, meta.ids.length);
-        const throughEntity = relOpts.through();
-        const throughMeta = getMeta(throughEntity);
-        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === targetColumn));
-        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]: {
-                    ...targetQuery,
-                    $required: true,
-                },
-            },
-        };
-        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) => ({
-            ...it[targetRelKey],
-            ...Object.fromEntries(joins.map(({ joined }) => [joined, it[joined]])),
-        }));
-        this.putChildrenInParents(payload, founds, joins, relKey);
-    }
-    async fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity) {
-        const joins = parentJoins(relOpts, meta.ids.length);
-        // The FK is what putChildrenInParents groups on, so it outlives the relation's projection
-        // either way: added to a whitelisting `$select` (the raw-array form has nothing to augment),
-        // dropped from a subtractive `$exclude`. `relationQuery` is already a clone.
-        const select = asSelectMap(relationQuery.$select);
-        const exclude = relationQuery.$exclude;
-        for (const { joined } of joins) {
-            if (select && !select[joined]) {
-                select[joined] = true;
-            }
-            delete exclude?.[joined];
-        }
-        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 = 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) {
-            (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[rowKey(parent, parentKeys)] ?? []);
-        }
-    }
     async insertRelations(entity, payload) {
         const meta = getMeta(entity);
         const entries = payload.reduce((acc, it) => {
@@ -625,6 +505,32 @@ export class AbstractQuerier {
     hasHook(entity, event) {
         return (this.extra?.listeners?.some((listener) => listener[event]) || (getMeta(entity).hooks?.[event]?.length ?? 0) > 0);
     }
+    /** Whether an `afterLoad` listens on the entity a read returns or on any relation it populated. */
+    listensForLoad(entity, populate) {
+        if (this.hasHook(entity, 'afterLoad')) {
+            return true;
+        }
+        const meta = getMeta(entity);
+        return getRelationRequestSummary(meta, populate).requestedKeys.some((relKey) => this.listensForLoad(relationOf(meta, relKey).entity(), parseRelationAtKey(relKey, populate).query.$populate));
+    }
+    /**
+     * `afterLoad` for every row a read loaded, a populated relation's before the rows holding them, so a
+     * parent's hook sees its children as their own hooks left them. Rows are walked only where a hook
+     * listens.
+     */
+    async emitLoaded(entity, rows, populate) {
+        const meta = getMeta(entity);
+        for (const relKey of getRelationRequestSummary(meta, populate).requestedKeys) {
+            const relEntity = relationOf(meta, relKey).entity();
+            const relPopulate = parseRelationAtKey(relKey, populate).query.$populate;
+            if (this.listensForLoad(relEntity, relPopulate)) {
+                // A to-many holds a list and a to-one a row, which `flatMap` takes alike; an absent one adds none.
+                const loaded = rows.flatMap((row) => row[relKey] ?? []);
+                await this.emitLoaded(relEntity, loaded, relPopulate);
+            }
+        }
+        await this.emitHook(entity, 'afterLoad', rows);
+    }
     /**
      * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
      * not report them in payload order. A row that no read row matches, or that two do, keeps

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -31,7 +31,7 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
      * The connection outlives the call here: it is held until the iterator is drained or closed by a
      * `break`/`throw`. Abandoning the iterator instead leaks it until GC, so consume it in a `for await`.
      */
-    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): AsyncGenerator<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, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncGenerator<QueryFindResult<E, S, V, X, P, C>>;
     findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
     count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: QueryOptions): Promise<number>;
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,6 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { EntityData, ExtraOptions, 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 {
@@ -58,19 +57,6 @@ 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[]>;
     /**
      * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
      * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
@@ -107,9 +93,10 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     private hydrateAll;
     /**
-     * One row of {@link hydrateAll}. `visited` guards a populated graph that points back at itself, and
-     * makes a node two paths reach decode once. Only a populated relation can lead the walk back, so the
-     * guard is created at the first one a row carries: rows that populated nothing never allocate one.
+     * One row of {@link hydrateAll}. A related row arrives as its parent's statement read it: a to-one
+     * joined and unflattened, there only when its key is, since an unmatched join still fills a computed
+     * column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
+     * Each is an object of its own, so the walk reaches none twice.
      */
     private hydrateFields;
     /**