uql-orm 0.27.0 → 0.28.0

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,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/mongo/mongoDialect.d.ts

@@ -95,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,
@@ -361,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.`);
+            }
+            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 this.pathOf(meta, key);
-        });
+        }
+        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;
     }
@@ -399,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
@@ -421,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 });
@@ -463,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;
             }
@@ -768,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;
@@ -820,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

@@ -32,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/sqlite/sqliteDialect.d.ts

@@ -27,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

@@ -53,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

package/dist/type/query.d.ts

@@ -126,7 +126,7 @@ export type QuerySortMap<E> = {
 } & {
     [P in JsonFieldPaths<E>]?: QuerySortDirection;
 } & {
-    [K in RelationKey<E>]?: QuerySortMap<NonNullable<Unpacked<E[K]>>>;
+    [K in RelationKey<E> as NonNullable<E[K]> extends readonly unknown[] ? never : K]?: QuerySortMap<NonNullable<E[K]>>;
 };
 /**
  * pager options.

package/dist/util/dialect.util.d.ts

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
+import { type CascadeType, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: E, callbackKey: CallbackKey): FieldKey<E>[];
 /**
@@ -47,7 +47,6 @@ export declare function isCascadable(action: CascadeType, configuration?: boolea
  */
 export declare function asSelectMap<E>(select: QuerySelectValue<E> | undefined): QuerySelect<E> | undefined;
 export declare function normalizeScalarFieldSelection<E>(meta: EntityMeta<E>, select?: QuerySelect<E>, exclude?: QueryExclude<E>): FieldKey<E>[];
-export declare function buildSortMap<E>(sort: QuerySortMap<E> | undefined): QuerySortMap<E>;
 /** Type guard: checks whether a sort value is a vector similarity search. */
 export declare function isVectorSearch(value: unknown): value is QueryVectorSearch;
 /** Type guard: checks whether an update payload value is a JSON operator object. */

package/dist/util/dialect.util.js

@@ -141,9 +141,6 @@ export function normalizeScalarFieldSelection(meta, select, exclude) {
     const excluded = excludedFields;
     return allFields.filter((it) => !excluded.has(it));
 }
-export function buildSortMap(sort) {
-    return (sort ?? {});
-}
 /** Type guard: checks whether a sort value is a vector similarity search. */
 export function isVectorSearch(value) {
     return value !== null && typeof value === 'object' && '$vector' in value;

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

@@ -1,12 +1,23 @@
-import type { EntityMeta, Except, Query, QueryPopulate, RelationKey } from '../type/index.js';
+import type { EntityMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
 export type RelationRequestSummary<E> = {
     readonly requestedKeys: RelationKey<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;
+/**
+ * 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
+ * to drop them without a word. `satisfies` ties each key to {@link RelationQuery}, so renaming one
+ * breaks this list at compile time rather than quietly stopping the check.
+ */
+declare const JOINED_RELATION_REJECTIONS: readonly [readonly ["$sort", "a join brings one row per parent, so there is nothing to order"], readonly ["$limit", "a join brings one row per parent, so there is nothing to page"], readonly ["$skip", "a join brings one row per parent, so there is nothing to page"], readonly ["$distinct", "it applies to the whole statement, not to one of its joins"]];
+/** A key only a to-many's own query can carry, and that a joined relation therefore rejects. */
+export type JoinedRelationRejectedKey = (typeof JOINED_RELATION_REJECTIONS)[number][0];
 export declare function getRelationRequestSummary<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): RelationRequestSummary<E>;
 /** True when `$populate` includes at least one relation key. */
-export declare function isPopulatingRelations<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): boolean;
+export declare function populatesRelations<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): boolean;
 export type RelationQuery<E extends object = object> = Except<Query<E>, '$lock'> & {
     $required?: boolean;
 };
@@ -20,3 +31,4 @@ export declare function parseRelationQueryValue<E extends object = object>(value
 /** Parses the relation payload for `relKey` */
 export declare function parseRelationAtKey<E>(relKey: RelationKey<E>, populate?: QueryPopulate<E>): ParsedRelationQuery;
 export declare function forEachRequestedRelation<E extends object>(meta: EntityMeta<E>, populate: QueryPopulate<E> | undefined, fn: (relKey: RelationKey<E>, rawValue: unknown) => void): void;
+export {};

package/dist/util/relationQuery.util.js

@@ -1,4 +1,31 @@
 import { getKeys } from './object.util.js';
+/** Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. */
+export function isToManyRelation(relation) {
+    return relation.cardinality === '1m' || relation.cardinality === 'mm';
+}
+/**
+ * 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
+ * to drop them without a word. `satisfies` ties each key to {@link RelationQuery}, so renaming one
+ * breaks this list at compile time rather than quietly stopping the check.
+ */
+const JOINED_RELATION_REJECTIONS = [
+    ['$sort', 'a join brings one row per parent, so there is nothing to order'],
+    ['$limit', 'a join brings one row per parent, so there is nothing to page'],
+    ['$skip', 'a join brings one row per parent, so there is nothing to page'],
+    ['$distinct', 'it applies to the whole statement, not to one of its joins'],
+];
+const JOINED_RELATION_REJECTED_KEYS = new Map(JOINED_RELATION_REJECTIONS);
+function assertJoinableRelationQuery(relKey, value) {
+    if (!value || typeof value !== 'object') {
+        return;
+    }
+    for (const [key, reason] of JOINED_RELATION_REJECTED_KEYS) {
+        if (key in value) {
+            throw new TypeError(`'${key}' is not supported inside $populate of the to-one relation '${relKey}': ${reason}.`);
+        }
+    }
+}
 export function getRelationRequestSummary(meta, populate) {
     const requestedKeys = [];
     const joinableKeys = [];
@@ -12,17 +39,20 @@ export function getRelationRequestSummary(meta, populate) {
         if (!relOpts)
             continue;
         requestedKeys.push(key);
-        if (relOpts.cardinality === '1m' || relOpts.cardinality === 'mm') {
+        if (isToManyRelation(relOpts)) {
             toManyKeys.push(key);
         }
         else {
+            // Validated where the cardinality is decided, so every backend and every nesting level rejects
+            // the same shapes - the SQL dialects, MongoDB's lookups, and whatever reads this summary next.
+            assertJoinableRelationQuery(key, populate[key]);
             joinableKeys.push(key);
         }
     }
     return { requestedKeys, joinableKeys, toManyKeys };
 }
 /** True when `$populate` includes at least one relation key. */
-export function isPopulatingRelations(meta, populate) {
+export function populatesRelations(meta, populate) {
     if (!populate)
         return false;
     return getKeys(populate).some((key) => populate[key] && key in meta.relations);

package/dist/util/sql.util.d.ts

@@ -1,6 +1,5 @@
 import type { InsertIdSource, QueryUpdateResult, RawRow } from '../type/index.js';
 import type { PrimaryKey } from '../type/utility.js';
-export declare function flatObject<E extends object>(obj: E, pre?: string): E;
 export declare function unflatObjects<T extends object>(objects: RawRow[]): T[];
 /**
  * Unflattens a single raw row using pre-computed attribute paths.
@@ -17,7 +16,7 @@ export declare function obtainAttrsPaths<T extends object>(row: T): {
  * @param forbidQualified whether to forbid qualified identifiers (containing dots)
  * @param addDot whether to add a dot suffix
  */
-export declare function escapeSqlId(val: string, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
+export declare function escapeSqlId(val: string | undefined, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
 /**
  * Payload for building a QueryUpdateResult.
  */

package/dist/util/sql.util.js

@@ -1,17 +1,6 @@
-import { getKeys, hasKeys } from './object.util.js';
+import { hasKeys } from './object.util.js';
 /** Pre-computed regex for each SQL identifier escape character to avoid per-call allocation. */
 const escapeIdRegexCache = { '`': /`/g, '"': /"/g };
-export function flatObject(obj, pre) {
-    return getKeys(obj).reduce((acc, key) => flatObjectEntry(acc, key, obj[key], typeof obj[key] === 'object' ? '' : pre), {});
-}
-function flatObjectEntry(map, key, val, pre) {
-    const prefix = pre ? `${pre}.${key}` : key;
-    if (typeof val === 'object' && val !== null) {
-        return getKeys(val).reduce((acc, prop) => flatObjectEntry(acc, prop, val[prop], prefix), map);
-    }
-    map[prefix] = val;
-    return map;
-}
 export function unflatObjects(objects) {
     if (!Array.isArray(objects) || !objects.length) {
         return objects;