@mikro-orm/core 7.0.9-dev.9 → 7.0.9

package/entity/EntityFactory.js

@@ -8,442 +8,485 @@ import { JsonType } from '../types/JsonType.js';
 import { isRaw } from '../utils/RawQueryFragment.js';
 /** @internal Factory responsible for creating, merging, and hydrating entity instances. */
 export class EntityFactory {
-    #driver;
-    #platform;
-    #config;
-    #metadata;
-    #hydrator;
-    #eventManager;
-    #comparator;
-    #em;
-    constructor(em) {
-        this.#em = em;
-        this.#driver = this.#em.getDriver();
-        this.#platform = this.#driver.getPlatform();
-        this.#config = this.#em.config;
-        this.#metadata = this.#em.getMetadata();
-        this.#hydrator = this.#config.getHydrator(this.#metadata);
-        this.#eventManager = this.#em.getEventManager();
-        this.#comparator = this.#em.getComparator();
+  #driver;
+  #platform;
+  #config;
+  #metadata;
+  #hydrator;
+  #eventManager;
+  #comparator;
+  #em;
+  constructor(em) {
+    this.#em = em;
+    this.#driver = this.#em.getDriver();
+    this.#platform = this.#driver.getPlatform();
+    this.#config = this.#em.config;
+    this.#metadata = this.#em.getMetadata();
+    this.#hydrator = this.#config.getHydrator(this.#metadata);
+    this.#eventManager = this.#em.getEventManager();
+    this.#comparator = this.#em.getComparator();
+  }
+  /** Creates a new entity instance or returns an existing one from the identity map, hydrating it with the provided data. */
+  create(entityName, data, options = {}) {
+    data = Reference.unwrapReference(data);
+    options.initialized ??= true;
+    if (EntityHelper.isEntity(data)) {
+      return data;
     }
-    /** Creates a new entity instance or returns an existing one from the identity map, hydrating it with the provided data. */
-    create(entityName, data, options = {}) {
-        data = Reference.unwrapReference(data);
-        options.initialized ??= true;
-        if (EntityHelper.isEntity(data)) {
-            return data;
-        }
-        const meta = this.#metadata.get(entityName);
-        if (meta.virtual) {
-            data = { ...data };
-            const entity = this.createEntity(data, meta, options);
-            this.hydrate(entity, meta, data, options);
-            return entity;
-        }
-        if (meta.serializedPrimaryKey) {
-            this.denormalizePrimaryKey(meta, data);
-        }
-        const meta2 = this.processDiscriminatorColumn(meta, data);
-        const exists = this.findEntity(data, meta2, options);
-        let wrapped = exists && helper(exists);
-        if (wrapped && !options.refresh) {
-            const wasInitialized = wrapped.isInitialized();
-            wrapped.__processing = true;
-            Utils.dropUndefinedProperties(data);
-            this.mergeData(meta2, exists, data, options);
-            wrapped.__processing = false;
-            wrapped.__initialized ||= !!options.initialized;
-            if (wrapped.isInitialized()) {
-                if (!wasInitialized) {
-                    if (meta.root.inheritanceType && !(exists instanceof meta2.class)) {
-                        Object.setPrototypeOf(exists, meta2.prototype);
-                    }
-                    if (options.merge && wrapped.hasPrimaryKey()) {
-                        this.unitOfWork.register(exists, data, { loaded: options.initialized });
-                        // ensure all data keys are tracked as loaded for shouldRefresh checks,
-                        // but don't overwrite __originalEntityData — mergeData already set it
-                        // with DB values for non-user-modified keys, leaving user changes detectable
-                        for (const key of Utils.keys(data)) {
-                            if (meta2.properties[key]) {
-                                wrapped.__loadedProperties.add(key);
-                            }
-                        }
-                    }
-                    if (this.#eventManager.hasListeners(EventType.onInit, meta2)) {
-                        this.#eventManager.dispatchEvent(EventType.onInit, { entity: exists, meta: meta2, em: this.#em });
-                    }
-                }
-                return exists;
-            }
-        }
-        data = { ...data };
-        const entity = exists ?? this.createEntity(data, meta2, options);
-        wrapped = helper(entity);
-        wrapped.__processing = true;
-        wrapped.__initialized = options.initialized;
-        if (options.newEntity || meta.forceConstructor || meta.virtual) {
-            const tmp = { ...data };
-            meta.constructorParams?.forEach(prop => delete tmp[prop]);
-            this.hydrate(entity, meta2, tmp, options);
-            // since we now process only a copy of the `data` via hydrator, but later we register the state with the full snapshot,
-            // we need to go through all props with custom types that have `ensureComparable: true` and ensure they are comparable
-            // even if they are not part of constructor parameters (as this is otherwise normalized during hydration, here only in `tmp`)
-            if (options.convertCustomTypes) {
-                for (const prop of meta.props) {
-                    if (prop.customType?.ensureComparable(meta, prop) && data[prop.name]) {
-                        if ([ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(prop.kind)) {
-                            continue;
-                        }
-                        if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
-                            Utils.isPlainObject(data[prop.name])) {
-                            data[prop.name] = Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta, true);
-                        }
-                        if (prop.customType instanceof JsonType && this.#platform.convertsJsonAutomatically()) {
-                            data[prop.name] = prop.customType.convertToDatabaseValue(data[prop.name], this.#platform, {
-                                key: prop.name,
-                                mode: 'hydration',
-                            });
-                        }
-                    }
-                }
-            }
-        }
-        else {
-            this.hydrate(entity, meta2, data, options);
-        }
-        if (exists && meta.root.inheritanceType && !(entity instanceof meta2.class)) {
-            Object.setPrototypeOf(entity, meta2.prototype);
-        }
-        if (options.merge && wrapped.hasPrimaryKey()) {
-            this.unitOfWork.register(entity, data, {
-                // Always refresh to ensure the payload is in correct shape for joined strategy. When loading nested relations,
-                // they will be created early without `Type.ensureComparable` being properly handled, resulting in extra updates.
-                refresh: options.initialized,
-                newEntity: options.newEntity,
-                loaded: options.initialized,
-            });
-            if (options.recomputeSnapshot) {
-                wrapped.__originalEntityData = this.#comparator.prepareEntity(entity);
+    const meta = this.#metadata.get(entityName);
+    if (meta.virtual) {
+      data = { ...data };
+      const entity = this.createEntity(data, meta, options);
+      this.hydrate(entity, meta, data, options);
+      return entity;
+    }
+    if (meta.serializedPrimaryKey) {
+      this.denormalizePrimaryKey(meta, data);
+    }
+    const meta2 = this.processDiscriminatorColumn(meta, data);
+    const exists = this.findEntity(data, meta2, options);
+    let wrapped = exists && helper(exists);
+    if (wrapped && !options.refresh) {
+      const wasInitialized = wrapped.isInitialized();
+      wrapped.__processing = true;
+      Utils.dropUndefinedProperties(data);
+      this.mergeData(meta2, exists, data, options);
+      wrapped.__processing = false;
+      wrapped.__initialized ||= !!options.initialized;
+      if (wrapped.isInitialized()) {
+        if (!wasInitialized) {
+          if (meta.root.inheritanceType && !(exists instanceof meta2.class)) {
+            Object.setPrototypeOf(exists, meta2.prototype);
+          }
+          if (options.merge && wrapped.hasPrimaryKey()) {
+            this.unitOfWork.register(exists, data, { loaded: options.initialized });
+            // ensure all data keys are tracked as loaded for shouldRefresh checks,
+            // but don't overwrite __originalEntityData — mergeData already set it
+            // with DB values for non-user-modified keys, leaving user changes detectable
+            for (const key of Utils.keys(data)) {
+              if (meta2.properties[key]) {
+                wrapped.__loadedProperties.add(key);
+              }
             }
+          }
+          if (this.#eventManager.hasListeners(EventType.onInit, meta2)) {
+            this.#eventManager.dispatchEvent(EventType.onInit, { entity: exists, meta: meta2, em: this.#em });
+          }
         }
-        if (this.#eventManager.hasListeners(EventType.onInit, meta2)) {
-            this.#eventManager.dispatchEvent(EventType.onInit, { entity, meta: meta2, em: this.#em });
-        }
-        wrapped.__processing = false;
-        return entity;
+        return exists;
+      }
     }
-    /** Merges new data into an existing entity, preserving user-modified properties. */
-    mergeData(meta, entity, data, options = {}) {
-        // merge unchanged properties automatically
-        data = QueryHelper.processParams(data);
-        const existsData = this.#comparator.prepareEntity(entity);
-        const originalEntityData = helper(entity).__originalEntityData ?? {};
-        const diff = this.#comparator.diffEntities(meta.class, originalEntityData, existsData);
-        // version properties are not part of entity snapshots
-        if (meta.versionProperty &&
-            data[meta.versionProperty] &&
-            data[meta.versionProperty] !== originalEntityData[meta.versionProperty]) {
-            diff[meta.versionProperty] = data[meta.versionProperty];
-        }
-        const diff2 = this.#comparator.diffEntities(meta.class, existsData, data, { includeInverseSides: true });
-        // do not override values changed by user; for uninitialized entities,
-        // the diff may include stale snapshot entries (value is undefined) — skip those
-        if (helper(entity).__initialized) {
-            Utils.keys(diff).forEach(key => delete diff2[key]);
-        }
-        else {
-            Utils.keys(diff).forEach(key => {
-                if (diff[key] !== undefined) {
-                    delete diff2[key];
-                }
-            });
-        }
-        Utils.keys(diff2)
-            .filter(key => {
-            // ignore null values if there is already present non-null value
-            if (existsData[key] != null) {
-                return diff2[key] == null;
-            }
-            return diff2[key] === undefined;
-        })
-            .forEach(key => delete diff2[key]);
-        // but always add collection properties and formulas if they are part of the `data`
-        Utils.keys(data)
-            .filter(key => meta.properties[key]?.formula ||
-            [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(meta.properties[key]?.kind))
-            .forEach(key => (diff2[key] = data[key]));
-        // rehydrated with the new values, skip those changed by user
-        // use full hydration if the entity is already initialized, even if the caller used `initialized: false`
-        // (e.g. from createReference), otherwise scalar properties in diff2 won't be applied
-        const initialized = options.initialized || helper(entity).__initialized;
-        this.hydrate(entity, meta, diff2, initialized ? { ...options, initialized } : options);
-        // we need to update the entity data only with keys that were not present before
-        const nullVal = this.#config.get('forceUndefined') ? undefined : null;
-        Utils.keys(diff2).forEach(key => {
-            const prop = meta.properties[key];
-            if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
-                Utils.isPlainObject(data[prop.name])) {
-                // oxfmt-ignore
-                diff2[key] = entity[prop.name] ? helper(entity[prop.name]).getPrimaryKey(options.convertCustomTypes) : null;
-            }
-            if (!options.convertCustomTypes &&
-                [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE, ReferenceKind.SCALAR].includes(prop.kind) &&
-                prop.customType?.ensureComparable(meta, prop) &&
-                diff2[key] != null) {
-                const converted = prop.customType.convertToJSValue(diff2[key], this.#platform, { force: true });
-                diff2[key] = prop.customType.convertToDatabaseValue(converted, this.#platform, { fromQuery: true });
+    data = { ...data };
+    const entity = exists ?? this.createEntity(data, meta2, options);
+    wrapped = helper(entity);
+    wrapped.__processing = true;
+    wrapped.__initialized = options.initialized;
+    if (options.newEntity || meta.forceConstructor || meta.virtual) {
+      const tmp = { ...data };
+      meta.constructorParams?.forEach(prop => delete tmp[prop]);
+      this.hydrate(entity, meta2, tmp, options);
+      // since we now process only a copy of the `data` via hydrator, but later we register the state with the full snapshot,
+      // we need to go through all props with custom types that have `ensureComparable: true` and ensure they are comparable
+      // even if they are not part of constructor parameters (as this is otherwise normalized during hydration, here only in `tmp`)
+      if (options.convertCustomTypes) {
+        for (const prop of meta.props) {
+          if (prop.customType?.ensureComparable(meta, prop) && data[prop.name]) {
+            if ([ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(prop.kind)) {
+              continue;
             }
-            originalEntityData[key] = diff2[key] === null ? nullVal : diff2[key];
-            helper(entity).__loadedProperties.add(key);
-        });
-        // in case of joined loading strategy, we need to cascade the merging to possibly loaded relations manually
-        meta.relations.forEach(prop => {
-            if ([ReferenceKind.MANY_TO_MANY, ReferenceKind.ONE_TO_MANY].includes(prop.kind) &&
-                Array.isArray(data[prop.name])) {
-                // instead of trying to match the collection items (which could easily fail if the collection was loaded with different ordering),
-                // we just create the entity from scratch, which will automatically pick the right one from the identity map and call `mergeData` on it
-                data[prop.name]
-                    .filter(child => Utils.isPlainObject(child)) // objects with prototype can be PKs (e.g. `ObjectId`)
-                    .forEach(child => this.create(prop.targetMeta.class, child, options)); // we can ignore the value, we just care about the `mergeData` call
-                return;
+            if (
+              [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
+              Utils.isPlainObject(data[prop.name])
+            ) {
+              data[prop.name] = Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta, true);
             }
-            if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
-                Utils.isPlainObject(data[prop.name]) &&
-                entity[prop.name] &&
-                helper(entity[prop.name]).__initialized) {
-                this.create(prop.targetMeta.class, data[prop.name], options); // we can ignore the value, we just care about the `mergeData` call
+            if (prop.customType instanceof JsonType && this.#platform.convertsJsonAutomatically()) {
+              data[prop.name] = prop.customType.convertToDatabaseValue(data[prop.name], this.#platform, {
+                key: prop.name,
+                mode: 'hydration',
+              });
             }
-        });
-        this.unitOfWork.normalizeEntityData(meta, originalEntityData);
-    }
-    /** Creates or retrieves an uninitialized entity reference by its primary key or alternate key. */
-    createReference(entityName, id, options = {}) {
-        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);
-            const exists = this.unitOfWork.getByKey(entityName, options.key, value, schema, options.convertCustomTypes);
-            if (exists) {
-                return exists;
-            }
-            // 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);
-            return entity;
-        }
-        if (meta.simplePK) {
-            const exists = this.unitOfWork.getById(entityName, id, schema);
-            if (exists) {
-                return exists;
-            }
-            const data = Utils.isPlainObject(id) ? id : { [meta.primaryKeys[0]]: Array.isArray(id) ? id[0] : id };
-            return this.create(entityName, data, { ...options, initialized: false });
-        }
-        if (Array.isArray(id)) {
-            id = Utils.getPrimaryKeyCondFromArray(id, meta);
-        }
-        const pks = Utils.getOrderedPrimaryKeys(id, meta, this.#platform);
-        const exists = this.unitOfWork.getById(entityName, pks, schema, options.convertCustomTypes);
-        if (exists) {
-            return exists;
-        }
-        if (Utils.isPrimaryKey(id)) {
-            id = { [meta.primaryKeys[0]]: id };
+          }
         }
-        return this.create(entityName, id, { ...options, initialized: false });
+      }
+    } else {
+      this.hydrate(entity, meta2, data, options);
     }
-    /** Creates an embeddable entity instance from the provided data. */
-    createEmbeddable(entityName, data, options = {}) {
-        data = { ...data };
-        const meta = this.#metadata.get(entityName);
-        const meta2 = this.processDiscriminatorColumn(meta, data);
-        return this.createEntity(data, meta2, options);
+    if (exists && meta.root.inheritanceType && !(entity instanceof meta2.class)) {
+      Object.setPrototypeOf(entity, meta2.prototype);
     }
-    /** Returns the EntityComparator instance used for diffing entities. */
-    getComparator() {
-        return this.#comparator;
+    if (options.merge && wrapped.hasPrimaryKey()) {
+      this.unitOfWork.register(entity, data, {
+        // Always refresh to ensure the payload is in correct shape for joined strategy. When loading nested relations,
+        // they will be created early without `Type.ensureComparable` being properly handled, resulting in extra updates.
+        refresh: options.initialized,
+        newEntity: options.newEntity,
+        loaded: options.initialized,
+      });
+      if (options.recomputeSnapshot) {
+        wrapped.__originalEntityData = this.#comparator.prepareEntity(entity);
+      }
     }
-    createEntity(data, meta, options) {
-        const schema = this.#driver.getSchemaName(meta, options);
-        if (options.newEntity || meta.forceConstructor || meta.virtual) {
-            if (meta.polymorphs) {
-                throw new Error(`Cannot create entity ${meta.className}, class prototype is unknown`);
-            }
-            const params = this.extractConstructorParams(meta, data, options);
-            const Entity = meta.class;
-            // creates new instance via constructor as this is the new entity
-            const entity = new Entity(...params);
-            // creating managed entity instance when `forceEntityConstructor` is enabled,
-            // we need to wipe all the values as they would cause update queries on next flush
-            if (!options.newEntity && (meta.forceConstructor || this.#config.get('forceEntityConstructor'))) {
-                meta.props
-                    .filter(prop => prop.persist !== false && !prop.primary && data[prop.name] === undefined)
-                    .forEach(prop => delete entity[prop.name]);
-            }
-            if (meta.virtual) {
-                return entity;
-            }
-            helper(entity).__schema = schema;
-            if (options.initialized) {
-                EntityHelper.ensurePropagation(entity);
-            }
-            return entity;
-        }
-        // creates new entity instance, bypassing constructor call as its already persisted entity
-        const entity = Object.create(meta.class.prototype);
-        helper(entity).__managed = true;
-        helper(entity).__processing = !meta.embeddable && !meta.virtual;
-        helper(entity).__schema = schema;
-        if (options.merge && !options.newEntity) {
-            this.#hydrator.hydrateReference(entity, meta, data, this, options.convertCustomTypes, options.schema, options.parentSchema);
-            this.unitOfWork.register(entity);
+    if (this.#eventManager.hasListeners(EventType.onInit, meta2)) {
+      this.#eventManager.dispatchEvent(EventType.onInit, { entity, meta: meta2, em: this.#em });
+    }
+    wrapped.__processing = false;
+    return entity;
+  }
+  /** Merges new data into an existing entity, preserving user-modified properties. */
+  mergeData(meta, entity, data, options = {}) {
+    // merge unchanged properties automatically
+    data = QueryHelper.processParams(data);
+    const existsData = this.#comparator.prepareEntity(entity);
+    const originalEntityData = helper(entity).__originalEntityData ?? {};
+    const diff = this.#comparator.diffEntities(meta.class, originalEntityData, existsData);
+    // version properties are not part of entity snapshots
+    if (
+      meta.versionProperty &&
+      data[meta.versionProperty] &&
+      data[meta.versionProperty] !== originalEntityData[meta.versionProperty]
+    ) {
+      diff[meta.versionProperty] = data[meta.versionProperty];
+    }
+    const diff2 = this.#comparator.diffEntities(meta.class, existsData, data, { includeInverseSides: true });
+    // do not override values changed by user; for uninitialized entities,
+    // the diff may include stale snapshot entries (value is undefined) — skip those
+    if (helper(entity).__initialized) {
+      Utils.keys(diff).forEach(key => delete diff2[key]);
+    } else {
+      Utils.keys(diff).forEach(key => {
+        if (diff[key] !== undefined) {
+          delete diff2[key];
         }
-        if (options.initialized) {
-            EntityHelper.ensurePropagation(entity);
+      });
+    }
+    Utils.keys(diff2)
+      .filter(key => {
+        // ignore null values if there is already present non-null value
+        if (existsData[key] != null) {
+          return diff2[key] == null;
         }
+        return diff2[key] === undefined;
+      })
+      .forEach(key => delete diff2[key]);
+    // but always add collection properties, formulas, and generated columns if they are part of the `data`,
+    // as these are excluded from `comparableProps` and won't appear in the diff
+    Utils.keys(data)
+      .filter(
+        key =>
+          meta.properties[key]?.formula ||
+          (meta.properties[key]?.generated && !meta.properties[key]?.primary) ||
+          [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(meta.properties[key]?.kind),
+      )
+      .forEach(key => (diff2[key] = data[key]));
+    // rehydrated with the new values, skip those changed by user
+    // use full hydration if the entity is already initialized, even if the caller used `initialized: false`
+    // (e.g. from createReference), otherwise scalar properties in diff2 won't be applied
+    const initialized = options.initialized || helper(entity).__initialized;
+    this.hydrate(entity, meta, diff2, initialized ? { ...options, initialized } : options);
+    // we need to update the entity data only with keys that were not present before
+    const nullVal = this.#config.get('forceUndefined') ? undefined : null;
+    Utils.keys(diff2).forEach(key => {
+      const prop = meta.properties[key];
+      if (
+        [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
+        Utils.isPlainObject(data[prop.name])
+      ) {
+        // oxfmt-ignore
+        diff2[key] = entity[prop.name] ? helper(entity[prop.name]).getPrimaryKey(options.convertCustomTypes) : null;
+      }
+      if (
+        !options.convertCustomTypes &&
+        [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE, ReferenceKind.SCALAR].includes(prop.kind) &&
+        prop.customType?.ensureComparable(meta, prop) &&
+        diff2[key] != null
+      ) {
+        const converted = prop.customType.convertToJSValue(diff2[key], this.#platform, { force: true });
+        diff2[key] = prop.customType.convertToDatabaseValue(converted, this.#platform, { fromQuery: true });
+      }
+      originalEntityData[key] = diff2[key] === null ? nullVal : diff2[key];
+      helper(entity).__loadedProperties.add(key);
+    });
+    // in case of joined loading strategy, we need to cascade the merging to possibly loaded relations manually
+    meta.relations.forEach(prop => {
+      if (
+        [ReferenceKind.MANY_TO_MANY, ReferenceKind.ONE_TO_MANY].includes(prop.kind) &&
+        Array.isArray(data[prop.name])
+      ) {
+        // instead of trying to match the collection items (which could easily fail if the collection was loaded with different ordering),
+        // we just create the entity from scratch, which will automatically pick the right one from the identity map and call `mergeData` on it
+        data[prop.name]
+          .filter(child => Utils.isPlainObject(child)) // objects with prototype can be PKs (e.g. `ObjectId`)
+          .forEach(child => this.create(prop.targetMeta.class, child, options)); // we can ignore the value, we just care about the `mergeData` call
+        return;
+      }
+      if (
+        [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
+        Utils.isPlainObject(data[prop.name]) &&
+        entity[prop.name] &&
+        helper(entity[prop.name]).__initialized
+      ) {
+        this.create(prop.targetMeta.class, data[prop.name], options); // we can ignore the value, we just care about the `mergeData` call
+      }
+    });
+    this.unitOfWork.normalizeEntityData(meta, originalEntityData);
+  }
+  /** Creates or retrieves an uninitialized entity reference by its primary key or alternate key. */
+  createReference(entityName, id, options = {}) {
+    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);
+      const exists = this.unitOfWork.getByKey(entityName, options.key, value, schema, options.convertCustomTypes);
+      if (exists) {
+        return exists;
+      }
+      // 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);
+      return entity;
+    }
+    if (meta.simplePK) {
+      const exists = this.unitOfWork.getById(entityName, id, schema);
+      if (exists) {
+        return exists;
+      }
+      const data = Utils.isPlainObject(id) ? id : { [meta.primaryKeys[0]]: Array.isArray(id) ? id[0] : id };
+      return this.create(entityName, data, { ...options, initialized: false });
+    }
+    if (Array.isArray(id)) {
+      id = Utils.getPrimaryKeyCondFromArray(id, meta);
+    }
+    const pks = Utils.getOrderedPrimaryKeys(id, meta, this.#platform);
+    const exists = this.unitOfWork.getById(entityName, pks, schema, options.convertCustomTypes);
+    if (exists) {
+      return exists;
+    }
+    if (Utils.isPrimaryKey(id)) {
+      id = { [meta.primaryKeys[0]]: id };
+    }
+    return this.create(entityName, id, { ...options, initialized: false });
+  }
+  /** Creates an embeddable entity instance from the provided data. */
+  createEmbeddable(entityName, data, options = {}) {
+    data = { ...data };
+    const meta = this.#metadata.get(entityName);
+    const meta2 = this.processDiscriminatorColumn(meta, data);
+    return this.createEntity(data, meta2, options);
+  }
+  /** Returns the EntityComparator instance used for diffing entities. */
+  getComparator() {
+    return this.#comparator;
+  }
+  createEntity(data, meta, options) {
+    const schema = this.#driver.getSchemaName(meta, options);
+    if (options.newEntity || meta.forceConstructor || meta.virtual) {
+      if (meta.polymorphs) {
+        throw new Error(`Cannot create entity ${meta.className}, class prototype is unknown`);
+      }
+      const params = this.extractConstructorParams(meta, data, options);
+      const Entity = meta.class;
+      // creates new instance via constructor as this is the new entity
+      const entity = new Entity(...params);
+      // creating managed entity instance when `forceEntityConstructor` is enabled,
+      // we need to wipe all the values as they would cause update queries on next flush
+      if (!options.newEntity && (meta.forceConstructor || this.#config.get('forceEntityConstructor'))) {
+        meta.props
+          .filter(prop => prop.persist !== false && !prop.primary && data[prop.name] === undefined)
+          .forEach(prop => delete entity[prop.name]);
+      }
+      if (meta.virtual) {
         return entity;
+      }
+      helper(entity).__schema = schema;
+      if (options.initialized) {
+        EntityHelper.ensurePropagation(entity);
+      }
+      return entity;
     }
-    /** @internal */
-    assignDefaultValues(entity, meta, onCreateOnly) {
-        for (const prop of meta.props) {
-            if (prop.embedded || [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
-                continue;
-            }
-            if (prop.onCreate) {
-                entity[prop.name] ??= prop.onCreate(entity, this.#em);
-            }
-            else if (!onCreateOnly && prop.default != null && !isRaw(prop.default) && entity[prop.name] === undefined) {
-                entity[prop.name] = prop.default;
-            }
-            if (prop.kind === ReferenceKind.EMBEDDED && entity[prop.name]) {
-                const items = prop.array ? entity[prop.name] : [entity[prop.name]];
-                for (const item of items) {
-                    // Embedded sub-properties need all defaults since the DB can't apply them within JSON columns.
-                    this.assignDefaultValues(item, prop.targetMeta);
-                }
-            }
-        }
+    // creates new entity instance, bypassing constructor call as its already persisted entity
+    const entity = Object.create(meta.class.prototype);
+    helper(entity).__managed = true;
+    helper(entity).__processing = !meta.embeddable && !meta.virtual;
+    helper(entity).__schema = schema;
+    if (options.merge && !options.newEntity) {
+      this.#hydrator.hydrateReference(
+        entity,
+        meta,
+        data,
+        this,
+        options.convertCustomTypes,
+        options.schema,
+        options.parentSchema,
+      );
+      this.unitOfWork.register(entity);
     }
-    hydrate(entity, meta, data, options) {
-        if (options.initialized) {
-            this.#hydrator.hydrate(entity, meta, data, this, 'full', options.newEntity, options.convertCustomTypes, options.schema, this.#driver.getSchemaName(meta, options), options.normalizeAccessors);
-        }
-        else {
-            this.#hydrator.hydrateReference(entity, meta, data, this, options.convertCustomTypes, options.schema, this.#driver.getSchemaName(meta, options), options.normalizeAccessors);
-        }
-        Utils.keys(data).forEach(key => {
-            helper(entity)?.__loadedProperties.add(key);
-            helper(entity)?.__serializationContext.fields?.add(key);
-        });
-        const processOnCreateHooksEarly = options.processOnCreateHooksEarly ?? this.#config.get('processOnCreateHooksEarly');
-        if (options.newEntity && processOnCreateHooksEarly) {
-            this.assignDefaultValues(entity, meta);
-        }
+    if (options.initialized) {
+      EntityHelper.ensurePropagation(entity);
     }
-    findEntity(data, meta, options) {
-        const schema = this.#driver.getSchemaName(meta, options);
-        if (meta.simplePK) {
-            return this.unitOfWork.getById(meta.class, data[meta.primaryKeys[0]], schema);
-        }
-        if (!Array.isArray(data) && meta.primaryKeys.some(pk => data[pk] == null)) {
-            return undefined;
+    return entity;
+  }
+  /** @internal */
+  assignDefaultValues(entity, meta, onCreateOnly) {
+    for (const prop of meta.props) {
+      if (prop.embedded || [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+        continue;
+      }
+      if (prop.onCreate) {
+        entity[prop.name] ??= prop.onCreate(entity, this.#em);
+      } else if (!onCreateOnly && prop.default != null && !isRaw(prop.default) && entity[prop.name] === undefined) {
+        entity[prop.name] = prop.default;
+      }
+      if (prop.kind === ReferenceKind.EMBEDDED && entity[prop.name]) {
+        const items = prop.array ? entity[prop.name] : [entity[prop.name]];
+        for (const item of items) {
+          // Embedded sub-properties need all defaults since the DB can't apply them within JSON columns.
+          this.assignDefaultValues(item, prop.targetMeta);
         }
-        const pks = Utils.getOrderedPrimaryKeys(data, meta, this.#platform, options.convertCustomTypes);
-        return this.unitOfWork.getById(meta.class, pks, schema);
+      }
+    }
+  }
+  hydrate(entity, meta, data, options) {
+    if (options.initialized) {
+      this.#hydrator.hydrate(
+        entity,
+        meta,
+        data,
+        this,
+        'full',
+        options.newEntity,
+        options.convertCustomTypes,
+        options.schema,
+        this.#driver.getSchemaName(meta, options),
+        options.normalizeAccessors,
+      );
+    } else {
+      this.#hydrator.hydrateReference(
+        entity,
+        meta,
+        data,
+        this,
+        options.convertCustomTypes,
+        options.schema,
+        this.#driver.getSchemaName(meta, options),
+        options.normalizeAccessors,
+      );
+    }
+    Utils.keys(data).forEach(key => {
+      helper(entity)?.__loadedProperties.add(key);
+      helper(entity)?.__serializationContext.fields?.add(key);
+    });
+    const processOnCreateHooksEarly =
+      options.processOnCreateHooksEarly ?? this.#config.get('processOnCreateHooksEarly');
+    if (options.newEntity && processOnCreateHooksEarly) {
+      this.assignDefaultValues(entity, meta);
     }
-    processDiscriminatorColumn(meta, data) {
-        // Handle STI discriminator (persisted column)
-        if (meta.root.inheritanceType === 'sti') {
-            const prop = meta.properties[meta.root.discriminatorColumn];
-            const value = data[prop.name];
-            const type = meta.root.discriminatorMap[value];
-            meta = type ? this.#metadata.get(type) : meta;
-            return meta;
+  }
+  findEntity(data, meta, options) {
+    const schema = this.#driver.getSchemaName(meta, options);
+    if (meta.simplePK) {
+      return this.unitOfWork.getById(meta.class, data[meta.primaryKeys[0]], schema);
+    }
+    if (!Array.isArray(data) && meta.primaryKeys.some(pk => data[pk] == null)) {
+      return undefined;
+    }
+    const pks = Utils.getOrderedPrimaryKeys(data, meta, this.#platform, options.convertCustomTypes);
+    return this.unitOfWork.getById(meta.class, pks, schema);
+  }
+  processDiscriminatorColumn(meta, data) {
+    // Handle STI discriminator (persisted column)
+    if (meta.root.inheritanceType === 'sti') {
+      const prop = meta.properties[meta.root.discriminatorColumn];
+      const value = data[prop.name];
+      const type = meta.root.discriminatorMap[value];
+      meta = type ? this.#metadata.get(type) : meta;
+      return meta;
+    }
+    // Handle TPT discriminator (computed at query time)
+    if (meta.root.inheritanceType === 'tpt' && meta.root.discriminatorMap) {
+      const value = data[meta.root.tptDiscriminatorColumn];
+      if (value) {
+        const type = meta.root.discriminatorMap[value];
+        meta = type ? this.#metadata.get(type) : meta;
+      }
+    }
+    return meta;
+  }
+  /**
+   * denormalize PK to value required by driver (e.g. ObjectId)
+   */
+  denormalizePrimaryKey(meta, data) {
+    const pk = meta.getPrimaryProp();
+    const spk = meta.properties[meta.serializedPrimaryKey];
+    if (!spk?.serializedPrimaryKey) {
+      return;
+    }
+    if (pk.type === 'ObjectId' && (data[pk.name] != null || data[spk.name] != null)) {
+      data[pk.name] = this.#platform.denormalizePrimaryKey(data[spk.name] || data[pk.name]);
+      delete data[spk.name];
+    }
+  }
+  /**
+   * returns parameters for entity constructor, creating references from plain ids
+   */
+  extractConstructorParams(meta, data, options) {
+    if (!meta.constructorParams) {
+      return [data];
+    }
+    return meta.constructorParams.map(k => {
+      const prop = meta.properties[k];
+      const value = data[k];
+      if (prop && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && value) {
+        const pk = Reference.unwrapReference(value);
+        const entity = this.unitOfWork.getById(prop.targetMeta.class, pk, options.schema, true);
+        if (entity) {
+          return entity;
         }
-        // Handle TPT discriminator (computed at query time)
-        if (meta.root.inheritanceType === 'tpt' && meta.root.discriminatorMap) {
-            const value = data[meta.root.tptDiscriminatorColumn];
-            if (value) {
-                const type = meta.root.discriminatorMap[value];
-                meta = type ? this.#metadata.get(type) : meta;
-            }
+        if (Utils.isEntity(value)) {
+          return value;
         }
-        return meta;
-    }
-    /**
-     * denormalize PK to value required by driver (e.g. ObjectId)
-     */
-    denormalizePrimaryKey(meta, data) {
-        const pk = meta.getPrimaryProp();
-        const spk = meta.properties[meta.serializedPrimaryKey];
-        if (!spk?.serializedPrimaryKey) {
-            return;
+        const nakedPk = Utils.extractPK(value, prop.targetMeta, true);
+        if (Utils.isObject(value) && !nakedPk) {
+          return this.create(prop.targetMeta.class, value, options);
         }
-        if (pk.type === 'ObjectId' && (data[pk.name] != null || data[spk.name] != null)) {
-            data[pk.name] = this.#platform.denormalizePrimaryKey((data[spk.name] || data[pk.name]));
-            delete data[spk.name];
+        const { newEntity, initialized, ...rest } = options;
+        const target = this.createReference(prop.targetMeta.class, nakedPk, rest);
+        return Reference.wrapReference(target, prop);
+      }
+      if (prop?.kind === ReferenceKind.EMBEDDED && value) {
+        /* v8 ignore next */
+        if (Utils.isEntity(value)) {
+          return value;
         }
-    }
-    /**
-     * returns parameters for entity constructor, creating references from plain ids
-     */
-    extractConstructorParams(meta, data, options) {
-        if (!meta.constructorParams) {
-            return [data];
+        return this.createEmbeddable(prop.targetMeta.class, value, options);
+      }
+      if (!prop) {
+        const tmp = { ...data };
+        for (const prop of meta.props) {
+          if (!options.convertCustomTypes || !prop.customType || tmp[prop.name] == null) {
+            continue;
+          }
+          if (
+            [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
+            Utils.isPlainObject(tmp[prop.name]) &&
+            !Utils.extractPK(tmp[prop.name], prop.targetMeta, true)
+          ) {
+            tmp[prop.name] = Reference.wrapReference(this.create(prop.targetMeta.class, tmp[prop.name], options), prop);
+          } else if (prop.kind === ReferenceKind.SCALAR) {
+            tmp[prop.name] = prop.customType.convertToJSValue(tmp[prop.name], this.#platform);
+          }
         }
-        return meta.constructorParams.map(k => {
-            const prop = meta.properties[k];
-            const value = data[k];
-            if (prop && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && value) {
-                const pk = Reference.unwrapReference(value);
-                const entity = this.unitOfWork.getById(prop.targetMeta.class, pk, options.schema, true);
-                if (entity) {
-                    return entity;
-                }
-                if (Utils.isEntity(value)) {
-                    return value;
-                }
-                const nakedPk = Utils.extractPK(value, prop.targetMeta, true);
-                if (Utils.isObject(value) && !nakedPk) {
-                    return this.create(prop.targetMeta.class, value, options);
-                }
-                const { newEntity, initialized, ...rest } = options;
-                const target = this.createReference(prop.targetMeta.class, nakedPk, rest);
-                return Reference.wrapReference(target, prop);
-            }
-            if (prop?.kind === ReferenceKind.EMBEDDED && value) {
-                /* v8 ignore next */
-                if (Utils.isEntity(value)) {
-                    return value;
-                }
-                return this.createEmbeddable(prop.targetMeta.class, value, options);
-            }
-            if (!prop) {
-                const tmp = { ...data };
-                for (const prop of meta.props) {
-                    if (!options.convertCustomTypes || !prop.customType || tmp[prop.name] == null) {
-                        continue;
-                    }
-                    if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
-                        Utils.isPlainObject(tmp[prop.name]) &&
-                        !Utils.extractPK(tmp[prop.name], prop.targetMeta, true)) {
-                        tmp[prop.name] = Reference.wrapReference(this.create(prop.targetMeta.class, tmp[prop.name], options), prop);
-                    }
-                    else if (prop.kind === ReferenceKind.SCALAR) {
-                        tmp[prop.name] = prop.customType.convertToJSValue(tmp[prop.name], this.#platform);
-                    }
-                }
-                return tmp;
-            }
-            if (options.convertCustomTypes && prop.customType && value != null) {
-                return prop.customType.convertToJSValue(value, this.#platform);
-            }
-            return value;
-        });
-    }
-    get unitOfWork() {
-        return this.#em.getUnitOfWork(false);
-    }
+        return tmp;
+      }
+      if (options.convertCustomTypes && prop.customType && value != null) {
+        return prop.customType.convertToJSValue(value, this.#platform);
+      }
+      return value;
+    });
+  }
+  get unitOfWork() {
+    return this.#em.getUnitOfWork(false);
+  }
 }