@yandjin-mikro-orm/core 6.1.4-rc-sti-changes-1

package/entity/EntityFactory.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityFactory = void 0;
+const Utils_1 = require("../utils/Utils");
+const QueryHelper_1 = require("../utils/QueryHelper");
+const enums_1 = require("../enums");
+const Reference_1 = require("./Reference");
+const wrap_1 = require("./wrap");
+const EntityHelper_1 = require("./EntityHelper");
+class EntityFactory {
+    em;
+    driver;
+    platform;
+    config;
+    metadata;
+    hydrator;
+    eventManager;
+    comparator;
+    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();
+    }
+    create(entityName, data, options = {}) {
+        data = Reference_1.Reference.unwrapReference(data);
+        options.initialized ??= true;
+        if (data.__entity) {
+            return data;
+        }
+        entityName = Utils_1.Utils.className(entityName);
+        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 (this.platform.usesDifferentSerializedPrimaryKey()) {
+            meta.primaryKeys.forEach(pk => this.denormalizePrimaryKey(data, pk, meta.properties[pk]));
+        }
+        const meta2 = this.processDiscriminatorColumn(meta, data);
+        const exists = this.findEntity(data, meta2, options);
+        let wrapped = exists && (0, wrap_1.helper)(exists);
+        if (wrapped && !options.refresh) {
+            wrapped.__processing = true;
+            this.mergeData(meta2, exists, data, options);
+            wrapped.__processing = false;
+            if (wrapped.isInitialized()) {
+                return exists;
+            }
+        }
+        data = { ...data };
+        const entity = exists ?? this.createEntity(data, meta2, options);
+        wrapped = (0, wrap_1.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);
+        }
+        else {
+            this.hydrate(entity, meta2, data, options);
+        }
+        wrapped.__touched = false;
+        if (exists && meta.discriminatorColumn && !(entity instanceof meta2.class)) {
+            Object.setPrototypeOf(entity, meta2.prototype);
+        }
+        if (options.merge && wrapped.hasPrimaryKey()) {
+            this.unitOfWork.register(entity, data, {
+                refresh: options.refresh && options.initialized,
+                newEntity: options.newEntity,
+                loaded: options.initialized,
+            });
+            if (options.recomputeSnapshot) {
+                wrapped.__originalEntityData = this.comparator.prepareEntity(entity);
+            }
+        }
+        if (this.eventManager.hasListeners(enums_1.EventType.onInit, meta2)) {
+            this.eventManager.dispatchEvent(enums_1.EventType.onInit, { entity, meta: meta2, em: this.em });
+        }
+        wrapped.__processing = false;
+        return entity;
+    }
+    mergeData(meta, entity, data, options = {}) {
+        // merge unchanged properties automatically
+        data = QueryHelper_1.QueryHelper.processParams(data);
+        const existsData = this.comparator.prepareEntity(entity);
+        const originalEntityData = (0, wrap_1.helper)(entity).__originalEntityData ?? {};
+        const diff = this.comparator.diffEntities(meta.className, 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.className, existsData, data);
+        // do not override values changed by user
+        Utils_1.Utils.keys(diff).forEach(key => delete diff2[key]);
+        Utils_1.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_1.Utils.keys(data)
+            .filter(key => meta.properties[key]?.formula || [enums_1.ReferenceKind.ONE_TO_MANY, enums_1.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
+        this.hydrate(entity, meta, diff2, 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_1.Utils.keys(diff2).forEach(key => {
+            const prop = meta.properties[key];
+            if ([enums_1.ReferenceKind.MANY_TO_ONE, enums_1.ReferenceKind.ONE_TO_ONE].includes(prop.kind) && Utils_1.Utils.isPlainObject(data[prop.name])) {
+                diff2[key] = entity[prop.name] ? (0, wrap_1.helper)(entity[prop.name]).getPrimaryKey(options.convertCustomTypes) : null;
+            }
+            originalEntityData[key] = diff2[key] === null ? nullVal : diff2[key];
+            (0, wrap_1.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 ([enums_1.ReferenceKind.MANY_TO_MANY, enums_1.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_1.Utils.isPlainObject(child)) // objects with prototype can be PKs (e.g. `ObjectId`)
+                    .forEach(child => this.create(prop.type, child, options)); // we can ignore the value, we just care about the `mergeData` call
+                return;
+            }
+            if ([enums_1.ReferenceKind.MANY_TO_ONE, enums_1.ReferenceKind.ONE_TO_ONE].includes(prop.kind) && Utils_1.Utils.isPlainObject(data[prop.name]) && entity[prop.name] && (0, wrap_1.helper)(entity[prop.name]).__initialized) {
+                this.create(prop.type, data[prop.name], options); // we can ignore the value, we just care about the `mergeData` call
+            }
+        });
+        (0, wrap_1.helper)(entity).__touched = false;
+    }
+    createReference(entityName, id, options = {}) {
+        options.convertCustomTypes ??= true;
+        entityName = Utils_1.Utils.className(entityName);
+        const meta = this.metadata.get(entityName);
+        const schema = this.driver.getSchemaName(meta, options);
+        if (Array.isArray(id)) {
+            id = Utils_1.Utils.getPrimaryKeyCondFromArray(id, meta);
+        }
+        const pks = Utils_1.Utils.getOrderedPrimaryKeys(id, meta);
+        const exists = this.unitOfWork.getById(entityName, pks, schema);
+        if (exists) {
+            return exists;
+        }
+        if (Utils_1.Utils.isPrimaryKey(id)) {
+            id = { [meta.primaryKeys[0]]: id };
+        }
+        return this.create(entityName, id, { ...options, initialized: false });
+    }
+    createEmbeddable(entityName, data, options = {}) {
+        entityName = Utils_1.Utils.className(entityName);
+        data = { ...data };
+        const meta = this.metadata.get(entityName);
+        const meta2 = this.processDiscriminatorColumn(meta, data);
+        return this.createEntity(data, meta2, options);
+    }
+    getComparator() {
+        return this.comparator;
+    }
+    createEntity(data, meta, options) {
+        if (options.newEntity || meta.forceConstructor || meta.virtual) {
+            if (!meta.class) {
+                throw new Error(`Cannot create entity ${meta.className}, class prototype is unknown`);
+            }
+            options.initialized = options.newEntity || options.initialized;
+            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.initialized && 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;
+            }
+            (0, wrap_1.helper)(entity).__schema = this.driver.getSchemaName(meta, options);
+            if (options.initialized) {
+                EntityHelper_1.EntityHelper.ensurePropagation(entity);
+            }
+            return entity;
+        }
+        // creates new entity instance, bypassing constructor call as its already persisted entity
+        const entity = Object.create(meta.class.prototype);
+        (0, wrap_1.helper)(entity).__managed = true;
+        (0, wrap_1.helper)(entity).__processing = !meta.embeddable && !meta.virtual;
+        (0, wrap_1.helper)(entity).__schema = this.driver.getSchemaName(meta, options);
+        if (options.merge && !options.newEntity) {
+            this.hydrator.hydrateReference(entity, meta, data, this, options.convertCustomTypes, this.driver.getSchemaName(meta, options));
+            this.unitOfWork.register(entity);
+        }
+        if (options.initialized) {
+            EntityHelper_1.EntityHelper.ensurePropagation(entity);
+        }
+        return entity;
+    }
+    hydrate(entity, meta, data, options) {
+        if (options.initialized) {
+            this.hydrator.hydrate(entity, meta, data, this, 'full', options.newEntity, options.convertCustomTypes, this.driver.getSchemaName(meta, options));
+        }
+        else {
+            this.hydrator.hydrateReference(entity, meta, data, this, options.convertCustomTypes, this.driver.getSchemaName(meta, options));
+        }
+        Utils_1.Utils.keys(data).forEach(key => {
+            (0, wrap_1.helper)(entity)?.__loadedProperties.add(key);
+            (0, wrap_1.helper)(entity)?.__serializationContext.fields?.add(key);
+        });
+    }
+    findEntity(data, meta, options) {
+        const schema = this.driver.getSchemaName(meta, options);
+        if (meta.simplePK) {
+            return this.unitOfWork.getById(meta.className, data[meta.primaryKeys[0]], schema);
+        }
+        if (!Array.isArray(data) && meta.primaryKeys.some(pk => data[pk] == null)) {
+            return undefined;
+        }
+        const pks = Utils_1.Utils.getOrderedPrimaryKeys(data, meta);
+        return this.unitOfWork.getById(meta.className, pks, schema);
+    }
+    processDiscriminatorColumn(meta, data) {
+        if (!meta.root.discriminatorColumn) {
+            return meta;
+        }
+        const prop = meta.properties[meta.root.discriminatorColumn];
+        const value = data[prop.name];
+        const type = meta.root.discriminatorMap[value];
+        meta = type ? this.metadata.find(type) : meta;
+        return meta;
+    }
+    /**
+     * denormalize PK to value required by driver (e.g. ObjectId)
+     */
+    denormalizePrimaryKey(data, primaryKey, prop) {
+        const pk = this.platform.getSerializedPrimaryKeyField(primaryKey);
+        if (data[pk] != null || data[primaryKey] != null) {
+            let id = (data[pk] || data[primaryKey]);
+            if (prop.type.toLowerCase() === 'objectid') {
+                id = this.platform.denormalizePrimaryKey(id);
+            }
+            delete data[pk];
+            data[primaryKey] = id;
+        }
+    }
+    /**
+     * returns parameters for entity constructor, creating references from plain ids
+     */
+    extractConstructorParams(meta, data, options) {
+        return meta.constructorParams.map(k => {
+            if (meta.properties[k] && [enums_1.ReferenceKind.MANY_TO_ONE, enums_1.ReferenceKind.ONE_TO_ONE].includes(meta.properties[k].kind) && data[k]) {
+                const entity = this.unitOfWork.getById(meta.properties[k].type, data[k], options.schema);
+                if (entity) {
+                    return entity;
+                }
+                if (Utils_1.Utils.isEntity(data[k])) {
+                    return data[k];
+                }
+                if (Utils_1.Utils.isObject(data[k]) && !Utils_1.Utils.extractPK(data[k], meta.properties[k].targetMeta, true)) {
+                    return this.create(meta.properties[k].type, data[k], options);
+                }
+                const { newEntity, initialized, ...rest } = options;
+                return this.createReference(meta.properties[k].type, data[k], rest);
+            }
+            if (meta.properties[k]?.kind === enums_1.ReferenceKind.EMBEDDED && data[k]) {
+                /* istanbul ignore next */
+                if (Utils_1.Utils.isEntity(data[k])) {
+                    return data[k];
+                }
+                return this.createEmbeddable(meta.properties[k].type, data[k], options);
+            }
+            if (!meta.properties[k]) {
+                const tmp = { ...data };
+                for (const prop of meta.props) {
+                    if (options.convertCustomTypes && prop.customType && tmp[prop.name] != null) {
+                        tmp[prop.name] = prop.customType.convertToJSValue(tmp[prop.name], this.platform);
+                    }
+                }
+                return tmp;
+            }
+            if (options.convertCustomTypes && meta.properties[k].customType && data[k] != null) {
+                return meta.properties[k].customType.convertToJSValue(data[k], this.platform);
+            }
+            return data[k];
+        });
+    }
+    get unitOfWork() {
+        return this.em.getUnitOfWork(false);
+    }
+}
+exports.EntityFactory = EntityFactory;

package/entity/EntityHelper.d.ts

@@ -0,0 +1,29 @@
+import type { EntityManager } from '../EntityManager';
+import { type EntityMetadata, type EntityProperty, type IHydrator } from '../typings';
+/**
+ * @internal
+ */
+export declare class EntityHelper {
+    static decorate<T extends object>(meta: EntityMetadata<T>, em: EntityManager): void;
+    /**
+     * As a performance optimization, we create entity state methods in a lazy manner. We first add
+     * the `null` value to the prototype to reserve space in memory. Then we define a setter on the
+     * prototype, that will be executed exactly once per entity instance. There we redefine given
+     * property on the entity instance, so shadowing the prototype setter.
+     */
+    private static defineBaseProperties;
+    /**
+     * Defines getter and setter for every owning side of m:1 and 1:1 relation. This is then used for propagation of
+     * changes to the inverse side of bi-directional relations. Rest of the properties are also defined this way to
+     * achieve dirtiness, which is then used for fast checks whether we need to auto-flush because of managed entities.
+     *
+     * First defines a setter on the prototype, once called, actual get/set handlers are registered on the instance rather
+     * than on its prototype. Thanks to this we still have those properties enumerable (e.g. part of `Object.keys(entity)`).
+     */
+    private static defineProperties;
+    static defineCustomInspect<T extends object>(meta: EntityMetadata<T>): void;
+    static defineReferenceProperty<T extends object>(meta: EntityMetadata<T>, prop: EntityProperty<T>, ref: T, hydrator: IHydrator): void;
+    static propagate<T extends object>(meta: EntityMetadata<T>, entity: T, owner: T, prop: EntityProperty<T>, value?: T[keyof T & string], old?: T): void;
+    private static propagateOneToOne;
+    static ensurePropagation<T extends object>(entity: T): void;
+}

package/entity/EntityHelper.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityHelper = void 0;
+const util_1 = require("util");
+const typings_1 = require("../typings");
+const EntityTransformer_1 = require("../serialization/EntityTransformer");
+const Reference_1 = require("./Reference");
+const Utils_1 = require("../utils/Utils");
+const WrappedEntity_1 = require("./WrappedEntity");
+const enums_1 = require("../enums");
+const wrap_1 = require("./wrap");
+/**
+ * @internal
+ */
+class EntityHelper {
+    static decorate(meta, em) {
+        const fork = em.fork(); // use fork so we can access `EntityFactory`
+        const serializedPrimaryKey = meta.props.find(p => p.serializedPrimaryKey);
+        if (serializedPrimaryKey) {
+            Object.defineProperty(meta.prototype, serializedPrimaryKey.name, {
+                get() {
+                    return this._id ? em.getPlatform().normalizePrimaryKey(this._id) : null;
+                },
+                set(id) {
+                    this._id = id ? em.getPlatform().denormalizePrimaryKey(id) : null;
+                },
+                configurable: true,
+            });
+        }
+        EntityHelper.defineBaseProperties(meta, meta.prototype, fork);
+        EntityHelper.defineCustomInspect(meta);
+        if (em.config.get('propagationOnPrototype') && !meta.embeddable && !meta.virtual) {
+            EntityHelper.defineProperties(meta, fork);
+        }
+        const prototype = meta.prototype;
+        if (!prototype.toJSON) { // toJSON can be overridden
+            prototype.toJSON = function (...args) {
+                return EntityTransformer_1.EntityTransformer.toObject(this, ...args.slice(meta.toJsonParams.length));
+            };
+        }
+    }
+    /**
+     * As a performance optimization, we create entity state methods in a lazy manner. We first add
+     * the `null` value to the prototype to reserve space in memory. Then we define a setter on the
+     * prototype, that will be executed exactly once per entity instance. There we redefine given
+     * property on the entity instance, so shadowing the prototype setter.
+     */
+    static defineBaseProperties(meta, prototype, em) {
+        const helperParams = meta.embeddable || meta.virtual ? [] : [em.getComparator().getPkGetter(meta), em.getComparator().getPkSerializer(meta), em.getComparator().getPkGetterConverted(meta)];
+        Object.defineProperties(prototype, {
+            __entity: { value: !meta.embeddable, configurable: true },
+            __meta: { value: meta, configurable: true },
+            __config: { value: em.config, configurable: true },
+            __platform: { value: em.getPlatform(), configurable: true },
+            __factory: { value: em.getEntityFactory(), configurable: true },
+            __helper: {
+                get() {
+                    Object.defineProperty(this, '__helper', {
+                        value: new WrappedEntity_1.WrappedEntity(this, em.getHydrator(), ...helperParams),
+                        enumerable: false,
+                        configurable: true,
+                    });
+                    return this.__helper;
+                },
+                configurable: true, // otherwise jest fails when trying to compare entities ¯\_(ツ)_/¯
+            },
+        });
+    }
+    /**
+     * Defines getter and setter for every owning side of m:1 and 1:1 relation. This is then used for propagation of
+     * changes to the inverse side of bi-directional relations. Rest of the properties are also defined this way to
+     * achieve dirtiness, which is then used for fast checks whether we need to auto-flush because of managed entities.
+     *
+     * First defines a setter on the prototype, once called, actual get/set handlers are registered on the instance rather
+     * than on its prototype. Thanks to this we still have those properties enumerable (e.g. part of `Object.keys(entity)`).
+     */
+    static defineProperties(meta, em) {
+        Object
+            .values(meta.properties)
+            .forEach(prop => {
+            const isCollection = [enums_1.ReferenceKind.ONE_TO_MANY, enums_1.ReferenceKind.MANY_TO_MANY].includes(prop.kind);
+            const isReference = [enums_1.ReferenceKind.ONE_TO_ONE, enums_1.ReferenceKind.MANY_TO_ONE].includes(prop.kind) && (prop.inversedBy || prop.mappedBy) && !prop.mapToPk;
+            if (isReference) {
+                Object.defineProperty(meta.prototype, prop.name, {
+                    set(val) {
+                        EntityHelper.defineReferenceProperty(meta, prop, this, em.getHydrator());
+                        this[prop.name] = val;
+                    },
+                    configurable: true,
+                });
+                return;
+            }
+            if (prop.inherited || prop.primary || prop.persist === false || prop.trackChanges === false || prop.embedded || isCollection) {
+                return;
+            }
+            Object.defineProperty(meta.prototype, prop.name, {
+                set(val) {
+                    Object.defineProperty(this, prop.name, {
+                        get() {
+                            return this.__helper?.__data[prop.name];
+                        },
+                        set(val) {
+                            this.__helper.__data[prop.name] = val;
+                            this.__helper.__touched = !this.__helper.hydrator.isRunning();
+                        },
+                        enumerable: true,
+                        configurable: true,
+                    });
+                    this.__helper.__data[prop.name] = val;
+                    this.__helper.__touched = !this.__helper.hydrator.isRunning();
+                },
+                configurable: true,
+            });
+        });
+    }
+    static defineCustomInspect(meta) {
+        // @ts-ignore
+        meta.prototype[util_1.inspect.custom] ??= function (depth) {
+            const object = { ...this };
+            // ensure we dont have internal symbols in the POJO
+            [typings_1.OptionalProps, typings_1.EntityRepositoryType, typings_1.PrimaryKeyProp, typings_1.EagerProps, typings_1.HiddenProps].forEach(sym => delete object[sym]);
+            meta.props
+                .filter(prop => object[prop.name] === undefined)
+                .forEach(prop => delete object[prop.name]);
+            const ret = (0, util_1.inspect)(object, { depth });
+            let name = (this).constructor.name;
+            const showEM = ['true', 't', '1'].includes(process.env.MIKRO_ORM_LOG_EM_ID?.toString().toLowerCase() ?? '');
+            if (showEM) {
+                if ((0, wrap_1.helper)(this).__em) {
+                    name += ` [managed by ${(0, wrap_1.helper)(this).__em.id}]`;
+                }
+                else {
+                    name += ` [not managed]`;
+                }
+            }
+            // distinguish not initialized entities
+            if (!(0, wrap_1.helper)(this).__initialized) {
+                name = `(${name})`;
+            }
+            return ret === '[Object]' ? `[${name}]` : name + ' ' + ret;
+        };
+    }
+    static defineReferenceProperty(meta, prop, ref, hydrator) {
+        const wrapped = (0, wrap_1.helper)(ref);
+        Object.defineProperty(ref, prop.name, {
+            get() {
+                return (0, wrap_1.helper)(ref).__data[prop.name];
+            },
+            set(val) {
+                const entity = Reference_1.Reference.unwrapReference(val ?? wrapped.__data[prop.name]);
+                const old = Reference_1.Reference.unwrapReference(wrapped.__data[prop.name]);
+                wrapped.__data[prop.name] = Reference_1.Reference.wrapReference(val, prop);
+                // when propagation from inside hydration, we set the FK to the entity data immediately
+                if (val && hydrator.isRunning() && wrapped.__originalEntityData && prop.owner) {
+                    wrapped.__originalEntityData[prop.name] = Utils_1.Utils.getPrimaryKeyValues(wrapped.__data[prop.name], prop.targetMeta.primaryKeys, true);
+                }
+                else {
+                    wrapped.__touched = !hydrator.isRunning();
+                }
+                EntityHelper.propagate(meta, entity, this, prop, Reference_1.Reference.unwrapReference(val), old);
+            },
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    static propagate(meta, entity, owner, prop, value, old) {
+        const inverseProps = prop.targetMeta.bidirectionalRelations
+            .filter(prop2 => (prop2.inversedBy || prop2.mappedBy) === prop.name)
+            .filter(prop2 => {
+            const meta2 = prop2.targetMeta;
+            return meta2.abstract ? meta2.root.className === meta.root.className : meta2.className === meta.className;
+        });
+        for (const prop2 of inverseProps) {
+            const inverse = value?.[prop2.name];
+            if (prop.kind === enums_1.ReferenceKind.MANY_TO_ONE && Utils_1.Utils.isCollection(inverse) && inverse.isInitialized()) {
+                inverse.add(owner);
+            }
+            if (prop.kind === enums_1.ReferenceKind.ONE_TO_ONE && entity && (!prop.owner || (0, wrap_1.helper)(entity).__initialized)) {
+                if ((value != null && Reference_1.Reference.unwrapReference(inverse) !== owner) ||
+                    (value == null && entity[prop2.name] != null)) {
+                    EntityHelper.propagateOneToOne(entity, owner, prop, prop2, value, old);
+                }
+            }
+        }
+    }
+    static propagateOneToOne(entity, owner, prop, prop2, value, old) {
+        (0, wrap_1.helper)(entity).__pk = (0, wrap_1.helper)(entity).getPrimaryKey();
+        // the inverse side will be changed on the `value` too, so we need to clean-up and schedule orphan removal there too
+        if (!prop.primary && !prop2.mapToPk && value?.[prop2.name] != null && Reference_1.Reference.unwrapReference(value[prop2.name]) !== entity) {
+            const other = Reference_1.Reference.unwrapReference(value[prop2.name]);
+            delete (0, wrap_1.helper)(other).__data[prop.name];
+            if (prop2.orphanRemoval) {
+                (0, wrap_1.helper)(other).__em?.getUnitOfWork().scheduleOrphanRemoval(other);
+            }
+        }
+        if (value == null) {
+            entity[prop2.name] = value;
+        }
+        else if (prop2.mapToPk) {
+            entity[prop2.name] = (0, wrap_1.helper)(owner).getPrimaryKey();
+        }
+        else {
+            entity[prop2.name] = Reference_1.Reference.wrapReference(owner, prop);
+        }
+        if (old && prop.orphanRemoval) {
+            (0, wrap_1.helper)(old).__em?.getUnitOfWork().scheduleOrphanRemoval(old);
+        }
+        if (old?.[prop2.name] != null) {
+            delete (0, wrap_1.helper)(old).__data[prop2.name];
+        }
+    }
+    static ensurePropagation(entity) {
+        if (entity.__gettersDefined) {
+            return;
+        }
+        const wrapped = (0, wrap_1.helper)(entity);
+        const meta = wrapped.__meta;
+        const platform = wrapped.__platform;
+        const serializedPrimaryKey = meta.props.find(p => p.serializedPrimaryKey);
+        const values = [];
+        if (serializedPrimaryKey) {
+            const pk = meta.getPrimaryProps()[0];
+            const val = entity[serializedPrimaryKey.name];
+            delete entity[serializedPrimaryKey.name];
+            Object.defineProperty(entity, serializedPrimaryKey.name, {
+                get() {
+                    return this[pk.name] ? platform.normalizePrimaryKey(this[pk.name]) : null;
+                },
+                set(id) {
+                    this[pk.name] = id ? platform.denormalizePrimaryKey(id) : null;
+                },
+                configurable: true,
+            });
+            if (entity[pk.name] == null && val != null) {
+                values.push([serializedPrimaryKey.name, val]);
+            }
+        }
+        meta.trackingProps.forEach(prop => {
+            if (entity[prop.name] !== undefined) {
+                values.push([prop.name, entity[prop.name]]);
+            }
+        });
+        meta.trackingProps.forEach(prop => {
+            delete entity[prop.name];
+        });
+        Object.defineProperties(entity, meta.definedProperties);
+        values.forEach(val => entity[val[0]] = val[1]);
+    }
+}
+exports.EntityHelper = EntityHelper;

package/entity/EntityIdentifier.d.ts

@@ -0,0 +1,10 @@
+import type { IPrimaryKey } from '../typings';
+/**
+ * @internal
+ */
+export declare class EntityIdentifier {
+    private value?;
+    constructor(value?: import("../typings").IPrimaryKeyValue | undefined);
+    setValue(value: IPrimaryKey): void;
+    getValue<T extends IPrimaryKey = IPrimaryKey>(): T;
+}

package/entity/EntityIdentifier.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityIdentifier = void 0;
+/**
+ * @internal
+ */
+class EntityIdentifier {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    setValue(value) {
+        this.value = value;
+    }
+    getValue() {
+        return this.value;
+    }
+}
+exports.EntityIdentifier = EntityIdentifier;

package/entity/EntityLoader.d.ts

@@ -0,0 +1,65 @@
+import type { ConnectionType, Dictionary, FilterQuery, PopulateOptions } from '../typings';
+import type { EntityManager } from '../EntityManager';
+import { LoadStrategy, type LockMode, type PopulateHint, type QueryOrderMap } from '../enums';
+import type { EntityField } from '../drivers/IDatabaseDriver';
+import type { LoggingOptions } from '../logging/Logger';
+export type EntityLoaderOptions<Entity, Fields extends string = '*', Excludes extends string = never> = {
+    where?: FilterQuery<Entity>;
+    populateWhere?: PopulateHint | `${PopulateHint}`;
+    fields?: readonly EntityField<Entity, Fields>[];
+    exclude?: readonly EntityField<Entity, Excludes>[];
+    orderBy?: QueryOrderMap<Entity> | QueryOrderMap<Entity>[];
+    refresh?: boolean;
+    validate?: boolean;
+    lookup?: boolean;
+    convertCustomTypes?: boolean;
+    ignoreLazyScalarProperties?: boolean;
+    filters?: Dictionary<boolean | Dictionary> | string[] | boolean;
+    strategy?: LoadStrategy;
+    lockMode?: Exclude<LockMode, LockMode.OPTIMISTIC>;
+    schema?: string;
+    connectionType?: ConnectionType;
+    logging?: LoggingOptions;
+};
+export declare class EntityLoader {
+    private readonly em;
+    private readonly metadata;
+    private readonly driver;
+    constructor(em: EntityManager);
+    /**
+     * Loads specified relations in batch.
+     * This will execute one query for each relation, that will populate it on all the specified entities.
+     */
+    populate<Entity extends object, Fields extends string = '*'>(entityName: string, entities: Entity[], populate: PopulateOptions<Entity>[] | boolean, options: EntityLoaderOptions<Entity, Fields>): Promise<void>;
+    normalizePopulate<Entity>(entityName: string, populate: (PopulateOptions<Entity> | boolean)[] | PopulateOptions<Entity> | boolean, strategy?: LoadStrategy, lookup?: boolean): PopulateOptions<Entity>[];
+    private expandDotPaths;
+    /**
+     * Merge multiple populates for the same entity with different children. Also skips `*` fields, those can come from
+     * partial loading hints (`fields`) that are used to infer the `populate` hint if missing.
+     */
+    private mergeNestedPopulate;
+    /**
+     * Expands `books.perex` like populate to use `children` array instead of the dot syntax
+     */
+    private expandNestedPopulate;
+    /**
+     * preload everything in one call (this will update already existing references in IM)
+     */
+    private populateMany;
+    private initializeCollections;
+    private initializeOneToMany;
+    private initializeManyToMany;
+    private findChildren;
+    private mergePrimaryCondition;
+    private populateField;
+    private findChildrenFromPivotTable;
+    private extractChildCondition;
+    private buildFields;
+    private getChildReferences;
+    private filterCollections;
+    private filterReferences;
+    private filterByReferences;
+    private lookupAllRelationships;
+    private getRelationName;
+    private lookupEagerLoadedRelationships;
+}