@mikro-orm/core 7.0.0-dev.15 → 7.0.0-dev.150

package/entity/EntityLoader.js

@@ -4,8 +4,8 @@ import { ValidationError } from '../errors.js';
 import { LoadStrategy, PopulatePath, ReferenceKind, } from '../enums.js';
 import { Reference } from './Reference.js';
 import { helper } from './wrap.js';
-import { raw, RawQueryFragment } from '../utils/RawQueryFragment.js';
 import { expandDotPaths } from './utils.js';
+import { Raw } from '../utils/RawQueryFragment.js';
 export class EntityLoader {
     em;
     metadata;
@@ -32,17 +32,16 @@ export class EntityLoader {
         const visited = options.visited ??= new Set();
         options.where ??= {};
         options.orderBy ??= {};
-        options.filters ??= {};
         options.lookup ??= true;
         options.validate ??= true;
         options.refresh ??= false;
         options.convertCustomTypes ??= true;
         if (references.length > 0) {
-            await this.populateScalar(meta, references, options);
+            await this.populateScalar(meta, references, { ...options, populateWhere: undefined });
         }
         populate = this.normalizePopulate(entityName, populate, options.strategy, options.lookup);
         const invalid = populate.find(({ field }) => !this.em.canPopulate(entityName, field));
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (options.validate && invalid) {
             throw ValidationError.invalidPropertyName(entityName, invalid.field);
         }
@@ -140,35 +139,39 @@ export class EntityLoader {
         const innerOrderBy = Utils.asArray(options.orderBy)
             .filter(orderBy => (Array.isArray(orderBy[prop.name]) && orderBy[prop.name].length > 0) || Utils.isObject(orderBy[prop.name]))
             .flatMap(orderBy => orderBy[prop.name]);
+        const where = await this.extractChildCondition(options, prop);
         if (prop.kind === ReferenceKind.MANY_TO_MANY && this.driver.getPlatform().usesPivotTable()) {
             const res = await this.findChildrenFromPivotTable(filtered, prop, options, innerOrderBy, populate, !!ref);
             return Utils.flatten(res);
         }
-        const where = await this.extractChildCondition(options, prop);
-        const data = await this.findChildren(entities, prop, populate, { ...options, where, orderBy: innerOrderBy }, !!(ref || prop.mapToPk));
-        this.initializeCollections(filtered, prop, field, data, innerOrderBy.length > 0);
-        return data;
+        const { items, partial } = await this.findChildren(options.filtered ?? entities, prop, populate, {
+            ...options,
+            where,
+            orderBy: innerOrderBy,
+        }, !!(ref || prop.mapToPk));
+        this.initializeCollections(filtered, prop, field, items, innerOrderBy.length > 0, partial);
+        return items;
     }
     async populateScalar(meta, filtered, options) {
         const pk = Utils.getPrimaryKeyHash(meta.primaryKeys);
-        const ids = Utils.unique(filtered.map(e => Utils.getPrimaryKeyValues(e, meta.primaryKeys, true)));
+        const ids = Utils.unique(filtered.map(e => Utils.getPrimaryKeyValues(e, meta, true)));
         const where = this.mergePrimaryCondition(ids, pk, options, meta, this.metadata, this.driver.getPlatform());
         const { filters, convertCustomTypes, lockMode, strategy, populateWhere, connectionType, logging, fields } = options;
-        await this.em.find(meta.className, where, {
+        await this.em.find(meta.class, where, {
             filters, convertCustomTypes, lockMode, strategy, populateWhere, connectionType, logging,
             fields: fields,
             populate: [],
         });
     }
-    initializeCollections(filtered, prop, field, children, customOrder) {
+    initializeCollections(filtered, prop, field, children, customOrder, partial) {
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
-            this.initializeOneToMany(filtered, children, prop, field);
+            this.initializeOneToMany(filtered, children, prop, field, partial);
         }
         if (prop.kind === ReferenceKind.MANY_TO_MANY && !this.driver.getPlatform().usesPivotTable()) {
-            this.initializeManyToMany(filtered, children, prop, field, customOrder);
+            this.initializeManyToMany(filtered, children, prop, field, customOrder, partial);
         }
     }
-    initializeOneToMany(filtered, children, prop, field) {
+    initializeOneToMany(filtered, children, prop, field, partial) {
         const mapToPk = prop.targetMeta.properties[prop.mappedBy].mapToPk;
         const map = {};
         for (const entity of filtered) {
@@ -178,20 +181,20 @@ export class EntityLoader {
         for (const child of children) {
             const pk = child.__helper.__data[prop.mappedBy] ?? child[prop.mappedBy];
             if (pk) {
-                const key = helper(mapToPk ? this.em.getReference(prop.type, pk) : pk).getSerializedPrimaryKey();
+                const key = helper(mapToPk ? this.em.getReference(prop.targetMeta.class, pk) : pk).getSerializedPrimaryKey();
                 map[key]?.push(child);
             }
         }
         for (const entity of filtered) {
             const key = helper(entity).getSerializedPrimaryKey();
-            entity[field].hydrate(map[key]);
+            entity[field].hydrate(map[key], undefined, partial);
         }
     }
-    initializeManyToMany(filtered, children, prop, field, customOrder) {
+    initializeManyToMany(filtered, children, prop, field, customOrder, partial) {
         if (prop.mappedBy) {
             for (const entity of filtered) {
                 const items = children.filter(child => child[prop.mappedBy].contains(entity, false));
-                entity[field].hydrate(items, true);
+                entity[field].hydrate(items, true, partial);
             }
         }
         else { // owning side of M:N without pivot table needs to be reordered
@@ -201,15 +204,16 @@ export class EntityLoader {
                 if (!customOrder) {
                     items.sort((a, b) => order.indexOf(a) - order.indexOf(b));
                 }
-                entity[field].hydrate(items, true);
+                entity[field].hydrate(items, true, partial);
             }
         }
     }
     async findChildren(entities, prop, populate, options, ref) {
-        const children = this.getChildReferences(entities, prop, options, ref);
+        const children = Utils.unique(this.getChildReferences(entities, prop, options, ref));
         const meta = prop.targetMeta;
         let fk = Utils.getPrimaryKeyHash(meta.primaryKeys);
         let schema = options.schema;
+        const partial = !Utils.isEmpty(prop.where) || !Utils.isEmpty(options.where);
         if (prop.kind === ReferenceKind.ONE_TO_MANY || (prop.kind === ReferenceKind.MANY_TO_MANY && !prop.owner)) {
             fk = meta.properties[prop.mappedBy].name;
         }
@@ -219,7 +223,7 @@ export class EntityLoader {
             children.push(...this.filterByReferences(entities, prop.name, options.refresh));
         }
         if (children.length === 0) {
-            return [];
+            return { items: [], partial };
         }
         if (!schema && [ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind)) {
             schema = children.find(e => e.__helper.__schema)?.__helper.__schema;
@@ -228,33 +232,19 @@ export class EntityLoader {
         let where = this.mergePrimaryCondition(ids, fk, options, meta, this.metadata, this.driver.getPlatform());
         const fields = this.buildFields(options.fields, prop, ref);
         /* eslint-disable prefer-const */
-        let { refresh, filters, convertCustomTypes, lockMode, strategy, populateWhere, connectionType, logging, } = options;
+        let { refresh, filters, convertCustomTypes, lockMode, strategy, populateWhere = 'infer', connectionType, logging, } = options;
         /* eslint-enable prefer-const */
         if (typeof populateWhere === 'object') {
             populateWhere = await this.extractChildCondition({ where: populateWhere }, prop);
         }
-        if (!Utils.isEmpty(prop.where)) {
+        if (!Utils.isEmpty(prop.where) || Raw.hasObjectFragments(prop.where)) {
             where = { $and: [where, prop.where] };
         }
-        const propOrderBy = [];
-        if (prop.orderBy) {
-            for (const item of Utils.asArray(prop.orderBy)) {
-                for (const field of Utils.keys(item)) {
-                    const rawField = RawQueryFragment.getKnownFragment(field, false);
-                    if (rawField) {
-                        const raw2 = raw(rawField.sql, rawField.params);
-                        propOrderBy.push({ [raw2.toString()]: item[field] });
-                        continue;
-                    }
-                    propOrderBy.push({ [field]: item[field] });
-                }
-            }
-        }
-        const orderBy = [...Utils.asArray(options.orderBy), ...propOrderBy].filter((order, idx, array) => {
+        const orderBy = [...Utils.asArray(options.orderBy), ...Utils.asArray(prop.orderBy)].filter((order, idx, array) => {
             // skip consecutive ordering with the same key to get around mongo issues
-            return idx === 0 || !Utils.equals(Object.keys(array[idx - 1]), Object.keys(order));
+            return idx === 0 || !Utils.equals(Utils.getObjectQueryKeys(array[idx - 1]), Utils.getObjectQueryKeys(order));
         });
-        const items = await this.em.find(prop.type, where, {
+        const items = await this.em.find(meta.class, where, {
             filters, convertCustomTypes, lockMode, populateWhere, logging,
             orderBy,
             populate: populate.children ?? populate.all ?? [],
@@ -265,6 +255,24 @@ export class EntityLoader {
             // @ts-ignore not a public option, will be propagated to the populate call
             visited: options.visited,
         });
+        if ([ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) && items.length !== children.length) {
+            const nullVal = this.em.config.get('forceUndefined') ? undefined : null;
+            const itemsMap = new Set();
+            const childrenMap = new Set();
+            for (const item of items) {
+                itemsMap.add(helper(item).getSerializedPrimaryKey());
+            }
+            for (const child of children) {
+                childrenMap.add(helper(child).getSerializedPrimaryKey());
+            }
+            for (const entity of entities) {
+                const key = helper(entity[prop.name] ?? {})?.getSerializedPrimaryKey();
+                if (childrenMap.has(key) && !itemsMap.has(key)) {
+                    entity[prop.name] = nullVal;
+                    helper(entity).__originalEntityData[prop.name] = null;
+                }
+            }
+        }
         for (const item of items) {
             if (ref && !helper(item).__onLoadFired) {
                 helper(item).__initialized = false;
@@ -272,10 +280,10 @@ export class EntityLoader {
                 this.em.getUnitOfWork()['loadedEntities'].delete(item);
             }
         }
-        return items;
+        return { items, partial };
     }
     mergePrimaryCondition(ids, pk, options, meta, metadata, platform) {
-        const cond1 = QueryHelper.processWhere({ where: { [pk]: { $in: ids } }, entityName: meta.className, metadata, platform, convertCustomTypes: !options.convertCustomTypes });
+        const cond1 = QueryHelper.processWhere({ where: { [pk]: { $in: ids } }, entityName: meta.class, metadata, platform, convertCustomTypes: !options.convertCustomTypes });
         const where = { ...options.where };
         Utils.dropUndefinedProperties(where);
         return where[pk]
@@ -288,6 +296,7 @@ export class EntityLoader {
         if (prop.kind === ReferenceKind.SCALAR && !prop.lazy) {
             return;
         }
+        options = { ...options, filters: QueryHelper.mergePropertyFilters(prop.filters, options.filters) };
         const populated = await this.populateMany(entityName, entities, populate, options);
         if (!populate.children && !populate.all) {
             return;
@@ -321,11 +330,16 @@ export class EntityLoader {
         for (const entity of entities) {
             visited.delete(entity);
         }
-        const filtered = Utils.unique(children.filter(e => !visited.has(e)));
+        const unique = Utils.unique(children);
+        const filtered = unique.filter(e => !visited.has(e));
         for (const entity of entities) {
             visited.add(entity);
         }
-        await this.populate(prop.type, filtered, populate.children ?? populate.all, {
+        // skip lazy scalar properties
+        if (!prop.targetMeta) {
+            return;
+        }
+        await this.populate(prop.targetMeta.class, unique, populate.children ?? populate.all, {
             where: await this.extractChildCondition(options, prop, false),
             orderBy: innerOrderBy,
             fields,
@@ -342,6 +356,8 @@ export class EntityLoader {
             refresh: refresh && !filtered.every(item => options.visited.has(item)),
             // @ts-ignore not a public option, will be propagated to the populate call
             visited: options.visited,
+            // @ts-ignore not a public option
+            filtered,
         });
     }
     /** @internal */
@@ -368,12 +384,12 @@ export class EntityLoader {
         for (const entity of filtered) {
             const items = map[entity.__helper.getSerializedPrimaryKey()].map(item => {
                 if (pivotJoin) {
-                    return this.em.getReference(prop.type, item, {
+                    return this.em.getReference(prop.targetMeta.class, item, {
                         convertCustomTypes: true,
                         schema: options.schema ?? this.em.config.get('schema'),
                     });
                 }
-                const entity = this.em.getEntityFactory().create(prop.type, item, {
+                const entity = this.em.getEntityFactory().create(prop.targetMeta.class, item, {
                     refresh,
                     merge: true,
                     convertCustomTypes: true,
@@ -389,16 +405,13 @@ export class EntityLoader {
     async extractChildCondition(options, prop, filters = false) {
         const where = options.where;
         const subCond = Utils.isPlainObject(where[prop.name]) ? where[prop.name] : {};
-        const meta2 = this.metadata.find(prop.type);
-        if (!meta2) {
-            return {};
-        }
+        const meta2 = prop.targetMeta;
         const pk = Utils.getPrimaryKeyHash(meta2.primaryKeys);
         ['$and', '$or'].forEach(op => {
             if (where[op]) {
                 const child = where[op]
                     .map((cond) => cond[prop.name])
-                    .filter((sub) => sub != null && !(Utils.isPlainObject(sub) && Object.keys(sub).every(key => Utils.isOperator(key, false))))
+                    .filter((sub) => sub != null && !(Utils.isPlainObject(sub) && Utils.getObjectQueryKeys(sub).every(key => Utils.isOperator(key, false))))
                     .map((cond) => {
                     if (Utils.isPrimaryKey(cond)) {
                         return { [pk]: cond };
@@ -419,7 +432,7 @@ export class EntityLoader {
             });
         }
         if (filters) {
-            return this.em.applyFilters(prop.type, subCond, options.filters, 'read', options);
+            return this.em.applyFilters(meta2.class, subCond, options.filters, 'read', options);
         }
         return subCond;
     }
@@ -437,7 +450,7 @@ export class EntityLoader {
                 const parts = f.toString().split('.');
                 const propName = parts.shift();
                 const childPropName = parts.join('.');
-                /* v8 ignore next 3 */
+                /* v8 ignore next */
                 if (propName === prop.name) {
                     ret.push(childPropName);
                 }
@@ -458,23 +471,20 @@ export class EntityLoader {
     }
     getChildReferences(entities, prop, options, ref) {
         const filtered = this.filterCollections(entities, prop.name, options, ref);
-        const children = [];
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
-            children.push(...filtered.map(e => e[prop.name].owner));
+            return filtered.map(e => e[prop.name].owner);
         }
-        else if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.owner) {
-            children.push(...filtered.reduce((a, b) => {
+        if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.owner) {
+            return filtered.reduce((a, b) => {
                 a.push(...b[prop.name].getItems());
                 return a;
-            }, []));
+            }, []);
         }
-        else if (prop.kind === ReferenceKind.MANY_TO_MANY) { // inverse side
-            children.push(...filtered);
+        if (prop.kind === ReferenceKind.MANY_TO_MANY) { // inverse side
+            return filtered;
         }
-        else { // MANY_TO_ONE or ONE_TO_ONE
-            children.push(...this.filterReferences(entities, prop.name, options, ref));
-        }
-        return children;
+        // MANY_TO_ONE or ONE_TO_ONE
+        return this.filterReferences(entities, prop.name, options, ref);
     }
     filterCollections(entities, field, options, ref) {
         if (options.refresh) {
@@ -491,7 +501,7 @@ export class EntityLoader {
             return wrapped.__loadedProperties.has(field);
         }
         const [f, ...r] = field.split('.');
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (!wrapped.__loadedProperties.has(f) || !wrapped.__meta.properties[f]?.targetMeta) {
             return false;
         }
@@ -524,7 +534,7 @@ export class EntityLoader {
             .map(e => Reference.unwrapReference(e[field]));
     }
     filterByReferences(entities, field, refresh) {
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (refresh) {
             return entities;
         }
@@ -555,10 +565,10 @@ export class EntityLoader {
         if (!meta && !prefix) {
             return populate;
         }
-        if (visited.includes(entityName) || !meta) {
+        if (!meta || visited.includes(meta)) {
             return [];
         }
-        visited.push(entityName);
+        visited.push(meta);
         const ret = prefix === '' ? [...populate] : [];
         meta.relations
             .filter(prop => {
@@ -571,12 +581,12 @@ export class EntityLoader {
             const field = this.getRelationName(meta, prop);
             const prefixed = prefix ? `${prefix}.${field}` : field;
             const nestedPopulate = populate.filter(p => p.field === prop.name).flatMap(p => p.children).filter(Boolean);
-            const nested = this.lookupEagerLoadedRelationships(prop.type, nestedPopulate, strategy, prefixed, visited.slice());
+            const nested = this.lookupEagerLoadedRelationships(prop.targetMeta.class, nestedPopulate, strategy, prefixed, visited.slice());
             if (nested.length > 0) {
                 ret.push(...nested);
             }
             else {
-                const selfReferencing = [meta.className, meta.root.className, ...visited].includes(prop.type) && prop.eager;
+                const selfReferencing = [meta.tableName, ...visited.map(m => m.tableName)].includes(prop.targetMeta.tableName) && prop.eager;
                 ret.push({
                     field: prefixed,
                     // enforce select-in strategy for self-referencing relations

package/entity/EntityRepository.d.ts

@@ -2,7 +2,7 @@ import type { PopulatePath } from '../enums.js';
 import type { CreateOptions, EntityManager, MergeOptions } from '../EntityManager.js';
 import type { AssignOptions } from './EntityAssigner.js';
 import type { EntityData, EntityName, Primary, Loaded, FilterQuery, EntityDictionary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement } from '../typings.js';
-import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
+import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
 import type { Cursor } from '../utils/Cursor.js';
 export declare class EntityRepository<Entity extends object> {
@@ -80,11 +80,15 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * @inheritDoc EntityManager.findByCursor
      */
-    findByCursor<Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(where: FilterQuery<Entity>, options: FindByCursorOptions<Entity, Hint, Fields, Excludes>): Promise<Cursor<Entity, Hint, Fields, Excludes>>;
+    findByCursor<Hint extends string = never, Fields extends string = '*', Excludes extends string = never, IncludeCount extends boolean = true>(options: FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
     /**
      * Finds all entities of given type. You can pass additional options via the `options` parameter.
      */
     findAll<Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(options?: FindAllOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    /**
+     * @inheritDoc EntityManager.stream
+     */
+    stream<Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(options?: StreamOptions<Entity, Hint, Fields, Excludes>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
     /**
      * @inheritDoc EntityManager.insert
      */

package/entity/EntityRepository.js

@@ -90,8 +90,8 @@ export class EntityRepository {
     /**
      * @inheritDoc EntityManager.findByCursor
      */
-    async findByCursor(where, options) {
-        return this.getEntityManager().findByCursor(this.entityName, where, options);
+    async findByCursor(options) {
+        return this.getEntityManager().findByCursor(this.entityName, options);
     }
     /**
      * Finds all entities of given type. You can pass additional options via the `options` parameter.
@@ -99,6 +99,12 @@ export class EntityRepository {
     async findAll(options) {
         return this.getEntityManager().findAll(this.entityName, options);
     }
+    /**
+     * @inheritDoc EntityManager.stream
+     */
+    async *stream(options) {
+        yield* this.getEntityManager().stream(this.entityName, options);
+    }
     /**
      * @inheritDoc EntityManager.insert
      */

package/entity/Reference.d.ts

@@ -1,8 +1,8 @@
-import { inspect } from 'node:util';
 import type { AddEager, AddOptional, Dictionary, EntityClass, EntityKey, EntityProperty, Loaded, LoadedReference, Primary, Ref } from '../typings.js';
 import type { FindOneOptions, FindOneOrFailOptions } from '../drivers/IDatabaseDriver.js';
 export declare class Reference<T extends object> {
     private entity;
+    private property?;
     constructor(entity: T);
     static create<T extends object>(entity: T | Ref<T>): Ref<T>;
     static createFromPK<T extends object>(entityType: EntityClass<T>, pk: Primary<T>, options?: {
@@ -42,8 +42,6 @@ export declare class Reference<T extends object> {
     isInitialized(): boolean;
     populated(populated?: boolean): void;
     toJSON(...args: any[]): Dictionary;
-    /** @ignore */
-    [inspect.custom](depth?: number): string;
 }
 export declare class ScalarReference<Value> {
     private value?;
@@ -56,12 +54,15 @@ export declare class ScalarReference<Value> {
      * Returns either the whole entity, or the requested property.
      */
     load(options?: Omit<LoadReferenceOptions<any, any>, 'populate' | 'fields' | 'exclude'>): Promise<Value | undefined>;
+    /**
+     * Ensures the underlying entity is loaded first (without reloading it if it already is loaded).
+     * Returns the entity or throws an error just like `em.findOneOrFail()` (and respects the same config options).
+     */
+    loadOrFail(options?: Omit<LoadReferenceOrFailOptions<any, any>, 'populate' | 'fields' | 'exclude'>): Promise<Value>;
     set(value: Value): void;
     bind<Entity extends object>(entity: Entity, property: EntityKey<Entity>): void;
     unwrap(): Value | undefined;
     isInitialized(): boolean;
-    /** @ignore */
-    [inspect.custom](): string;
 }
 export interface LoadReferenceOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never> extends FindOneOptions<T, P, F, E> {
     dataloader?: boolean;

package/entity/Reference.js

@@ -1,9 +1,12 @@
-import { inspect } from 'node:util';
 import { DataloaderType } from '../enums.js';
 import { helper, wrap } from './wrap.js';
 import { Utils } from '../utils/Utils.js';
+import { QueryHelper } from '../utils/QueryHelper.js';
+import { NotFoundError } from '../errors.js';
+import { inspect } from '../logging/inspect.js';
 export class Reference {
     entity;
+    property;
     constructor(entity) {
         this.entity = entity;
         this.set(entity);
@@ -33,10 +36,15 @@ export class Reference {
     }
     static createFromPK(entityType, pk, options) {
         const ref = this.createNakedFromPK(entityType, pk, options);
-        return helper(ref).toReference();
+        return helper(ref)?.toReference() ?? ref;
     }
     static createNakedFromPK(entityType, pk, options) {
         const factory = entityType.prototype.__factory;
+        if (!factory) {
+            // this can happen only if `ref()` is used as a property initializer, and the value is important only for the
+            // inference of defaults, so it's fine to return it directly without wrapping with `Reference` class
+            return pk;
+        }
         const entity = factory.createReference(entityType, pk, {
             merge: false,
             convertCustomTypes: false,
@@ -58,7 +66,9 @@ export class Reference {
      */
     static wrapReference(entity, prop) {
         if (entity && prop.ref && !Reference.isReference(entity)) {
-            return Reference.create(entity);
+            const ref = Reference.create(entity);
+            ref.property = prop;
+            return ref;
         }
         return entity;
     }
@@ -78,13 +88,14 @@ export class Reference {
         if (!wrapped.__em) {
             return this.entity;
         }
+        options = { ...options, filters: QueryHelper.mergePropertyFilters(this.property?.filters, options.filters) };
         if (this.isInitialized() && !options.refresh && options.populate) {
             await wrapped.__em.populate(this.entity, options.populate, options);
         }
         if (!this.isInitialized() || options.refresh) {
             if (options.dataloader ?? [DataloaderType.ALL, DataloaderType.REFERENCE].includes(wrapped.__em.config.getDataloaderType())) {
-                // eslint-disable-next-line dot-notation
-                return wrapped.__em['refLoader'].load([this, options]);
+                const dataLoader = await wrapped.__em.getDataLoader('ref');
+                return dataLoader.load([this, options]);
             }
             return wrapped.init(options);
         }
@@ -135,9 +146,9 @@ export class Reference {
         return wrap(this.entity).toJSON(...args);
     }
     /** @ignore */
-    [inspect.custom](depth = 2) {
+    [Symbol.for('nodejs.util.inspect.custom')](depth = 2) {
         const object = { ...this };
-        const hidden = ['meta'];
+        const hidden = ['meta', 'property'];
         hidden.forEach(k => delete object[k]);
         const ret = inspect(object, { depth });
         const wrapped = helper(this.entity);
@@ -171,6 +182,20 @@ export class ScalarReference {
         }
         return this.value;
     }
+    /**
+     * Ensures the underlying entity is loaded first (without reloading it if it already is loaded).
+     * Returns the entity or throws an error just like `em.findOneOrFail()` (and respects the same config options).
+     */
+    async loadOrFail(options = {}) {
+        const ret = await this.load(options);
+        if (ret == null) {
+            const wrapped = helper(this.entity);
+            options.failHandler ??= wrapped.__em.config.get('findOneOrFailHandler');
+            const entityName = this.entity.constructor.name;
+            throw NotFoundError.failedToLoadProperty(entityName, this.property, wrapped.getPrimaryKey());
+        }
+        return ret;
+    }
     set(value) {
         this.value = value;
         this.initialized = true;
@@ -186,9 +211,9 @@ export class ScalarReference {
     isInitialized() {
         return this.initialized;
     }
-    /* v8 ignore next 4 */
     /** @ignore */
-    [inspect.custom]() {
+    /* v8 ignore next */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.initialized ? `Ref<${inspect(this.value)}>` : `Ref<?>`;
     }
 }

package/entity/WrappedEntity.d.ts

@@ -1,5 +1,4 @@
 import type { PopulatePath } from '../enums.js';
-import { inspect } from 'node:util';
 import type { EntityManager } from '../EntityManager.js';
 import type { Dictionary, EntityData, EntityDictionary, EntityMetadata, IHydrator, EntityKey, PopulateOptions, Primary, AutoPath, Ref, AddEager, LoadedReference, EntityDTO, Loaded, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
 import { Reference } from './Reference.js';
@@ -11,7 +10,6 @@ import { type SerializeOptions } from '../serialization/EntitySerializer.js';
 import type { FindOneOptions, LoadHint } from '../drivers/IDatabaseDriver.js';
 export declare class WrappedEntity<Entity extends object> {
     __initialized: boolean;
-    __touched: boolean;
     __populated?: boolean;
     __managed?: boolean;
     __onLoadFired?: boolean;
@@ -41,7 +39,6 @@ export declare class WrappedEntity<Entity extends object> {
     private readonly pkGetterConverted?;
     constructor(entity: Entity, hydrator: IHydrator, pkGetter?: (e: Entity) => Primary<Entity>, pkSerializer?: (e: Entity) => string, pkGetterConverted?: (e: Entity) => Primary<Entity>);
     isInitialized(): boolean;
-    isTouched(): boolean;
     isManaged(): boolean;
     populated(populated?: boolean | undefined): void;
     setSerializationContext<Hint extends string = never, Fields extends string = '*', Exclude extends string = never>(options: LoadHint<Entity, Hint, Fields, Exclude>): void;
@@ -61,9 +58,7 @@ export declare class WrappedEntity<Entity extends object> {
     setPrimaryKey(id: Primary<Entity> | null): void;
     getSerializedPrimaryKey(): string;
     get __meta(): EntityMetadata<Entity>;
-    get __platform(): import("../index.js").Platform;
-    get __config(): import("../index.js").Configuration<import("../drivers/IDatabaseDriver.js").IDatabaseDriver<import("../index.js").Connection>, EntityManager<import("../drivers/IDatabaseDriver.js").IDatabaseDriver<import("../index.js").Connection>>>;
+    get __platform(): import("@mikro-orm/sql").Platform;
+    get __config(): import("@mikro-orm/sql").Configuration<import("../drivers/IDatabaseDriver.js").IDatabaseDriver<import("@mikro-orm/sql").Connection>, EntityManager<import("../drivers/IDatabaseDriver.js").IDatabaseDriver<import("@mikro-orm/sql").Connection>>>;
     get __primaryKeys(): Primary<Entity>[];
-    /** @ignore */
-    [inspect.custom](): string;
 }

package/entity/WrappedEntity.js

@@ -1,4 +1,3 @@
-import { inspect } from 'node:util';
 import { Reference } from './Reference.js';
 import { EntityTransformer } from '../serialization/EntityTransformer.js';
 import { EntityAssigner } from './EntityAssigner.js';
@@ -15,7 +14,6 @@ export class WrappedEntity {
         this.pkSerializer = pkSerializer;
         this.pkGetterConverted = pkGetterConverted;
         this.__initialized = true;
-        this.__touched = false;
         this.__serializationContext = {};
         this.__loadedProperties = new Set();
         this.__data = {};
@@ -24,9 +22,6 @@ export class WrappedEntity {
     isInitialized() {
         return this.__initialized;
     }
-    isTouched() {
-        return this.__touched;
-    }
     isManaged() {
         return !!this.__managed;
     }
@@ -76,7 +71,7 @@ export class WrappedEntity {
         if (!this.__em) {
             throw ValidationError.entityNotManaged(this.entity);
         }
-        return this.__em.findOne(this.entity.constructor.name, this.entity, { ...options, refresh: true, schema: this.__schema });
+        return this.__em.findOne(this.entity.constructor, this.entity, { ...options, refresh: true, schema: this.__schema });
     }
     async populate(populate, options = {}) {
         if (!this.__em) {
@@ -150,10 +145,10 @@ export class WrappedEntity {
         return this.__em?.config ?? this.entity.__config;
     }
     get __primaryKeys() {
-        return Utils.getPrimaryKeyValues(this.entity, this.__meta.primaryKeys);
+        return Utils.getPrimaryKeyValues(this.entity, this.__meta);
     }
     /** @ignore */
-    [inspect.custom]() {
+    [Symbol.for('nodejs.util.inspect.custom')]() {
         return `[WrappedEntity<${this.__meta.className}>]`;
     }
 }