uql-orm 0.26.3 → 0.28.0

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -55,9 +55,12 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      */
     protected indexKeyword(index: IndexSchema): string;
     protected readonly indexFeatures: Set<IndexFeature>;
+    /**
+     * No `FOR NO KEY UPDATE`/`FOR KEY SHARE`: those are PostgreSQL's weaker pair and the family has
+     * no equivalent, so asking for one is rejected rather than served a stronger lock.
+     */
     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

@@ -102,15 +102,16 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         return index.type === 'fulltext' ? 'FULLTEXT INDEX' : super.indexKeyword(index);
     }
     indexFeatures = new Set(['expression', 'prefixLength']);
+    /**
+     * No `FOR NO KEY UPDATE`/`FOR KEY SHARE`: those are PostgreSQL's weaker pair and the family has
+     * no equivalent, so asking for one is rejected rather than served a stronger lock.
+     */
     indexAccessMethod(index) {
         return index.type && index.type !== 'fulltext' ? ` USING ${index.type}` : '';
     }
     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,44 @@
+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 = {
+    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;
+/**
+ * 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.
+ */
+export declare function isSortMap(value: unknown): value is QuerySortMap<object>;

package/dist/dialect/queryJoins.js

@@ -0,0 +1,73 @@
+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 = {
+        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);
+    }
+}
+/**
+ * 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.
+ */
+export 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/http/query.js

