@mikro-orm/core 7.1.16-dev.1 → 7.1.16-dev.11

package/drivers/DatabaseDriver.d.ts

@@ -65,13 +65,22 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
         where: FilterQuery<T>;
     };
     /**
-     * Restores the JS value of a single cursor offset: ISO strings become `Date` instances based on the
-     * property type (never based on the string shape alone), and custom types are restored via
-     * `convertToJSValue`. Values compared against a JSON document keep their serialized form instead,
-     * unless the platform preserves native date types inside JSON documents (mongo).
+     * 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. 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;
+    /**
+     * Restores the JS value of a single cursor offset. String-cursor values (`fromJson`) are decoded
+     * JSON: types implementing `fromJSON` own the round trip, other custom types restore via
+     * `convertToJSValue`, with `Date` healing for date-like columns based on the property type (never
+     * based on the string shape alone). POJO values are already JS values and only date-like strings
+     * are healed. Values compared against a JSON document keep their serialized form instead, unless
+     * the platform preserves native date types inside JSON documents (mongo).
      */
     private mapCursorOffset;
-    protected createCursorCondition<T extends object>(definition: (readonly [keyof T & string, QueryOrder])[], offsets: Dictionary[], inverse: boolean, meta: EntityMetadata<T>): FilterQuery<T>;
+    protected createCursorCondition<T extends object>(definition: (readonly [keyof T & string, QueryOrder])[], offsets: Dictionary[], inverse: boolean, meta: EntityMetadata<T>, fromJson?: boolean): FilterQuery<T>;
     /** @internal */
     mapDataToFieldNames(data: Dictionary, stringifyJsonArrays: boolean, properties?: Record<string, EntityProperty>, convertCustomTypes?: boolean, object?: boolean): Dictionary;
     protected inlineEmbeddables<T extends object>(meta: EntityMetadata<T>, data: T, where?: boolean): void;

package/drivers/DatabaseDriver.js

@@ -10,7 +10,6 @@ import { helper } from '../entity/wrap.js';
 import { Reference } from '../entity/Reference.js';
 import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { JsonType } from '../types/JsonType.js';
-import { DateTimeType } from '../types/DateTimeType.js';
 import { QueryHelper } from '../utils/QueryHelper.js';
 import { MikroORM } from '../MikroORM.js';
 /** Abstract base class for all database drivers, implementing common driver logic. */
@@ -146,6 +145,7 @@ export class DatabaseDriver {
         const createCursor = (val, key, inverse = false) => {
             const def = Reference.unwrapReference((isCursor(val, key) ? val[key] : val));
             let offsets;
+            let fromJson = false;
             // entity (and reference) instances are supported as cursors too, their properties are read the same way
             if (Utils.isPlainObject(def) || Utils.isEntity(def)) {
                 // POJO values are already JS values, extract them ordered per the definition,
@@ -158,11 +158,17 @@ export class DatabaseDriver {
                 });
             }
             else {
-                /* v8 ignore next */
-                offsets = def ? Cursor.decode(def) : [];
+                try {
+                    /* v8 ignore next */
+                    offsets = def ? Cursor.decode(def) : [];
+                }
+                catch (error) {
+                    throw CursorError.invalidCursor(meta.className, error);
+                }
+                fromJson = true;
             }
             if (definition.length > 0 && definition.length === offsets.length) {
-                return this.createCursorCondition(definition, offsets, inverse, meta);
+                return this.createCursorCondition(definition, offsets, inverse, meta, fromJson);
             }
             /* v8 ignore next */
             return {};
@@ -176,16 +182,24 @@ export class DatabaseDriver {
         if (limit != null) {
             options.limit = limit + (overfetch ? 1 : 0);
         }
-        const createOrderBy = (prop, direction) => {
+        const createOrderBy = (prop, direction, properties = meta.properties) => {
+            const propMeta = properties[prop];
             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]));
+                    Object.assign(o, createOrderBy(key, direction[key], childProps ?? {}));
                     return o;
                 }, {});
                 return { [prop]: value };
             }
