@mikro-orm/core 7.0.0-dev.224 → 7.0.0-dev.226

package/EntityManager.js

@@ -325,8 +325,10 @@ export class EntityManager {
         return ret;
     }
     async getJoinedFilters(meta, options) {
+        // If user provided populateFilter, merge it with computed filters
+        const userFilter = options.populateFilter;
         if (!this.config.get('filtersOnRelations') || !options.populate) {
-            return undefined;
+            return userFilter;
         }
         const ret = {};
         for (const hint of options.populate) {
@@ -360,7 +362,11 @@ export class EntityManager {
                 }
             }
         }
-        return ret;
+        // Merge user-provided populateFilter with computed filters
+        if (userFilter) {
+            Utils.merge(ret, userFilter);
+        }
+        return Utils.hasObjectKeys(ret) ? ret : undefined;
     }
     /**
      * When filters are active on M:1 or 1:1 relations, we need to ref join them eagerly as they might affect the FK value.

package/cache/FileCacheAdapter.js

@@ -53,7 +53,15 @@ export class FileCacheAdapter {
     clear() {
         const path = this.path('*');
         const files = fs.glob(path);
-        files.forEach(file => unlinkSync(file));
+        for (const file of files) {
+            /* v8 ignore next */
+            try {
+                unlinkSync(file);
+            }
+            catch {
+                // ignore if file is already gone
+            }
+        }
         this.cache = {};
     }
     combine() {

package/drivers/DatabaseDriver.js

@@ -8,6 +8,7 @@ import { EntityManager } from '../EntityManager.js';
 import { CursorError, ValidationError } from '../errors.js';
 import { DriverException } from '../exceptions.js';
 import { helper } from '../entity/wrap.js';
+import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { JsonType } from '../types/JsonType.js';
 import { MikroORM } from '../MikroORM.js';
 export class DatabaseDriver {
@@ -260,6 +261,43 @@ export class DatabaseDriver {
                 }
                 return;
             }
+            // Handle polymorphic relations - convert tuple or PolymorphicRef to separate columns
+            // Tuple format: ['discriminator', id] or ['discriminator', id1, id2] for composite keys
+            // Must be checked BEFORE joinColumns array handling since polymorphic uses fieldNames (includes discriminator)
+            if (prop.polymorphic && prop.fieldNames && prop.fieldNames.length >= 2) {
+                let discriminator;
+                let ids;
+                if (Array.isArray(data[k]) && typeof data[k][0] === 'string' && prop.discriminatorMap?.[data[k][0]]) {
+                    // Tuple format: ['discriminator', ...ids]
+                    const [disc, ...rest] = data[k];
+                    discriminator = disc;
+                    ids = rest;
+                }
+                else if (data[k] instanceof PolymorphicRef) {
+                    // PolymorphicRef wrapper (internal use)
+                    discriminator = data[k].discriminator;
+                    const polyId = data[k].id;
+                    // Handle object-style composite key IDs like { tenantId: 1, orgId: 100 }
+                    if (polyId && typeof polyId === 'object' && !Array.isArray(polyId)) {
+                        const targetEntity = prop.discriminatorMap?.[discriminator];
+                        const targetMeta = this.metadata.get(targetEntity);
+                        ids = targetMeta.primaryKeys.map(pk => polyId[pk]);
+                    }
+                    else {
+                        ids = Utils.asArray(polyId);
+                    }
+                }
+                if (discriminator) {
+                    const discriminatorColumn = prop.fieldNames[0];
+                    const idColumns = prop.fieldNames.slice(1);
+                    delete data[k];
+                    data[discriminatorColumn] = discriminator;
+                    idColumns.forEach((col, idx) => {
+                        data[col] = ids[idx];
+                    });
+                    return;
+                }
+            }
             if (prop.joinColumns && Array.isArray(data[k])) {
                 const copy = Utils.flatten(data[k]);
                 delete data[k];

package/entity/EntityHelper.js

@@ -176,7 +176,19 @@ export class EntityHelper {
         });
     }
     static propagate(meta, entity, owner, prop, value, old) {
-        for (const prop2 of prop.targetMeta.bidirectionalRelations) {
+        // For polymorphic relations, get bidirectional relations from the actual entity's metadata
+        let bidirectionalRelations;
+        if (prop.polymorphic && prop.polymorphTargets?.length) {
+            // For polymorphic relations, we need to get the bidirectional relations from the actual value's metadata
+            if (!value) {
+                return; // No value means no propagation needed
+            }
+            bidirectionalRelations = helper(value).__meta.bidirectionalRelations;
+        }
+        else {
+            bidirectionalRelations = prop.targetMeta.bidirectionalRelations;
+        }
+        for (const prop2 of bidirectionalRelations) {
             if ((prop2.inversedBy || prop2.mappedBy) !== prop.name) {
                 continue;
             }

package/entity/EntityLoader.d.ts

@@ -43,6 +43,7 @@ export declare class EntityLoader {
      */
     private populateMany;
     private populateScalar;
+    private populatePolymorphic;
     private initializeCollections;
     private initializeOneToMany;
     private initializeManyToMany;

package/entity/EntityLoader.js

@@ -144,6 +144,9 @@ export class EntityLoader {
             const res = await this.findChildrenFromPivotTable(filtered, prop, options, innerOrderBy, populate, !!ref);
             return Utils.flatten(res);
         }
+        if (prop.polymorphic && prop.polymorphTargets) {
+            return this.populatePolymorphic(entities, prop, options, !!ref);
+        }
         const { items, partial } = await this.findChildren(options.filtered ?? entities, prop, populate, {
             ...options,
             where,
@@ -163,6 +166,64 @@ export class EntityLoader {
             populate: [],
         });
     }
+    async populatePolymorphic(entities, prop, options, ref) {
+        const ownerMeta = this.metadata.get(entities[0].constructor);
+        // Separate entities: those with loaded refs vs those needing FK load
+        const toPopulate = [];
+        const needsFkLoad = [];
+        for (const entity of entities) {
+            const refValue = entity[prop.name];
+            if (refValue && helper(refValue).hasPrimaryKey()) {
+                if ((ref && !options.refresh) || // :ref hint - already have reference
+                    (!ref && helper(refValue).__initialized && !options.refresh) // already loaded
+                ) {
+                    continue;
+                }
+                toPopulate.push(entity);
+            }
+            else if (refValue == null && !helper(entity).__loadedProperties.has(prop.name)) {
+                // FK columns weren't loaded (partial loading) — need to re-fetch them.
+                // If the property IS in __loadedProperties, the FK was loaded and is genuinely null.
+                needsFkLoad.push(entity);
+            }
+        }
+        // Load FK columns using populateScalar pattern
+        if (needsFkLoad.length > 0) {
+            await this.populateScalar(ownerMeta, needsFkLoad, {
+                ...options,
+                fields: [...ownerMeta.primaryKeys, prop.name],
+            });
+            // After loading FKs, add to toPopulate if not using :ref hint
+            if (!ref) {
+                for (const entity of needsFkLoad) {
+                    const refValue = entity[prop.name];
+                    if (refValue && helper(refValue).hasPrimaryKey()) {
+                        toPopulate.push(entity);
+                    }
+                }
+            }
+        }
+        if (toPopulate.length === 0) {
+            return [];
+        }
+        // Group references by target class for batch loading
+        const groups = new Map();
+        for (const entity of toPopulate) {
+            const refValue = Reference.unwrapReference(entity[prop.name]);
+            const discriminator = QueryHelper.findDiscriminatorValue(prop.discriminatorMap, helper(refValue).__meta.class);
+            const group = groups.get(discriminator) ?? [];
+            group.push(refValue);
+            groups.set(discriminator, group);
+        }
+        // Load each group concurrently - identity map handles merging with existing references
+        const allItems = [];
+        await Promise.all([...groups].map(async ([discriminator, children]) => {
+            const targetMeta = this.metadata.find(prop.discriminatorMap[discriminator]);
+            await this.populateScalar(targetMeta, children, options);
+            allItems.push(...children);
+        }));
+        return allItems;
+    }
     initializeCollections(filtered, prop, field, children, customOrder, partial) {
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
             this.initializeOneToMany(filtered, children, prop, field, partial);
@@ -215,8 +276,17 @@ export class EntityLoader {
         let fk = prop.targetKey ?? Utils.getPrimaryKeyHash(meta.primaryKeys);
         let schema = options.schema;
         const partial = !Utils.isEmpty(prop.where) || !Utils.isEmpty(options.where);
+        let polymorphicOwnerProp;
         if (prop.kind === ReferenceKind.ONE_TO_MANY || (prop.kind === ReferenceKind.MANY_TO_MANY && !prop.owner)) {
-            fk = meta.properties[prop.mappedBy].name;
+            const ownerProp = meta.properties[prop.mappedBy];
+            if (ownerProp.polymorphic && ownerProp.fieldNames.length >= 2) {
+                const idColumns = ownerProp.fieldNames.slice(1);
+                fk = idColumns.length === 1 ? idColumns[0] : idColumns;
+                polymorphicOwnerProp = ownerProp;
+            }
+            else {
+                fk = ownerProp.name;
+            }
         }
         if (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && !ref) {
             children.length = 0;
@@ -229,9 +299,24 @@ export class EntityLoader {
         if (!schema && [ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind)) {
             schema = children.find(e => e.__helper.__schema)?.__helper.__schema;
         }
-        // When targetKey is set, get the targetKey value instead of PK
         const ids = Utils.unique(children.map(e => prop.targetKey ? e[prop.targetKey] : e.__helper.getPrimaryKey()));
-        let where = this.mergePrimaryCondition(ids, fk, options, meta, this.metadata, this.driver.getPlatform());
+        let where;
+        if (polymorphicOwnerProp && Array.isArray(fk)) {
+            const conditions = ids.map(id => {
+                const pkValues = Object.values(id);
+                return Object.fromEntries(fk.map((col, idx) => [col, pkValues[idx]]));
+            });
+            where = (conditions.length === 1 ? conditions[0] : { $or: conditions });
+        }
+        else {
+            where = this.mergePrimaryCondition(ids, fk, options, meta, this.metadata, this.driver.getPlatform());
+        }
+        if (polymorphicOwnerProp) {
+            const parentMeta = this.metadata.find(entities[0].constructor);
+            const discriminatorValue = QueryHelper.findDiscriminatorValue(polymorphicOwnerProp.discriminatorMap, parentMeta.class) ?? parentMeta.tableName;
+            const discriminatorColumn = polymorphicOwnerProp.fieldNames[0];
+            where = { $and: [where, { [discriminatorColumn]: discriminatorValue }] };
+        }
         const fields = this.buildFields(options.fields, prop, ref);
         /* eslint-disable prefer-const */
         let { refresh, filters, convertCustomTypes, lockMode, strategy, populateWhere = 'infer', connectionType, logging, } = options;
@@ -362,30 +447,42 @@ export class EntityLoader {
         for (const entity of entities) {
             visited.add(entity);
         }
-        // skip lazy scalar properties
         if (!prop.targetMeta) {
             return;
         }
-        await this.populate(prop.targetMeta.class, unique, populate.children ?? populate.all, {
-            where: await this.extractChildCondition(options, prop, false),
-            orderBy: innerOrderBy,
-            fields,
-            exclude,
-            validate: false,
-            lookup: false,
-            filters,
-            ignoreLazyScalarProperties,
-            populateWhere,
-            connectionType,
-            logging,
-            schema,
-            // @ts-ignore not a public option, will be propagated to the populate call
-            refresh: refresh && !filtered.every(item => options.visited.has(item)),
-            // @ts-ignore not a public option, will be propagated to the populate call
-            visited: options.visited,
-            // @ts-ignore not a public option
-            filtered,
-        });
+        const populateChildren = async (targetMeta, items) => {
+            await this.populate(targetMeta.class, items, populate.children ?? populate.all, {
+                where: await this.extractChildCondition(options, prop, false),
+                orderBy: innerOrderBy,
+                fields,
+                exclude,
+                validate: false,
+                lookup: false,
+                filters,
+                ignoreLazyScalarProperties,
+                populateWhere,
+                connectionType,
+                logging,
+                schema,
+                // @ts-ignore not a public option, will be propagated to the populate call
+                refresh: refresh && !filtered.every(item => options.visited.has(item)),
+                // @ts-ignore not a public option, will be propagated to the populate call
+                visited: options.visited,
+                // @ts-ignore not a public option
+                filtered,
+            });
+        };
+        if (prop.polymorphic && prop.polymorphTargets) {
+            await Promise.all(prop.polymorphTargets.map(async (targetMeta) => {
+                const targetChildren = unique.filter(child => helper(child).__meta.className === targetMeta.className);
+                if (targetChildren.length > 0) {
+                    await populateChildren(targetMeta, targetChildren);
+                }
+            }));
+        }
+        else {
+            await populateChildren(prop.targetMeta, unique);
+        }
     }
     /** @internal */
     async findChildrenFromPivotTable(filtered, prop, options, orderBy, populate, pivotJoin) {
@@ -394,7 +491,8 @@ export class EntityLoader {
         let where = await this.extractChildCondition(options, prop, true);
         const fields = this.buildFields(options.fields, prop);
         const exclude = Array.isArray(options.exclude) ? Utils.extractChildElements(options.exclude, prop.name) : options.exclude;
-        const options2 = { ...options, fields, exclude };
+        const populateFilter = options.populateFilter?.[prop.name];
+        const options2 = { ...options, fields, exclude, populateFilter };
         ['limit', 'offset', 'first', 'last', 'before', 'after', 'overfetch'].forEach(prop => delete options2[prop]);
         options2.populate = (populate?.children ?? []);
         if (prop.customType) {

package/entity/PolymorphicRef.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wrapper class for polymorphic relation reference data.
+ * Holds the discriminator value (type identifier) and the primary key value(s).
+ * Used internally to track polymorphic FK values before hydration.
+ */
+export declare class PolymorphicRef {
+    readonly discriminator: string;
+    id: unknown;
+    constructor(discriminator: string, id: unknown);
+    /** Returns `[discriminator, ...idValues]` tuple suitable for column-level expansion. */
+    toTuple(): unknown[];
+}

package/entity/PolymorphicRef.js

@@ -0,0 +1,18 @@
+import { Utils } from '../utils/Utils.js';
+/**
+ * Wrapper class for polymorphic relation reference data.
+ * Holds the discriminator value (type identifier) and the primary key value(s).
+ * Used internally to track polymorphic FK values before hydration.
+ */
+export class PolymorphicRef {
+    discriminator;
+    id;
+    constructor(discriminator, id) {
+        this.discriminator = discriminator;
+        this.id = id;
+    }
+    /** Returns `[discriminator, ...idValues]` tuple suitable for column-level expansion. */
+    toTuple() {
+        return [this.discriminator, ...Utils.asArray(this.id)];
+    }
+}

package/entity/defineEntity.d.ts

@@ -312,6 +312,10 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     owner<T extends boolean = true>(owner?: T): Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'owner'> & {
         owner: T;
     }, IncludeKeys>, IncludeKeys>;
+    /** For polymorphic relations. Specifies the property name that stores the entity type discriminator. Defaults to the property name. */
+    discriminator(discriminator: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    /** For polymorphic relations. Custom mapping of discriminator values to entity class names. */
+    discriminatorMap(discriminatorMap: Dictionary<string>): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Point to the inverse side property name. */
     inversedBy(inversedBy: keyof Value | ((e: Value) => any)): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Point to the owning side property name. */
@@ -390,11 +394,11 @@ declare const propertyBuilders: {
     manyToMany: <Target extends EntityTarget>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target>, EmptyOptions & {
         kind: "m:n";
     }, IncludeKeysForManyToManyOptions>;
-    manyToOne: <Target extends EntityTarget>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target>, EmptyOptions & {
+    manyToOne: <Target extends EntityTarget | EntityTarget[]>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target extends (infer T)[] ? T : Target>, EmptyOptions & {
         kind: "m:1";
     }, IncludeKeysForManyToOneOptions>;
     oneToMany: <Target extends EntityTarget>(target: Target) => OneToManyOptionsBuilderOnlyMappedBy<InferEntity<Target>>;
-    oneToOne: <Target extends EntityTarget>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target>, EmptyOptions & {
+    oneToOne: <Target extends EntityTarget | EntityTarget[]>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target extends (infer T)[] ? T : Target>, EmptyOptions & {
         kind: "1:1";
     }, IncludeKeysForOneToOneOptions>;
     date: () => UniversalPropertyOptionsBuilder<string, EmptyOptions, IncludeKeysForProperty>;
@@ -468,11 +472,11 @@ export declare namespace defineEntity {
         manyToMany: <Target extends EntityTarget>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target>, EmptyOptions & {
             kind: "m:n";
         }, IncludeKeysForManyToManyOptions>;
-        manyToOne: <Target extends EntityTarget>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target>, EmptyOptions & {
+        manyToOne: <Target extends EntityTarget | EntityTarget[]>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target extends (infer T)[] ? T : Target>, EmptyOptions & {
             kind: "m:1";
         }, IncludeKeysForManyToOneOptions>;
         oneToMany: <Target extends EntityTarget>(target: Target) => OneToManyOptionsBuilderOnlyMappedBy<InferEntity<Target>>;
-        oneToOne: <Target extends EntityTarget>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target>, EmptyOptions & {
+        oneToOne: <Target extends EntityTarget | EntityTarget[]>(target: Target) => UniversalPropertyOptionsBuilder<InferEntity<Target extends (infer T)[] ? T : Target>, EmptyOptions & {
             kind: "1:1";
         }, IncludeKeysForOneToOneOptions>;
         date: () => UniversalPropertyOptionsBuilder<string, EmptyOptions, IncludeKeysForProperty>;

package/entity/defineEntity.js

@@ -353,6 +353,14 @@ export class UniversalPropertyOptionsBuilder {
     owner(owner = true) {
         return this.assignOptions({ owner });
     }
+    /** For polymorphic relations. Specifies the property name that stores the entity type discriminator. Defaults to the property name. */
+    discriminator(discriminator) {
+        return this.assignOptions({ discriminator });
+    }
+    /** For polymorphic relations. Custom mapping of discriminator values to entity class names. */
+    discriminatorMap(discriminatorMap) {
+        return this.assignOptions({ discriminatorMap });
+    }
     /** Point to the inverse side property name. */
     inversedBy(inversedBy) {
         return this.assignOptions({ inversedBy });

package/entity/index.d.ts

@@ -1,5 +1,6 @@
 export * from './EntityRepository.js';
 export * from './EntityIdentifier.js';
+export * from './PolymorphicRef.js';
 export * from './EntityAssigner.js';
 export * from './EntityHelper.js';
 export * from './EntityFactory.js';

package/entity/index.js

@@ -1,5 +1,6 @@
 export * from './EntityRepository.js';
 export * from './EntityIdentifier.js';
+export * from './PolymorphicRef.js';
 export * from './EntityAssigner.js';
 export * from './EntityHelper.js';
 export * from './EntityFactory.js';

package/errors.d.ts

@@ -63,8 +63,9 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static propertyTargetsEntityType(meta: EntityMetadata, prop: EntityProperty, target: EntityMetadata): MetadataError<Partial<any>>;
     static fromMissingOption(meta: EntityMetadata, prop: EntityProperty, option: string): MetadataError<Partial<any>>;
     static targetKeyOnManyToMany(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
-    static targetKeyNotUnique(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
-    static targetKeyNotFound(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
+    static targetKeyNotUnique(meta: EntityMetadata, prop: EntityProperty, target?: EntityMetadata): MetadataError<Partial<any>>;
+    static targetKeyNotFound(meta: EntityMetadata, prop: EntityProperty, target?: EntityMetadata): MetadataError<Partial<any>>;
+    static incompatiblePolymorphicTargets(meta: EntityMetadata, prop: EntityProperty, target1: EntityMetadata, target2: EntityMetadata, reason: string): MetadataError<Partial<any>>;
     static dangerousPropertyName(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
     static viewEntityWithoutExpression(meta: EntityMetadata): MetadataError;
     private static fromMessage;

package/errors.js

@@ -216,11 +216,16 @@ export class MetadataError extends ValidationError {
     static targetKeyOnManyToMany(meta, prop) {
         return this.fromMessage(meta, prop, `uses 'targetKey' option which is not supported for ManyToMany relations`);
     }
-    static targetKeyNotUnique(meta, prop) {
-        return this.fromMessage(meta, prop, `has 'targetKey' set to '${prop.targetKey}', but ${prop.type}.${prop.targetKey} is not marked as unique. The target property must have a unique constraint.`);
+    static targetKeyNotUnique(meta, prop, target) {
+        const targetName = target?.className ?? prop.type;
+        return this.fromMessage(meta, prop, `has 'targetKey' set to '${prop.targetKey}', but ${targetName}.${prop.targetKey} is not marked as unique`);
     }
-    static targetKeyNotFound(meta, prop) {
-        return this.fromMessage(meta, prop, `has 'targetKey' set to '${prop.targetKey}', but ${prop.type}.${prop.targetKey} does not exist`);
+    static targetKeyNotFound(meta, prop, target) {
+        const targetName = target?.className ?? prop.type;
+        return this.fromMessage(meta, prop, `has 'targetKey' set to '${prop.targetKey}', but ${targetName}.${prop.targetKey} does not exist`);
+    }
+    static incompatiblePolymorphicTargets(meta, prop, target1, target2, reason) {
+        return this.fromMessage(meta, prop, `has incompatible polymorphic targets ${target1.className} and ${target2.className}: ${reason}`);
     }
     static dangerousPropertyName(meta, prop) {
         return this.fromMessage(meta, prop, `uses a dangerous property name '${prop.name}' which could lead to prototype pollution. Please use a different property name.`);

package/hydration/ObjectHydrator.js

@@ -1,9 +1,11 @@
 import { Hydrator } from './Hydrator.js';
 import { Collection } from '../entity/Collection.js';
 import { Reference, ScalarReference } from '../entity/Reference.js';
+import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { parseJsonSafe, Utils } from '../utils/Utils.js';
 import { ReferenceKind } from '../enums.js';
 import { Raw } from '../utils/RawQueryFragment.js';
+import { ValidationError } from '../errors.js';
 export class ObjectHydrator extends Hydrator {
     hydrators = {
         'full~true': new Map(),
@@ -49,6 +51,8 @@ export class ObjectHydrator extends Hydrator {
         context.set('isPrimaryKey', Utils.isPrimaryKey);
         context.set('Collection', Collection);
         context.set('Reference', Reference);
+        context.set('PolymorphicRef', PolymorphicRef);
+        context.set('ValidationError', ValidationError);
         const registerCustomType = (prop, convertorKey, method, context) => {
             context.set(`${method}_${convertorKey}`, (val) => {
                 /* v8 ignore next */
@@ -134,23 +138,51 @@ export class ObjectHydrator extends Hydrator {
             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') {`);
-            ret.push(`    if (isPrimaryKey(data${dataKey}, true)) {`);
-            const targetKey = this.safeKey(`${prop.targetMeta.tableName}_${this.tmpIndex++}`);
-            context.set(targetKey, prop.targetMeta.class);
+            // For polymorphic: instanceof check; for regular: isPrimaryKey() check
+            const pkCheck = prop.polymorphic ? `data${dataKey} instanceof PolymorphicRef` : `isPrimaryKey(data${dataKey}, true)`;
+            ret.push(`    if (${pkCheck}) {`);
             // When targetKey is set, pass the key option to createReference so it uses the alternate key
             const keyOption = prop.targetKey ? `, key: '${prop.targetKey}'` : '';
-            if (prop.ref) {
-                ret.push(`      entity${entityKey} = Reference.create(factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} }));`);
+            if (prop.polymorphic) {
+                // For polymorphic: target class from discriminator map, PK from data.id
+                const discriminatorMapKey = this.safeKey(`discriminatorMap_${prop.name}_${this.tmpIndex++}`);
+                context.set(discriminatorMapKey, prop.discriminatorMap);
+                ret.push(`      const targetClass = ${discriminatorMapKey}[data${dataKey}.discriminator];`);
+                ret.push(`      if (!targetClass) throw new ValidationError(\`Unknown discriminator value '\${data${dataKey}.discriminator}' for polymorphic relation '${prop.name}'. Valid values: \${Object.keys(${discriminatorMapKey}).join(', ')}\`);`);
+                if (prop.ref) {
+                    ret.push(`      entity${entityKey} = Reference.create(factory.createReference(targetClass, data${dataKey}.id, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} }));`);
+                }
+                else {
+                    ret.push(`      entity${entityKey} = factory.createReference(targetClass, data${dataKey}.id, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} });`);
+                }
             }
             else {
-                ret.push(`      entity${entityKey} = factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} });`);
+                // For regular: fixed target class, PK is the data itself
+                const targetKey = this.safeKey(`${prop.targetMeta.tableName}_${this.tmpIndex++}`);
+                context.set(targetKey, prop.targetMeta.class);
+                if (prop.ref) {
+                    ret.push(`      entity${entityKey} = Reference.create(factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} }));`);
+                }
+                else {
+                    ret.push(`      entity${entityKey} = factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} });`);
+                }
             }
             ret.push(`    } else if (data${dataKey} && typeof data${dataKey} === 'object') {`);
+            // For full entity hydration, polymorphic needs to determine target class from entity itself
+            let hydrateTargetExpr;
+            if (prop.polymorphic) {
+                hydrateTargetExpr = `data${dataKey}.constructor`;
+            }
+            else {
+                const targetKey = this.safeKey(`${prop.targetMeta.tableName}_${this.tmpIndex++}`);
+                context.set(targetKey, prop.targetMeta.class);
+                hydrateTargetExpr = targetKey;
+            }
             if (prop.ref) {
-                ret.push(`      entity${entityKey} = Reference.create(factory.${method}(${targetKey}, data${dataKey}, { initialized: true, merge: true, newEntity, convertCustomTypes, normalizeAccessors, schema }));`);
+                ret.push(`      entity${entityKey} = Reference.create(factory.${method}(${hydrateTargetExpr}, data${dataKey}, { initialized: true, merge: true, newEntity, convertCustomTypes, normalizeAccessors, schema }));`);
             }
             else {
-                ret.push(`      entity${entityKey} = factory.${method}(${targetKey}, data${dataKey}, { initialized: true, merge: true, newEntity, convertCustomTypes, normalizeAccessors, schema });`);
+                ret.push(`      entity${entityKey} = factory.${method}(${hydrateTargetExpr}, data${dataKey}, { initialized: true, merge: true, newEntity, convertCustomTypes, normalizeAccessors, schema });`);
             }
             ret.push(`    }`);
             ret.push(`  }`);

package/metadata/EntitySchema.d.ts

@@ -7,7 +7,7 @@ type TypeType = string | NumberConstructor | StringConstructor | BooleanConstruc
 type TypeDef<Target> = {
     type: TypeType;
 } | {
-    entity: () => EntityName<Target>;
+    entity: () => EntityName<Target> | EntityName[];
 };
 type EmbeddedTypeDef<Target> = {
     type: TypeType;

package/metadata/MetadataDiscovery.d.ts

@@ -42,11 +42,33 @@ export declare class MetadataDiscovery {
     private initFactoryField;
     private ensureCorrectFKOrderInPivotEntity;
     private definePivotTableEntity;
+    /**
+     * Create a scalar property for a pivot table column.
+     */
+    private createPivotScalarProperty;
+    /**
+     * Get column types for an entity's primary keys, initializing them if needed.
+     */
+    private getPrimaryKeyColumnTypes;
+    /**
+     * Add missing FK columns for a polymorphic entity to an existing pivot table.
+     */
+    private addPolymorphicPivotColumns;
+    /**
+     * Define properties for a polymorphic pivot table.
+     */
+    private definePolymorphicPivotProperties;
+    /**
+     * Create a virtual M:1 relation from pivot to a polymorphic owner entity.
+     * This enables single-query join loading for inverse-side polymorphic M:N.
+     */
+    private definePolymorphicOwnerRelation;
     private defineFixedOrderProperty;
     private definePivotProperty;
     private autoWireBidirectionalProperties;
     private defineBaseEntityProperties;
     private initPolyEmbeddables;
+    private initPolymorphicRelation;
     private initEmbeddables;
     private initSingleTableInheritance;
     private createDiscriminatorProperty;