uql-orm 0.24.4 → 0.24.6

package/dist/dialect/abstractSqlDialect.d.ts

@@ -79,7 +79,6 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     protected renderWhere<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
     compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
     protected compareLogicalOperator<E>(ctx: QueryContext, entity: Type<E>, key: '$and' | '$or' | '$not' | '$nor', val: QueryWhereArray<E>, opts: QueryComparisonOptions): void;
-    /** Simple comparison operators: `getComparisonKey → op → addValue`. */
     /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
     private readonly escapedColumns;
     private static readonly NEGATE_OP_MAP;

package/dist/dialect/abstractSqlDialect.js

@@ -100,23 +100,13 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         const meta = getMeta(entity);
         const prefix = opts.prefix ? opts.prefix + '.' : '';
         const escapedPrefix = this.escapeId(opts.prefix, true, true);
-        let selectArr;
-        if (select) {
-            if (Array.isArray(select)) {
-                // Raw SQL projections passed as QueryRaw[]
-                selectArr = select;
-            }
-            else {
-                selectArr = normalizeScalarFieldSelection(meta, asSelectMap(select), exclude);
-            }
-            const id = meta.id;
-            if (id && opts.prefix && !selectArr.includes(id)) {
-                selectArr = [id, ...selectArr];
-            }
-        }
-        else {
-            selectArr = normalizeScalarFieldSelection(meta, undefined, exclude);
-        }
+        const scalars = Array.isArray(select)
+            ? select // raw SQL projections passed as QueryRaw[]
+            : normalizeScalarFieldSelection(meta, asSelectMap(select), exclude);
+        // A prefix means relations are in play: rows arrive keyed by the id and `fillToManyRelations`
+        // groups children by it, so it outlives any subtraction - `$exclude` or falsy `$select` alike.
+        const id = meta.id;
+        const selectArr = id && opts.prefix && !scalars.includes(id) ? [id, ...scalars] : scalars;
         if (!selectArr.length) {
             ctx.append(escapedPrefix + '*');
             return;
@@ -387,7 +377,6 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             ctx.append(')');
         }
     }
