@mikro-orm/core 7.0.0-dev.99 → 7.0.0-rc.1

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 { RawQueryFragment } from '../utils/RawQueryFragment.js';
+import { Raw } from '../utils/RawQueryFragment.js';
+import { ValidationError } from '../errors.js';
 export class ObjectHydrator extends Hydrator {
     hydrators = {
         'full~true': new Map(),
@@ -39,7 +41,7 @@ export class ObjectHydrator extends Hydrator {
      */
     getEntityHydrator(meta, type, normalizeAccessors = false) {
         const key = `${type}~${normalizeAccessors}`;
-        const exists = this.hydrators[key].get(meta.className);
+        const exists = this.hydrators[key].get(meta.class);
         if (exists) {
             return exists;
         }
@@ -49,17 +51,19 @@ 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 */
-                if (RawQueryFragment.isKnownFragment(val)) {
+                if (Raw.isKnownFragment(val)) {
                     return val;
                 }
                 return prop.customType[method](val, this.platform, { mode: 'serialization' });
             });
             return convertorKey;
         };
-        const hydrateScalar = (prop, object, path, dataKey) => {
+        const hydrateScalar = (prop, path, dataKey) => {
             const entityKey = path.map(k => this.wrap(k)).join('');
             const tz = this.platform.getTimezone();
             const convertorKey = path.filter(k => !k.match(/\[idx_\d+]/)).map(k => this.safeKey(k)).join('_');
@@ -134,24 +138,56 @@ 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)) {`);
-            if (prop.ref) {
-                ret.push(`      entity${entityKey} = Reference.create(factory.createReference('${prop.type}', data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema }));`);
+            // 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.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('${prop.type}', data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema });`);
+                // 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}('${prop.type}', 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}('${prop.type}', 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(`  }`);
             if (prop.kind === ReferenceKind.ONE_TO_ONE) {
-                const meta2 = this.metadata.get(prop.type);
+                const meta2 = this.metadata.get(prop.targetMeta.class);
                 const prop2 = meta2.properties[prop.inversedBy || prop.mappedBy];
                 if (prop2 && !prop2.mapToPk) {
                     ret.push(`  if (data${dataKey} && entity${entityKey} && !entity${entityKey}.${this.safeKey(prop2.name)}) {`);
@@ -169,7 +205,7 @@ export class ObjectHydrator extends Hydrator {
         };
         const hydrateToMany = (prop, dataKey, entityKey) => {
             const ret = [];
-            ret.push(...this.createCollectionItemMapper(prop));
+            ret.push(...this.createCollectionItemMapper(prop, context));
             ret.push(`  if (data${dataKey} && !Array.isArray(data${dataKey}) && typeof data${dataKey} === 'object') {`);
             ret.push(`    data${dataKey} = [data${dataKey}];`);
             ret.push(`  }`);
@@ -252,10 +288,11 @@ export class ObjectHydrator extends Hydrator {
                 prop.targetMeta.polymorphs.forEach(childMeta => {
                     const childProp = prop.embeddedProps[prop.targetMeta.discriminatorColumn];
                     const childDataKey = prop.object ? dataKey + this.wrap(childProp.embedded[1]) : this.wrap(childProp.name);
+                    context.set(childMeta.className, childMeta.class);
                     // weak comparison as we can have numbers that might have been converted to strings due to being object keys
                     ret.push(`    if (data${childDataKey} == '${childMeta.discriminatorValue}') {`);
                     ret.push(`      if (entity${entityKey} == null) {`);
-                    ret.push(`        entity${entityKey} = factory.createEmbeddable('${childMeta.className}', embeddedData, { newEntity, convertCustomTypes, normalizeAccessors });`);
+                    ret.push(`        entity${entityKey} = factory.createEmbeddable(${childMeta.className}, embeddedData, { newEntity, convertCustomTypes, normalizeAccessors });`);
                     ret.push(`      }`);
                     meta.props
                         .filter(p => p.embedded?.[0] === prop.name)
@@ -275,8 +312,10 @@ export class ObjectHydrator extends Hydrator {
                 });
             }
             else {
+                const targetKey = this.safeKey(`${prop.targetMeta.tableName}_${this.tmpIndex++}`);
+                context.set(targetKey, prop.targetMeta.class);
                 ret.push(`    if (entity${entityKey} == null) {`);
-                ret.push(`      entity${entityKey} = factory.createEmbeddable('${prop.targetMeta.className}', embeddedData, { newEntity, convertCustomTypes, normalizeAccessors });`);
+                ret.push(`      entity${entityKey} = factory.createEmbeddable(${targetKey}, embeddedData, { newEntity, convertCustomTypes, normalizeAccessors });`);
                 ret.push(`    }`);
                 meta.props
                     .filter(p => p.embedded?.[0] === prop.name)
@@ -334,7 +373,7 @@ export class ObjectHydrator extends Hydrator {
                 }
             }
             else { // ReferenceKind.SCALAR
-                ret.push(...hydrateScalar(prop, object, path, dataKey));
+                ret.push(...hydrateScalar(prop, path, dataKey));
             }
             if (this.config.get('forceUndefined')) {
                 ret.push(`  if (data${dataKey} === null) entity${entityKey} = undefined;`);
@@ -347,12 +386,13 @@ 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 hydrator = Utils.createFunction(context, code);
-        this.hydrators[key].set(meta.className, hydrator);
+        const fnKey = `hydrator-${meta.uniqueName}-${type}-${normalizeAccessors}`;
+        const hydrator = Utils.createFunction(context, code, this.config.get('compiledFunctions'), fnKey);
+        this.hydrators[key].set(meta.class, hydrator);
         return hydrator;
     }
-    createCollectionItemMapper(prop) {
-        const meta = this.metadata.get(prop.type);
+    createCollectionItemMapper(prop, context) {
+        const meta = this.metadata.get(prop.targetMeta.class);
         const lines = [];
         lines.push(`  const createCollectionItem_${this.safeKey(prop.name)} = (value, entity) => {`);
         const prop2 = prop.targetMeta.properties[prop.mappedBy];
@@ -361,9 +401,11 @@ export class ObjectHydrator extends Hydrator {
             lines.push(`      value = { ...value, ['${prop2.name}']: Reference.wrapReference(entity, { ref: ${prop2.ref} }) };`);
             lines.push(`    }`);
         }
-        lines.push(`    if (isPrimaryKey(value, ${meta.compositePK})) return factory.createReference('${prop.type}', value, { convertCustomTypes, schema, normalizeAccessors, merge: true });`);
+        const targetKey = this.safeKey(`${prop.targetMeta.tableName}_${this.tmpIndex++}`);
+        context.set(targetKey, prop.targetMeta.class);
+        lines.push(`    if (isPrimaryKey(value, ${meta.compositePK})) return factory.createReference(${targetKey}, value, { convertCustomTypes, schema, normalizeAccessors, merge: true });`);
         lines.push(`    if (value && value.__entity) return value;`);
-        lines.push(`    return factory.create('${prop.type}', value, { newEntity, convertCustomTypes, schema, normalizeAccessors, merge: true });`);
+        lines.push(`    return factory.create(${targetKey}, value, { newEntity, convertCustomTypes, schema, normalizeAccessors, merge: true });`);
         lines.push(`  }`);
         return lines;
     }

package/index.d.ts

@@ -3,7 +3,7 @@
  * @module core
  */
 export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config } from './typings.js';
-export type { Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, EntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, QBFilterQuery, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, MigrationDiff, GenerateOptions, FilterObject, IEntityGenerator, ISeedManager, RequiredEntityData, CheckCallback, IndexCallback, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, UmzugMigration, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, NoInfer, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, GeneratedColumnCallback, FilterDef, } from './typings.js';
+export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, EntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, MigrationDiff, GenerateOptions, FilterObject, IEntityGenerator, ISeedManager, RequiredEntityData, CheckCallback, IndexCallback, FormulaCallback, FormulaTable, SchemaTable, SchemaColumns, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, UmzugMigration, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
 export * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';

package/logging/colors.d.ts

@@ -5,5 +5,5 @@ export declare const colors: {
     yellow: (text: string) => string;
     grey: (text: string) => string;
     cyan: (text: string) => string;
-    enabled: () => boolean | "" | undefined;
+    enabled: () => boolean;
 };

package/logging/colors.js

@@ -1,9 +1,10 @@
-const bool = (v) => v && ['true', 't', '1'].includes(v.toLowerCase());
-const boolIfDefined = (v) => v != null ? bool(v) : true;
-const enabled = () => !bool(process.env.NO_COLOR)
-    && !bool(process.env.MIKRO_ORM_NO_COLOR)
-    && boolIfDefined(process.env.FORCE_COLOR)
-    && boolIfDefined(process.env.MIKRO_ORM_COLORS);
+import { getEnv } from '../utils/env-vars.js';
+const bool = (k) => ['true', 't', '1'].includes(getEnv(k)?.toLowerCase() ?? '');
+const boolIfDefined = (k) => getEnv(k) != null ? bool(k) : true;
+const enabled = () => !bool('NO_COLOR')
+    && !bool('MIKRO_ORM_NO_COLOR')
+    && boolIfDefined('FORCE_COLOR')
+    && boolIfDefined('MIKRO_ORM_COLORS');
 const wrap = (fn) => (text) => enabled() ? fn(text) : text;
 /** @internal */
 export const colors = {

package/logging/inspect.js

@@ -1,12 +1,7 @@
 let nodeInspect;
 /** @internal */
 export function inspect(value, options) {
-    if (nodeInspect === undefined) {
-        /* v8 ignore else */
-        if (globalThis.process?.getBuiltinModule) {
-            nodeInspect = globalThis.process.getBuiltinModule('node:util').inspect;
-        }
-    }
+    nodeInspect ??= globalThis.process?.getBuiltinModule?.('node:util').inspect;
     /* v8 ignore else */
     if (nodeInspect) {
         return nodeInspect(value, options);

package/metadata/EntitySchema.d.ts

@@ -1,17 +1,18 @@
-import { EntityMetadata, type AnyEntity, type EntityKey, type Constructor, type DeepPartial, type EntityName, type EntityProperty, type CleanKeys, type ExpandProperty, type IsNever, type EntityClass } from '../typings.js';
-import { ReferenceKind } from '../enums.js';
+import { EntityMetadata, type AnyEntity, type EntityKey, type Constructor, type DeepPartial, type EntityName, type EntityProperty, type CleanKeys, type ExpandProperty, type IsNever, type EntityCtor } from '../typings.js';
+import { type EventType, ReferenceKind } from '../enums.js';
+import type { EventSubscriber } from '../events/EventSubscriber.js';
 import { Type } from '../types/Type.js';
 import type { PropertyOptions, ManyToOneOptions, OneToOneOptions, OneToManyOptions, ManyToManyOptions, EmbeddedOptions, EnumOptions, PrimaryKeyOptions, SerializedPrimaryKeyOptions, IndexOptions, UniqueOptions } from './types.js';
 type TypeType = string | NumberConstructor | StringConstructor | BooleanConstructor | DateConstructor | ArrayConstructor | Constructor<Type<any>> | Type<any>;
 type TypeDef<Target> = {
     type: TypeType;
 } | {
-    entity: string | (() => string | EntityName<Target>);
+    entity: () => EntityName<Target> | EntityName[];
 };
 type EmbeddedTypeDef<Target> = {
     type: TypeType;
 } | {
-    entity: string | (() => string | EntityName<Target> | EntityName<Target>[]);
+    entity: () => EntityName<Target> | EntityName[];
 };
 export type EntitySchemaProperty<Target, Owner> = ({
     kind: ReferenceKind.MANY_TO_ONE | 'm:1';
@@ -27,10 +28,10 @@ export type EntitySchemaProperty<Target, Owner> = ({
     enum: true;
 } & EnumOptions<Owner>) | (TypeDef<Target> & PropertyOptions<Owner>);
 type OmitBaseProps<Entity, Base> = IsNever<Base> extends true ? Entity : Omit<Entity, keyof Base>;
-export type EntitySchemaMetadata<Entity, Base = never> = Omit<Partial<EntityMetadata<Entity>>, 'name' | 'properties' | 'extends'> & ({
+export type EntitySchemaMetadata<Entity, Base = never, Class extends EntityCtor = EntityCtor<Entity>> = Omit<Partial<EntityMetadata<Entity>>, 'name' | 'properties' | 'extends'> & ({
     name: string;
 } | {
-    class: EntityClass<Entity>;
+    class: Class;
     name?: string;
 }) & {
     extends?: EntityName<Base>;
@@ -38,17 +39,21 @@ export type EntitySchemaMetadata<Entity, Base = never> = Omit<Partial<EntityMeta
     properties?: {
         [Key in keyof OmitBaseProps<Entity, Base> as CleanKeys<OmitBaseProps<Entity, Base>, Key>]-?: EntitySchemaProperty<ExpandProperty<NonNullable<Entity[Key]>>, Entity>;
     };
+} & {
+    inheritance?: 'tpt';
 };
-export declare class EntitySchema<Entity = any, Base = never> {
+export declare class EntitySchema<Entity = any, Base = never, Class extends EntityCtor = EntityCtor<Entity>> {
     /**
      * When schema links the entity class via `class` option, this registry allows the lookup from opposite side,
      * so we can use the class in `entities` option just like the EntitySchema instance.
      */
-    static REGISTRY: Map<Partial<any>, EntitySchema<any, never>>;
+    static REGISTRY: Map<Partial<any>, EntitySchema<any, never, EntityCtor<any>>>;
+    /** @internal Type-level marker for fast entity type inference */
+    readonly '~entity': Entity;
     private readonly _meta;
     private internal;
     private initialized;
-    constructor(meta: EntitySchemaMetadata<Entity, Base>);
+    constructor(meta: EntitySchemaMetadata<Entity, Base, Class>);
     static fromMetadata<T = AnyEntity, U = never>(meta: EntityMetadata<T> | DeepPartial<EntityMetadata<T>>): EntitySchema<T, U>;
     addProperty(name: EntityKey<Entity>, type?: TypeType, options?: PropertyOptions<Entity> | EntityProperty<Entity>): void;
     addEnum(name: EntityKey<Entity>, type?: TypeType, options?: EnumOptions<Entity>): void;
@@ -63,21 +68,46 @@ export declare class EntitySchema<Entity = any, Base = never> {
     addIndex<Key extends string>(options: IndexOptions<Entity, Key>): void;
     addUnique<Key extends string>(options: UniqueOptions<Entity, Key>): void;
     setCustomRepository(repository: () => Constructor): void;
-    setExtends(base: EntityName<any>): void;
-    setClass(proto: EntityClass<Entity>): void;
-    get meta(): EntityMetadata<Entity>;
-    get name(): EntityName<Entity>;
+    setExtends(base: EntityName): void;
+    setClass(cls: Class): void;
+    get meta(): EntityMetadata<Entity, Class>;
+    get name(): string | EntityName<Entity>;
     get tableName(): string;
+    get class(): Class;
     get properties(): Record<string, any>;
+    new(...params: ConstructorParameters<Class>): Entity;
     /**
      * @internal
      */
     init(): this;
+    /**
+     * Check if this entity is part of a TPT hierarchy by walking up the extends chain.
+     * This handles mid-level abstract entities (e.g., Animal -> Mammal -> Dog where Mammal is abstract).
+     */
+    private isPartOfTPTHierarchy;
     private initProperties;
     private initPrimaryKeys;
     private normalizeType;
     private createProperty;
     private rename;
     private renameCompositeOptions;
+    /**
+     * Adds a lifecycle hook handler to the entity schema.
+     * This method allows registering hooks after the entity is defined,
+     * which can be useful for avoiding circular type references.
+     *
+     * @example
+     * ```ts
+     * export const Article = defineEntity({
+     *   name: 'Article',
+     *   properties: { ... },
+     * });
+     *
+     * Article.addHook('beforeCreate', async args => {
+     *   args.entity.slug = args.entity.title.toLowerCase();
+     * });
+     * ```
+     */
+    addHook<Event extends EventType | `${EventType}`>(event: Event, handler: NonNullable<EventSubscriber<Entity>[Event]>): this;
 }
 export {};

package/metadata/EntitySchema.js

@@ -10,7 +10,7 @@ export class EntitySchema {
      * so we can use the class in `entities` option just like the EntitySchema instance.
      */
     static REGISTRY = new Map();
-    _meta = new EntityMetadata();
+    _meta;
     internal = false;
     initialized = false;
     constructor(meta) {
@@ -18,15 +18,14 @@ export class EntitySchema {
         if (meta.name) {
             meta.abstract ??= false;
         }
+        this._meta = new EntityMetadata({
+            className: meta.name,
+            ...meta,
+        });
+        this._meta.root ??= this._meta;
         if (meta.class && !meta.internal) {
             EntitySchema.REGISTRY.set(meta.class, this);
         }
-        if (meta.tableName || meta.collection) {
-            Utils.renameKey(meta, 'tableName', 'collection');
-            meta.tableName = meta.collection;
-        }
-        Object.assign(this._meta, { className: meta.name }, meta);
-        this._meta.root ??= this._meta;
     }
     static fromMetadata(meta) {
         const schema = new EntitySchema({ ...meta, internal: true });
@@ -35,7 +34,7 @@ export class EntitySchema {
     }
     addProperty(name, type, options = {}) {
         this.renameCompositeOptions(name, options);
-        const prop = { name, kind: ReferenceKind.SCALAR, ...options, type: this.normalizeType(options, type) };
+        const prop = { name, kind: ReferenceKind.SCALAR, ...options, ...this.normalizeType(options, type) };
         if (type && Type.isMappedType(type.prototype)) {
             prop.type = type;
         }
@@ -85,8 +84,8 @@ export class EntitySchema {
         }
         this._meta.properties[name] = {
             name,
-            type: this.normalizeType(options),
             kind: ReferenceKind.EMBEDDED,
+            ...this.normalizeType(options),
             ...options,
         };
     }
@@ -151,19 +150,29 @@ export class EntitySchema {
     setExtends(base) {
         this._meta.extends = base;
     }
-    setClass(proto) {
-        const sameClass = this._meta.className === proto.name;
-        this._meta.class = proto;
-        this._meta.prototype = proto.prototype;
-        this._meta.className = proto.name;
+    setClass(cls) {
+        const oldClass = this._meta.class;
+        const sameClass = this._meta.class === cls;
+        this._meta.class = cls;
+        this._meta.prototype = cls.prototype;
+        this._meta.className = this._meta.name ?? cls.name;
         if (!sameClass || !this._meta.constructorParams) {
-            this._meta.constructorParams = Utils.getConstructorParams(proto);
+            this._meta.constructorParams = Utils.getConstructorParams(cls);
         }
         if (!this.internal) {
-            EntitySchema.REGISTRY.set(proto, this);
+            // Remove old class from registry if it's being replaced with a different class
+            if (oldClass && oldClass !== cls && EntitySchema.REGISTRY.get(oldClass) === this) {
+                EntitySchema.REGISTRY.delete(oldClass);
+            }
+            EntitySchema.REGISTRY.set(cls, this);
         }
-        if (Object.getPrototypeOf(proto) !== BaseEntity) {
-            this._meta.extends = this._meta.extends || Object.getPrototypeOf(proto).name || undefined;
+        const base = Object.getPrototypeOf(cls);
+        // Only set extends if the parent is NOT the auto-generated class for this same entity.
+        // When the user extends the auto-generated class (from defineEntity without a class option)
+        // and registers their custom class via setClass, we don't want to discover the
+        // auto-generated class as a separate parent entity.
+        if (base !== BaseEntity && base.name !== this._meta.className) {
+            this._meta.extends ??= base.name ? base : undefined;
         }
     }
     get meta() {
@@ -175,9 +184,15 @@ export class EntitySchema {
     get tableName() {
         return this._meta.tableName;
     }
+    get class() {
+        return this._meta.class;
+    }
     get properties() {
         return this._meta.properties;
     }
+    new(...params) {
+        return new this._meta.class(...params);
+    }
     /**
      * @internal
      */
@@ -185,19 +200,16 @@ export class EntitySchema {
         if (this.initialized) {
             return this;
         }
-        if (!this._meta.class) {
-            const name = this.name;
-            this._meta.class = ({ [name]: class {
-                } })[name];
-        }
         this.setClass(this._meta.class);
-        if (this._meta.abstract && !this._meta.discriminatorColumn) {
+        // Abstract TPT entities keep their name because they have their own table
+        const isTPT = this._meta.inheritance === 'tpt' || this.isPartOfTPTHierarchy();
+        if (this._meta.abstract && !this._meta.discriminatorColumn && !isTPT) {
             delete this._meta.name;
         }
         const tableName = this._meta.collection ?? this._meta.tableName;
         if (tableName?.includes('.') && !this._meta.schema) {
             this._meta.schema = tableName.substring(0, tableName.indexOf('.'));
-            this._meta.collection = tableName.substring(tableName.indexOf('.') + 1);
+            this._meta.tableName = tableName.substring(tableName.indexOf('.') + 1);
         }
         this.initProperties();
         this.initPrimaryKeys();
@@ -206,6 +218,24 @@ export class EntitySchema {
         this.initialized = true;
         return this;
     }
+    /**
+     * Check if this entity is part of a TPT hierarchy by walking up the extends chain.
+     * This handles mid-level abstract entities (e.g., Animal -> Mammal -> Dog where Mammal is abstract).
+     */
+    isPartOfTPTHierarchy() {
+        let parent = this._meta.extends;
+        while (parent) {
+            const parentSchema = parent instanceof EntitySchema ? parent : EntitySchema.REGISTRY.get(parent);
+            if (!parentSchema) {
+                break;
+            }
+            if (parentSchema._meta.inheritance === 'tpt') {
+                return true;
+            }
+            parent = parentSchema._meta.extends;
+        }
+        return false;
+    }
     initProperties() {
         Utils.entries(this._meta.properties).forEach(([name, options]) => {
             if (Type.isMappedType(options.type)) {
@@ -263,12 +293,15 @@ export class EntitySchema {
     }
     normalizeType(options, type) {
         if ('entity' in options) {
+            /* v8 ignore next */
             if (typeof options.entity === 'string') {
-                type = options.type = options.entity;
+                throw new Error(`Relation target needs to be an entity class or EntitySchema instance, string '${options.entity}' given instead for ${this._meta.className}.${options.name}.`);
             }
             else if (options.entity) {
                 const tmp = options.entity();
                 type = options.type = Array.isArray(tmp) ? tmp.map(t => Utils.className(t)).sort().join(' | ') : Utils.className(tmp);
+                const target = tmp instanceof EntitySchema ? tmp.meta.class : tmp;
+                return { type, target };
             }
         }
         if (type instanceof Function) {
@@ -277,7 +310,7 @@ export class EntitySchema {
         if (['String', 'Number', 'Boolean', 'Array'].includes(type)) {
             type = type.toLowerCase();
         }
-        return type;
+        return { type };
     }
     createProperty(kind, options) {
         return {
@@ -307,4 +340,26 @@ export class EntitySchema {
         this.rename(options, 'referenceColumnName', 'referencedColumnNames');
         this.rename(options, 'columnType', 'columnTypes');
     }
+    /**
+     * Adds a lifecycle hook handler to the entity schema.
+     * This method allows registering hooks after the entity is defined,
+     * which can be useful for avoiding circular type references.
+     *
+     * @example
+     * ```ts
+     * export const Article = defineEntity({
+     *   name: 'Article',
+     *   properties: { ... },
+     * });
+     *
+     * Article.addHook('beforeCreate', async args => {
+     *   args.entity.slug = args.entity.title.toLowerCase();
+     * });
+     * ```
+     */
+    addHook(event, handler) {
+        this._meta.hooks[event] ??= [];
+        this._meta.hooks[event].push(handler);
+        return this;
+    }
 }

package/metadata/MetadataDiscovery.d.ts

@@ -1,4 +1,4 @@
-import { type EntityClass, EntityMetadata } from '../typings.js';
+import { type EntityClass, EntityMetadata, type EntityName } from '../typings.js';
 import type { Configuration } from '../utils/Configuration.js';
 import { MetadataStorage } from './MetadataStorage.js';
 import { EntitySchema } from './EntitySchema.js';
@@ -16,7 +16,6 @@ export declare class MetadataDiscovery {
     constructor(metadata: MetadataStorage, platform: Platform, config: Configuration);
     discover(preferTs?: boolean): Promise<MetadataStorage>;
     discoverSync(): MetadataStorage;
-    validateDiscovered(metadata: EntityMetadata[]): void;
     private mapDiscoveredEntities;
     private initAccessors;
     processDiscoveredEntities(discovered: EntityMetadata[]): EntityMetadata[];
@@ -24,7 +23,7 @@ export declare class MetadataDiscovery {
     private discoverMissingTargets;
     private tryDiscoverTargets;
     discoverReferences<T>(refs: Iterable<EntityClass<T> | EntitySchema<T>>, validate?: boolean): EntityMetadata<T>[];
-    reset(className: string): void;
+    reset<T>(entityName: EntityName<T>): void;
     private getSchema;
     private getRootEntity;
     private discoverEntity;
@@ -35,6 +34,7 @@ export declare class MetadataDiscovery {
     private initManyToOneFieldName;
     private initManyToManyFieldName;
     private initManyToManyFields;
+    private isExplicitTableName;
     private initManyToOneFields;
     private initOneToManyFields;
     private processEntity;
@@ -42,15 +42,72 @@ 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;
+    /**
+     * First pass of TPT initialization: sets up hierarchy relationships
+     * (inheritanceType, tptParent, tptChildren) before properties have fieldNames.
+     */
+    private initTPTRelationships;
+    /**
+     * Second pass of TPT initialization: re-resolves metadata references after fieldNames
+     * are set, syncs to registry metadata, and sets up discriminators.
+     */
+    private finalizeTPTInheritance;
+    /**
+     * Initialize TPT discriminator map and virtual discriminator property.
+     * Unlike STI where the discriminator is a persisted column, TPT discriminator is computed
+     * at query time using CASE WHEN expressions based on which child table has data.
+     */
+    private initTPTDiscriminator;
+    /**
+     * Recursively collect all TPT descendants (children, grandchildren, etc.)
+     */
+    private collectAllTPTDescendants;
+    /**
+     * Computes ownProps for TPT entities - only properties defined in THIS entity,
+     * not inherited from parent. Also creates synthetic join properties for parent/child relationships.
+     *
+     * Called multiple times during discovery as metadata is progressively built.
+     * Each pass overwrites earlier results to reflect the final state of properties.
+     */
+    private computeTPTOwnProps;
+    /** Returns the depth of a TPT entity in its hierarchy (0 for root). */
+    private getTPTDepth;
+    /**
+     * Find the direct TPT parent entity for the given entity.
+     */
+    private getTPTParent;
     private createDiscriminatorProperty;
     private initAutoincrement;
+    private createSchemaTable;
     private initCheckConstraints;
     private initGeneratedColumn;
     private getDefaultVersionValue;