-            const desc = direction === QueryOrderNumeric.DESC || direction.toString().toLowerCase() === 'desc';
+            const { desc, nullsFirst, explicit } = this.parseCursorDirection(direction);
             const dir = Utils.xor(desc, isLast) ? 'desc' : 'asc';
+            // 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}` };
+            }
             return { [prop]: dir };
         };
         // the cursor condition is created at the driver level, after the EM already converted custom types
@@ -203,12 +217,30 @@ export class DatabaseDriver {
         };
     }
     /**
-     * Restores the JS value of a single cursor offset: ISO strings become `Date` instances based on the
-     * property type (never based on the string shape alone), and custom types are restored via
-     * `convertToJSValue`. Values compared against a JSON document keep their serialized form instead,
-     * unless the platform preserves native date types inside JSON documents (mongo).
+     * 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. 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.
      */
-    mapCursorOffset(prop, value, insideJson) {
+    parseCursorDirection(direction) {
+        const dir = ('' + direction).toLowerCase();
+        const desc = direction === QueryOrderNumeric.DESC || dir.startsWith('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 };
+        }
+        return { desc, nullsFirst, explicit };
+    }
+    /**
+     * Restores the JS value of a single cursor offset. String-cursor values (`fromJson`) are decoded
+     * JSON: types implementing `fromJSON` own the round trip, other custom types restore via
+     * `convertToJSValue`, with `Date` healing for date-like columns based on the property type (never
+     * based on the string shape alone). POJO values are already JS values and only date-like strings
+     * are healed. Values compared against a JSON document keep their serialized form instead, unless
+     * the platform preserves native date types inside JSON documents (mongo).
+     */
+    mapCursorOffset(prop, value, insideJson, fromJson) {
         if (Utils.isScalarReference(value)) {
             value = value.unwrap();
         }
@@ -219,25 +251,65 @@ export class DatabaseDriver {
         if (value == null) {
             return value;
         }
+        // mongo preserves native date types inside JSON documents, restored JS values compare directly
         if (insideJson && !this.platform.preservesDatesInsideJson()) {
-            // compared against the JSON document, which holds the serialized form
+            // compared against the JSON document, which holds the JSON form of the database value
             if (value instanceof Date) {
                 return value.toISOString();
             }
-            // restore the JS value from the serialized form, `processWhere` then converts it to
-            // the database form, which is what the JSON document holds for custom typed props
-            return prop?.customType ? prop.customType.convertToJSValue(value, this.platform) : value;
+            if (prop?.customType && fromJson) {
+                const restored = prop.customType.fromJSON
+                    ? prop.customType.fromJSON(value, this.platform)
+                    : prop.customType.convertToJSValue(value, this.platform);
+                // a restored `Date` compares against its ISO string in the document, everything else
+                // keeps the JS value and gets its single `convertToDatabaseValue` in `processWhere`
+                if (restored instanceof Date) {
+                    const converted = prop.customType.convertToDatabaseValue(restored, this.platform, {
+                        fromQuery: true,
+                        key: prop.name,
+                        mode: 'query',
+                    });
+                    if (converted instanceof Date) {
+                        return converted.toISOString();
+                    }
+                }
+                return restored;
+            }
+            return value;
+        }
+        if (prop?.customType) {
+            if (fromJson && prop.customType.fromJSON) {
+                // the type owns its JSON round trip
+                return prop.customType.fromJSON(value, this.platform);
+            }
+            // A string is either a serialized form (string cursor) or a hand-written one (POJO).
+            // Types whose JS value is a `Date` must receive one. The rest get the string first,
+            // so any sub-millisecond precision survives.
+            if (typeof value === 'string' &&
+                (prop.runtimeType === 'Date' || this.platform.getMappedType(prop.columnTypes?.[0] ?? '').runtimeType === 'Date')) {
+                if (prop.runtimeType !== 'Date') {
+                    try {
+                        return prop.customType.convertToJSValue(value, this.platform);
+                    }
+                    catch {
+                        // the type cannot read the serialized string, fall back to the `Date` form
+                    }
+                }
+                return prop.customType.convertToJSValue(new Date(value), this.platform);
+            }
+            // serialized non-string values still need restoring; POJO values are already JS values
+            return fromJson ? prop.customType.convertToJSValue(value, this.platform) : value;
         }
-        if (typeof value === 'string' &&
-            (prop?.runtimeType === 'Date' ||
-                (prop?.customType && this.platform.getMappedType(prop.columnTypes?.[0] ?? '') instanceof DateTimeType))) {
-            value = new Date(value);
+        if (typeof value === 'string' && prop?.runtimeType === 'Date') {
+            return new Date(value);
         }
-        return prop?.customType ? prop.customType.convertToJSValue(value, this.platform) : value;
+        return value;
     }
-    createCursorCondition(definition, offsets, inverse, meta) {
-        const createCondition = (prop, direction, offset, eq = false, path = prop, properties = meta.properties, insideJson = false) => {
+    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];
+            // 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);
@@ -247,40 +319,57 @@ 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 value = Utils.keys(direction).reduce((o, key) => {
-                    Object.assign(o, createCondition(key, direction[key], offset?.[key], eq, `${path}.${key}`, childProps ?? {}, insideJson));
-                    return o;
-                }, {});
-                return { [prop]: value };
-            }
-            const isDesc = direction === QueryOrderNumeric.DESC || direction.toString().toLowerCase() === 'desc';
-            const dirStr = direction.toString().toLowerCase();
-            let nullsFirst;
-            if (dirStr.includes('nulls first')) {
-                nullsFirst = true;
-            }
-            else if (dirStr.includes('nulls last')) {
-                nullsFirst = false;
-            }
-            else {
-                // Default: NULLS LAST for ASC, NULLS FIRST for DESC (matches most databases)
-                nullsFirst = isDesc;
+                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], 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';
             // For leaf-level properties, undefined means missing value
             if (offset === undefined) {
                 throw CursorError.missingValue(meta.className, path);
             }
-            offset = this.mapCursorOffset(propMeta, offset, insideJson);
+            // string-cursor values are client supplied, so a value the type cannot restore is an
+            // invalid cursor, letting callers map `CursorError` to a client error response
+            try {
+                offset = this.mapCursorOffset(propMeta, offset, insideJson, fromJson);
+            }
+            catch (error) {
+                if (!fromJson || error instanceof CursorError) {
+                    throw error;
+                }
+                throw CursorError.invalidCursor(meta.className, error);
+            }
             // Handle null offset (intentional null cursor value)
             if (offset === null) {
+                // hasItemsAfterNull: forward + nullsFirst, or backward + nullsLast
+                const hasItemsAfterNull = Utils.xor(nullsFirst, inverse);
                 if (eq) {
-                    // Equal to null
-                    return { [prop]: null };
+                    // at-or-after a null sort key means every row when non-null rows follow the null block,
+                    // so the tie-breaker in the `$or` sibling can reach past it
+                    return hasItemsAfterNull ? {} : { [prop]: null };
                 }
                 // Strict comparison with null cursor value
-                // hasItemsAfterNull: forward + nullsFirst, or backward + nullsLast
-                const hasItemsAfterNull = Utils.xor(nullsFirst, inverse);
                 if (hasItemsAfterNull) {
                     return { [prop]: { $ne: null } };
                 }
@@ -288,7 +377,12 @@ export class DatabaseDriver {
                 return { [prop]: [] };
             }
             // Non-null offset
-            return { [prop]: { [operator + (eq ? 'e' : '')]: offset } };
+            const condition = { [prop]: { [operator + (eq ? 'e' : '')]: offset } };
+            // null sort keys lie past the offset here, and no comparison ever matches them
+            if (nullable && !Utils.xor(nullsFirst, inverse)) {
+                return { $or: [condition, { [prop]: null }] };
+            }
+            return condition;
         };
         const [order, ...otherOrders] = definition;
         const [offset, ...otherOffsets] = offsets;
@@ -296,13 +390,18 @@ export class DatabaseDriver {
         if (!otherOrders.length) {
             return createCondition(prop, direction, offset);
         }
-        return {
-            ...createCondition(prop, direction, offset, true),
+        const atOrPast = createCondition(prop, direction, offset, true);
+        const past = {
             $or: [
                 createCondition(prop, direction, offset),
-                this.createCursorCondition(otherOrders, otherOffsets, inverse, meta),
+                this.createCursorCondition(otherOrders, otherOffsets, inverse, meta, fromJson),
             ],
         };
+        // the `at or past` prefix is itself a group condition when it compares against nulls
+        if ('$or' in atOrPast) {
+            return { $and: [atOrPast, past] };
+        }
+        return { ...atOrPast, ...past };
     }
     /** @internal */
     mapDataToFieldNames(data, stringifyJsonArrays, properties, convertCustomTypes, object) {
@@ -422,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/Collection.js

@@ -117,9 +117,11 @@ export class Collection {
             opts.orderBy = QueryHelper.mergeOrderBy(opts.orderBy, this.property.orderBy, this.property.targetMeta?.orderBy);
             options.populate = (await em.preparePopulate(this.property.targetMeta.class, options));
             const cond = (await em.applyFilters(this.property.targetMeta.class, where, options.filters ?? {}, 'read'));
-            const map = await em
+            // fall back to the ambient transaction context, or `withSessionContext` would wrap the pivot load in a
+            // second concurrent transaction (a deadlock with a single-connection pool) instead of joining the open one
+            const map = await em.withSessionContext(ctx ?? em.getTransactionContext(), trx => em
                 .getDriver()
-                .loadFromPivotTable(this.property, [helper(this.owner).__primaryKeys], cond, opts.orderBy, ctx, options);
+                .loadFromPivotTable(this.property, [helper(this.owner).__primaryKeys], cond, opts.orderBy, trx, options));
             items = map[helper(this.owner).getSerializedPrimaryKey()].map((item) => em.merge(this.property.targetMeta.class, item, { convertCustomTypes: true }));
             await em.populate(items, options.populate, options);
         }

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 ?? [];
@@ -624,7 +635,7 @@ export class EntityLoader {
         if (!Utils.isEmpty(prop.where)) {
             where = { $and: [where, prop.where] };
         }
-        const map = await this.#driver.loadFromPivotTable(prop, ids, where, orderBy, this.#em.getTransactionContext(), options2, pivotJoin);
+        const map = await this.#em.withSessionContext(this.#em.getTransactionContext(), ctx => this.#driver.loadFromPivotTable(prop, ids, where, orderBy, ctx, options2, pivotJoin));
         const children = [];
         const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
         for (let i = 0; i < filtered.length; i++) {
@@ -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/entity/EntityRepository.d.ts

@@ -1,5 +1,5 @@
 import type { PopulatePath } from '../enums.js';
-import type { CreateOptions, EntityManager, MergeOptions } from '../EntityManager.js';
+import type { CreateOptions, EntityManager, MapOptions, MergeOptions } from '../EntityManager.js';
 import type { AssignOptions } from './EntityAssigner.js';
 import type { Dictionary, EntityData, EntityDictionary, EntityKey, EntityName, FilterQuery, Loaded, Primary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement, IndexFilterQuery, WithUsingOptions } from '../typings.js';
 import type { CountByOptions, CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
@@ -115,11 +115,10 @@ export declare class EntityRepository<Entity extends object> {
      */
     nativeDelete(where: FilterQuery<Entity>, options?: DeleteOptions<Entity>): Promise<number>;
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
-    map(result: EntityDictionary<Entity>, options?: {
-        schema?: string;
-    }): Entity;
+    map(result: EntityDictionary<Entity>, options?: Omit<MapOptions, 'mapped'>): Entity;
     /**
      * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
      * The key option specifies which property to use for identity map lookup instead of the primary key.

package/entity/EntityRepository.js

@@ -131,7 +131,8 @@ export class EntityRepository {
         return this.getEntityManager().nativeDelete(this.entityName, where, options);
     }
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
     map(result, options) {
         return this.getEntityManager().map(this.entityName, result, options);

package/entity/defineEntity.d.ts

@@ -22,7 +22,7 @@ type HasKind<Options, K extends string> = Options extends {
     kind: infer X extends string;
 } ? X extends K ? true : false : false;
 /** Lightweight chain result type for property builders - reduces type instantiation cost by avoiding full class resolution. */
-export interface PropertyChain<Value, Options> {
+export interface PropertyChain<in out Value, in out Options> {
     '~type'?: {
         value: Value;
     };
@@ -148,6 +148,8 @@ export interface PropertyChain<Value, Options> {
     orphanRemoval(orphanRemoval?: boolean): HasKind<Options, '1:m' | '1:1'> extends true ? PropertyChain<Value, Options> : never;
     discriminator(discriminator: string): HasKind<Options, 'm:1' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     discriminatorMap(discriminatorMap: Dictionary<string>): HasKind<Options, 'm:1' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
+    /** Resolve this read-only to-one relation via a subquery on another entity (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through(through: () => EntityName): HasKind<Options, 'm:1' | '1:1'> extends true ? PropertyChain<Value, Options> : never;
     pivotTable(pivotTable: string): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     pivotEntity(pivotEntity: () => EntityName): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     fixedOrder(fixedOrder?: boolean): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
@@ -180,7 +182,7 @@ export interface PropertyChain<Value, Options> {
     foreignKeyName(foreignKeyName: string): HasKind<Options, 'm:1' | '1:m' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
 }
 /** @internal */
-export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys extends BuilderKeys> implements Record<Exclude<UniversalPropertyKeys, ExcludeKeys>, any> {
+export declare class UniversalPropertyOptionsBuilder<in out Value, in out Options, in out IncludeKeys extends BuilderKeys> implements Record<Exclude<UniversalPropertyKeys, ExcludeKeys>, any> {
     '~options': Options;
     '~type'?: {
         value: Value;
@@ -528,6 +530,8 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     fixedOrderColumn(fixedOrderColumn: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Override default name for pivot table (see {@doclink naming-strategy | Naming Strategy}). */
     pivotTable(pivotTable: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    /** Resolve this read-only to-one relation via a subquery on another entity (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through(through: () => EntityName): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Set pivot entity for this relation (see {@doclink collections#custom-pivot-table-entity | Custom pivot table entity}). */
     pivotEntity(pivotEntity: () => EntityName): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Override the default database column name on the owning side (see {@doclink naming-strategy | Naming Strategy}). This option is only for simple properties represented by a single column. */
@@ -570,6 +574,13 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
 export interface EmptyOptions extends Partial<Record<UniversalPropertyKeys, unknown>> {
 }
 /** @internal */
+export declare class StringPropertyOptionsBuilder<Value, Options> extends UniversalPropertyOptionsBuilder<Value, Options, IncludeKeysForProperty> {
+    trim(): StringPropertyOptionsBuilder<Value, Options>;
+    lowercase(): StringPropertyOptionsBuilder<Value, Options>;
+    uppercase(): StringPropertyOptionsBuilder<Value, Options>;
+    private withOptions;
+}
+/** @internal */
 export declare class OneToManyOptionsBuilderOnlyMappedBy<Value extends object> extends UniversalPropertyOptionsBuilder<Value, EmptyOptions & {
     kind: '1:m';
 }, IncludeKeysForOneToManyOptions> {
@@ -582,7 +593,7 @@ type EntityTarget = {
     '~entity': any;
 } | EntityClass;
 declare const propertyBuilders: PropertyBuilders;
-type PropertyBuildersOverrideKeys = 'bigint' | 'array' | 'decimal' | 'json' | 'datetime' | 'time' | 'enum';
+type PropertyBuildersOverrideKeys = 'bigint' | 'array' | 'decimal' | 'json' | 'string' | 'text' | 'datetime' | 'time' | 'enum';
 /** Map of factory functions for creating type-safe property builders (scalars, enums, embeddables, and relations). */
 export type PropertyBuilders = {
     [K in Exclude<keyof typeof types, PropertyBuildersOverrideKeys>]: () => UniversalPropertyOptionsBuilder<InferPropertyValueType<(typeof types)[K]>, EmptyOptions, IncludeKeysForProperty>;
@@ -591,6 +602,8 @@ export type PropertyBuilders = {
     array: <T = string>(toJsValue?: (i: string) => T, toDbValue?: (i: T) => string) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.array<T>>, EmptyOptions, IncludeKeysForProperty>;
     decimal: <Mode extends 'number' | 'string' = 'string'>(mode?: Mode) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.decimal<Mode>>, EmptyOptions, IncludeKeysForProperty>;
     json: <T>() => UniversalPropertyOptionsBuilder<T, EmptyOptions, IncludeKeysForProperty>;
+    string: () => StringPropertyOptionsBuilder<InferPropertyValueType<typeof types.string>, EmptyOptions>;
+    text: () => StringPropertyOptionsBuilder<InferPropertyValueType<typeof types.text>, EmptyOptions>;
     formula: <T>(formula: string | FormulaCallback<any>) => UniversalPropertyOptionsBuilder<T, EmptyOptions, IncludeKeysForProperty>;
     datetime: (length?: number) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.datetime>, EmptyOptions, IncludeKeysForProperty>;
     time: (length?: number) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.time>, EmptyOptions, IncludeKeysForProperty>;
@@ -638,6 +651,9 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         entity?: EntityName<any> | EntityName<any>[];
         args?: boolean;
         strict?: boolean;
+        rls?: boolean | {
+            setting?: string;
+        };
     }>;
     forceObject?: TForceObject;
     embeddable?: TEmbeddable;
@@ -726,16 +742,18 @@ type InferTypeByString<T extends string> = T extends keyof typeof types ? InferJ
 type InferJSType<T> = T extends typeof Type<infer TValue, any> ? NonNullable<TValue> : never;
 type InferColumnType<T extends string> = T extends 'int' | 'int4' | 'integer' | 'bigint' | 'int8' | 'int2' | 'tinyint' | 'smallint' | 'mediumint' ? number : T extends 'double' | 'double precision' | 'real' | 'float8' | 'decimal' | 'numeric' | 'float' | 'float4' ? number : T extends 'datetime' | 'time' | 'time with time zone' | 'timestamp' | 'timestamp with time zone' | 'timetz' | 'timestamptz' | 'date' | 'interval' ? Date : T extends 'ObjectId' | 'objectId' | 'character varying' | 'varchar' | 'char' | 'character' | 'uuid' | 'text' | 'tinytext' | 'mediumtext' | 'longtext' | 'enum' ? string : T extends 'boolean' | 'bool' | 'bit' ? boolean : T extends 'blob' | 'tinyblob' | 'mediumblob' | 'longblob' | 'bytea' ? Buffer : T extends 'point' | 'line' | 'lseg' | 'box' | 'circle' | 'path' | 'polygon' | 'geometry' ? number[] : T extends 'tsvector' | 'tsquery' ? string[] : T extends 'json' | 'jsonb' ? any : any;
 type BaseEntityMethodKeys = 'toObject' | 'toPOJO' | 'serialize' | 'assign' | 'populate' | 'init' | 'toReference';
+interface BaseEntityMethods<in out Entity extends object> extends Pick<IWrappedEntity<Entity>, BaseEntityMethodKeys> {
+}
 /** Infers the entity type from a `defineEntity()` properties map, resolving builders, base classes, and primary keys. */
 export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined, Embeddable extends boolean = false> = (IsNever<Base> extends true ? {} : Base extends {
     toObject(...args: any[]): any;
-} ? Pick<IWrappedEntity<{
+} ? BaseEntityMethods<{
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
 } & {
     [PrimaryKeyProp]?: InferCombinedPrimaryKey<Properties, PK, Base>;
 } & (IsNever<Repository> extends true ? {} : {
     [EntityRepositoryType]?: Repository extends Constructor<infer R> ? R : Repository;
-}) & NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue, Embeddable>>, BaseEntityMethodKeys> : {}) & {
+}) & NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue, Embeddable>> : {}) & {
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
 } & {
     [PrimaryKeyProp]?: InferCombinedPrimaryKey<Properties, PK, Base>;