uql-orm 0.28.0 → 0.28.1

package/README.md

@@ -3,13 +3,13 @@
 <a href="https://uql-orm.dev">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rogerpadilla/uql/main/assets/logo-dark.svg">
-    <img src="https://raw.githubusercontent.com/rogerpadilla/uql/main/assets/logo.svg" alt="UQL" width="90">
+    <img src="https://raw.githubusercontent.com/rogerpadilla/uql/main/assets/logo.svg" alt="UQL" width="72" height="72">
   </picture>
 </a>
 
-<h3>The ORM with type-safe JSON queries</h3>
+<h3>The JSON-native TypeScript ORM</h3>
 
-<p>Queries are plain JSON values, typed to the leaf. Build them, store them, send them from the browser, and run them unchanged on every SQL database and MongoDB. And it is the <a href="https://uql-orm.dev/benchmark">fastest</a>.</p>
+<p>Queries are plain JSON, typed to the leaf. Unified across SQL databases and MongoDB.</p>
 
 <p>
   <a href="https://uql-orm.dev"><b>Website</b></a> ·
@@ -77,4 +77,4 @@ Release notes live in [CHANGELOG.md](https://github.com/rogerpadilla/uql/blob/ma
 
 Built something? [Open a PR](https://github.com/rogerpadilla/uql/blob/main/CONTRIBUTING.md) and add it here.
 
-[![Made with UQL](https://img.shields.io/badge/made%20with-UQL-4F46E5?style=flat)](https://uql-orm.dev)
+[![Made with UQL](https://img.shields.io/badge/made%20with-UQL-3282b5?style=flat)](https://uql-orm.dev)

package/dist/dialect/abstractSqlDialect.d.ts

@@ -203,8 +203,6 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * carries instead of two quoted identifiers.
      */
     private collectSortTerms;
-    /** The join an `ORDER BY` term addresses, or why the statement cannot order by it. */
-    private resolveSortJoin;
     /**
      * The `ORDER BY` operand for one key. A key that is not a column of `meta` - a virtual field, a
      * `raw()` projection - is an output alias, which is never table-qualified and needs no resolving.

package/dist/dialect/abstractSqlDialect.js

@@ -1,12 +1,12 @@
 import { getMeta } from '../entity/index.js';
 import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
-import { asSelectMap, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, isBooleanType, isJsonType, isJsonUpdateOp, isNumericType, isOperatorObject, isOperatorOnlyObject, isToManyRelation, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, populatesRelations, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, isBooleanType, isJsonType, isJsonUpdateOp, isNumericType, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, populatesRelations, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { isJsonbOp, JSON_ELEM_ALIAS_PREFIX, jsonCompareMode, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-import { isSortMap, NO_JOINS, resolveQueryJoins, } from './queryJoins.js';
+import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { isVectorFieldType, resolveVectorCast } from './vectorCast.js';
 export class AbstractSqlDialect extends IndexSqlDialect {
     isolationLevelStrategy = 'inline';
@@ -323,6 +323,10 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     compareLogicalOperator(ctx, entity, key, val, opts) {
         const op = AbstractSqlDialect.NEGATE_OP_MAP.get(key) ?? key;
         const negate = AbstractSqlDialect.NEGATE_OP_MAP.has(key);
+        if (val !== undefined && !Array.isArray(val)) {
+            // Not covered by the types: `/http` casts client JSON straight to `Query`, so this arrives untyped.
+            throw TypeError(`${key} expects an array, got ${val === null ? 'null' : typeof val}`);
+        }
         const items = val ?? [];
         // With more than one item each is an operand of the operator joining them, so a compound item
         // parenthesizes itself and precedence never applies; a lone item is this group verbatim, so it
@@ -660,11 +664,13 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             const relation = meta.relations[key];
             if (relation) {
                 const relPath = path ? `${path}.${key}` : key;
-                if (!isSortMap(value)) {
-                    throw new TypeError(`$sort by relation '${relPath}' expects a map of its fields, got ${String(value)}`);
+                const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, value, opts.joins ?? NO_JOINS, `cannot $sort by relation '${relPath}': this statement joins no relations`);
+                // `SELECT DISTINCT` can only order by what it selected, on every engine here, so a join
+                // brought in for the sort alone has nothing to order by. Populating it selects its columns.
+                if (opts.distinct && !join.projected) {
+                    throw new TypeError(`cannot $sort by relation '${relPath}' with $distinct unless '${relPath}' is populated: SELECT DISTINCT orders only by selected columns`);
                 }
-                const join = this.resolveSortJoin(relation, relPath, opts);
-                this.collectSortTerms(ctx, join.meta, value, opts, vectors, columns, relPath);
+                this.collectSortTerms(ctx, join.meta, relationSort, opts, vectors, columns, relPath);
                 continue;
             }
             if (isVectorSearch(value)) {
@@ -680,22 +686,6 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             columns.push(this.sortColumn(meta, key, prefix) + this.resolveSortDirection(value));
         }
     }
-    /** The join an `ORDER BY` term addresses, or why the statement cannot order by it. */
-    resolveSortJoin(relation, path, opts) {
-        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.`);
-        }
-        const join = opts.joins?.get(path);
-        if (!join) {
-            throw new TypeError(`cannot $sort by relation '${path}': this statement joins no relations`);
-        }
-        // `SELECT DISTINCT` can only order by what it selected, on every engine here, so a join brought in
-        // for the sort alone has nothing to order by. Populating it puts its columns in the select list.
-        if (opts.distinct && !join.projected) {
-            throw new TypeError(`cannot $sort by relation '${path}' with $distinct unless '${path}' is populated: SELECT DISTINCT orders only by selected columns`);
-        }
-        return join;
-    }
     /**
      * The `ORDER BY` operand for one key. A key that is not a column of `meta` - a virtual field, a
      * `raw()` projection - is an output alias, which is never table-qualified and needs no resolving.

package/dist/dialect/queryJoins.d.ts

@@ -6,6 +6,9 @@ import { type RelationQuery } from '../util/index.js';
  * `$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>;
@@ -38,7 +41,13 @@ export type QuerySortOptions = {
  */
 export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>): QueryJoins;
 /**
- * A nested `$sort` map, as opposed to a direction or a vector search. Shared with the `ORDER BY`
- * renderer so what counts as a relation sort is decided once, not once per side.
+ * 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 isSortMap(value: unknown): value is QuerySortMap<object>;
+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

@@ -26,6 +26,7 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
     }
     const entity = relation.entity();
     const join = {
+        key,
         path,
         entity,
         meta: getMeta(entity),
@@ -65,9 +66,26 @@ function addSortJoins(joins, meta, sort, parent) {
     }
 }
 /**
- * A nested `$sort` map, as opposed to a direction or a vector search. Shared with the `ORDER BY`
- * renderer so what counts as a relation sort is decided once, not once per side.
+ * 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 isSortMap(value) {
+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/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 {
@@ -98,10 +106,12 @@ export declare class MongoDialect extends AbstractDialect {
     /**
      * 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* to-one: a lookup adds a field to the result, so one added for the sort alone
-     * would change what the caller gets back, and MongoDB's lookups do not nest.
+     * 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>): Sort;
+    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;
     /**
@@ -114,19 +124,33 @@ export declare class MongoDialect extends AbstractDialect {
      * 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, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorObject, isToManyRelation, 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,
@@ -364,30 +365,32 @@ export class MongoDialect extends AbstractDialect {
     /**
      * 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* to-one: a lookup adds a field to the result, so one added for the sort alone
-     * would change what the caller gets back, and MongoDB's lookups do not nest.
+     * 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) {
+    sort(entity, sort, populate) {
         const meta = getMeta(entity);
         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) {
-                normalized[this.pathOf(meta, key)] = sortDirection(value);
+                out[path + this.pathOf(meta, key)] = sortDirection(value);
                 continue;
             }
-            if (isToManyRelation(relation)) {
-                throw new TypeError(`cannot $sort by '${key}': a parent has many of them, so there is no single value to order by. Sort the relation's own rows inside $populate instead.`);
-            }
-            const relMeta = getMeta(relation.entity());
-            for (const [relKey, relValue] of Object.entries(value ?? {})) {
-                if (relMeta.relations[relKey]) {
-                    throw new TypeError(`cannot $sort by '${key}.${relKey}' on MongoDB: its lookups reach one level, so a nested relation is not joined`);
-                }
-                normalized[`${key}.${this.pathOf(relMeta, relKey)}`] = sortDirection(relValue);
-            }
+            // 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);
         }
-        return normalized;
     }
     /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
     sortsRelations(entity, sort) {
@@ -416,44 +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);
-        // Ordering by a related field reads what the lookups produced, so it cannot ride along with the
-        // `$match` the way an ordering by the parent's own columns does.
-        const sortsRelations = this.sortsRelations(entity, q.$sort);
-        const sortStage = hasKeys(sort) ? [{ $sort: sort }] : [];
-        const match = {};
-        if (hasKeys(filter)) {
-            match.$match = filter;
-        }
-        if (!sortsRelations && sortStage.length) {
-            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. So does a sort that reads one, or a page would be cut from unordered
-        // rows. Otherwise paging first is equivalent and spares the lookups.
-        const dropsParents = relStages.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
-        pipeline.push(...(dropsParents || sortsRelations ? [...relStages, ...sortStage, ...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:
@@ -461,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;
         }
@@ -480,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 (isToManyRelation(relOpts)) {
-                // '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;
     }

package/dist/mongo/mongodbQuerier.js

@@ -1,6 +1,6 @@
 import { getMeta } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
 export class MongodbQuerier extends AbstractQuerier {
     dialect;
     conn;
@@ -30,14 +30,13 @@ export class MongodbQuerier extends AbstractQuerier {
                 await this.fillToManyRelations(entity, documents, q.$populate);
             }
             else {
-                const relationSummary = getRelationRequestSummary(meta, q.$populate);
                 // 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. A plain
                 // `find` cursor can express none of the three.
-                if (relationSummary.requestedKeys.length ||
+                if (populatesRelations(meta, q.$populate) ||
                     this.dialect.constrainsRelations(entity, q.$where) ||
                     this.dialect.sortsRelations(entity, q.$sort)) {
-                    const pipeline = this.dialect.aggregationPipeline(entity, q, relationSummary, opts);
+                    const pipeline = this.dialect.aggregationPipeline(entity, q, opts);
                     documents = await this.runPipeline(entity, meta, pipeline);
                     await this.fillToManyRelations(entity, documents, q.$populate);
                 }
@@ -86,7 +85,7 @@ export class MongodbQuerier extends AbstractQuerier {
         if (hasKeys(select)) {
             cursor.project(select);
         }
-        const sort = this.dialect.sort(entity, q.$sort);
+        const sort = this.dialect.sort(entity, q.$sort, q.$populate);
         if (hasKeys(sort)) {
             cursor.sort(sort);
         }
@@ -108,43 +107,18 @@ export class MongodbQuerier extends AbstractQuerier {
      * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
      */
     buildVectorPipeline(entity, q, vectorSort, opts) {
-        const pipeline = [];
-        pipeline.push(this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts));
-        const meta = getMeta(entity);
-        const relationSummary = getRelationRequestSummary(meta, q.$populate);
         const scoreAlias = vectorSort.vectorSearch.$project;
-        // With relations the score is captured with `$addFields` before the lookups, and the scalar
-        // projection waits until after them: projecting any earlier drops the join keys and the joined
-        // documents, which is why `$populate` used to come back empty under a vector sort.
-        if (relationSummary.requestedKeys.length) {
-            if (scoreAlias) {
-                pipeline.push({ $addFields: { [scoreAlias]: { $meta: 'vectorSearchScore' } } });
-            }
-            pipeline.push(...this.dialect.relationStages(entity, q, relationSummary));
-            const projection = this.dialect.pipelineProjection(entity, q, relationSummary);
-            if (projection) {
-                // `$addFields` already made the score a real field, so it projects like any other.
-                pipeline.push({ $project: scoreAlias ? { ...projection, [scoreAlias]: 1 } : projection });
-            }
-        }
-        else if (scoreAlias) {
-            const select = q.$select || q.$exclude ? this.buildScalarProjection(entity, q) : {};
-            pipeline.push({
-                $project: {
-                    ...select,
-                    [scoreAlias]: { $meta: 'vectorSearchScore' },
-                },
-            });
-        }
-        else if ((q.$select && hasKeys(q.$select)) || (q.$exclude && hasKeys(q.$exclude))) {
-            pipeline.push({ $project: this.buildScalarProjection(entity, q) });
-        }
-        // Secondary sort for non-vector fields
-        const regularSort = this.dialect.sort(entity, vectorSort.regularSort);
-        if (hasKeys(regularSort)) {
-            pipeline.push({ $sort: regularSort });
-        }
-        return pipeline;
+        return [
+            this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts),
+            // The score becomes a real field before anything reads it, so the lookups and the projection
+            // 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, {
+                sort: this.dialect.sort(entity, vectorSort.regularSort, q.$populate),
+                project: scoreAlias ? { [scoreAlias]: 1 } : undefined,
+            }),
+        ];
     }
     async internalAggregate(entity, q, opts) {
         return this.timed('internalAggregate', undefined, async () => {

package/dist/type/query.d.ts

@@ -121,12 +121,12 @@ export type QuerySortValue = QuerySortDirection | QueryVectorSearch;
  * like `QueryWhereMap`), relation sort via nested objects, and vector similarity search on
  * `number[]` fields.
  */
-export type QuerySortMap<E> = {
-    [K in FieldKey<E>]?: NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection;
+export type QuerySortMap<E, Vector extends boolean = true> = {
+    [K in FieldKey<E>]?: Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection;
 } & {
     [P in JsonFieldPaths<E>]?: QuerySortDirection;
 } & {
-    [K in RelationKey<E> as NonNullable<E[K]> extends readonly unknown[] ? never : K]?: QuerySortMap<NonNullable<E[K]>>;
+    [K in RelationKey<E> as NonNullable<E[K]> extends readonly unknown[] ? never : K]?: QuerySortMap<NonNullable<E[K]>, false>;
 };
 /**
  * pager options.

package/dist/util/relationQuery.util.d.ts

@@ -4,8 +4,11 @@ export type RelationRequestSummary<E> = {
     readonly joinableKeys: RelationKey<E>[];
     readonly toManyKeys: RelationKey<E>[];
 };
-/** Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. */
-export declare function isToManyRelation(relation: RelationMeta): boolean;
+/**
+ * Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. Takes
+ * the one field it reads, so it answers for a relation being declared as well as for a resolved one.
+ */
+export declare function isToManyRelation(relation: Pick<RelationMeta, 'cardinality'>): boolean;
 /**
  * What a joined relation cannot carry, and why. A to-many is loaded by a query of its own, which is
  * what gives these four a meaning there; a to-one is one row of the parent's, so every backend used

package/dist/util/relationQuery.util.js

@@ -1,5 +1,8 @@
 import { getKeys } from './object.util.js';
-/** Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. */
+/**
+ * Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. Takes
+ * the one field it reads, so it answers for a relation being declared as well as for a resolved one.
+ */
 export function isToManyRelation(relation) {
     return relation.cardinality === '1m' || relation.cardinality === 'mm';
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "homepage": "https://uql-orm.dev",
-  "description": "Extremely fast, type-safe TypeScript ORM - one API for every database",
+  "description": "JSON-native TypeScript ORM: queries are plain JSON, typed to the leaf. One API for SQL databases and MongoDB.",
   "license": "MIT",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "type": "module",
   "engines": {
     "node": ">=24"