uql-orm 0.55.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,112 +28,23 @@ 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 ?? 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;
         }
         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]) || [doc];
+                const [normalized] = this.dialect.normalizeIds(meta, [doc]);
                 yield normalized;
             }
         }
@@ -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,
             }),
@@ -257,7 +183,7 @@ export class MongodbQuerier extends AbstractQuerier {
         const founds = await this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
         // `normalizeIds` has already spread a compound `_id` back into its columns, so the settled rows
         // are named the same way every other driver names them.
-        return (this.dialect.normalizeIds(meta, founds) || []).map((found) => idOf(meta, found));
+        return this.dialect.normalizeIds(meta, founds).map((found) => idOf(meta, found));
     }
     async internalInsertMany(entity, rows) {
         return this.timed('internalInsertMany', undefined, async () => {
@@ -356,7 +282,7 @@ export class MongodbQuerier extends AbstractQuerier {
                 };
             });
             const res = await this.execute((session) => this.collection(entity).bulkWrite(operations, { session }));
-            const changes = (res.upsertedCount ?? 0) + (res.modifiedCount ?? 0);
+            const changes = res.upsertedCount + res.modifiedCount;
             // `upsertedIds` names only the documents inserted, keyed by operation index, so each lands on
             // its own row; an updated document's `_id` is read back by the conflict fields instead.
             const reported = payload.map((_, index) => {

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