uql-orm 0.27.0 → 0.28.1

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -61,7 +61,6 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      */
     protected indexAccessMethod(index: IndexSchema): string;
     protected numericCast(expr: string): string;
-    protected ilikeExpr(f: string, ph: string): string;
     protected neExpr(field: string, ph: string): string;
     /** How a surviving element is fed back into the array a `$pull` rebuilds. */
     protected jsonPullElem(alias: string): string;

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -112,9 +112,6 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     numericCast(expr) {
         return `CAST(${expr} AS DECIMAL)`;
     }
-    ilikeExpr(f, ph) {
-        return `${f} LIKE ${ph}`;
-    }
     neExpr(field, ph) {
         // MySQL/MariaDB null-safe inequality: true when values differ or one side is NULL.
         return `NOT (${field} <=> ${ph})`;

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -63,7 +63,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected jsonElemFrom(jsonField: string, fields: readonly string[], alias: string, asJson?: boolean): string;
     protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
     protected get regexpOp(): string;
-    protected ilikeExpr(f: string, ph: string): string;
+    protected readonly caseInsensitiveMatch = "ilike";
     protected get neOp(): string;
     protected formatIn(ctx: QueryContext, values: unknown[], negate: boolean): string;
     protected numericCast(expr: string): string;

package/dist/dialect/pgLikeSqlDialect.js

@@ -155,9 +155,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     get regexpOp() {
         return '~';
     }
-    ilikeExpr(f, ph) {
-        return `${f} ILIKE ${ph}`;
-    }
+    caseInsensitiveMatch = 'ilike';
     get neOp() {
         return 'IS DISTINCT FROM';
     }

package/dist/dialect/queryContext.d.ts

@@ -8,6 +8,7 @@ import type { QueryContext, QueryDialect } from '../type/index.js';
  */
 export declare class SqlQueryContext implements QueryContext {
     readonly dialect: QueryDialect;
+    private readonly statement?;
     private readonly sqlChunks;
     private readonly params;
     private aliasCounter;
@@ -17,8 +18,11 @@ export declare class SqlQueryContext implements QueryContext {
      * fragment context built via {@link AbstractSqlDialect.buildFragment}, so a bound value's
      * placeholder is numbered correctly against the real query from the moment it's added, rather
      * than needing to be reconciled after the fact.
+     * @param statement The context this one renders a fragment of, which owns the alias counter: a
+     * fragment is part of one statement, so its aliases have to be unique across the whole of it.
      */
-    constructor(dialect: QueryDialect, params?: unknown[]);
+    constructor(dialect: QueryDialect, params?: unknown[], statement?: SqlQueryContext | undefined);
+    createFragment(): QueryContext;
     /**
      * Appends raw SQL string fragments to the query.
      *
@@ -43,10 +47,8 @@ export declare class SqlQueryContext implements QueryContext {
      */
     pushValue(...values: unknown[]): this;
     /**
-     * A fresh alias unique within this context, e.g. `nextAlias('_uql_elem')` -> `'_uql_elem_1'`,
-     * `'_uql_elem_2'`, ... A fragment context (see the constructor) counts independently of the `ctx`
-     * it shares values with - fine today since no fragment-building hook also generates aliases, but
-     * worth widening (share this counter too, the same way `params` is shared) if one ever does.
+     * A fresh alias unique within the statement being built, e.g. `nextAlias('_uql_elem')` ->
+     * `'_uql_elem_1'`, `'_uql_elem_2'`, ...
      */
     nextAlias(prefix: string): string;
     /**

package/dist/dialect/queryContext.js

@@ -7,6 +7,7 @@
  */
 export class SqlQueryContext {
     dialect;
+    statement;
     sqlChunks = [];
     params;
     aliasCounter = 0;
@@ -16,11 +17,17 @@ export class SqlQueryContext {
      * fragment context built via {@link AbstractSqlDialect.buildFragment}, so a bound value's
      * placeholder is numbered correctly against the real query from the moment it's added, rather
      * than needing to be reconciled after the fact.
+     * @param statement The context this one renders a fragment of, which owns the alias counter: a
+     * fragment is part of one statement, so its aliases have to be unique across the whole of it.
      */
-    constructor(dialect, params = []) {
+    constructor(dialect, params = [], statement) {
         this.dialect = dialect;
+        this.statement = statement;
         this.params = params;
     }
+    createFragment() {
+        return new SqlQueryContext(this.dialect, this.params, this.statement ?? this);
+    }
     /**
      * Appends raw SQL string fragments to the query.
      *
@@ -56,13 +63,11 @@ export class SqlQueryContext {
         return this;
     }
     /**
-     * A fresh alias unique within this context, e.g. `nextAlias('_uql_elem')` -> `'_uql_elem_1'`,
-     * `'_uql_elem_2'`, ... A fragment context (see the constructor) counts independently of the `ctx`
-     * it shares values with - fine today since no fragment-building hook also generates aliases, but
-     * worth widening (share this counter too, the same way `params` is shared) if one ever does.
+     * A fresh alias unique within the statement being built, e.g. `nextAlias('_uql_elem')` ->
+     * `'_uql_elem_1'`, `'_uql_elem_2'`, ...
      */
     nextAlias(prefix) {
-        return `${prefix}_${++this.aliasCounter}`;
+        return this.statement ? this.statement.nextAlias(prefix) : `${prefix}_${++this.aliasCounter}`;
     }
     /**
      * Returns the complete SQL query string by joining all accumulated chunks.

package/dist/dialect/queryJoins.d.ts

@@ -0,0 +1,53 @@
+import type { EntityMeta, Query, QuerySortMap, RelationMeta, Type } from '../type/index.js';
+import { type RelationQuery } from '../util/index.js';
+/**
+ * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
+ * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
+ * `$sort` needs - which joins the same way, filters included, but adds nothing to the result.
+ */
+export type QueryJoin = {
+    /** The relation key on its parent, which is how MongoDB names the field a `$lookup` adds. */
+    readonly key: string;
+    /** Dotted path from the queried entity, which is how the SQL dialects alias the join. */
+    readonly path: string;
+    readonly entity: Type<object>;
+    readonly meta: EntityMeta<object>;
+    readonly relation: RelationMeta;
+    readonly query: RelationQuery;
+    readonly required: boolean;
+    readonly projected: boolean;
+    /** `undefined` at the first level, where the parent is the queried entity itself. */
+    readonly parent: QueryJoin | undefined;
+};
+/**
+ * Every relation a statement joins, in the order the joins are emitted. Flat rather than a tree: a
+ * parent is always resolved before its children, so iterating it in order visits them the same way
+ * recursion would, and looking an alias up - which is what `$sort` needs - is a plain `get`.
+ */
+export type QueryJoins = ReadonlyMap<string, QueryJoin>;
+export declare const NO_JOINS: QueryJoins;
+/** What rendering an `ORDER BY` needs beyond the map itself: where columns live, and what is joined. */
+export type QuerySortOptions = {
+    /** Alias the queried entity's own columns are qualified by, when the statement qualifies them. */
+    readonly prefix?: string;
+    readonly joins?: QueryJoins;
+    readonly distinct?: boolean;
+};
+/**
+ * What the statement joins, from the whole query rather than from `$populate` alone: ordering by a
+ * related column needs that relation joined just as much as selecting it does. The two sources meet
+ * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
+ * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ */
+export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>): QueryJoins;
+/**
+ * The join an ordering may address at `path`, with the relation's own sort map, or why it may not.
+ * Every backend answers this the same way - a to-many has no single value to order by, a relation
+ * sort is a map of that relation's fields, and the path has to be joined - so it is answered once
+ * here rather than per dialect, where the three checks had already drifted apart twice. Only the
+ * remedy for an unjoined path is the dialect's business, which is what `unjoinable` says.
+ */
+export declare function resolveSortableJoin(relation: RelationMeta, path: string, value: unknown, joins: QueryJoins, unjoinable: string): {
+    readonly join: QueryJoin;
+    readonly sort: QuerySortMap<object>;
+};

package/dist/dialect/queryJoins.js

@@ -0,0 +1,91 @@
+import { getMeta } from '../entity/index.js';
+import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey, } from '../util/index.js';
+export const NO_JOINS = new Map();
+/**
+ * What the statement joins, from the whole query rather than from `$populate` alone: ordering by a
+ * related column needs that relation joined just as much as selecting it does. The two sources meet
+ * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
+ * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ */
+export function resolveQueryJoins(meta, q) {
+    if (!q.$populate && !q.$sort) {
+        return NO_JOINS;
+    }
+    const joins = new Map();
+    addPopulateJoins(joins, meta, q.$populate);
+    addSortJoins(joins, meta, q.$sort);
+    return joins;
+}
+function addJoin(joins, parent, key, relation, query, required, projected) {
+    const path = parent ? `${parent.path}.${key}` : key;
+    const existing = joins.get(path);
+    // `$populate` runs first, so an already-joined relation keeps its columns and its `$required`
+    // INNER join: sorting by it asks for nothing a populated join does not already provide.
+    if (existing) {
+        return existing;
+    }
+    const entity = relation.entity();
+    const join = {
+        key,
+        path,
+        entity,
+        meta: getMeta(entity),
+        relation,
+        query,
+        required,
+        projected,
+        parent,
+    };
+    joins.set(path, join);
+    return join;
+}
+function addPopulateJoins(joins, meta, populate, parent) {
+    for (const key of getRelationRequestSummary(meta, populate).joinableKeys) {
+        const relation = meta.relations[key];
+        if (!relation)
+            continue;
+        const { query, required } = parseRelationAtKey(key, populate);
+        const join = addJoin(joins, parent, key, relation, query, required, true);
+        addPopulateJoins(joins, join.meta, query.$populate, join);
+    }
+}
+function addSortJoins(joins, meta, sort, parent) {
+    if (!sort) {
+        return;
+    }
+    for (const key of getKeys(sort)) {
+        const relation = meta.relations[key];
+        const value = sort[key];
+        // A to-many, or a value that is not a map of the relation's own fields, cannot be joined and is
+        // reported where the `ORDER BY` is rendered - the one place that knows how to name it.
+        if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
+            continue;
+        }
+        const join = addJoin(joins, parent, key, relation, {}, false, false);
+        addSortJoins(joins, join.meta, value, join);
+    }
+}
+/**
+ * The join an ordering may address at `path`, with the relation's own sort map, or why it may not.
+ * Every backend answers this the same way - a to-many has no single value to order by, a relation
+ * sort is a map of that relation's fields, and the path has to be joined - so it is answered once
+ * here rather than per dialect, where the three checks had already drifted apart twice. Only the
+ * remedy for an unjoined path is the dialect's business, which is what `unjoinable` says.
+ */
+export function resolveSortableJoin(relation, path, value, joins, unjoinable) {
+    if (isToManyRelation(relation)) {
+        throw new TypeError(`cannot $sort by '${path}': a parent has many of them, so there is no single value to order by. Sort the relation's own rows inside $populate instead.`);
+    }
+    if (!isSortMap(value)) {
+        throw new TypeError(`$sort by relation '${path}' expects a map of its fields, got ${String(value)}`);
+    }
+    const join = joins.get(path);
+    if (!join) {
+        throw new TypeError(unjoinable);
+    }
+    return { join, sort: value };
+}
+/** A nested `$sort` map, as opposed to a direction or a vector search. */
+function isSortMap(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && !('$vector' in value);
+}

package/dist/dialect/vectorSqlDialect.d.ts

@@ -22,7 +22,7 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      */
     protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
-    abstract escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
+    abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
      * Resolve common parameters for a vector similarity ORDER BY expression.
      * Shared by all dialect overrides of `appendVectorSort`.

package/dist/entity/metadata/definition.js

@@ -1,4 +1,4 @@
-import { getKeys, hasKeys, lowerFirst, normalizeIndexColumn, upperFirst } from '../../util/index.js';
+import { getKeys, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 // Held on `globalThis` via the global symbol registry so a single metadata map survives multiple
 // evaluations of this module (HMR, duplicated/federated bundles, ESM+CJS dual-loading). Version-suffixed
@@ -225,7 +225,7 @@ function fillOwningSide(at, meta, relKey, relOpts) {
         ];
         return;
     }
-    if (relOpts.cardinality === '1m' || relOpts.cardinality === 'mm') {
+    if (isToManyRelation(relOpts)) {
         throw new TypeError(`${at} is a to-many relation with no way to join: it needs 'mappedBy' (the field on the other side), ` +
             "'through' (a junction entity), or 'references' (the columns).");
     }

package/dist/mongo/mongoDialect.d.ts

@@ -1,7 +1,15 @@
 import { type Document, type Filter, ObjectId, type Sort, type UpdateFilter } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import type { DialectFeatures, EntityMeta, FieldValue, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
-import { type CallbackKey, type RelationRequestSummary } from '../util/index.js';
+import type { DialectFeatures, EntityMeta, FieldValue, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPopulate, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
+import { type CallbackKey } from '../util/index.js';
+/** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
+type MongoReadStages = {
+    /** Ordering, which runs after the lookups when it reads one of their fields. */
+    readonly sort?: Sort;
+    readonly pager?: MongoAggregationPipelineEntry<Document>[];
+    /** Keys merged into the query's projection, when it has one: a vector search's score. */
+    readonly project?: Record<string, 1>;
+};
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export declare const mongoDialectFeatures: DialectFeatures;
 export declare class MongoDialect extends AbstractDialect {
@@ -95,32 +103,54 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private transformElemMatch;
     select<E extends Document>(entity: Type<E>, select?: QuerySelectValue<E>, exclude?: QueryExclude<E>): Record<string, 0 | 1>;
-    sort<E extends Document>(entity: Type<E>, sort?: QuerySortMap<E>): Sort;
+    /**
+     * The `$sort` stage. A relation key reads the document a `$lookup` unwound onto the parent, so - as
+     * on the SQL dialects - it is only addressable when the statement joins that relation. Here that
+     * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
+     * added for the sort alone would change what the caller gets back.
+     */
+    sort<E extends Document>(entity: Type<E>, sort?: QuerySortMap<E>, populate?: QueryPopulate<E>): Sort;
+    /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
+    private collectSort;
+    /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
+    sortsRelations<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): boolean;
     /**
      * Aggregate results are keyed by `$group`/`$agg` alias rather than by column, so an aggregate
      * `$sort` addresses those aliases as-is - the same reason the SQL dialects sort by alias there.
      */
     private aliasSort;
-    /** Shared direction normalization; `mapKey` decides whether keys are columns or aggregate aliases. */
-    private sortBy;
     /**
      * {@link columnOf} for a possibly dotted key: only the root is a field key, the rest addresses an
      * embedded path (`kind.city` -> `<kind's column>.city`).
      */
     private pathOf;
-    aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, relationSummary?: RelationRequestSummary<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
+    aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
+    /**
+     * What a read runs after its entry stage, in the one order that works: the lookups its relations
+     * need, the ordering and paging that may read them, and the projection last of all - it names the
+     * fields the lookups add, and no stage after it could read what it dropped.
+     *
+     * Shared by the plain pipeline and the `$vectorSearch` one, which each used to spell the order out
+     * for themselves and each got a different part of it wrong.
+     */
+    readStages<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions, extra?: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
     /**
      * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
      * the joined documents, and the `_id` a to-many fill groups children by. It goes last, after the
      * lookups have read the join keys - projecting any earlier is what used to leave `$populate`
      * empty, and is why the pipeline emitted no projection at all and returned every column.
      */
-    pipelineProjection<E extends Document>(entity: Type<E>, q: Query<E>, relationSummary?: RelationRequestSummary<E>): Record<string, 0 | 1> | undefined;
+    pipelineProjection<E extends Document>(entity: Type<E>, q: Query<E>): Record<string, 0 | 1> | undefined;
     /**
      * `$lookup`/`$unwind` stages for the joinable relations a query populates. Shared by the plain
      * aggregation pipeline and the `$vectorSearch` one, so relations load the same way in both.
      */
-    relationStages<E extends Document>(entity: Type<E>, q: Query<E>, relationSummary?: RelationRequestSummary<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
+    relationStages<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
+    /**
+     * The `$lookup`/`$unwind` pair for each relation joined below `parent`, its own relations nested
+     * inside its pipeline and resolved before the projection that reads them.
+     */
+    private lookupStages;
     /**
      * The correlated join for a single-valued or one-to-many relation. MongoDB runs a lookup's `pipeline`
      * after its own localField/foreignField match, so the target's filters layer on top of the join

package/dist/mongo/mongoDialect.js

@@ -1,8 +1,9 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
+import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
 import { getMeta } from '../entity/index.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, buildQueryWhereAsMap, buildSortMap, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, } from '../util/index.js';
+import { asSelectMap, buildQueryWhereAsMap, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -361,27 +362,49 @@ export class MongoDialect extends AbstractDialect {
         }
         return projection;
     }
-    sort(entity, sort) {
+    /**
+     * The `$sort` stage. A relation key reads the document a `$lookup` unwound onto the parent, so - as
+     * on the SQL dialects - it is only addressable when the statement joins that relation. Here that
+     * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
+     * added for the sort alone would change what the caller gets back.
+     */
+    sort(entity, sort, populate) {
         const meta = getMeta(entity);
-        return this.sortBy(sort, (key) => {
-            if (meta.relations[key]) {
-                throw new TypeError(`sorting by relation '${key}' is not supported on MongoDB`);
+        const normalized = {};
+        // The same join set the lookups are built from, so what an `ORDER BY` may address and what the
+        // pipeline actually produces cannot drift apart.
+        this.collectSort(meta, sort, resolveQueryJoins(meta, { $populate: populate }), '', normalized);
+        return normalized;
+    }
+    /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
+    collectSort(meta, sort, joins, path, out) {
+        for (const [key, value] of Object.entries(sort ?? {})) {
+            const relation = meta.relations[key];
+            if (!relation) {
+                out[path + this.pathOf(meta, key)] = sortDirection(value);
+                continue;
             }
-            return this.pathOf(meta, key);
-        });
+            // A `$lookup` is what puts the relation's fields on the document, and only `$populate` asks for
+            // one: ordering by a relation nothing looked up reads a field that is not there, which MongoDB
+            // ranks as all-equal rather than rejecting. The SQL dialects can add the join themselves.
+            const relPath = `${path}${key}`;
+            const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, value, joins, `cannot $sort by relation '${relPath}' on MongoDB unless it is populated: only $populate adds its fields to the document`);
+            this.collectSort(join.meta, relationSort, joins, `${relPath}.`, out);
+        }
+    }
+    /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
+    sortsRelations(entity, sort) {
+        const meta = getMeta(entity);
+        return Object.keys(sort ?? {}).some((key) => Boolean(meta.relations[key]));
     }
     /**
      * Aggregate results are keyed by `$group`/`$agg` alias rather than by column, so an aggregate
      * `$sort` addresses those aliases as-is - the same reason the SQL dialects sort by alias there.
      */
     aliasSort(sort) {
-        return this.sortBy(sort, (alias) => alias);
-    }
-    /** Shared direction normalization; `mapKey` decides whether keys are columns or aggregate aliases. */
-    sortBy(sort, mapKey) {
         const normalized = {};
-        for (const [key, dir] of Object.entries(buildSortMap(sort))) {
-            normalized[mapKey(key)] = dir === 'desc' || dir === -1 ? -1 : 1;
+        for (const [alias, dir] of Object.entries(sort ?? {})) {
+            normalized[alias] = sortDirection(dir);
         }
         return normalized;
     }
@@ -396,39 +419,47 @@ export class MongoDialect extends AbstractDialect {
         }
         return this.columnOf(meta, key.slice(0, dot)) + key.slice(dot);
     }
-    aggregationPipeline(entity, q, relationSummary, opts) {
-        const { stages, filter, unset } = this.whereWithRelations(entity, q.$where, opts);
-        const sort = this.sort(entity, q.$sort);
-        const match = {};
-        if (hasKeys(filter)) {
-            match.$match = filter;
-        }
-        if (hasKeys(sort)) {
-            match.$sort = sort;
-        }
+    aggregationPipeline(entity, q, opts) {
         // Lookups that a relation condition needs come first, then the match that reads them, then the
         // temporary fields are dropped so they never reach the caller.
-        const pipeline = [...stages];
-        if (hasKeys(match)) {
-            pipeline.push(match);
-        }
-        if (unset.length) {
-            pipeline.push({ $unset: unset });
-        }
-        const relStages = this.relationStages(entity, q, relationSummary, opts);
-        const pager = [
-            ...(q.$skip === undefined ? [] : [{ $skip: q.$skip }]),
-            ...(q.$limit === undefined ? [] : [{ $limit: q.$limit }]),
+        const { stages, filter, unset } = this.whereWithRelations(entity, q.$where, opts);
+        return [
+            ...stages,
+            ...(hasKeys(filter) ? [{ $match: filter }] : []),
+            ...(unset.length ? [{ $unset: unset }] : []),
+            ...this.readStages(entity, q, opts, {
+                sort: this.sort(entity, q.$sort, q.$populate),
+                pager: [
+                    ...(q.$skip === undefined ? [] : [{ $skip: q.$skip }]),
+                    ...(q.$limit === undefined ? [] : [{ $limit: q.$limit }]),
+                ],
+            }),
+        ];
+    }
+    /**
+     * What a read runs after its entry stage, in the one order that works: the lookups its relations
+     * need, the ordering and paging that may read them, and the projection last of all - it names the
+     * fields the lookups add, and no stage after it could read what it dropped.
+     *
+     * Shared by the plain pipeline and the `$vectorSearch` one, which each used to spell the order out
+     * for themselves and each got a different part of it wrong.
+     */
+    readStages(entity, q, opts, extra = {}) {
+        const lookups = this.relationStages(entity, q, opts);
+        const projection = this.pipelineProjection(entity, q);
+        const sort = hasKeys(extra.sort) ? [{ $sort: extra.sort }] : [];
+        const pager = extra.pager ?? [];
+        // A `$required` relation drops parents when it unwinds, and an ordering may read a field only a
+        // lookup produces: either one puts the lookups first, as an INNER JOIN does. Otherwise paging
+        // first is equivalent and spares the lookups the rows it cuts.
+        const lookupsFirst = this.sortsRelations(entity, q.$sort) ||
+            lookups.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
+        return [
+            ...(lookupsFirst ? [...lookups, ...sort, ...pager] : [...sort, ...pager, ...lookups]),
+            // Merged into the query's own projection rather than standing in for one: a query that asked
+            // for no columns wants the whole document, not just the field this adds to it.
+            ...(projection ? [{ $project: { ...projection, ...extra.project } }] : []),
         ];
-        // A `$required` relation drops parents when it unwinds, so paging has to come after it - as it
-        // does after an INNER JOIN. Otherwise paging first is equivalent and spares the lookups.
-        const dropsParents = relStages.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
-        pipeline.push(...(dropsParents ? [...relStages, ...pager] : [...pager, ...relStages]));
-        const projection = this.pipelineProjection(entity, q, relationSummary);
-        if (projection) {
-            pipeline.push({ $project: projection });
-        }
-        return pipeline;
     }
     /**
      * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
@@ -436,12 +467,12 @@ export class MongoDialect extends AbstractDialect {
      * lookups have read the join keys - projecting any earlier is what used to leave `$populate`
      * empty, and is why the pipeline emitted no projection at all and returned every column.
      */
-    pipelineProjection(entity, q, relationSummary) {
+    pipelineProjection(entity, q) {
         if (!q.$select && !q.$exclude) {
             return undefined;
         }
         const projection = this.select(entity, q.$select, q.$exclude);
-        const summary = relationSummary ?? getRelationRequestSummary(getMeta(entity), q.$populate);
+        const summary = getRelationRequestSummary(getMeta(entity), q.$populate);
         for (const relKey of summary.joinableKeys) {
             projection[relKey] = 1;
         }
@@ -455,46 +486,51 @@ export class MongoDialect extends AbstractDialect {
      * `$lookup`/`$unwind` stages for the joinable relations a query populates. Shared by the plain
      * aggregation pipeline and the `$vectorSearch` one, so relations load the same way in both.
      */
-    relationStages(entity, q, relationSummary, opts) {
+    relationStages(entity, q, opts) {
+        // Resolved from `$populate` alone, deliberately: on the SQL dialects a `$sort` can add a join of
+        // its own because a join is invisible in the result, while a `$lookup` puts a field on the
+        // document. Same join model, and this backend takes the part of it that it can carry.
         const meta = getMeta(entity);
+        return this.lookupStages(meta, resolveQueryJoins(meta, { $populate: q.$populate }), undefined, opts);
+    }
+    /**
+     * The `$lookup`/`$unwind` pair for each relation joined below `parent`, its own relations nested
+     * inside its pipeline and resolved before the projection that reads them.
+     */
+    lookupStages(parentMeta, joins, parent, opts) {
         const pipeline = [];
-        const relKeys = (relationSummary ?? getRelationRequestSummary(meta, q.$populate)).joinableKeys;
-        for (const relKey of relKeys) {
-            const relOpts = meta.relations[relKey];
-            if (!relOpts)
-                continue;
-            if (relOpts.cardinality === '1m' || relOpts.cardinality === 'mm') {
-                // '1m' and 'mm' are resolved in a higher layer: they need a second query each.
+        // Every join at this level hangs off `parent`, so its metadata is `parentMeta` - no branch, and
+        // no union of two unrelated entity types to resolve the join column through.
+        for (const join of joins.values()) {
+            if (join.parent !== parent) {
                 continue;
             }
-            const relEntity = relOpts.entity();
-            const relMeta = getMeta(relEntity);
-            const { query: relQuery, required } = parseRelationAtKey(relKey, q.$populate);
             // Unconditional, not gated by an explicit relation-level `$where`: the related entity's own
             // filters (in particular `security: true` ones) must apply even to a bare
             // `$populate: { rel: true }`, exactly like the SQL dialects' JOIN ON-clause filters.
-            const relationFilter = this.where(relEntity, relQuery.$where ?? {}, opts);
+            const relationFilter = this.where(join.entity, join.query.$where ?? {}, opts);
             // The relation's own projection runs inside the lookup, where its keys resolve against the
             // related entity. Left out, `$populate: { rel: { $select } }` returned all of `rel`'s columns.
-            const relationProjection = this.pipelineProjection(relEntity, relQuery);
+            const relationProjection = this.pipelineProjection(join.entity, join.query);
             // MongoDB returns `_id` unless a projection subtracts it, so dropping the key from the map is
             // how a joined document keeps its own id - as it does on the SQL dialects, and as a nested
             // to-many fill needs.
             delete relationProjection?.[MongoDialect.ID_KEY];
             const lookupPipeline = [
                 ...(hasKeys(relationFilter) ? [{ $match: relationFilter }] : []),
+                ...this.lookupStages(join.meta, joins, join, opts),
                 ...(relationProjection ? [{ $project: relationProjection }] : []),
             ];
             pipeline.push({
                 $lookup: {
-                    from: this.resolveTableName(relEntity, relMeta),
-                    ...this.joinKeys(meta, relMeta, relOpts),
+                    from: this.resolveTableName(join.entity, join.meta),
+                    ...this.joinKeys(parentMeta, join.meta, join.relation),
                     ...(lookupPipeline.length ? { pipeline: lookupPipeline } : {}),
-                    as: relKey,
+                    as: join.key,
                 },
             });
             // `$required` drops parents with no match, the aggregation equivalent of an INNER JOIN.
-            pipeline.push({ $unwind: { path: `$${relKey}`, preserveNullAndEmptyArrays: !required } });
+            pipeline.push({ $unwind: { path: `$${join.key}`, preserveNullAndEmptyArrays: !join.required } });
         }
         return pipeline;
     }
@@ -768,11 +804,10 @@ export class MongoDialect extends AbstractDialect {
     extractVectorSort(sort) {
         if (!sort)
             return undefined;
-        const raw = buildSortMap(sort);
         let vectorKey;
         let vectorSearch;
         const regularSort = {};
-        for (const [key, value] of Object.entries(raw)) {
+        for (const [key, value] of Object.entries(sort)) {
             if (isVectorSearch(value)) {
                 vectorKey = key;
                 vectorSearch = value;
@@ -820,3 +855,7 @@ export class MongoDialect extends AbstractDialect {
         return { $vectorSearch: stage };
     }
 }
+/** `-1` for the two descending spellings, `1` for everything else - MongoDB knows no other value. */
+function sortDirection(value) {
+    return value === 'desc' || value === -1 ? -1 : 1;
+}