@mikro-orm/core 7.3.0-dev.2 → 7.3.0-dev.20

package/EntityManager.js

@@ -743,10 +743,15 @@ export class EntityManager {
         if (Utils.isEmpty(options.orderBy) && !Raw.hasObjectFragments(options.orderBy)) {
             throw new Error('Explicit `orderBy` option required');
         }
+        const meta = this.metadata.get(entityName);
+        // same merge as em.find, so the cursor and the query see the same orderBy
+        if (meta.orderBy) {
+            options.orderBy = QueryHelper.mergeOrderBy(options.orderBy, meta.orderBy);
+        }
         const [entities, count] = options.includeCount !== false
             ? await em.findAndCount(entityName, options.where, options)
             : [await em.find(entityName, options.where, options)];
-        return new Cursor(entities, count, options, this.metadata.get(entityName));
+        return new Cursor(entities, count, options, meta);
     }
     /**
      * Refreshes the persistent state of an entity from the database, overriding any local changes that have not yet been
@@ -781,26 +786,46 @@ export class EntityManager {
             em.#unitOfWork.unsetIdentity(entity);
             return null;
         }
+        // `serialize()` applies `Type.toJSON()` and `serializedName`, take only relations and embeddables from it, scalars from the entity
+        const getData = (e, data = helper(e).serialize({
+            ignoreSerializers: true,
+            includeHidden: true,
+            convertCustomTypes: false,
+        })) => {
+            for (const prop of helper(e).__meta.props) {
+                if (prop.kind === ReferenceKind.SCALAR && !prop.ref) {
+                    if (helper(e).__initialized || prop.primary) {
+                        data[prop.name] = e[prop.name];
+                    }
+                    continue;
+                }
+                if (prop.serializedName && prop.serializedName in data) {
+                    data[prop.name] = data[prop.serializedName];
+                }
+                if (prop.kind === ReferenceKind.EMBEDDED && e[prop.name] != null) {
+                    Utils.asArray(e[prop.name]).forEach((item, i) => getData(item, prop.array ? data[prop.name][i] : data[prop.name]));
+                }
+            }
+            return data;
+        };
+        const hydrate = (target, source) => {
+            em.config
+                .getHydrator(this.metadata)
+                .hydrate(target, helper(target).__meta, getData(source), em.#entityFactory, 'full', false, false);
+            Utils.merge(helper(target).__originalEntityData, this.#comparator.prepareEntity(source));
+        };
         let found = false;
         for (const e of fork.#unitOfWork.getIdentityMap()) {
             const ref = em.getReference(e.constructor, helper(e).getPrimaryKey());
-            const data = helper(e).serialize({ ignoreSerializers: true, includeHidden: true, convertCustomTypes: false });
-            em.config
-                .getHydrator(this.metadata)
-                .hydrate(ref, helper(ref).__meta, data, em.#entityFactory, 'full', false, false);
-            Utils.merge(helper(ref).__originalEntityData, this.#comparator.prepareEntity(e));
+            hydrate(ref, e);
+            // index a refreshed `targetKey` value, `getByKey` ignores the old one as stale
+            if (helper(ref).__meta.root.targetKeys) {
+                em.#unitOfWork.getIdentityMap().store(ref);
+            }
             found ||= ref === entity;
         }
         if (!found) {
-            const data = helper(reloaded).serialize({
-                ignoreSerializers: true,
-                includeHidden: true,
-                convertCustomTypes: false,
-            });
-            em.config
-                .getHydrator(this.metadata)
-                .hydrate(entity, wrapped.__meta, data, em.#entityFactory, 'full', false, false);
-            Utils.merge(wrapped.__originalEntityData, this.#comparator.prepareEntity(reloaded));
+            hydrate(entity, reloaded);
         }
         return entity;
     }
@@ -1021,6 +1046,15 @@ export class EntityManager {
                     where[meta.primaryKeys[0]] = ret.insertId;
                 }
             }
+            // a `null` unique value cannot identify the row, and as it never conflicts, the row was inserted
+            if (!Utils.hasObjectKeys(where)) {
+                const insertId = meta.simplePK && ret.insertId != null ? { [meta.primaryKeys[0]]: ret.insertId } : {};
+                Object.assign(where, Utils.getPrimaryKeyCond(entity, meta.primaryKeys) ?? insertId);
+            }
+            // an empty condition would hydrate the entity from an arbitrary row, mongo still gets one for nested conflict fields
+            if (!Utils.hasObjectKeys(where) && platform.usesPivotTable()) {
+                throw new Error(`Cannot find the upserted ${meta.className} row, as neither its primary key nor a unique value is known`);
+            }
             const data2 = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => this.driver.findOne(meta.class, where, {
                 fields: returning.concat(...(options.onConflictMergeFields ?? [])),
                 ctx,
@@ -1028,6 +1062,9 @@ export class EntityManager {
                 connectionType: 'write',
                 schema: options.schema,
             }));
+            if (!data2) {
+                throw new Error(`Cannot find the upserted ${meta.className} row for condition ${JSON.stringify(where)}`);
+            }
             em.getHydrator().hydrate(entity, meta, data2, em.#entityFactory, 'full', false, true);
         }
         // recompute the data as there might be some values missing (e.g. those with db column defaults)
@@ -1179,8 +1216,10 @@ export class EntityManager {
                     unique.findIndex(p => data[p] ?? data[p.substring(0, p.indexOf('.'))] != null);
             const tmp = getWhereCondition(meta, options.onConflictFields, row, where);
             propIndex = tmp.propIndex;
+            // a partial composite PK cannot identify the row
+            const partialPK = meta.compositePK && !Utils.isPlainObject(tmp.where) && meta.primaryKeys.some(pk => row[pk] == null);
             where = QueryHelper.processWhere({
-                where: tmp.where,
+                where: partialPK ? {} : tmp.where,
                 entityName,
                 metadata: this.metadata,
                 platform: this.getPlatform(),
@@ -1195,6 +1234,25 @@ export class EntityManager {
             allWhere.push(where);
             dataIndexes.push(i);
         }
+        // mongo inserts the rows with an empty condition as part of the batch and reports their ids
+        const positional = !this.getPlatform().usesPivotTable() ||
+            ((this.getPlatform().usesReturningStatement() || this.getPlatform().usesOutputStatement()) &&
+                options.onConflictAction !== 'ignore' &&
+                !options.onConflictWhere);
+        const hasUniqueKey = !!options.onConflictFields || meta.uniques.length > 0 || meta.props.some(p => p.unique && !p.primary);
+        // only an autoincrement PK can be derived from the `insertId` of the batch
+        const autoincrement = meta.getPrimaryProps().some(p => p.autoincrement);
+        // a TPT child table does not return its rows, so they are never mapped by position
+        const peel = !!meta.tptParent || (!positional && (hasUniqueKey || !autoincrement));
+        // a row with a `null` unique value has nothing to be reloaded by, the single row path maps its PK from the insert
+        for (let idx = 0; peel && idx < allWhere.length; idx++) {
+            if (!Utils.hasObjectKeys(allWhere[idx])) {
+                result[dataIndexes[idx]] = await em.upsert(entityName, data[dataIndexes[idx]], options);
+                allData.splice(idx, 1);
+                allWhere.splice(idx, 1);
+                dataIndexes.splice(idx--, 1);
+            }
+        }
         if (allData.length === 0) {
             return [...new Set(result)];
         }
@@ -1244,7 +1302,11 @@ export class EntityManager {
         // skip the reload only when RETURNING brought back a row for every input
         // (onConflictWhere can suppress writes, leaving some rows out)
         // oxfmt-ignore
-        const uniqueFields = options.onConflictFields ?? (Utils.isPlainObject(allWhere[0]) ? Object.keys(allWhere[0]).flatMap(key => Utils.splitPrimaryKeys(key)) : meta.primaryKeys);
+        const getUniqueFields = (where) => options.onConflictFields ?? (Utils.isPlainObject(where) ? Object.keys(where).flatMap(key => Utils.splitPrimaryKeys(key)) : meta.primaryKeys);
+        // a row without a condition has no unique fields to derive
+        const uniqueFields = getUniqueFields(allWhere.find(cond => Utils.hasObjectKeys(cond)) ?? allWhere[0]);
+        // an empty condition identifies no row, it must not turn into a reload condition matching every row
+        const getRowUniqueFields = (where) => Utils.isPlainObject(where) && !Utils.hasObjectKeys(where) ? uniqueFields : getUniqueFields(where);
         const platform = this.getPlatform();
         const returning = getOnConflictReturningFields(meta, data[dataIndexes[0]], uniqueFields, options, platform);
         if (options.onConflictWhere && res.rows?.length !== allData.length) {
@@ -1261,10 +1323,14 @@ export class EntityManager {
                 Utils.keys(cond).forEach(key => add.add(key));
             }
             const where = { $or: [] };
+            // a row without a condition was inserted, only the primary key reported for it can identify it
+            const insertedPKs = allData.map((row, idx) => Utils.hasObjectKeys(allWhere[idx]) ? null : Utils.getPrimaryKeyCond(entitiesByData.get(row), meta.primaryKeys));
             dataIndexes.forEach((index, idx) => {
                 const item = data[index];
-                where.$or[idx] = {};
-                const props = Array.isArray(uniqueFields) ? uniqueFields : Object.keys(item);
+                where.$or[idx] = { ...insertedPKs[idx] };
+                // the inputs of one batch can be identified by different unique keys
+                const fields = insertedPKs[idx] ? [] : getRowUniqueFields(allWhere[idx]);
+                const props = Array.isArray(fields) ? fields : Object.keys(item);
                 props.forEach(prop => {
                     where.$or[idx][prop] = item[prop];
                 });
@@ -1279,8 +1345,8 @@ export class EntityManager {
                 connectionType: 'write',
                 schema: options.schema,
             }));
-            for (const [entity, cond] of loadPK.entries()) {
-                const row = data2.find(row => {
+            if (loadPK.size > 0) {
+                const comparableRows = data2.map(row => {
                     const tmp = {};
                     add.forEach(k => {
                         const prop = meta.properties[k];
@@ -1288,25 +1354,58 @@ export class EntityManager {
                             tmp[k] = prop?.customType ? prop.customType.convertToDatabaseValue(row[k], this.getPlatform()) : row[k];
                         }
                     });
-                    return this.#comparator.matching(entityName, cond, tmp);
+                    return tmp;
                 });
-                /* v8 ignore next */
-                if (!row) {
-                    throw new Error(`Cannot find matching entity for condition ${JSON.stringify(cond)}`);
+                // rows carry the keys of every condition in the batch, compare only this one's
+                const isMatch = (cond, idx) => this.#comparator.matching(entityName, cond, Object.fromEntries(Object.entries(comparableRows[idx]).filter(([k]) => k in cond)));
+                // When every condition key is a comparable prop checked with `!==`, a matching row has the same primitive
+                // values, so rows can be grouped by those values once instead of comparing every row for every entity.
+                // Props outside `comparableProps` are skipped by the comparator, so they never qualify for grouping.
+                const groupableProps = new Set(meta.comparableProps.filter(prop => this.#comparator.isStrictlyCompared(prop)));
+                const groups = new Map();
+                // `null` and `undefined` share a key, which can only make a group wider than what `matching` accepts
+                const groupKey = (data, keys) => keys.map(k => (data[k] == null ? 'null' : `${typeof data[k]}:${data[k]}`)).join('\0');
+                const findRowIndex = (cond) => {
+                    const keys = Utils.keys(cond);
+                    if (!keys.every(k => groupableProps.has(meta.properties[k]))) {
+                        return comparableRows.findIndex((_, idx) => isMatch(cond, idx));
+                    }
+                    const signature = keys.join('\0');
+                    if (!groups.has(signature)) {
+                        const rowsByKey = new Map();
+                        comparableRows.forEach((tmp, idx) => {
+                            const rowKey = groupKey(tmp, keys);
+                            const indexes = rowsByKey.get(rowKey) ?? [];
+                            indexes.push(idx);
+                            rowsByKey.set(rowKey, indexes);
+                        });
+                        groups.set(signature, rowsByKey);
+                    }
+                    const group = groups.get(signature);
+                    return group.get(groupKey(cond, keys))?.find(idx => isMatch(cond, idx)) ?? -1;
+                };
+                for (const [entity, cond] of loadPK.entries()) {
+                    const row = data2[findRowIndex(cond)];
+                    /* v8 ignore next */
+                    if (!row) {
+                        throw new Error(`Cannot find matching entity for condition ${JSON.stringify(cond)}`);
+                    }
+                    em.getHydrator().hydrate(entity, meta, row, em.#entityFactory, 'full', false, true);
                 }
-                em.getHydrator().hydrate(entity, meta, row, em.#entityFactory, 'full', false, true);
             }
             if (loadPK.size !== data2.length && Array.isArray(uniqueFields)) {
                 for (let i = 0; i < allData.length; i++) {
                     const data = allData[i];
-                    const cond = uniqueFields.reduce((a, b) => {
-                        // @ts-ignore
-                        a[b] = data[b];
-                        return a;
-                    }, {});
+                    const fields = (insertedPKs[i] ? meta.primaryKeys : getRowUniqueFields(allWhere[i]));
+                    const cond = insertedPKs[i] ??
+                        fields.reduce((a, b) => {
+                            // @ts-ignore
+                            a[b] = data[b];
+                            return a;
+                        }, {});
                     const entity = entitiesByData.get(data);
                     const row = data2.find(item => {
-                        const pk = uniqueFields.reduce((a, b) => {
+                        const pk = fields.reduce((a, b) => {
                             // @ts-ignore
                             a[b] = item[b];
                             return a;

package/drivers/DatabaseDriver.d.ts

@@ -81,6 +81,8 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
      */
     private mapCursorOffset;
     protected createCursorCondition<T extends object>(definition: (readonly [keyof T & string, QueryOrder])[], offsets: Dictionary[], inverse: boolean, meta: EntityMetadata<T>, fromJson?: boolean): FilterQuery<T>;
+    /** @internal Polymorphic embeddable variants can declare same-named properties with different field names. */
+    protected variantProps(prop: EntityProperty, data?: Dictionary): Dictionary<EntityProperty>;
     /** @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

@@ -403,6 +403,19 @@ export class DatabaseDriver {
         }
         return { ...atOrPast, ...past };
     }
+    /** @internal Polymorphic embeddable variants can declare same-named properties with different field names. */
+    variantProps(prop, data) {
+        const meta = prop.targetMeta;
+        // eslint-disable-next-line eqeqeq
+        const variant = meta?.polymorphs?.find(m => m.discriminatorValue == data?.[meta.discriminatorColumn]);
+        const props = variant ? { ...prop.embeddedProps } : prop.embeddedProps;
+        for (const p of variant ? Object.values(props) : []) {
+            if (variant.properties[p.embedded[1]] && Utils.isSameKind(variant.properties[p.embedded[1]], p)) {
+                props[p.embedded[1]] = p;
+            }
+        }
+        return props;
+    }
     /** @internal */
     mapDataToFieldNames(data, stringifyJsonArrays, properties, convertCustomTypes, object) {
         if (!properties || data == null) {
@@ -417,17 +430,17 @@ export class DatabaseDriver {
             if (prop.embeddedProps && !prop.object && !object) {
                 const copy = data[k];
                 delete data[k];
-                Object.assign(data, this.mapDataToFieldNames(copy, stringifyJsonArrays, prop.embeddedProps, convertCustomTypes));
+                Object.assign(data, this.mapDataToFieldNames(copy, stringifyJsonArrays, this.variantProps(prop, copy), convertCustomTypes));
                 return;
             }
             if (prop.embeddedProps && (object || prop.object)) {
                 const copy = data[k];
                 delete data[k];
                 if (prop.array) {
-                    data[prop.fieldNames[0]] = copy?.map((item) => this.mapDataToFieldNames(item, stringifyJsonArrays, prop.embeddedProps, convertCustomTypes, true));
+                    data[prop.fieldNames[0]] = copy?.map((item) => this.mapDataToFieldNames(item, stringifyJsonArrays, this.variantProps(prop, item), convertCustomTypes, true));
                 }
                 else {
-                    data[prop.fieldNames[0]] = this.mapDataToFieldNames(copy, stringifyJsonArrays, prop.embeddedProps, convertCustomTypes, true);
+                    data[prop.fieldNames[0]] = this.mapDataToFieldNames(copy, stringifyJsonArrays, this.variantProps(prop, copy), convertCustomTypes, true);
                 }
                 if (stringifyJsonArrays && prop.array && !object) {
                     data[prop.fieldNames[0]] = this.platform.convertJsonToDatabaseValue(data[prop.fieldNames[0]]);

package/entity/EntityAssigner.js

@@ -234,14 +234,26 @@ export class EntityAssigner {
                 entity[propName].push(...Object.values(tmp));
             });
         }
+        const polymorphs = prop.targetMeta?.polymorphs;
+        // eslint-disable-next-line eqeqeq
+        const variant = polymorphs?.find(m => m.discriminatorValue == value[prop.targetMeta.discriminatorColumn]);
         const create = () => EntityAssigner.validateEM(em) &&
-            em.getEntityFactory().createEmbeddable(prop.targetMeta.class, value, {
+            em.getEntityFactory().createEmbeddable((variant ?? prop.targetMeta).class, value, {
                 convertCustomTypes: options.convertCustomTypes,
                 newEntity: options.mergeEmbeddedProperties ? !('propName' in entity) : true,
             });
-        entity[propName] = (options.mergeEmbeddedProperties ? entity[propName] || create() : create());
+        // a different polymorphic variant cannot be merged into the current one
+        const merge = options.mergeEmbeddedProperties && (!variant || entity[propName]?.constructor === variant.class);
+        entity[propName] = (merge ? entity[propName] || create() : create());
+        const props = polymorphs ? { ...prop.embeddedProps } : prop.embeddedProps;
+        // polymorphic variants can declare same-named properties of different kinds or relation targets
+        for (const p of polymorphs ? entity[propName].__meta.props : []) {
+            if (props[p.name] && props[p.name].targetMeta?.class !== p.targetMeta?.class) {
+                props[p.name] = { ...p, nullable: prop.nullable || p.nullable };
+            }
+        }
         Object.keys(value).forEach(key => {
-            EntityAssigner.assignProperty(entity[propName], key, prop.embeddedProps, value, options);
+            EntityAssigner.assignProperty(entity[propName], key, props, value, options);
         });
     }
     static createCollectionItem(item, em, prop, invalid, options) {

package/entity/EntityFactory.d.ts

@@ -38,6 +38,13 @@ export declare class EntityFactory {
     constructor(em: EntityManager);
     /** Creates a new entity instance or returns an existing one from the identity map, hydrating it with the provided data. */
     create<T extends object, P extends string = string>(entityName: EntityName<T>, data: EntityData<T>, options?: FactoryOptions): New<T, P>;
+    /**
+     * Whether merging `data` into an initialized entity would change nothing: every key is a scalar the entity already
+     * holds by identity, and keys `mergeData` always re-applies (formula, version, generated, discriminator) match the snapshot.
+     */
+    private isNoopMerge;
+    /** Whether hydrating `value` into `prop` would leave `current` as is, mirroring the hydrator's Date and boolean coercion. */
+    private holdsValue;
     /** Merges new data into an existing entity, preserving user-modified properties. */
     mergeData<T extends object>(meta: EntityMetadata<T>, entity: T, data: EntityData<T>, options?: FactoryOptions): void;
     /** Creates or retrieves an uninitialized entity reference by its primary key or alternate key. */
@@ -51,6 +58,7 @@ export declare class EntityFactory {
     assignDefaultValues<T extends object>(entity: T, meta: EntityMetadata<T>, onCreateOnly?: boolean): void;
     private hydrate;
     private findEntity;
+    private findEntityByPrimaryKey;
     private processDiscriminatorColumn;
     /**
      * denormalize PK to value required by driver (e.g. ObjectId)

package/entity/EntityFactory.js

@@ -55,6 +55,10 @@ export class EntityFactory {
             Utils.dropUndefinedProperties(data);
             this.mergeData(meta2, exists, data, options);
             wrapped.__processing = false;
+            // index a merged `targetKey` value, `getByKey` ignores the old one as stale
+            if (meta2.root.targetKeys) {
+                this.unitOfWork.getIdentityMap().store(exists);
+            }
             wrapped.__initialized ||= !!options.initialized;
             if (wrapped.isInitialized()) {
                 if (!wasInitialized) {
@@ -145,8 +149,45 @@ export class EntityFactory {
         wrapped.__processing = false;
         return entity;
     }
+    /**
+     * Whether merging `data` into an initialized entity would change nothing: every key is a scalar the entity already
+     * holds by identity, and keys `mergeData` always re-applies (formula, version, generated, discriminator) match the snapshot.
+     */
+    isNoopMerge(meta, entity, data, options) {
+        const wrapped = helper(entity);
+        if (!wrapped.__initialized || options.normalizeAccessors) {
+            return false;
+        }
+        for (const key of Utils.keys(data)) {
+            const prop = meta.properties[key];
+            const value = data[key];
+            // custom types are left to the full merge, as their JS and database values can differ
+            if (!prop || prop.customType || value === undefined || !this.holdsValue(prop, entity[key], value)) {
+                return false;
+            }
+            const reapplied = prop.formula || prop.version || prop.generated || key === meta.root.discriminatorColumn;
+            if (reapplied && (wrapped.__originalEntityData?.[key] !== value || !wrapped.__loadedProperties.has(key))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Whether hydrating `value` into `prop` would leave `current` as is, mirroring the hydrator's Date and boolean coercion. */
+    holdsValue(prop, current, value) {
+        if (current instanceof Date && value instanceof Date) {
+            return current.getTime() === value.getTime();
+        }
+        if (prop.runtimeType === 'boolean' && value != null) {
+            return current === !!value;
+        }
+        return current === value;
+    }
     /** Merges new data into an existing entity, preserving user-modified properties. */
     mergeData(meta, entity, data, options = {}) {
+        // joined rows often repeat exactly what the entity already holds, skip the snapshot and diffing then
+        if (this.isNoopMerge(meta, entity, data, options)) {
+            return;
+        }
         // merge unchanged properties automatically
         data = QueryHelper.processParams(data);
         const existsData = this.#comparator.prepareEntity(entity);
@@ -232,9 +273,9 @@ export class EntityFactory {
         options.convertCustomTypes ??= true;
         const meta = this.#metadata.get(entityName);
         const schema = this.#driver.getSchemaName(meta, options);
-        // Handle alternate key lookup
-        if (options.key) {
-            const value = '' + (Array.isArray(id) ? id[0] : Utils.isPlainObject(id) ? id[options.key] : id);
+        // Handle alternate key lookup, a `key` pointing at the single PK is a plain PK reference
+        if (options.key && !(meta.primaryKeys.length === 1 && meta.primaryKeys[0] === options.key)) {
+            const value = Array.isArray(id) ? id[0] : Utils.isPlainObject(id) ? id[options.key] : id;
             const exists = this.unitOfWork.getByKey(entityName, options.key, value, schema, options.convertCustomTypes);
             if (exists) {
                 return exists;
@@ -242,6 +283,8 @@ export class EntityFactory {
             // Create entity stub - storeByKey will set the alternate key property and store in identity map
             const entity = this.create(entityName, {}, { ...options, initialized: false });
             this.unitOfWork.storeByKey(entity, options.key, value, schema, options.convertCustomTypes);
+            // snapshot the stub like a PK reference, so flush treats it as existing instead of inserting it
+            helper(entity).__originalEntityData = this.#comparator.prepareEntity(entity);
             return entity;
         }
         if (meta.simplePK) {
@@ -310,6 +353,12 @@ export class EntityFactory {
         if (options.merge && !options.newEntity) {
             this.#hydrator.hydrateReference(entity, meta, data, this, options.convertCustomTypes, options.schema, options.parentSchema);
             this.unitOfWork.register(entity);
+            // relations hydrated together with this entity (joined strategy) resolve it via `targetKey` before it is hydrated
+            for (const key of meta.root.targetKeys ?? []) {
+                if (data[key] != null) {
+                    this.unitOfWork.storeByKey(entity, key, data[key], schema, options.convertCustomTypes);
+                }
+            }
         }
         if (options.initialized) {
             EntityHelper.ensurePropagation(entity);
@@ -379,6 +428,23 @@ export class EntityFactory {
     }
     findEntity(data, meta, options) {
         const schema = this.#driver.getSchemaName(meta, options);
+        const exists = this.findEntityByPrimaryKey(data, meta, schema, options);
+        // a new entity must not adopt a reference stub, that one is never inserted
+        if (exists || Array.isArray(data) || options.newEntity) {
+            return exists;
+        }
+        // a reference created via `targetKey` is only known by that key until the entity is loaded
+        for (const key of meta.root.targetKeys ?? []) {
+            if (data[key] != null) {
+                const ref = this.unitOfWork.getByKey(meta.class, key, data[key], schema, options.convertCustomTypes);
+                if (ref && !helper(ref).__initialized) {
+                    return ref;
+                }
+            }
+        }
+        return undefined;
+    }
+    findEntityByPrimaryKey(data, meta, schema, options) {
         if (meta.simplePK) {
             return this.unitOfWork.getById(meta.class, data[meta.primaryKeys[0]], schema);
         }

package/entity/EntityLoader.js

@@ -197,9 +197,9 @@ export class EntityLoader {
         this.initializeCollections(filtered, prop, field, items, customOrder, isPartial, hasLimit);
         return items;
     }
-    async populateScalar(meta, filtered, options) {
-        const pk = Utils.getPrimaryKeyHash(meta.primaryKeys);
-        const ids = Utils.unique(filtered.map(e => Utils.getPrimaryKeyValues(e, meta, true)));
+    async populateScalar(meta, filtered, options, key) {
+        const pk = (key ?? Utils.getPrimaryKeyHash(meta.primaryKeys));
+        const ids = Utils.unique(filtered.map(e => (key ? e[key] : 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.class, where, {
@@ -221,7 +221,8 @@ export class EntityLoader {
         const needsFkLoad = [];
         for (const entity of entities) {
             const refValue = entity[prop.name];
-            if (refValue && helper(refValue).hasPrimaryKey()) {
+            // a `targetKey` reference is identified by its key, it might not have the PK yet
+            if (refValue && helper(refValue).getTargetKeyValue(prop.targetKey) != null) {
                 if ((ref && !options.refresh) || // :ref hint - already have reference
                     (!ref && helper(refValue).__initialized && !options.refresh) // already loaded
                 ) {
@@ -246,7 +247,7 @@ export class EntityLoader {
             if (!ref) {
                 for (const entity of needsFkLoad) {
                     const refValue = entity[prop.name];
-                    if (refValue && helper(refValue).hasPrimaryKey()) {
+                    if (refValue && helper(refValue).getTargetKeyValue(prop.targetKey) != null) {
                         toPopulate.push(entity);
                     }
                 }
@@ -268,7 +269,7 @@ export class EntityLoader {
         const allItems = [];
         await Promise.all([...groups].map(async ([discriminator, children]) => {
             const targetMeta = this.#metadata.find(prop.discriminatorMap[discriminator]);
-            await this.populateScalar(targetMeta, children, options);
+            await this.populateScalar(targetMeta, children, options, prop.targetKey);
             allItems.push(...children);
         }));
         return allItems;
@@ -311,18 +312,25 @@ export class EntityLoader {
     }
     initializeManyToMany(filtered, children, prop, field, customOrder, partial, readonly) {
         if (prop.mappedBy) {
+            // group children by owner in one pass
+            const map = new Map(filtered.map(entity => [entity, []]));
+            for (const child of children) {
+                for (const owner of child[prop.mappedBy].getItems(false)) {
+                    map.get(owner)?.push(child);
+                }
+            }
             for (const entity of filtered) {
-                const items = children.filter(child => child[prop.mappedBy].contains(entity, false));
-                entity[field].hydrate(items, true, partial, readonly);
+                entity[field].hydrate(map.get(entity), true, partial, readonly);
             }
         }
         else {
             // owning side of M:N without pivot table needs to be reordered
+            const childIndex = new Map(children.map((child, idx) => [child, idx]));
             for (const entity of filtered) {
-                const order = !customOrder ? [...entity[prop.name].getItems(false)] : []; // copy order of references
-                const items = children.filter(child => entity[prop.name].contains(child, false));
-                if (!customOrder) {
-                    items.sort((a, b) => order.indexOf(a) - order.indexOf(b));
+                // keep the order of references, or the order of loaded children when a custom order is used
+                const items = entity[prop.name].getItems(false).filter(item => childIndex.has(item));
+                if (customOrder) {
+                    items.sort((a, b) => childIndex.get(a) - childIndex.get(b));
                 }
                 entity[field].hydrate(items, true, partial, readonly);
             }
@@ -672,12 +680,20 @@ export class EntityLoader {
         const subCond = Utils.isPlainObject(where[prop.name]) ? { ...where[prop.name] } : {};
         const meta2 = prop.targetMeta;
         const pk = Utils.getPrimaryKeyHash(meta2.primaryKeys);
+        // `$not` wrapping entity conditions stays on the target entity, only operators on the relation itself map to its PK
+        const isRelationOperator = (key, value) => {
+            if (key === '$not' && Utils.isPlainObject(value)) {
+                return Utils.getObjectQueryKeys(value).every(k => Utils.isOperator(k, false));
+            }
+            return Utils.isOperator(key, false);
+        };
         ['$and', '$or'].forEach(op => {
             if (where[op]) {
                 const child = where[op]
                     .map((cond) => cond[prop.name])
                     .filter((sub) => sub != null &&
-                    !(Utils.isPlainObject(sub) && Utils.getObjectQueryKeys(sub).every(key => Utils.isOperator(key, false))))
+                    !(Utils.isPlainObject(sub) &&
+                        Utils.getObjectQueryKeys(sub).every(key => isRelationOperator(key, sub[key]))))
                     .map((cond) => {
                     if (Utils.isPrimaryKey(cond)) {
                         return { [pk]: cond };
@@ -690,7 +706,7 @@ export class EntityLoader {
                 }
             }
         });
-        const operators = Object.keys(subCond).filter(key => Utils.isOperator(key, false));
+        const operators = Object.keys(subCond).filter(key => isRelationOperator(key, subCond[key]));
         if (operators.length > 0) {
             subCond[pk] = Utils.isPlainObject(subCond[pk]) ? { ...subCond[pk] } : (subCond[pk] ?? {});
             operators.forEach(op => {
@@ -808,7 +824,7 @@ export class EntityLoader {
         if ([ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(wrapped.__meta.properties[f].kind)) {
             return entity[f].getItems(false).every((item) => this.isPropertyLoaded(item, r.join('.')));
         }
-        return this.isPropertyLoaded(entity[f], r.join('.'));
+        return this.isPropertyLoaded(Reference.unwrapReference(entity[f]), r.join('.'));
     }
     filterReferences(entities, field, options, ref, populate) {
         if (ref) {

package/entity/WrappedEntity.js

@@ -83,7 +83,12 @@ export class WrappedEntity {
         if (!this.__em) {
             throw ValidationError.entityNotManaged(this.entity);
         }
-        return this.__em.findOne(this.entity.constructor, this.entity, {
+        // a reference known only by its `targetKey` has no PK, so look it up by the key instead
+        const key = this.hasPrimaryKey()
+            ? undefined
+            : this.__meta.root.targetKeys?.find(k => this.entity[k] != null);
+        const where = key ? { [key]: this.entity[key] } : this.entity;
+        return this.__em.findOne(this.entity.constructor, where, {
             ...options,
             refresh: true,
             schema: this.__schema,