@@ -14,6 +14,13 @@ const JSON_QUERY_KEYS = [
  * every entry to a real query/option key, so a typo or a renamed option fails to compile.
  */
 const ALLOWED_QUERY_KEYS = new Set([...JSON_QUERY_KEYS, '$skip', '$limit', 'hardDelete', 'count']);
+/**
+ * Keys that mean something locally but that this transport can never honor, so they are rejected
+ * rather than dropped like the rest. Each request runs on its own auto-committing connection, so a
+ * row lock taken here is released before the response is written: honoring `$lock` is impossible,
+ * and ignoring it would hand the caller a read they believe is serialized and is not.
+ */
+const REJECTED_QUERY_KEYS = new Set(['$lock']);
 /**
  * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.
  * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
@@ -21,6 +28,9 @@ const ALLOWED_QUERY_KEYS = new Set([...JSON_QUERY_KEYS, '$skip', '$limit', 'hard
 export function parseQueryParams(params = {}) {
     const query = {};
     for (const key of getKeys(params)) {
+        if (REJECTED_QUERY_KEYS.has(key)) {
+            throw Object.assign(new TypeError(`'${key}' is not supported over HTTP`), { status: 400 });
+        }
         if (ALLOWED_QUERY_KEYS.has(key)) {
             query[key] = params[key];
         }

package/dist/maria/mariaDialect.d.ts

@@ -9,6 +9,8 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      * family shares and drops expressions.
      */
     protected readonly indexFeatures: Set<IndexFeature>;
+    /** MariaDB has no `FOR ... OF`, so a lock cannot be narrowed to one table of a join. */
+    readonly supportsLockOf = false;
     /** Unlike MySQL: `VECTOR(n)` takes its dimension, and its vector index is declared inline. */
     protected readonly featureOverrides: Partial<DialectFeatures>;
     /** MariaDB 10.5+ supports `INSERT ... RETURNING`, so the ids are exact per row. */

package/dist/maria/mariaDialect.js

@@ -11,6 +11,8 @@ export class MariaDialect extends MysqlLikeSqlDialect {
      * family shares and drops expressions.
      */
     indexFeatures = new Set(['prefixLength']);
+    /** MariaDB has no `FOR ... OF`, so a lock cannot be narrowed to one table of a join. */
+    supportsLockOf = false;
     /** Unlike MySQL: `VECTOR(n)` takes its dimension, and its vector index is declared inline. */
     featureOverrides = {
         vectorSupportsLength: true,

package/dist/mongo/mongoDialect.d.ts

@@ -64,6 +64,12 @@ export declare class MongoDialect extends AbstractDialect {
     private compareRelationCount;
     /** Whether a query subtracts `key` from the projection, via `$exclude` or a negative `$select`. */
     private subtractsKey;
+    /**
+     * MongoDB has no row-level lock to map `$lock` onto: its concurrency control is the transaction
+     * plus atomic document updates. Rejected rather than ignored, like `raw()` below, since a dropped
+     * lock silently removes the mutual exclusion the caller asked for.
+     */
+    assertNoLock<E>(q: Query<E>): void;
     /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
     private assertNoRaw;
     /**
@@ -89,14 +95,20 @@ 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>;
+    /**
+     * 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.
+     */
     sort<E extends Document>(entity: Type<E>, sort?: QuerySortMap<E>): Sort;
+    /** 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`).

package/dist/mongo/mongoDialect.js

@@ -2,7 +2,7 @@ import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.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, isToManyRelation, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -221,6 +221,16 @@ export class MongoDialect extends AbstractDialect {
         const at = (map) => map?.[key];
         return at(exclude) === true || at(select) === false;
     }
+    /**
+     * MongoDB has no row-level lock to map `$lock` onto: its concurrency control is the transaction
+     * plus atomic document updates. Rejected rather than ignored, like `raw()` below, since a dropped
+     * lock silently removes the mutual exclusion the caller asked for.
+     */
+    assertNoLock(q) {
+        if (q.$lock !== undefined) {
+            throw new TypeError('$lock (row-level locking) is not supported on MongoDB');
+        }
+    }
     /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
     assertNoRaw(value) {
         if (value instanceof QueryRaw) {
@@ -351,27 +361,47 @@ export class MongoDialect extends AbstractDialect {
         }
         return projection;
     }
+    /**
+     * 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.
+     */
     sort(entity, sort) {
         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 = {};
+        for (const [key, value] of Object.entries(sort ?? {})) {
+            const relation = meta.relations[key];
+            if (!relation) {
+                normalized[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.`);
             }
-            return this.pathOf(meta, key);
-        });
+            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);
+            }
+        }
+        return normalized;
+    }
+    /** 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;
     }
@@ -389,11 +419,15 @@ export class MongoDialect extends AbstractDialect {
     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 (hasKeys(sort)) {
+        if (!sortsRelations && sortStage.length) {
             match.$sort = sort;
         }
         // Lookups that a relation condition needs come first, then the match that reads them, then the
@@ -411,9 +445,10 @@ export class MongoDialect extends AbstractDialect {
             ...(q.$limit === undefined ? [] : [{ $limit: q.$limit }]),
         ];
         // 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.
+        // 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 ? [...relStages, ...pager] : [...pager, ...relStages]));
+        pipeline.push(...(dropsParents || sortsRelations ? [...relStages, ...sortStage, ...pager] : [...pager, ...relStages]));
         const projection = this.pipelineProjection(entity, q, relationSummary);
         if (projection) {
             pipeline.push({ $project: projection });
@@ -453,7 +488,7 @@ export class MongoDialect extends AbstractDialect {
             const relOpts = meta.relations[relKey];
             if (!relOpts)
                 continue;
-            if (relOpts.cardinality === '1m' || relOpts.cardinality === 'mm') {
+            if (isToManyRelation(relOpts)) {
                 // '1m' and 'mm' are resolved in a higher layer: they need a second query each.
                 continue;
             }
@@ -758,11 +793,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;
@@ -810,3 +844,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;
+}

package/dist/mongo/mongodbQuerier.js

@@ -18,6 +18,7 @@ export class MongodbQuerier extends AbstractQuerier {
         });
     }
     async internalFindMany(entity, q, opts) {
+        this.dialect.assertNoLock(q);
         return this.timed('internalFindMany', undefined, async () => {
             const meta = getMeta(entity);
             const vectorSort = this.dialect.extractVectorSort(q.$sort);
@@ -31,8 +32,11 @@ export class MongodbQuerier extends AbstractQuerier {
             else {
                 const relationSummary = getRelationRequestSummary(meta, q.$populate);
                 // A relation condition needs `$lookup`, so it forces the aggregation path just like populating
-                // one does; a plain `find` cursor cannot express it.
-                if (relationSummary.requestedKeys.length || this.dialect.constrainsRelations(entity, q.$where)) {
+                // 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 ||
+                    this.dialect.constrainsRelations(entity, q.$where) ||
+                    this.dialect.sortsRelations(entity, q.$sort)) {
                     const pipeline = this.dialect.aggregationPipeline(entity, q, relationSummary, opts);
                     documents = await this.runPipeline(entity, meta, pipeline);
                     await this.fillToManyRelations(entity, documents, q.$populate);

package/dist/querier/abstractSqlQuerier.d.ts

@@ -33,6 +33,17 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     protected lazyConnect(): Promise<void>;
     all<T>(query: string, values?: unknown[]): Promise<T[]>;
     run(query: string, values?: unknown[]): Promise<QueryUpdateResult>;
+    /**
+     * `$lock` outside a transaction is always a bug, and a silent one. Every engine accepts
+     * `SELECT ... FOR UPDATE` in autocommit and then releases the lock as the statement commits,
+     * before the caller has seen a row: the SQL is correct, nothing is omitted, and no layer below
+     * this one can tell. The dialect cannot check it either, being stateless and shared by every
+     * connection of the pool, so this is the only place it can be caught.
+     *
+     * The capability check runs first on purpose: "this engine has no row locks" is the more
+     * actionable answer, and on SQLite it is the answer either way.
+     */
+    protected assertLockable<E>(entity: Type<E>, q: Query<E>): void;
     protected internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
     protected internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<Awaited<E>, void, unknown>;
     /**

package/dist/querier/abstractSqlQuerier.js

@@ -51,7 +51,27 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             return this.timed(query, values, () => this.internalRun(query, this.dialect.normalizeValues(values)));
         });
     }
+    /**
+     * `$lock` outside a transaction is always a bug, and a silent one. Every engine accepts
+     * `SELECT ... FOR UPDATE` in autocommit and then releases the lock as the statement commits,
+     * before the caller has seen a row: the SQL is correct, nothing is omitted, and no layer below
+     * this one can tell. The dialect cannot check it either, being stateless and shared by every
+     * connection of the pool, so this is the only place it can be caught.
+     *
+     * The capability check runs first on purpose: "this engine has no row locks" is the more
+     * actionable answer, and on SQLite it is the answer either way.
+     */
+    assertLockable(entity, q) {
+        if (!q.$lock) {
+            return;
+        }
+        this.dialect.assertLockSupported(entity, q);
+        if (!this.hasOpenTransaction) {
+            throw new TypeError('$lock requires an open transaction');
+        }
+    }
     async internalFindMany(entity, q, opts) {
+        this.assertLockable(entity, q);
         const ctx = this.dialect.createContext();
         this.dialect.find(ctx, entity, q, opts);
         const res = await this.all(ctx.sql, ctx.values);
@@ -60,6 +80,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         return founds;
     }
     async *internalFindManyStream(entity, q, opts) {
+        this.assertLockable(entity, q);
         const meta = getMeta(entity);
         const { toManyKeys } = getRelationRequestSummary(meta, q.$populate);
         if (toManyKeys.length) {

package/dist/sqlite/sqliteDialect.d.ts

@@ -12,6 +12,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     readonly rollbackTransactionCommand = "ROLLBACK";
     readonly isolationLevelStrategy = "none";
     readonly alterColumnSyntax = "none";
+    /** SQLite locks the whole database, not rows, so `$lock` has nothing to map onto. */
+    readonly supportsRowLocks = false;
     readonly booleanLiteral = "integer";
     readonly insertIdSource = "returning";
     /**
@@ -25,7 +27,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * when declared, else `NULL` (which is also how SQLite auto-generates INTEGER PRIMARY KEYs).
      */
     protected appendDefaultInsertValue(ctx: QueryContext, field: FieldOptions | undefined): void;
-    protected ilikeExpr(f: string, ph: string): string;
+    protected readonly caseInsensitiveMatch = "native";
     protected get neOp(): string;
     normalizeValue(value: unknown): unknown;
     /**

package/dist/sqlite/sqliteDialect.js

@@ -26,6 +26,8 @@ export class SqliteDialect extends AbstractSqlDialect {
     rollbackTransactionCommand = 'ROLLBACK';
     isolationLevelStrategy = 'none';
     alterColumnSyntax = 'none';
+    /** SQLite locks the whole database, not rows, so `$lock` has nothing to map onto. */
+    supportsRowLocks = false;
     booleanLiteral = 'integer';
     // SQLite supports `RETURNING` (including on `INSERT ... ON CONFLICT`), so IDs are exact per row.
     insertIdSource = 'returning';
@@ -51,9 +53,9 @@ export class SqliteDialect extends AbstractSqlDialect {
             ctx.append('NULL');
         }
     }
-    ilikeExpr(f, ph) {
-        return `${f} LIKE ${ph}`;
-    }
+    // SQLite's `LIKE` already ignores case on both sides, for ASCII - and only ASCII, with or without
+    // `NOCASE`, so folding the pattern here would break the accented text the engine leaves alone.
+    caseInsensitiveMatch = 'native';
     get neOp() {
         return 'IS NOT';
     }

package/dist/type/dialect.d.ts

@@ -7,9 +7,11 @@ import type { Type } from './utility.js';
  */
 export type QueryComparisonOptions = QueryOptions & {
     /**
-     * use precedence for the comparison or not.
+     * Whether this fragment is rendered as an operand of an enclosing `AND`/`OR`/`NOT`. An operand
+     * parenthesizes itself when it emits more than one term, so no fragment ever depends on the
+     * engine's operator precedence. Only the `WHERE` clause as a whole is not an operand.
      */
-    usePrecedence?: boolean;
+    operand?: boolean;
 };
 /**
  * query filter options.
@@ -31,6 +33,12 @@ export interface QueryContext {
      * alias would let the inner occurrence shadow the outer one it needs to correlate against.
      */
     nextAlias(prefix: string): string;
+    /**
+     * A context for a fragment of this same statement: it renders its own SQL in isolation while
+     * sharing the bound values and the generated aliases, so both stay unique and correctly numbered
+     * across the statement. See {@link AbstractSqlDialect.buildFragment}.
+     */
+    createFragment(): QueryContext;
     readonly sql: string;
     readonly values: unknown[];
 }
@@ -148,7 +156,7 @@ export interface QueryDialect {
      * @param forbidQualified don't escape dots
      * @param addDot use a dot as suffix
      */
-    escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
+    escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
      * escape a value.
      * @param val the value to escape