-    /** Simple comparison operators: `getComparisonKey → op → addValue`. */
     /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
     escapedColumns = new WeakMap();
     static NEGATE_OP_MAP = new Map([

package/dist/mongo/mongoDialect.d.ts

@@ -103,6 +103,13 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private pathOf;
     aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, relationSummary?: RelationRequestSummary<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
+    /**
+     * 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;
     /**
      * `$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.

package/dist/mongo/mongoDialect.js

@@ -414,8 +414,33 @@ export class MongoDialect extends AbstractDialect {
         // does after an INNER JOIN. Otherwise paging first is equivalent and spares the lookups.
         const dropsParents = relStages.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
         pipeline.push(...(dropsParents ? [...relStages, ...pager] : [...pager, ...relStages]));
+        const projection = this.pipelineProjection(entity, q, relationSummary);
+        if (projection) {
+            pipeline.push({ $project: projection });
+        }
         return pipeline;
     }
+    /**
+     * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
+     * 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(entity, q, relationSummary) {
+        if (!q.$select && !q.$exclude) {
+            return undefined;
+        }
+        const projection = this.select(entity, q.$select, q.$exclude);
+        const summary = relationSummary ?? getRelationRequestSummary(getMeta(entity), q.$populate);
+        for (const relKey of summary.joinableKeys) {
+            projection[relKey] = 1;
+        }
+        // Only ever undoes an exclusion: a relation cannot be filled onto a parent with no key.
+        if (summary.requestedKeys.length && projection[MongoDialect.ID_KEY] === 0) {
+            delete projection[MongoDialect.ID_KEY];
+        }
+        return projection;
+    }
     /**
      * `$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.
@@ -439,11 +464,22 @@ export class MongoDialect extends AbstractDialect {
             // 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);
+            // 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);
+            // 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 }] : []),
+                ...(relationProjection ? [{ $project: relationProjection }] : []),
+            ];
             pipeline.push({
                 $lookup: {
                     from: this.resolveTableName(relEntity, relMeta),
                     ...this.joinKeys(meta, relMeta, relOpts),
-                    ...(hasKeys(relationFilter) ? { pipeline: [{ $match: relationFilter }] } : {}),
+                    ...(lookupPipeline.length ? { pipeline: lookupPipeline } : {}),
                     as: relKey,
                 },
             });

package/dist/mongo/mongodbQuerier.js

@@ -109,14 +109,19 @@ export class MongodbQuerier extends AbstractQuerier {
         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 no scalar
-        // `$project` is emitted: projecting here would drop both the join keys and the joined documents,
-        // which is why `$populate` used to come back empty under a vector sort.
+        // 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) : {};

package/dist/querier/abstractQuerier.d.ts

@@ -6,9 +6,6 @@ import { LoggerWrapper } from '../util/index.js';
  */
 export declare abstract class AbstractQuerier implements Querier {
     readonly extra?: ExtraOptions | undefined;
-    private static readonly emittedWarnings;
-    /** Clears process-wide warning deduplication. For tests only. */
-    static clearEmittedWarningsForTests(): void;
     /**
      * Internal promise used to queue database operations.
      * This ensures that each operation is executed serially, preventing race conditions

package/dist/querier/abstractQuerier.js

@@ -7,11 +7,6 @@ import { enrichError } from './queryError.js';
  */
 export class AbstractQuerier {
     extra;
-    static emittedWarnings = new Set();
-    /** Clears process-wide warning deduplication. For tests only. */
-    static clearEmittedWarningsForTests() {
-        AbstractQuerier.emittedWarnings.clear();
-    }
     /**
      * Internal promise used to queue database operations.
      * This ensures that each operation is executed serially, preventing race conditions
@@ -207,8 +202,13 @@ export class AbstractQuerier {
         const throughMeta = getMeta(throughEntity);
         const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === relOpts.references[1].local));
         const ids = payload.map((it) => it[meta.id]);
+        // A relation query names the target's columns, not the join table's, so the projection and the
+        // filter belong on the populate below - resolved there against the entity that has them. Spread
+        // onto the through query they asked `ItemTag` for `Tag`'s columns: `$where`/`$sort` failed with
+        // "no such column", and `$exclude` collided with the `$select` this builds.
+        const { $select: _select, $exclude: _exclude, $where: _where, ...throughQuery } = relationQuery;
         const throughFounds = await this.findMany(throughEntity, {
-            ...relationQuery,
+            ...throughQuery,
             $select: {
                 [localField]: true,
             },
@@ -219,7 +219,6 @@ export class AbstractQuerier {
                 },
             },
             $where: {
-                ...relationQuery.$where,
                 [localField]: ids,
             },
         });
@@ -231,12 +230,14 @@ export class AbstractQuerier {
     }
     async fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity) {
         const foreignField = relOpts.references[0].foreign;
-        // Ensure the FK column is selected so putChildrenInParents can group by it; skips the raw-array
-        // `$select` form (nothing to augment). Mutates the same object asSelectMap returns.
+        // The FK is what putChildrenInParents groups on, so it outlives the relation's projection
+        // either way: added to a whitelisting `$select` (the raw-array form has nothing to augment),
+        // dropped from a subtractive `$exclude`. `relationQuery` is already a clone.
         const select = asSelectMap(relationQuery.$select);
         if (select && !select[foreignField]) {
             select[foreignField] = true;
         }
+        delete relationQuery.$exclude?.[foreignField];
         const ids = payload.map((it) => it[meta.id]);
         relationQuery.$where = { ...relationQuery.$where, [foreignField]: ids };
         const founds = await this.findMany(relEntity, relationQuery);

package/dist/type/entity.d.ts

@@ -347,10 +347,19 @@ export type RelationOptionsFor<V> = Omit<RelationOptions<RelationTarget<V>>, 'en
 export type MethodKey<E> = {
     readonly [K in keyof E]-?: NonNullable<E[K]> extends (...args: never[]) => unknown ? K : never;
 }[Key<E>];
+/**
+ * A deferred reference to an entity class, e.g. `() => Company`.
+ *
+ * A getter rather than the class itself because decorator expressions are evaluated while the class is
+ * being defined, before its binding is initialized, so naming the class directly is a `ReferenceError`
+ * for a self-reference and for whichever side of a circular import is evaluated first - the two shapes an
+ * entity graph almost always has. Nothing about the standard decorator spec changes that; it only removed
+ * the reflected `design:type` that used to make `entity` optional.
+ */
 export type EntityGetter<E = any> = () => Type<E>;
 export type CascadeType = 'persist' | 'delete';
 export type RelationOptions<E = any> = {
-    entity?: EntityGetter<E>;
+    entity: EntityGetter<E>;
     cardinality: RelationCardinality;
     readonly cascade?: boolean | CascadeType;
     mappedBy?: RelationMappedBy<E>;
@@ -362,12 +371,17 @@ export type RelationOptions<E = any> = {
     references?: RelationReferences;
 };
 /**
- * A relation once `getMeta` has resolved it: `entity` and `references` are settled and `mappedBy` is
- * the key its callback named. Consumers read this shape rather than {@link RelationOptions}, so they
- * need no assertions - `fillRelations` establishes the invariant once, and throws where it cannot.
+ * A relation once `getMeta` has resolved it: `references` is filled in and `mappedBy` is the key its
+ * callback named. Consumers read this shape rather than {@link RelationOptions}, so they need no
+ * assertions - `fillRelations` establishes the invariant once, and throws where it cannot.
+ *
+ * `entity` and `through` stay {@link EntityGetter}s. Resolution could call them once and store the class,
+ * but only by keeping the authored relations in a second map: it reads them *across* entities, and a
+ * circular import can leave the entity being read mid-resolution, where telling "no such relation" apart
+ * from "declared, but an inverse side too, so neither owns the foreign key" needs the unresolved shape
+ * still there to find. A phase-split metadata map costs more than the call parentheses it saves.
  */
-export type RelationMeta<E = any> = Omit<RelationOptions<E>, 'entity' | 'mappedBy' | 'references'> & {
-    entity: EntityGetter<E>;
+export type RelationMeta<E = any> = Omit<RelationOptions<E>, 'mappedBy' | 'references'> & {
     mappedBy?: Key<E>;
     references: RelationReferences;
 };
@@ -379,8 +393,8 @@ type RelationOwnerJoin<E> = Required<Pick<RelationOptions<E>, 'through'>> | Requ
  */
 type RelationJoin<E> = RelationOwnerJoin<E> | Required<Pick<RelationOptions<E>, 'mappedBy'>>;
 type RelationOptionsOwner<E> = Pick<RelationOptions<E>, 'entity' | 'references' | 'cascade'>;
-type RelationOptionsInverseSide<E> = Required<Pick<RelationOptions<E>, 'entity' | 'mappedBy'>> & Pick<RelationOptions<E>, 'cascade'>;
-type RelationOptionsThroughOwner<E> = Required<Pick<RelationOptions<E>, 'entity'>> & Pick<RelationOptions<E>, 'cascade'> & RelationOwnerJoin<E>;
+type RelationOptionsInverseSide<E> = Pick<RelationOptions<E>, 'entity' | 'cascade'> & Required<Pick<RelationOptions<E>, 'mappedBy'>>;
+type RelationOptionsThroughOwner<E> = Pick<RelationOptions<E>, 'entity' | 'cascade'> & RelationOwnerJoin<E>;
 /**
  * The key names of `E` as values, so `mappedBy` can be written as `(user) => user.company` instead of
  * a string literal and survive a rename.

package/dist/type/query.d.ts

@@ -172,6 +172,8 @@ export type Query<E> = {
     $populate?: QueryPopulate<E>;
     /**
      * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.
+     * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept
+     * regardless, since subtracting them would leave the relation unfilled.
      */
     $exclude?: QueryExclude<E>;
     /**

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "Extremely fast, type-safe TypeScript ORM - one API for every database",
   "license": "MIT",
-  "version": "0.24.4",
+  "version": "0.24.6",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -134,9 +134,9 @@
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.6",
-    "@types/pg": "^8.20.3",
+    "@types/pg": "^8.20.4",
     "@types/ws": "^8.18.1",
-    "better-sqlite3": "^13.0.2",
+    "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.3",
     "mongodb": "^7.5.0",
@@ -145,7 +145,7 @@
     "pg-query-stream": "^4.16.0",
     "rxjs": "^7.8.2",
     "sqlite-vec": "^0.1.9",
-    "ws": "^8.21.1"
+    "ws": "^8.21.2"
   },
   "author": "Roger Padilla",
   "repository": {
@@ -198,5 +198,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "bd6b7f65fcd1c7dfc9e1201f997cda7d687bdd5f"
+  "gitHead": "2610226954cdf152705dc47ca130f6908a91825d"
 }