uql-orm 0.27.0 → 0.28.1

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,11 +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; a plain `find` cursor cannot express it.
-                if (relationSummary.requestedKeys.length || this.dialect.constrainsRelations(entity, q.$where)) {
-                    const pipeline = this.dialect.aggregationPipeline(entity, q, relationSummary, opts);
+                // 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 (populatesRelations(meta, q.$populate) ||
+                    this.dialect.constrainsRelations(entity, q.$where) ||
+                    this.dialect.sortsRelations(entity, q.$sort)) {
+                    const pipeline = this.dialect.aggregationPipeline(entity, q, opts);
                     documents = await this.runPipeline(entity, meta, pipeline);
                     await this.fillToManyRelations(entity, documents, q.$populate);
                 }
@@ -83,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);
         }
@@ -105,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/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

@@ -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>]?: QuerySortMap<NonNullable<Unpacked<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/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,26 @@
-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. 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
+ * 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 +34,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,34 @@
 import { getKeys } from './object.util.js';
+/**
+ * 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';
+}
+/**
+ * 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 +42,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;

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.27.0",
+  "version": "0.28.1",
   "type": "module",
   "engines": {
     "node": ">=24"