@mikro-orm/core 7.3.0-dev.0 → 7.3.0-dev.10

package/EntityManager.js

@@ -789,6 +789,10 @@ export class EntityManager {
                 .getHydrator(this.metadata)
                 .hydrate(ref, helper(ref).__meta, data, em.#entityFactory, 'full', false, false);
             Utils.merge(helper(ref).__originalEntityData, this.#comparator.prepareEntity(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) {

package/entity/EntityFactory.d.ts

@@ -51,6 +51,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) {
@@ -190,7 +194,7 @@ export class EntityFactory {
         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;
+        const nullVal = (meta.forceUndefined ?? 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) &&
@@ -232,9 +236,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 +246,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 +316,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);
@@ -336,7 +348,7 @@ export class EntityFactory {
                 prop.default == null &&
                 !prop.defaultRaw &&
                 entity[prop.name] === undefined) {
-                entity[prop.name] = (this.#config.get('forceUndefined') ? undefined : null);
+                entity[prop.name] = ((meta.forceUndefined ?? this.#config.get('forceUndefined')) ? undefined : null);
             }
             if (prop.kind === ReferenceKind.EMBEDDED && entity[prop.name]) {
                 const items = prop.array ? entity[prop.name] : [entity[prop.name]];
@@ -379,6 +391,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;
@@ -458,7 +459,8 @@ export class EntityLoader {
         if ([ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) &&
             items.length !== children.length &&
             Utils.isEmpty(options.where)) {
-            const nullVal = this.#em.config.get('forceUndefined') ? undefined : null;
+            const ownerMeta = this.#metadata.find(prop.entity());
+            const nullVal = (ownerMeta.forceUndefined ?? this.#em.config.get('forceUndefined')) ? undefined : null;
             const itemsMap = new Set();
             const childrenMap = new Set();
             // `e` may be an unresolved reference here, so read the targetKey value directly instead of

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,

package/entity/defineEntity.d.ts

@@ -631,7 +631,7 @@ type PartialWhere<TProperties, TBase> = string | FilterQuery<{
     [K in AllKeys<TProperties, TBase> & string]?: unknown;
 }>;
 /** Metadata descriptor for `defineEntity()`, combining entity options with property definitions. */
-export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false, TDiscriminatorColumn extends string | undefined = undefined, TDiscriminatorValue extends string | number | undefined = undefined, TBaseDiscriminatorColumn extends string | undefined = undefined, TEmbeddable extends boolean = false> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminator' | 'discriminatorColumn' | 'discriminatorValue' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
+export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false, TDiscriminatorColumn extends string | undefined = undefined, TDiscriminatorValue extends string | number | undefined = undefined, TBaseDiscriminatorColumn extends string | undefined = undefined, TEmbeddable extends boolean = false, TForceUndefined extends boolean = false> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminator' | 'discriminatorColumn' | 'discriminatorValue' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
     name: TName;
     tableName?: TTableName;
     extends?: {
@@ -656,6 +656,8 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         };
     }>;
     forceObject?: TForceObject;
+    /** Hydrate `null` as `undefined` for this entity and infer nullable properties as `T | undefined`. */
+    forceUndefined?: TForceUndefined;
     embeddable?: TEmbeddable;
     inheritance?: 'tpt';
     orderBy?: {
@@ -707,7 +709,7 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
     }[];
 }
 /** Defines an entity schema using property builders, with full type inference from the property definitions. */
-export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false, const TDiscriminatorColumn extends string | undefined = undefined, const TDiscriminatorValue extends string | number | undefined = undefined, const TBaseDiscriminatorColumn extends string | undefined = undefined, const TEmbeddable extends boolean = false>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject, TDiscriminatorColumn, TDiscriminatorValue, TBaseDiscriminatorColumn, TEmbeddable>): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable>, TBase, TProperties, EntityCtor<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable>>, TDiscriminatorColumn>;
+export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false, const TDiscriminatorColumn extends string | undefined = undefined, const TDiscriminatorValue extends string | number | undefined = undefined, const TBaseDiscriminatorColumn extends string | undefined = undefined, const TEmbeddable extends boolean = false, const TForceUndefined extends boolean = false>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject, TDiscriminatorColumn, TDiscriminatorValue, TBaseDiscriminatorColumn, TEmbeddable, TForceUndefined>): EntitySchemaWithMeta<TName, TTableName, MaybeForceUndefined<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable, TForceUndefined>, EffectiveForceUndefined<TForceUndefined, TBase>>, TBase, TProperties, EntityCtor<MaybeForceUndefined<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable, TForceUndefined>, EffectiveForceUndefined<TForceUndefined, TBase>>>, TDiscriminatorColumn>;
 export declare namespace defineEntity {
     export { propertyBuilders as properties };
 }
@@ -744,8 +746,17 @@ type InferColumnType<T extends string> = T extends 'int' | 'int4' | 'integer' |
 type BaseEntityMethodKeys = 'toObject' | 'toPOJO' | 'serialize' | 'assign' | 'populate' | 'init' | 'toReference';
 interface BaseEntityMethods<in out Entity extends object> extends Pick<IWrappedEntity<Entity>, BaseEntityMethodKeys> {
 }
+type MaybeForceUndefined<Entity, ForceUndefined> = [ForceUndefined] extends [true] ? {
+    [K in keyof Entity]: SwapNull<Entity[K]>;
+} : Entity;
+type SwapNull<Value> = [Value] extends [ScalarReference<infer Inner>] ? [Extract<keyof Value, symbol>] extends [never] ? ScalarReference<SwapNull<Inner>> : ScalarReference<SwapNull<Inner>> & Pick<Value, Extract<keyof Value, symbol>> : null extends Value ? Exclude<Value, null> | undefined : Value;
+type EffectiveForceUndefined<Flag, Base> = [Flag] extends [true] ? true : IsNever<Base> extends true ? false : [Base] extends [{
+    [Config]?: infer C;
+}] ? [NonNullable<C>] extends [{
+    forceUndefined: true;
+}] ? true : false : false;
 /** Infers the entity type from a `defineEntity()` properties map, resolving builders, base classes, and primary keys. */
-export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined, Embeddable extends boolean = false> = (IsNever<Base> extends true ? {} : Base extends {
+export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined, Embeddable extends boolean = false, ForceUndefined extends boolean = false> = (IsNever<Base> extends true ? {} : Base extends {
     toObject(...args: any[]): any;
 } ? BaseEntityMethods<{
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
@@ -763,6 +774,10 @@ export type InferEntityFromProperties<Properties extends Record<string, any>, PK
     [Config]?: DefineConfig<{
         forceObject: true;
     }>;
+} : {}) & (ForceUndefined extends true ? {
+    [Config]?: DefineConfig<{
+        forceUndefined: true;
+    }>;
 } : {}) & {
     [IndexHints]?: [Omit<ExtractBaseProperties<Base>, keyof Properties> & Properties];
 };

package/errors.d.ts

@@ -10,6 +10,7 @@ export declare class ValidationError<T extends AnyEntity = AnyEntity> extends Er
     static fromWrongPropertyType(entity: AnyEntity, property: string, expectedType: string, givenType: string, givenValue: string): ValidationError;
     static fromWrongRepositoryType(entityName: string, repoType: string, method: string): ValidationError;
     static fromMergeWithoutPK(meta: EntityMetadata): ValidationError;
+    static referenceWithoutPK(entity: AnyEntity): ValidationError;
     static transactionRequired(): ValidationError;
     static entityNotManaged(entity: AnyEntity): ValidationError;
     static notEntity(owner: AnyEntity, prop: EntityProperty, data: any): ValidationError;

package/errors.js

@@ -28,6 +28,9 @@ export class ValidationError extends Error {
     static fromMergeWithoutPK(meta) {
         return new ValidationError(`You cannot merge entity '${meta.className}' without identifier!`);
     }
+    static referenceWithoutPK(entity) {
+        return new ValidationError(`Entity '${entity.constructor.name}' is only known by an alternate key and has no primary key, load it first`, entity);
+    }
     static transactionRequired() {
         return new ValidationError('An open transaction is required for this operation');
     }

package/hydration/ObjectHydrator.js

@@ -50,6 +50,8 @@ export class ObjectHydrator extends Hydrator {
         const lines = [];
         const context = new Map();
         const props = this.getProperties(meta, type);
+        const forceUndefined = meta.forceUndefined ?? this.config.get('forceUndefined');
+        const nullVal = forceUndefined ? 'undefined' : 'null';
         context.set('isPrimaryKey', Utils.isPrimaryKey);
         context.set('isEntity', EntityHelper.isEntity);
         context.set('isScalarReference', ScalarReference.isScalarReference);
@@ -76,7 +78,6 @@ export class ObjectHydrator extends Hydrator {
                 .join('_');
             const ret = [];
             const idx = this.#tmpIndex++;
-            const nullVal = this.config.get('forceUndefined') ? 'undefined' : 'null';
             if (prop.getter && !prop.setter && prop.persist === false) {
                 return [];
             }
@@ -142,7 +143,6 @@ export class ObjectHydrator extends Hydrator {
         const hydrateToOne = (prop, dataKey, entityKey) => {
             const ret = [];
             const method = type === 'reference' ? 'createReference' : 'create';
-            const nullVal = this.config.get('forceUndefined') ? 'undefined' : 'null';
             ret.push(`  if (data${dataKey} === null) {\n    entity${entityKey} = ${nullVal};`);
             ret.push(`  } else if (typeof data${dataKey} !== 'undefined') {`);
             // For polymorphic: instanceof check; for regular: isPrimaryKey() check
@@ -207,7 +207,7 @@ export class ObjectHydrator extends Hydrator {
             if (prop.customType?.ensureComparable(meta, prop)) {
                 registerCustomType(prop, this.safeKey(prop.name), 'convertToDatabaseValue', context);
                 ret.push(`  if (data${dataKey} != null && typeof data${dataKey} !== 'object' && convertCustomTypes) {`);
-                ret.push(`    data${dataKey} = convertToDatabaseValue_${this.safeKey(prop.name)}(entity${entityKey}.__helper.getPrimaryKey());`);
+                ret.push(`    data${dataKey} = convertToDatabaseValue_${this.safeKey(prop.name)}(entity${entityKey}.__helper.getTargetKeyValue(${prop.targetKey ? this.quote(prop.targetKey) : ''}));`);
                 ret.push(`  }`);
             }
             return ret;
@@ -341,8 +341,6 @@ export class ObjectHydrator extends Hydrator {
                     ...hydrateProperty(childProp, prop.object, [...path, childProp.embedded[1]], childDataKey).map(l => '  ' + l));
                 });
             }
-            /* v8 ignore next */
-            const nullVal = this.config.get('forceUndefined') ? 'undefined' : 'null';
             if (prop.object) {
                 ret.push(`  } else if (data${dataKey} === null) {`);
             }
@@ -365,8 +363,7 @@ export class ObjectHydrator extends Hydrator {
             ret.push(...hydrateEmbedded(prop, [...path, `[idx_${idx}]`], `${dataKey}[idx_${idx}]`).map(l => '    ' + l));
             ret.push(`    });`);
             ret.push(`  } else if (data${dataKey} === null) {`);
-            /* v8 ignore next */
-            ret.push(`    entity${entityKey} = ${this.config.get('forceUndefined') ? 'undefined' : 'null'};`);
+            ret.push(`    entity${entityKey} = ${nullVal};`);
             ret.push(`  }`);
             return ret;
         };
@@ -396,7 +393,7 @@ export class ObjectHydrator extends Hydrator {
                 // ReferenceKind.SCALAR
                 ret.push(...hydrateScalar(prop, path, dataKey));
             }
-            if (this.config.get('forceUndefined')) {
+            if (forceUndefined) {
                 ret.push(`  if (data${dataKey} === null) entity${entityKey} = undefined;`);
             }
             return ret;
@@ -407,7 +404,7 @@ export class ObjectHydrator extends Hydrator {
         const code = `// compiled hydrator for entity ${meta.className} (${type + normalizeAccessors ? ' normalized' : ''})\n` +
             `return function(entity, data, factory, newEntity, convertCustomTypes, schema, parentSchema, normalizeAccessors) {\n` +
             `${lines.join('\n')}\n}`;
-        const fnKey = `hydrator-${meta.uniqueName}-${type}-${normalizeAccessors}`;
+        const fnKey = `hydrator-${meta.compiledName}-${type}-${normalizeAccessors}`;
         const hydrator = Utils.createFunction(context, code, this.config.get('compiledFunctions'), fnKey);
         this.#hydrators[key].set(meta.class, hydrator);
         return hydrator;

package/metadata/MetadataDiscovery.js

@@ -547,7 +547,7 @@ export class MetadataDiscovery {
             const fieldNames1 = prop.targetMeta.getPrimaryProps().flatMap(pk => pk.fieldNames);
             const idColumns = fieldNames1.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, fieldName, fieldNames1.length > 1));
             prop.fieldNames ??= [prop.discriminatorColumn, ...idColumns];
-            prop.joinColumns ??= idColumns;
+            prop.joinColumns ??= prop.fieldNames.slice(1);
             prop.referencedColumnNames ??= fieldNames1;
             prop.referencedTableName ??= prop.targetMeta.tableName;
             return;
@@ -564,7 +564,10 @@ export class MetadataDiscovery {
         }
         Utils.defaultValue(prop, 'referencedTableName', meta2.tableName);
         if (!prop.joinColumns) {
-            prop.joinColumns = fieldNames.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.name, fieldName, fieldNames.length > 1));
+            // must match the real FK columns, which ignore `targetKey` naming for simple PK targets
+            prop.joinColumns = prop.targetKey
+                ? prop.fieldNames
+                : fieldNames.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.name, fieldName, fieldNames.length > 1));
         }
         if (!prop.referencedColumnNames) {
             prop.referencedColumnNames = fieldNames;
@@ -670,6 +673,12 @@ export class MetadataDiscovery {
                 if (prop2.kind !== ReferenceKind.SCALAR && prop2.type === meta.className) {
                     meta.referencingProperties.push({ meta: meta2, prop: prop2 });
                 }
+                if (prop2.targetKey &&
+                    (prop2.type === meta.className || prop2.polymorphTargets?.some(t => t.className === meta.className)) &&
+                    !(meta.primaryKeys.length === 1 && meta.primaryKeys[0] === prop2.targetKey) &&
+                    !meta.root.targetKeys?.includes(prop2.targetKey)) {
+                    (meta.root.targetKeys ??= []).push(prop2.targetKey);
+                }
             }
         }
     }
@@ -1062,6 +1071,7 @@ export class MetadataDiscovery {
         });
         ownProps.forEach(prop => (meta.properties[prop.name] = prop));
         meta.filters = { ...base.filters, ...meta.filters };
+        meta.forceUndefined ??= base.forceUndefined;
         if (!meta.discriminatorValue) {
             Object.values(base.properties)
                 .filter(prop => !old.includes(prop.name))
@@ -1174,12 +1184,24 @@ export class MetadataDiscovery {
         if (!prop.discriminator && !prop.discriminatorColumn && !prop.discriminatorMap && !Array.isArray(prop.target)) {
             return;
         }
+        const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
+        const isUnionTargetMN = prop.kind === ReferenceKind.MANY_TO_MANY && Array.isArray(prop.target);
         prop.polymorphic = true;
         prop.discriminator ??= prop.name;
+        // explicit `fieldNames` use the `[discriminatorColumn, ...fkIdColumns]` layout
+        if (isToOne && prop.fieldNames && prop.fieldNames.length > 1) {
+            prop.discriminatorColumn ??= prop.fieldNames[0];
+            // `EntitySchema` mirrors `fieldNames` into `joinColumns`, let `initManyToOneFields` derive them after embedded prefixing
+            if (Utils.equals(prop.joinColumns, prop.fieldNames)) {
+                delete prop.joinColumns;
+            }
+        }
         prop.discriminatorColumn ??= this.#namingStrategy.discriminatorColumnName(prop.discriminator);
         prop.createForeignKeyConstraint = false;
-        const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
-        const isUnionTargetMN = prop.kind === ReferenceKind.MANY_TO_MANY && Array.isArray(prop.target);
+        // a single field name can only be the FK column, e.g. mirrored from `joinColumn`
+        if (isToOne && prop.fieldNames?.length === 1) {
+            prop.fieldNames = [prop.discriminatorColumn, ...prop.fieldNames];
+        }
         if (isToOne || isUnionTargetMN) {
             const types = prop.type.split(/ ?\| ?/);
             prop.polymorphTargets = discovered.filter(m => types.includes(m.className) && !m.embeddable);
@@ -1439,7 +1461,8 @@ export class MetadataDiscovery {
                     }
                 }
                 rootProp.stiFieldNameMap[meta.discriminatorValue] = prop.fieldNames[0];
-                rootProp.stiFieldNames.push(...prop.fieldNames);
+                // subtypes that only differ in type share the column
+                rootProp.stiFieldNames = Utils.unique([...rootProp.stiFieldNames, ...prop.fieldNames]);
                 newProp.nullable = true;
                 newProp.name = name;
                 newProp.hydrate = false;

package/metadata/MetadataStorage.d.ts

@@ -32,6 +32,13 @@ export declare class MetadataStorage {
     getById<T>(id: number): EntityMetadata<T>;
     /** Returns metadata by class name, optionally throwing if not found. */
     getByClassName<T = any, V extends boolean = true>(className: string, validate?: V): V extends true ? EntityMetadata<T> : EntityMetadata<T> | undefined;
+    /**
+     * Returns the first registered metadata with the given table name, in registration order (entities sharing
+     * a table, like STI children, resolve to the one registered first). The index is built on first use, as table
+     * names are only final once discovery has finished.
+     * @internal
+     */
+    getByTableName<T = any>(tableName: string): EntityMetadata<T> | undefined;
     /** Returns metadata by unique name, optionally throwing if not found. */
     getByUniqueName<T = any, V extends boolean = true>(uniqueName: string, validate?: V): V extends true ? EntityMetadata<T> : EntityMetadata<T> | undefined;
     private validate;

package/metadata/MetadataStorage.js

@@ -18,6 +18,8 @@ export class MetadataStorage {
     #classNameMap;
     #uniqueNameMap;
     #ambiguousNames = new Set();
+    /** Built on first use by `getByTableName()`, dropped whenever an entity is registered or removed. */
+    #tableNameMap;
     constructor(metadata = {}) {
         this.#idMap = {};
         this.#uniqueNameMap = {};
@@ -102,6 +104,7 @@ export class MetadataStorage {
     /** Registers metadata for the given entity. */
     set(entityName, meta) {
         this.#metadataMap.set(entityName, meta);
+        this.#tableNameMap = undefined;
         this.#idMap[meta._id] = meta;
         this.#uniqueNameMap[meta.uniqueName] = meta;
         const className = Utils.className(entityName);
@@ -110,6 +113,12 @@ export class MetadataStorage {
         if (existing && existing !== meta && existing.class !== meta.class) {
             this.#ambiguousNames.add(className);
         }
+        // colliding names are numbered in storage order, which follows the discovery config, not module evaluation
+        const sameName = this.#ambiguousNames.has(className)
+            ? [...new Set(this.#metadataMap.values())].filter(m => m.className === meta.className)
+            : [meta];
+        const ordinal = sameName.indexOf(meta);
+        meta.compiledName = ordinal > 0 ? `${meta.className}#${ordinal}` : meta.className;
         this.#classNameMap[className] = meta;
         return meta;
     }
@@ -118,6 +127,7 @@ export class MetadataStorage {
         const meta = this.find(entityName);
         if (meta) {
             this.#metadataMap.delete(meta.class);
+            this.#tableNameMap = undefined;
             delete this.#idMap[meta._id];
             delete this.#uniqueNameMap[meta.uniqueName];
             delete this.#classNameMap[meta.className];
@@ -145,6 +155,23 @@ export class MetadataStorage {
     getByClassName(className, validate = true) {
         return this.validate(this.#classNameMap[className], className, validate);
     }
+    /**
+     * Returns the first registered metadata with the given table name, in registration order (entities sharing
+     * a table, like STI children, resolve to the one registered first). The index is built on first use, as table
+     * names are only final once discovery has finished.
+     * @internal
+     */
+    getByTableName(tableName) {
+        if (!this.#tableNameMap) {
+            this.#tableNameMap = new Map();
+            for (const meta of this.#metadataMap.values()) {
+                if (!this.#tableNameMap.has(meta.tableName)) {
+                    this.#tableNameMap.set(meta.tableName, meta);
+                }
+            }
+        }
+        return this.#tableNameMap.get(tableName);
+    }
     /** Returns metadata by unique name, optionally throwing if not found. */
     getByUniqueName(uniqueName, validate = true) {
         return this.validate(this.#uniqueNameMap[uniqueName], uniqueName, validate);

package/metadata/types.d.ts

@@ -85,6 +85,8 @@ export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     abstract?: boolean;
     /** Disables change tracking - such entities are ignored during flush. */
     readonly?: boolean;
+    /** Hydrate `null` values as `undefined` for this entity, overriding the global `forceUndefined` option. */
+    forceUndefined?: boolean;
     /** Marks entity as {@doclink virtual-entities | virtual}. This is set automatically when you use `expression` option (unless `view` is set). */
     virtual?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.3.0-dev.0",
+  "version": "7.3.0-dev.10",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",

package/typings.d.ts

@@ -246,6 +246,8 @@ export type CleanTypeConfig<T> = Compute<Pick<T, Extract<keyof T, keyof TypeConf
 /** Configuration options that can be set on an entity via the `[Config]` symbol. */
 export interface TypeConfig {
     forceObject?: boolean;
+    /** Type-level marker of the `forceUndefined` entity option: `defineEntity` infers nullable properties as `T | undefined` instead of `T | null | undefined`. */
+    forceUndefined?: boolean;
 }
 declare const __selectedType: unique symbol;
 declare const __loadedType: unique symbol;
@@ -1173,6 +1175,7 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
         meta: EntityMetadata<Entity>;
         prop: EntityProperty<Entity>;
     }[];
+    targetKeys?: EntityKey<Entity>[];
     comparableProps: EntityProperty<Entity>[];
     trackingProps: EntityProperty<Entity>[];
     hydrateProps: EntityProperty<Entity>[];
@@ -1223,6 +1226,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     selfReferencing?: boolean;
     hasUniqueProps?: boolean;
     readonly?: boolean;
+    /** Per-entity override of the global `forceUndefined` option. */
+    forceUndefined?: boolean;
     polymorphs?: EntityMetadata[];
     root: EntityMetadata<Entity>;
     definedProperties: Dictionary;
@@ -1254,6 +1259,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     orderBy?: QueryOrderMap<Entity> | QueryOrderMap<Entity>[];
     /** @internal can be used for computed numeric cache keys */
     readonly _id: number;
+    /** @internal name that does not depend on module evaluation order (unlike `_id`), used to key `compiledFunctions` */
+    compiledName?: string;
 }
 /** Options for `ISchemaGenerator.create()`. */
 export interface CreateSchemaOptions {

package/unit-of-work/ChangeSetComputer.js

@@ -7,6 +7,7 @@ import { Reference } from '../entity/Reference.js';
 import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { ReferenceKind } from '../enums.js';
 import { isRaw } from '../utils/RawQueryFragment.js';
+import { ValidationError } from '../errors.js';
 /** @internal Computes change sets by comparing entity state against original snapshots. */
 export class ChangeSetComputer {
     #comparator;
@@ -48,6 +49,10 @@ export class ChangeSetComputer {
             if (Utils.equals(data, wrapped.__originalEntityData)) {
                 return null;
             }
+            // a reference known only by its `targetKey` has no PK, so the update would have no condition
+            if (!wrapped.hasPrimaryKey()) {
+                throw ValidationError.referenceWithoutPK(entity);
+            }
         }
         const changeSet = new ChangeSet(entity, type, this.computePayload(entity), meta);
         changeSet.originalEntity = wrapped.__originalEntityData;
@@ -162,21 +167,30 @@ export class ChangeSetComputer {
             const target = Reference.unwrapReference(rawTarget);
             const needsProcessing = target != null && (prop.targetKey != null || !target.__helper.hasPrimaryKey());
             if (needsProcessing) {
+                // a reference known only by its `targetKey` has no PK, and is never inserted to generate one
+                if (!prop.targetKey && !target.__helper.__initialized) {
+                    throw ValidationError.referenceWithoutPK(target);
+                }
                 let value = prop.targetKey ? target[prop.targetKey] : target.__helper.__identifier;
-                /* v8 ignore next */
-                if (prop.targetKey && prop.targetMeta) {
-                    const targetProp = prop.targetMeta.properties[prop.targetKey];
+                // use the actual target's meta, a polymorphic relation has several
+                if (prop.targetKey) {
+                    const targetProp = target.__meta.properties[prop.targetKey];
                     if (targetProp?.customType) {
                         value = targetProp.customType.convertToDatabaseValue(value, this.#platform, { mode: 'serialization' });
                     }
                 }
                 if (prop.polymorphic) {
                     const discriminator = QueryHelper.findDiscriminatorValue(prop.discriminatorMap, target.constructor);
-                    Utils.setPayloadProperty(changeSet.payload, changeSet.meta, prop, new PolymorphicRef(discriminator, value), idx);
+                    value = new PolymorphicRef(discriminator, value);
                 }
-                else {
-                    Utils.setPayloadProperty(changeSet.payload, changeSet.meta, prop, value, idx);
+                // an unchanged `targetKey` FK is not part of the diff
+                if (prop.targetKey &&
+                    changeSet.type === ChangeSetType.UPDATE &&
+                    !(prop.name in changeSet.payload) &&
+                    Utils.equals(changeSet.originalEntity?.[prop.name], value)) {
+                    return;
                 }
+                Utils.setPayloadProperty(changeSet.payload, changeSet.meta, prop, value, idx);
             }
         });
     }

package/unit-of-work/IdentityMap.d.ts

@@ -1,9 +1,9 @@
 import type { AnyEntity, EntityMetadata } from '../typings.js';
-/** @internal Stores managed entity instances keyed by their primary key hash, ensuring each row is loaded once. */
+/** @internal Stores managed entity instances keyed by their primary key hash (and `targetKey` values), ensuring each row is loaded once. */
 export declare class IdentityMap {
     #private;
     constructor(defaultSchema?: string);
-    /** Stores an entity in the identity map under its primary key hash. */
+    /** Stores an entity in the identity map under its primary key hash and the `targetKey` values referencing it. */
     store<T>(item: T): void;
     /**
      * Stores an entity under an alternate key (non-PK property).
@@ -25,6 +25,7 @@ export declare class IdentityMap {
     /** Returns all entities currently in the identity map. */
     values(): AnyEntity[];
     [Symbol.iterator](): IterableIterator<AnyEntity>;
+    private getEntities;
     /** Returns all hash keys currently in the identity map. */
     keys(): string[];
     /**

package/unit-of-work/IdentityMap.js

@@ -1,15 +1,29 @@
-/** @internal Stores managed entity instances keyed by their primary key hash, ensuring each row is loaded once. */
+/** @internal Stores managed entity instances keyed by their primary key hash (and `targetKey` values), ensuring each row is loaded once. */
 export class IdentityMap {
     #defaultSchema;
     #registry = new Map();
     /** Tracks alternate key hashes for each entity so we can clean them up on delete */
     #alternateKeys = new WeakMap();
+    #storesWithAlternateKeys = new WeakSet();
     constructor(defaultSchema) {
         this.#defaultSchema = defaultSchema;
     }
-    /** Stores an entity in the identity map under its primary key hash. */
+    /** Stores an entity in the identity map under its primary key hash and the `targetKey` values referencing it. */
     store(item) {
-        this.getStore(item.__meta.root).set(this.getPkHash(item), item);
+        const meta = item.__meta.root;
+        const wrapped = item.__helper;
+        // PK-less references (known only by a `targetKey`) would share one slot that outlives their later removal
+        if (!meta.targetKeys || wrapped.hasPrimaryKey()) {
+            this.getStore(meta).set(this.getPkHash(item), item);
+        }
+        // references resolved via `targetKey` look the entity up by that key instead of the PK
+        for (const key of meta.targetKeys ?? []) {
+            const value = item[key];
+            if (value != null) {
+                const schema = wrapped.__schema ?? meta.schema ?? this.#defaultSchema;
+                this.storeByKey(item, key, '' + value, schema);
+            }
+        }
     }
     /**
      * Stores an entity under an alternate key (non-PK property).
@@ -17,7 +31,9 @@ export class IdentityMap {
      */
     storeByKey(item, key, value, schema) {
         const hash = this.getKeyHash(key, value, schema);
-        this.getStore(item.__meta.root).set(hash, item);
+        const store = this.getStore(item.__meta.root);
+        store.set(hash, item);
+        this.#storesWithAlternateKeys.add(store);
         // Track this alternate key so we can clean it up when the entity is deleted
         let keys = this.#alternateKeys.get(item);
         if (!keys) {
@@ -35,7 +51,10 @@ export class IdentityMap {
         const altKeys = this.#alternateKeys.get(item);
         if (altKeys) {
             for (const hash of altKeys) {
-                store.delete(hash);
+                // the hash might be owned by another entity by now, e.g. after swapping unique values
+                if (store.get(hash) === item) {
+                    store.delete(hash);
+                }
             }
             this.#alternateKeys.delete(item);
         }
@@ -69,7 +88,7 @@ export class IdentityMap {
     values() {
         const ret = [];
         for (const store of this.#registry.values()) {
-            for (const item of store.values()) {
+            for (const item of this.getEntities(store)) {
                 ret.push(item);
             }
         }
@@ -77,11 +96,15 @@ export class IdentityMap {
     }
     *[Symbol.iterator]() {
         for (const store of this.#registry.values()) {
-            for (const item of store.values()) {
+            for (const item of this.getEntities(store)) {
                 yield item;
             }
         }
     }
+    getEntities(store) {
+        // an entity indexed by alternate keys occupies several slots of its store
+        return this.#storesWithAlternateKeys.has(store) ? new Set(store.values()) : store.values();
+    }
     /** Returns all hash keys currently in the identity map. */
     keys() {
         const ret = [];

package/unit-of-work/UnitOfWork.js

@@ -79,7 +79,7 @@ export class UnitOfWork {
      * @internal
      */
     normalizeEntityData(meta, data) {
-        const forceUndefined = this.#em.config.get('forceUndefined');
+        const forceUndefined = meta.forceUndefined ?? this.#em.config.get('forceUndefined');
         for (const key of Utils.keys(data)) {
             const prop = meta.properties[key];
             if (!prop) {
@@ -89,7 +89,10 @@ export class UnitOfWork {
                 Utils.isPlainObject(data[prop.name])) {
                 // Skip polymorphic relations - they use PolymorphicRef wrapper
                 if (!prop.polymorphic) {
-                    data[prop.name] = Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta, true);
+                    // with `targetKey`, the FK holds that value instead of the PK
+                    data[prop.name] = prop.targetKey
+                        ? data[prop.name][prop.targetKey]
+                        : Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta, true);
                 }
             }
             else if (prop.kind === ReferenceKind.EMBEDDED && !prop.object && Utils.isPlainObject(data[prop.name])) {
@@ -205,7 +208,18 @@ export class UnitOfWork {
             value = prop.customType.convertToJSValue(value, this.#platform, { mode: 'hydration' });
         }
         const hash = this.#identityMap.getKeyHash(key, '' + value, schema);
-        return this.#identityMap.getByHash(meta, hash);
+        const entity = this.#identityMap.getByHash(meta, hash);
+        // the entry is stale when the key changed via refresh or merge, unless only the unflushed value differs
+        if (entity && '' + entity[key] !== '' + value) {
+            // the snapshot holds the database value
+            const dbValue = prop?.customType
+                ? prop.customType.convertToDatabaseValue(value, this.#platform, { mode: 'serialization' })
+                : value;
+            if ('' + helper(entity).__originalEntityData?.[key] !== '' + dbValue) {
+                return undefined;
+            }
+        }
+        return entity;
     }
     /**
      * Stores an entity in the identity map under an alternate key (non-PK property).
@@ -368,6 +382,10 @@ export class UnitOfWork {
     }
     /** Marks an entity for removal, cascading to related entities. */
     remove(entity, visited, options = {}) {
+        // a reference known only by its `targetKey` has no PK, so the delete would match nothing
+        if (!helper(entity).__initialized && !helper(entity).hasPrimaryKey()) {
+            throw ValidationError.referenceWithoutPK(entity);
+        }
         // allow removing not managed entities if they are not part of the persist stack
         if (helper(entity).__managed || !this.#persistStack.has(entity)) {
             this.#removeStack.add(entity);
@@ -1118,6 +1136,11 @@ export class UnitOfWork {
         for (const changeSet of changeSets) {
             const wrapped = helper(changeSet.entity);
             wrapped.__originalEntityData = this.#comparator.prepareEntity(changeSet.entity);
+            // re-index so the entity is found by its new `targetKey` values instead of the old ones
+            if (changeSet.meta.root.targetKeys?.some(key => key in changeSet.payload)) {
+                this.#identityMap.delete(changeSet.entity);
+                this.#identityMap.store(changeSet.entity);
+            }
             if (!wrapped.__initialized) {
                 for (const prop of changeSet.meta.relations) {
                     if ([ReferenceKind.MANY_TO_MANY, ReferenceKind.ONE_TO_MANY].includes(prop.kind) &&

package/utils/EntityComparator.js

@@ -95,7 +95,7 @@ export class EntityComparator {
             lines.push(`  return entity${this.wrap(pk)};`);
         }
         const code = `// compiled pk getter for entity ${meta.className}\n` + `return function(entity) {\n${lines.join('\n')}\n}`;
-        const fnKey = `pkGetter-${meta.uniqueName}`;
+        const fnKey = `pkGetter-${meta.compiledName}`;
         const pkSerializer = Utils.createFunction(context, code, this.#config?.get('compiledFunctions'), fnKey);
         this.#pkGetters.set(meta, pkSerializer);
         return pkSerializer;
@@ -147,7 +147,7 @@ export class EntityComparator {
         }
         const code = `// compiled pk getter (with converted custom types) for entity ${meta.className}\n` +
             `return function(entity) {\n${lines.join('\n')}\n}`;
-        const fnKey = `pkGetterConverted-${meta.uniqueName}`;
+        const fnKey = `pkGetterConverted-${meta.compiledName}`;
         const pkSerializer = Utils.createFunction(context, code, this.#config?.get('compiledFunctions'), fnKey);
         this.#pkGettersConverted.set(meta, pkSerializer);
         return pkSerializer;
@@ -206,7 +206,7 @@ export class EntityComparator {
             }
         }
         const code = `// compiled pk serializer for entity ${meta.className}\n` + `return function(entity) {\n${lines.join('\n')}\n}`;
-        const fnKey = `pkSerializer-${meta.uniqueName}`;
+        const fnKey = `pkSerializer-${meta.compiledName}`;
         const pkSerializer = Utils.createFunction(context, code, this.#config?.get('compiledFunctions'), fnKey);
         this.#pkSerializers.set(meta, pkSerializer);
         return pkSerializer;
@@ -236,7 +236,7 @@ export class EntityComparator {
         })
             .forEach(prop => lines.push(this.getPropertySnapshot(meta, prop, context, this.wrap(prop.name), this.wrap(prop.name), [prop.name])));
         const code = `return function(entity) {\n  const ret = {};\n${lines.join('\n')}\n  return ret;\n}`;
-        const fnKey = `snapshotGenerator-${meta.uniqueName}`;
+        const fnKey = `snapshotGenerator-${meta.compiledName}`;
         const snapshotGenerator = Utils.createFunction(context, code, this.#config?.get('compiledFunctions'), fnKey);
         this.#snapshotGenerators.set(meta, snapshotGenerator);
         return snapshotGenerator;
@@ -350,14 +350,27 @@ export class EntityComparator {
                 if (prop.embedded && (meta.embeddable || meta.properties[prop.embedded[0]].object)) {
                     continue;
                 }
+                let defined = `typeof ${this.propName(prop.fieldNames[0])} !== 'undefined'`;
+                // STI subtypes with conflicting columns share the property, so another subtype's null column must not override it
+                if (prop.renamedFrom) {
+                    lines.push(`${padding}  ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
+                    defined = `${this.propName(prop.fieldNames[0])} != null`;
+                    // a column shared with a differently typed subtype is left for each subtype's hydrator to convert
+                    if (meta.props.some(p => p !== prop && p.name === prop.name && p.fieldNames?.[0] === prop.fieldNames[0])) {
+                        lines.push(`${padding}  if (${defined}) {`);
+                        lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])};`);
+                        lines.push(`${padding}  }`);
+                        continue;
+                    }
+                }
                 if (prop.runtimeType === 'boolean') {
-                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    lines.push(`${padding}  if (${defined}) {`);
                     lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])} == null ? ${this.propName(prop.fieldNames[0])} : !!${this.propName(prop.fieldNames[0])};`);
                     lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
                     lines.push(`${padding}  }`);
                 }
                 else if (prop.runtimeType === 'Date' && !this.#platform.isNumericProperty(prop)) {
-                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    lines.push(`${padding}  if (${defined}) {`);
                     context.set('parseDate', (value) => this.#platform.parseDate(value));
                     parseDate('ret' + this.wrap(prop.name), this.propName(prop.fieldNames[0]), padding);
                     lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
@@ -372,13 +385,13 @@ export class EntityComparator {
                         }
                         return item == null ? item : this.getResultMapper(prop.targetMeta)(item);
                     });
-                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    lines.push(`${padding}  if (${defined}) {`);
                     lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])} == null ? ${this.propName(prop.fieldNames[0])} : mapEmbeddedResult_${idx}(${this.propName(prop.fieldNames[0])});`);
                     lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
                     lines.push(`${padding}  }`);
                 }
                 else if (prop.kind !== ReferenceKind.EMBEDDED) {
-                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    lines.push(`${padding}  if (${defined}) {`);
                     lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])};`);
                     lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
                     lines.push(`${padding}  }`);
@@ -420,7 +433,7 @@ export class EntityComparator {
         lines.push(`  for (let k in result) { if (Object.hasOwn(result, k) && !mapped[k] && ret[k] === undefined${knownKeysGuard}) ret[k] = result[k]; }`);
         const code = `// compiled mapper for entity ${meta.className}\n` +
             `return function(result) {\n  const ret = {};\n${lines.join('\n')}\n  return ret;\n}`;
-        const fnKey = `resultMapper-${meta.uniqueName}`;
+        const fnKey = `resultMapper-${meta.compiledName}`;
         const resultMapper = Utils.createFunction(context, code, this.#config?.get('compiledFunctions'), fnKey);
         this.#mappers.set(meta, resultMapper);
         return resultMapper;
@@ -608,9 +621,24 @@ export class EntityComparator {
                 ret += `        if (discriminator !== undefined) break;\n`;
                 ret += `        __cls${level} = Object.getPrototypeOf(__cls${level});\n`;
                 ret += `      }\n`;
-                ret += `      const pk = val${level}?.__helper?.__identifier && !val${level}?.__helper?.hasPrimaryKey()\n`;
-                ret += `        ? val${level}.__helper.__identifier\n`;
-                ret += `        : toArray(val${level}?.__helper?.getPrimaryKey(true));\n`;
+                if (prop.targetKey) {
+                    // the FK holds the `targetKey` value in the format of the actual target's column
+                    const targetKey = prop.targetKey;
+                    const targetKeyValueKey = `targetKeyValue_${this.safeKey(prop.name)}`;
+                    context.set(targetKeyValueKey, (val) => {
+                        const customType = val.__meta.properties[targetKey]?.customType;
+                        const value = val[targetKey];
+                        return customType
+                            ? customType.convertToDatabaseValue(value, this.#platform, { mode: 'serialization' })
+                            : value;
+                    });
+                    ret += `      const pk = ${targetKeyValueKey}(val${level});\n`;
+                }
+                else {
+                    ret += `      const pk = val${level}?.__helper?.__identifier && !val${level}?.__helper?.hasPrimaryKey()\n`;
+                    ret += `        ? val${level}.__helper.__identifier\n`;
+                    ret += `        : toArray(val${level}?.__helper?.getPrimaryKey(true));\n`;
+                }
                 ret += `      ret${dataKey} = new PolymorphicRef(discriminator, pk);\n`;
                 ret += `    }\n`;
             }
@@ -624,8 +652,8 @@ export class EntityComparator {
                 ret += `    } else if (typeof entity${entityKey} !== 'undefined') {\n`;
                 ret += `      const val${level} = entity${entityKey}${unwrap};\n`;
                 if (targetProp?.customType) {
-                    // If targetKey property has a custom type, convert to database value
-                    const convertorKey = this.registerCustomType(targetProp, context);
+                    // keyed by the relation name to avoid clashing with a same-named owner prop, the relation itself lacks the custom type with an explicit `columnType`
+                    const convertorKey = this.registerCustomType({ ...prop, customType: targetProp.customType }, context);
                     ret += `      ret${dataKey} = convertToDatabaseValue_${convertorKey}(val${level}${targetAccess});\n`;
                 }
                 else {
@@ -688,7 +716,7 @@ export class EntityComparator {
         lines.push(`}`);
         const code = `// compiled comparator for entity ${meta.className}\n` +
             `return function(last, current, options) {\n  const diff = {};\n${lines.join('\n')}\n  return diff;\n}`;
-        const fnKey = `comparator-${meta.uniqueName}`;
+        const fnKey = `comparator-${meta.compiledName}`;
         const comparator = Utils.createFunction(context, code, this.#config?.get('compiledFunctions'), fnKey);
         this.#comparators.set(meta, comparator);
         return comparator;

package/utils/QueryHelper.d.ts

@@ -35,9 +35,35 @@ export declare class QueryHelper {
      */
     static liftGroupOperators<T extends object>(where: Dictionary, meta: EntityMetadata<T>, metadata: MetadataStorage, key?: string): string | undefined;
     static inlinePrimaryKeyObjects<T extends object>(where: Dictionary, meta: EntityMetadata<T>, metadata: MetadataStorage, key?: string): boolean;
+    /**
+     * A bare value on a polymorphic relation would be compared to the discriminator column, so PK values are turned
+     * into a PK condition instead, e.g. `1` becomes `{ id: 1 }` and `[{ id: 1 }, { id: 2 }]` becomes `{ id: { $in: [1, 2] } }`.
+     * Null checks and `[type, id]` tuples keep their meaning.
+     */
+    private static inlinePolymorphicPrimaryKeys;
     /** Copies the plain object and array structure of the condition, keeping the leaf values (e.g. entities) by reference. */
     private static cloneWhere;
     static processWhere<T extends object>(options: ProcessWhereOptions<T>): FilterQuery<T>;
+    /** @internal Splits a polymorphic target key like `imageable[Article]` into the property and target class names. */
+    static splitPolymorphicKey(key: string): [string, string?];
+    /** @internal Resolves the targets of a polymorphic target key like `imageable[Article]` or `imageable[Product,Article]`. */
+    static findTargetMetas(prop: EntityProperty | null | undefined, key: string): EntityMetadata[];
+    /** @internal Resolves the target entity of a condition key, including polymorphic target keys like `imageable[Article]`. */
+    static findTargetMeta(prop: EntityProperty | null | undefined, key: string): EntityMetadata | undefined;
+    /**
+     * Routes conditions on polymorphic to-one relations to the targets that define all the queried properties,
+     * e.g. `{ imageable: { title } }` becomes `{ 'imageable[Article]': { title } }`, or an `$or` of such keys
+     * when more targets match. The first target alone keeps the regular relation join.
+     */
+    private static splitPolymorphicConditions;
+    /**
+     * Routes ordering by properties of polymorphic to-one relations to the targets that define them, e.g.
+     * `{ imageable: { name: 'asc' } }` becomes `{ 'imageable[Product,Article]': { name: 'asc' } }`, ordered by
+     * the first non-null value. Nested relations and formulas are ordered via the first target defining them.
+     */
+    private static splitPolymorphicOrderBy;
+    /** Property names used in a condition, including those nested in group operators. */
+    private static collectConditionKeys;
     static getActiveFilters<T>(meta: EntityMetadata<T>, options: FilterOptions | undefined, filters: Dictionary<FilterDef>): FilterDef[];
     /** @internal Sentinel wrapping for arguments accessed while statically resolving an `rls` filter condition. */
     static readonly RLS_SENTINEL_PREFIX = "__mikro_rls_arg__";

package/utils/QueryHelper.js

@@ -4,7 +4,7 @@ import { ARRAY_OPERATORS, GroupOperator, JSON_KEY_OPERATORS, ReferenceKind } fro
 import { JsonType } from '../types/JsonType.js';
 import { helper } from '../entity/wrap.js';
 import { isRaw, Raw } from './RawQueryFragment.js';
-import { MetadataError } from '../errors.js';
+import { MetadataError, ValidationError } from '../errors.js';
 /** @internal */
 export class QueryHelper {
     static SUPPORTED_OPERATORS = ['>', '<', '<=', '>=', '!', '!='];
@@ -102,10 +102,7 @@ export class QueryHelper {
         for (const k of keys) {
             const value = where[k];
             const prop = meta.properties[k];
-            // Polymorphic relations use multiple columns (discriminator + FK), so they cannot
-            // participate in the standard single-column FK expansion. Query by discriminator
-            // column directly instead, e.g. { likeableType: 'post', likeableId: 1 }.
-            if (!prop || ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) || prop.polymorphic) {
+            if (!prop || ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
                 continue;
             }
             const op = this.liftGroupOperators(value, prop.targetMeta, metadata, k);
@@ -130,7 +127,7 @@ export class QueryHelper {
         if (Array.isArray(where)) {
             where.forEach((item, i) => {
                 if (this.inlinePrimaryKeyObjects(item, meta, metadata, key)) {
-                    where[i] = Utils.getPrimaryKeyValues(item, meta, false);
+                    where[i] = Utils.getPrimaryKeyValues(item, meta, true);
                 }
             });
         }
@@ -158,17 +155,21 @@ export class QueryHelper {
                     })));
         }
         Object.keys(where).forEach(k => {
-            const prop = meta.properties[k];
-            const meta2 = metadata.find(prop?.targetMeta?.class) || meta;
+            const prop = meta.properties[QueryHelper.splitPolymorphicKey(k)[0]];
+            const meta2 = metadata.find(QueryHelper.findTargetMeta(prop, k)?.class) || meta;
+            if (prop?.polymorphic) {
+                where[k] = this.inlinePolymorphicPrimaryKeys(where[k], meta2, prop);
+            }
             if (this.inlinePrimaryKeyObjects(where[k], meta2, metadata, k)) {
                 // Skip the PK collapse when an owning M:1/1:1 relation's FK column count does not match
                 // the target's PK column count (e.g. FK references target PK + an extra unique column).
                 // The criteria layer would otherwise emit a malformed predicate such as
                 // `(joinCol1, joinCol2) = scalar`. Limited to owning relations — `joinColumns` on the
                 // inverse side (1:m) describes the owning entity's FK columns, not the LHS tuple.
+                // Polymorphic relations are skipped too, a scalar would be compared to the discriminator column.
                 if (prop?.owner &&
                     [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
-                    prop.joinColumns.length !== meta2.primaryKeys.length) {
+                    (prop.polymorphic || prop.joinColumns.length !== meta2.primaryKeys.length)) {
                     return;
                 }
                 where[k] = Utils.getPrimaryKeyValues(where[k], meta2, true);
@@ -176,6 +177,37 @@ export class QueryHelper {
         });
         return false;
     }
+    /**
+     * A bare value on a polymorphic relation would be compared to the discriminator column, so PK values are turned
+     * into a PK condition instead, e.g. `1` becomes `{ id: 1 }` and `[{ id: 1 }, { id: 2 }]` becomes `{ id: { $in: [1, 2] } }`.
+     * Null checks and `[type, id]` tuples keep their meaning.
+     */
+    static inlinePolymorphicPrimaryKeys(value, meta, prop) {
+        const pk = meta.primaryKeys[0];
+        const isScalar = (v) => v != null && !Array.isArray(v) && Utils.isPrimaryKey(v);
+        const isPrimaryKeyObject = (v) => Utils.isPlainObject(v) && Utils.getObjectKeysSize(v) === 1 && pk in v;
+        // lists of plain values are how `[type, id]` tuples get normalized (`{ $in: [type, id] }`), so only PK objects are inlined
+        const isList = (v) => Array.isArray(v) && v.length > 0 && v.every(isPrimaryKeyObject);
+        let cond;
+        if (isScalar(value)) {
+            cond = value;
+        }
+        else if (isList(value)) {
+            cond = { $in: value.map(v => v[pk]) };
+        }
+        else if (Utils.isPlainObject(value) &&
+            Utils.hasObjectKeys(value) &&
+            Object.entries(value).every(([op, v]) => Utils.isOperator(op) && !(op in GroupOperator) && op !== '$not' && (isScalar(v) || isList(v)))) {
+            cond = Object.fromEntries(Object.entries(value).map(([op, v]) => [op, isList(v) ? v.map(i => i[pk]) : v]));
+        }
+        else {
+            return value;
+        }
+        if (meta.compositePK) {
+            throw new ValidationError(`Polymorphic relation ${prop.name} targets entities with a composite primary key, use PK objects or entity references in the condition instead.`);
+        }
+        return { [pk]: cond };
+    }
     /** Copies the plain object and array structure of the condition, keeping the leaf values (e.g. entities) by reference. */
     static cloneWhere(where) {
         if (Array.isArray(where)) {
@@ -230,6 +262,11 @@ export class QueryHelper {
         if (!Utils.isPlainObject(where)) {
             return where;
         }
+        if (meta) {
+            where = (options.type === 'orderBy'
+                ? QueryHelper.splitPolymorphicOrderBy(meta, where)
+                : QueryHelper.splitPolymorphicConditions(meta, where));
+        }
         return Utils.getObjectQueryKeys(where).reduce((o, key) => {
             let value = where[key];
             const customExpression = Raw.isKnownFragmentSymbol(key);
@@ -277,10 +314,11 @@ export class QueryHelper {
                 return o;
             }
             if (Utils.isPlainObject(value)) {
+                const targetMeta = customExpression ? undefined : QueryHelper.findTargetMeta(prop, key);
                 o[key] = QueryHelper.processWhere({
                     ...options,
                     where: value,
-                    entityName: prop?.targetMeta?.class ?? entityName,
+                    entityName: targetMeta?.class ?? entityName,
                     root: false,
                 });
             }
@@ -290,6 +328,95 @@ export class QueryHelper {
             return o;
         }, {});
     }
+    /** @internal Splits a polymorphic target key like `imageable[Article]` into the property and target class names. */
+    static splitPolymorphicKey(key) {
+        const match = /^(\w+)\[([\w,]+)]$/.exec(key);
+        return match ? [match[1], match[2]] : [key];
+    }
+    /** @internal Resolves the targets of a polymorphic target key like `imageable[Article]` or `imageable[Product,Article]`. */
+    static findTargetMetas(prop, key) {
+        const [, targetNames] = QueryHelper.splitPolymorphicKey(key);
+        const targets = targetNames?.split(',').map(name => prop?.polymorphTargets?.find(t => t.className === name));
+        return targets?.every(Boolean) ? targets : [];
+    }
+    /** @internal Resolves the target entity of a condition key, including polymorphic target keys like `imageable[Article]`. */
+    static findTargetMeta(prop, key) {
+        return QueryHelper.splitPolymorphicKey(key)[1] ? QueryHelper.findTargetMetas(prop, key)[0] : prop?.targetMeta;
+    }
+    /**
+     * Routes conditions on polymorphic to-one relations to the targets that define all the queried properties,
+     * e.g. `{ imageable: { title } }` becomes `{ 'imageable[Article]': { title } }`, or an `$or` of such keys
+     * when more targets match. The first target alone keeps the regular relation join.
+     */
+    static splitPolymorphicConditions(meta, payload) {
+        let ret = payload;
+        for (const key of Object.keys(payload)) {
+            const prop = meta.properties[key];
+            const value = payload[key];
+            if (!prop?.polymorphTargets ||
+                ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) ||
+                !Utils.isPlainObject(value)) {
+                continue;
+            }
+            const keys = this.collectConditionKeys(value);
+            const targets = prop.polymorphTargets.filter(target => keys.every(k => k in target.properties));
+            const primaryKeys = keys.every(k => targets.every(target => target.primaryKeys.includes(k)));
+            // PK conditions compare the FK columns without checking the type, so only when every target defines them
+            if (keys.length === 0 ||
+                targets.length === 0 ||
+                (primaryKeys && targets.length === prop.polymorphTargets.length) ||
+                (!primaryKeys && targets.length === 1 && targets[0] === prop.targetMeta)) {
+                continue;
+            }
+            const branches = targets.map(target => ({ [`${key}[${target.className}]`]: value }));
+            ret = { ...ret };
+            delete ret[key];
+            if (branches.length === 1) {
+                Object.assign(ret, branches[0]);
+            }
+            else {
+                ret.$and = [...(ret.$and ?? []), { $or: branches }];
+            }
+        }
+        return ret;
+    }
+    /**
+     * Routes ordering by properties of polymorphic to-one relations to the targets that define them, e.g.
+     * `{ imageable: { name: 'asc' } }` becomes `{ 'imageable[Product,Article]': { name: 'asc' } }`, ordered by
+     * the first non-null value. Nested relations and formulas are ordered via the first target defining them.
+     */
+    static splitPolymorphicOrderBy(meta, orderBy) {
+        const ret = {};
+        for (const key of Utils.getObjectQueryKeys(orderBy)) {
+            const prop = meta.properties[key];
+            const value = orderBy[key];
+            if (!prop?.polymorphTargets ||
+                ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) ||
+                !Utils.isPlainObject(value)) {
+                ret[key] = value;
+                continue;
+            }
+            for (const field of Utils.getObjectQueryKeys(value)) {
+                const found = prop.polymorphTargets.filter(target => field in target.properties);
+                const sharedPK = found.length === prop.polymorphTargets.length && found.every(target => target.primaryKeys.includes(field));
+                const single = Utils.isPlainObject(value[field]) || found.some(target => target.properties[field].formula);
+                const targets = found.length === 0 ? [prop.targetMeta] : single ? [found[0]] : found;
+                // shared PKs are ordered by the FK column without a join
+                const targetKey = sharedPK ? key : `${key}[${targets.map(target => target.className).join(',')}]`;
+                ret[targetKey] = { ...ret[targetKey], [field]: value[field] };
+            }
+        }
+        return ret;
+    }
+    /** Property names used in a condition, including those nested in group operators. */
+    static collectConditionKeys(payload) {
+        return Object.keys(payload).flatMap(k => {
+            if (k in GroupOperator || k === '$not') {
+                return Utils.asArray(payload[k]).flatMap(item => Utils.isPlainObject(item) ? this.collectConditionKeys(item) : []);
+            }
+            return Utils.isOperator(k) ? [] : [k];
+        });
+    }
     static getActiveFilters(meta, options, filters) {
         if (options === false) {
             return [];
@@ -450,7 +577,7 @@ export class QueryHelper {
     }
     static findProperty(fieldName, options) {
         const parts = fieldName.split('.');
-        const propName = parts.pop();
+        const propName = QueryHelper.splitPolymorphicKey(parts.pop())[0];
         const alias = parts.length > 0 ? parts.join('.') : undefined;
         const entityName = alias ? options.aliasMap?.[alias] : options.entityName;
         const meta = entityName ? options.metadata.find(entityName) : undefined;
@@ -494,6 +621,9 @@ export class QueryHelper {
             if (expanded !== w) {
                 where[k] = expanded;
             }
+            else if (Array.isArray(w)) {
+                where[k] = w.map(expandItem);
+            }
             else if (Utils.isPlainObject(w)) {
                 for (const op of Object.keys(w)) {
                     if (!Utils.isOperator(op, false)) {

package/utils/TransactionManager.js

@@ -189,6 +189,10 @@ export class TransactionManager {
                 if (wrapped.__originalEntityData) {
                     parentWrapped.__originalEntityData = originalEntityData;
                 }
+                // index a merged `targetKey` value, `getByKey` ignores the old one as stale
+                if (meta.root.targetKeys) {
+                    parentUoW.getIdentityMap().store(parentEntity);
+                }
             }
             else {
                 parentUoW.merge(entity, new Set([entity]));

package/utils/Utils.js

@@ -153,7 +153,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.3.0-dev.0';
+    static #ORM_VERSION = '7.3.0-dev.10';
     /** Default session variable name backing an RLS filter argument (`current_setting('mikro.<filter>.<arg>')`). */
     static getRlsSettingName(filterName, argName) {
         return `mikro.${filterName}.${argName}`;