@mikro-orm/core 7.2.0-dev.17 → 7.2.0-dev.19

package/EntityManager.js

@@ -512,6 +512,7 @@ export class EntityManager {
                 filters,
                 populate: hint.children,
                 populateWhere: PopulateHint.ALL,
+                populateFilter: undefined,
             });
             if (Utils.hasObjectKeys(where)) {
                 ret[field] = ret[field] ? { $and: [where, ret[field]] } : where;

package/drivers/DatabaseDriver.d.ts

@@ -66,9 +66,9 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
     };
     /**
      * Resolves a leaf `orderBy` direction into the two flags the rewritten `orderBy` and the cursor
-     * condition have to agree on, or pagination skips rows at the null boundary. Platforms that cannot
-     * order nulls explicitly sort them as the lowest value, elsewhere the requested placement wins,
-     * defaulting to nulls last for `asc` and nulls first for `desc`.
+     * condition have to agree on, or pagination skips rows at the null boundary. A placement the caller
+     * asked for wins where the platform can honor it, anything else follows the platform's own default,
+     * which is what the untouched `orderBy` will get.
      */
     private parseCursorDirection;
     /**

package/drivers/DatabaseDriver.js

@@ -182,22 +182,21 @@ export class DatabaseDriver {
         if (limit != null) {
             options.limit = limit + (overfetch ? 1 : 0);
         }
-        const createOrderBy = (prop, direction, properties = meta.properties, nullable = false) => {
+        const createOrderBy = (prop, direction, properties = meta.properties) => {
             const propMeta = properties[prop];
-            // a nullable relation or embeddable makes its joined columns null too
-            nullable ||= !!propMeta?.nullable;
             if (Utils.isPlainObject(direction)) {
                 const childProps = propMeta?.kind === ReferenceKind.EMBEDDED ? propMeta.embeddedProps : propMeta?.targetMeta?.properties;
                 const value = Utils.getObjectQueryKeys(direction).reduce((o, key) => {
-                    Object.assign(o, createOrderBy(key, direction[key], childProps ?? {}, nullable));
+                    Object.assign(o, createOrderBy(key, direction[key], childProps ?? {}));
                     return o;
                 }, {});
                 return { [prop]: value };
             }
-            const { desc, nullsFirst } = this.parseCursorDirection(direction);
+            const { desc, nullsFirst, explicit } = this.parseCursorDirection(direction);
             const dir = Utils.xor(desc, isLast) ? 'desc' : 'asc';
-            // the condition assumes a placement, spell it out instead of taking the database default
-            if (nullable && this.platform.supportsNullsOrdering()) {
+            // only a requested placement is spelled out, an unqualified direction already lands where the
+            // condition expects it; backward pagination reverses the ordering, so the placement flips too
+            if (explicit) {
                 const nulls = Utils.xor(nullsFirst, isLast) ? 'first' : 'last';
                 return { [prop]: `${dir} nulls ${nulls}` };
             }
@@ -219,23 +218,19 @@ export class DatabaseDriver {
     }
     /**
      * Resolves a leaf `orderBy` direction into the two flags the rewritten `orderBy` and the cursor
-     * condition have to agree on, or pagination skips rows at the null boundary. Platforms that cannot
-     * order nulls explicitly sort them as the lowest value, elsewhere the requested placement wins,
-     * defaulting to nulls last for `asc` and nulls first for `desc`.
+     * condition have to agree on, or pagination skips rows at the null boundary. A placement the caller
+     * asked for wins where the platform can honor it, anything else follows the platform's own default,
+     * which is what the untouched `orderBy` will get.
      */
     parseCursorDirection(direction) {
         const dir = ('' + direction).toLowerCase();
         const desc = direction === QueryOrderNumeric.DESC || dir.startsWith('desc');
-        if (!this.platform.supportsNullsOrdering()) {
-            return { desc, nullsFirst: !desc };
+        const nullsFirst = dir.includes('nulls first');
+        const explicit = (nullsFirst || dir.includes('nulls last')) && this.platform.supportsNullsOrdering();
+        if (!explicit) {
+            return { desc, nullsFirst: this.platform.sortsNullsLowest() ? !desc : desc, explicit };
         }
-        if (dir.includes('nulls first')) {
-            return { desc, nullsFirst: true };
-        }
-        if (dir.includes('nulls last')) {
-            return { desc, nullsFirst: false };
-        }
-        return { desc, nullsFirst: desc };
+        return { desc, nullsFirst, explicit };
     }
     /**
      * Restores the JS value of a single cursor offset. String-cursor values (`fromJson`) are decoded
@@ -313,8 +308,8 @@ export class DatabaseDriver {
     createCursorCondition(definition, offsets, inverse, meta, fromJson = false) {
         const createCondition = (prop, direction, offset, eq = false, path = prop, properties = meta.properties, insideJson = false, nullable = false) => {
             const propMeta = properties[prop];
-            // a nullable relation or embeddable makes its joined columns null too
-            nullable ||= !!propMeta?.nullable;
+            // nullable relations and embeddables null out their joined columns, and a formula can yield null unannounced
+            nullable ||= !!propMeta?.nullable || !!propMeta?.formula;
             if (Utils.isPlainObject(direction)) {
                 if (offset === undefined) {
                     throw CursorError.missingValue(meta.className, path);
@@ -324,17 +319,29 @@ export class DatabaseDriver {
                 const childProps = propMeta?.kind === ReferenceKind.EMBEDDED ? propMeta.embeddedProps : propMeta?.targetMeta?.properties;
                 insideJson ||=
                     (propMeta?.kind === ReferenceKind.EMBEDDED && !!propMeta.object) || propMeta?.customType instanceof JsonType;
-                const children = Utils.keys(direction)
-                    .map(key => createCondition(key, direction[key], 
+                const keys = Utils.keys(direction);
+                const child = (key, childEq) => createCondition(key, direction[key], 
                 // a null relation offset means the whole sort key is null, propagate it to the leaves
-                offset === null ? null : offset[key], eq, `${path}.${key}`, childProps ?? {}, insideJson, nullable))
-                    .filter(child => Utils.hasObjectKeys(child));
-                // children comparing against nulls are group conditions, those cannot be merged into one object
-                const value = children.length > 1 && children.some(child => '$or' in child)
-                    ? { $and: children }
-                    : children.reduce((o, child) => Object.assign(o, child), {});
-                // an unconstrained child condition must not degrade to `{ [prop]: {} }`
-                return children.length > 0 ? { [prop]: value } : {};
+                offset === null ? null : offset[key], childEq, `${path}.${key}`, childProps ?? {}, insideJson, nullable);
+                // the group's own keys are a keyset in their own right, so they decompose the same way the
+                // top level does; merging them into one object would compare every key independently instead
+                const lex = (index) => {
+                    const key = keys[index];
+                    if (index === keys.length - 1) {
+                        return child(key, eq);
+                    }
+                    const atOrPast = child(key, true);
+                    const tail = lex(index + 1);
+                    // an unconstrained tail matches anything, leaving only the `at or past` prefix to constrain
+                    const past = Utils.hasObjectKeys(tail) ? { $or: [child(key, false), tail] } : {};
+                    if (!Utils.hasObjectKeys(past)) {
+                        return atOrPast;
+                    }
+                    return Utils.hasObjectKeys(atOrPast) ? { $and: [atOrPast, past] } : past;
+                };
+                const value = keys.length > 0 ? lex(0) : {};
+                // an unconstrained group condition must not degrade to `{ [prop]: {} }`
+                return Utils.hasObjectKeys(value) ? { [prop]: value } : {};
             }
             const { desc: isDesc, nullsFirst } = this.parseCursorDirection(direction);
             const operator = Utils.xor(isDesc, inverse) ? '$lt' : '$gt';
@@ -514,8 +521,8 @@ export class DatabaseDriver {
                 const props = prop.embeddedProps;
                 let unknownProp = false;
                 Object.keys(data[prop.name]).forEach(kk => {
-                    // explicitly allow `$exists`, `$eq`, `$ne` and `$elemMatch` operators here as they can't be misused this way
-                    const operator = Object.keys(data[prop.name]).some(f => Utils.isOperator(f) && !['$exists', '$ne', '$eq', '$elemMatch'].includes(f));
+                    // explicitly allow `$exists`, `$eq`, `$ne`, `$elemMatch` and `$all` operators here as they can't be misused this way
+                    const operator = Object.keys(data[prop.name]).some(f => Utils.isOperator(f) && !['$exists', '$ne', '$eq', '$elemMatch', '$all'].includes(f));
                     if (operator) {
                         throw ValidationError.cannotUseOperatorsInsideEmbeddables(meta.class, prop.name, data);
                     }

package/entity/EntityLoader.d.ts

@@ -1,4 +1,4 @@
-import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, PopulateHintOptions, PopulateOptions } from '../typings.js';
+import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, ObjectQuery, PopulateHintOptions, PopulateOptions } from '../typings.js';
 import type { EntityManager } from '../EntityManager.js';
 import { LoadStrategy, type LockMode, type PopulateHint, PopulatePath, type QueryOrderMap } from '../enums.js';
 import type { InflightQueryAbortStrategy } from '../connections/Connection.js';
@@ -14,6 +14,8 @@ export interface EntityLoaderOptions<Entity, Fields extends string = never, Excl
     where?: FilterQuery<Entity>;
     /** Controls how `where` conditions are applied to populated relations. */
     populateWhere?: PopulateHint | `${PopulateHint}`;
+    /** @see FindOptions.populateFilter */
+    populateFilter?: ObjectQuery<Entity>;
     /** Ordering for populated relations. */
     orderBy?: QueryOrderMap<Entity> | QueryOrderMap<Entity>[];
     /** Whether to reload already loaded entities. */
@@ -77,6 +79,10 @@ export declare class EntityLoader {
     /** @internal */
     findChildrenFromPivotTable<Entity extends object>(filtered: Entity[], prop: EntityProperty<Entity>, options: Required<EntityLoaderOptions<Entity>>, orderBy?: QueryOrderMap<Entity>[], populate?: PopulateOptions<Entity>, pivotJoin?: boolean): Promise<AnyEntity[][]>;
     private extractChildCondition;
+    /** Extracts the part of `options.populateFilter` that applies to the given relation. */
+    private extractChildPopulateFilter;
+    /** Splits an extracted populate filter into the conditions on the populated entity and those on its own relations. */
+    private splitPopulateFilter;
     private buildFields;
     private getChildReferences;
     private filterCollections;

package/entity/EntityLoader.js

@@ -334,7 +334,7 @@ export class EntityLoader {
         // When targetKey is set, use it for FK lookup instead of the PK
         let fk = prop.targetKey ?? Utils.getPrimaryKeyHash(meta.primaryKeys);
         let schema = options.schema;
-        const partial = !Utils.isEmpty(prop.where) || !Utils.isEmpty(options.where);
+        const partial = !Utils.isEmpty(prop.where) || !Utils.isEmpty(options.where) || !Utils.isEmpty(options.populateFilter);
         let polymorphicOwnerProp;
         const ownerProp = prop.kind === ReferenceKind.ONE_TO_MANY || (prop.kind === ReferenceKind.MANY_TO_MANY && !prop.owner)
             ? meta.properties[prop.mappedBy]
@@ -394,12 +394,20 @@ export class EntityLoader {
         if (!Utils.isEmpty(prop.where) || Raw.hasObjectFragments(prop.where)) {
             where = { $and: [where, prop.where] };
         }
+        const childFilter = options.populateFilter ? await this.extractChildPopulateFilter(options, prop) : undefined;
+        // conditions on the populated entity itself have no sink in the child query (the joined strategy puts
+        // them on the join), only the nested relation ones can be forwarded as its own `populateFilter`
+        const [ownFilter, nestedFilter] = this.splitPopulateFilter(childFilter, meta);
+        if (ownFilter) {
+            where = { $and: [where, ownFilter] };
+        }
         const orderBy = QueryHelper.mergeOrderBy(options.orderBy, prop.orderBy);
         const findOptions = {
             filters,
             convertCustomTypes,
             lockMode,
             populateWhere,
+            populateFilter: nestedFilter,
             logging,
             orderBy,
             populate: populate.children ?? populate.all ?? [],
@@ -575,6 +583,9 @@ export class EntityLoader {
                 filters,
                 ignoreLazyScalarProperties,
                 populateWhere,
+                populateFilter: options.populateFilter
+                    ? (await this.extractChildPopulateFilter(options, prop))
+                    : undefined,
                 connectionType,
                 logging,
                 schema,
@@ -611,7 +622,7 @@ export class EntityLoader {
         const fields = this.buildFields(options.fields, prop);
         // oxfmt-ignore
         const exclude = Array.isArray(options.exclude) ? Utils.extractChildElements(options.exclude, prop.name) : options.exclude;
-        const populateFilter = options.populateFilter?.[prop.name];
+        const populateFilter = options.populateFilter ? await this.extractChildPopulateFilter(options, prop) : undefined;
         const options2 = { ...options, fields, exclude, populateFilter };
         ['limit', 'offset', 'first', 'last', 'before', 'after', 'overfetch'].forEach(prop => delete options2[prop]);
         options2.populate = populate?.children ?? [];
@@ -656,7 +667,8 @@ export class EntityLoader {
     }
     async extractChildCondition(options, prop, filters = false) {
         const where = options.where;
-        const subCond = Utils.isPlainObject(where[prop.name]) ? where[prop.name] : {};
+        // shallow copy, the operator normalization below must not mutate the caller's condition
+        const subCond = Utils.isPlainObject(where[prop.name]) ? { ...where[prop.name] } : {};
         const meta2 = prop.targetMeta;
         const pk = Utils.getPrimaryKeyHash(meta2.primaryKeys);
         ['$and', '$or'].forEach(op => {
@@ -679,8 +691,8 @@ export class EntityLoader {
         });
         const operators = Object.keys(subCond).filter(key => Utils.isOperator(key, false));
         if (operators.length > 0) {
+            subCond[pk] = Utils.isPlainObject(subCond[pk]) ? { ...subCond[pk] } : (subCond[pk] ?? {});
             operators.forEach(op => {
-                subCond[pk] ??= {};
                 subCond[pk][op] = subCond[op];
                 delete subCond[op];
             });
@@ -690,6 +702,24 @@ export class EntityLoader {
         }
         return subCond;
     }
+    /** Extracts the part of `options.populateFilter` that applies to the given relation. */
+    async extractChildPopulateFilter(options, prop) {
+        const filter = await this.extractChildCondition({ ...options, where: options.populateFilter }, prop);
+        return Utils.isEmpty(filter) ? undefined : filter;
+    }
+    /** Splits an extracted populate filter into the conditions on the populated entity and those on its own relations. */
+    splitPopulateFilter(filter, meta) {
+        if (!filter) {
+            return [undefined, undefined];
+        }
+        const own = {};
+        const nested = {};
+        for (const key of Object.keys(filter)) {
+            const target = meta.relations.some(rel => rel.name === key) ? nested : own;
+            target[key] = filter[key];
+        }
+        return [Utils.isEmpty(own) ? undefined : own, Utils.isEmpty(nested) ? undefined : nested];
+    }
     buildFields(fields = [], prop, ref) {
         if (ref) {
             fields = prop.targetMeta.primaryKeys.map(targetPkName => `${prop.name}.${targetPkName}`);

package/enums.d.ts

@@ -39,6 +39,8 @@ export declare enum QueryOperator {
     $in = "in",
     /** Not included in the given list. */
     $nin = "not in",
+    /** Contains all of the given values, supported on collection properties and on mongo arrays. */
+    $all = "all",
     /** Greater than. */
     $gt = ">",
     /** Greater than or equal to. */

package/enums.js

@@ -41,6 +41,8 @@ export var QueryOperator;
     QueryOperator["$in"] = "in";
     /** Not included in the given list. */
     QueryOperator["$nin"] = "not in";
+    /** Contains all of the given values, supported on collection properties and on mongo arrays. */
+    QueryOperator["$all"] = "all";
     /** Greater than. */
     QueryOperator["$gt"] = ">";
     /** Greater than or equal to. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.2.0-dev.17",
+  "version": "7.2.0-dev.19",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",

package/platforms/Platform.d.ts

@@ -230,8 +230,10 @@ export declare abstract class Platform {
     convertsJsonAutomatically(): boolean;
     /** Whether date values inside JSON documents keep their native type (e.g. BSON dates), instead of being serialized to ISO strings. */
     preservesDatesInsideJson(): boolean;
-    /** Whether `nulls first`/`nulls last` can be requested in an `orderBy`. Platforms returning `false` always sort nulls as the lowest value. */
+    /** Whether `nulls first`/`nulls last` can be requested in an `orderBy`. */
     supportsNullsOrdering(): boolean;
+    /** Where nulls land when an `orderBy` requests no explicit placement: lowest (`asc` puts them first) or highest. */
+    sortsNullsLowest(): boolean;
     /** Converts a JS value to its JSON database representation (typically JSON.stringify). */
     convertJsonToDatabaseValue(value: unknown, context?: TransformContext): unknown;
     /** Converts a database JSON value to its JS representation. */

package/platforms/Platform.js

@@ -471,10 +471,14 @@ export class Platform {
     preservesDatesInsideJson() {
         return false;
     }
-    /** Whether `nulls first`/`nulls last` can be requested in an `orderBy`. Platforms returning `false` always sort nulls as the lowest value. */
+    /** Whether `nulls first`/`nulls last` can be requested in an `orderBy`. */
     supportsNullsOrdering() {
         return true;
     }
+    /** Where nulls land when an `orderBy` requests no explicit placement: lowest (`asc` puts them first) or highest. */
+    sortsNullsLowest() {
+        return false;
+    }
     /** Converts a JS value to its JSON database representation (typically JSON.stringify). */
     convertJsonToDatabaseValue(value, context) {
         return JSON.stringify(value);

package/typings.d.ts

@@ -314,6 +314,7 @@ export type OperatorMap<T> = {
     $ne?: ExpandScalar<T> | readonly ExpandScalar<T>[] | Subquery;
     $in?: readonly ExpandScalar<T>[] | readonly Primary<T>[] | Raw | Subquery;
     $nin?: readonly ExpandScalar<T>[] | readonly Primary<T>[] | Raw | Subquery;
+    $all?: readonly ExpandQuery<T>[];
     $not?: ExpandQuery<T>;
     $none?: ExpandQuery<T>;
     $some?: ExpandQuery<T>;

package/utils/Utils.js

@@ -153,7 +153,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.2.0-dev.17';
+    static #ORM_VERSION = '7.2.0-dev.19';
     /** Default session variable name backing an RLS filter argument (`current_setting('mikro.<filter>.<arg>')`). */
     static getRlsSettingName(filterName, argName) {
         return `mikro.${filterName}.${argName}`;
@@ -858,7 +858,11 @@ export class Utils {
             return await import(module);
         }
         catch (err) {
-            if (warning && err.code === 'ERR_MODULE_NOT_FOUND') {
+            // only a missing module is expected here, anything else is a real failure inside the module
+            if (!['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'].includes(err.code)) {
+                throw err;
+            }
+            if (warning) {
                 // eslint-disable-next-line no-console
                 console.warn(warning);
             }