@mikro-orm/core 7.0.0-dev.32 → 7.0.0-dev.321

package/metadata/EntitySchema.d.ts

@@ -1,25 +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 type { EmbeddedOptions } from '../decorators/Embedded.js';
-import type { EnumOptions } from '../decorators/Enum.js';
-import type { IndexOptions, UniqueOptions } from '../decorators/Indexed.js';
-import type { ManyToManyOptions } from '../decorators/ManyToMany.js';
-import type { ManyToOneOptions } from '../decorators/ManyToOne.js';
-import type { OneToManyOptions } from '../decorators/OneToMany.js';
-import type { OneToOneOptions } from '../decorators/OneToOne.js';
-import type { PrimaryKeyOptions, SerializedPrimaryKeyOptions } from '../decorators/PrimaryKey.js';
-import type { PropertyOptions } from '../decorators/Property.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 { EventArgs } 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';
@@ -35,28 +28,32 @@ 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?: string | EntitySchema<Base>;
+    extends?: EntityName<Base>;
 } & {
     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;
@@ -71,19 +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: string | EntitySchema): 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<T extends Entity = Entity>(event: EventType | `${EventType}`, handler: (args: EventArgs<T>) => void | Promise<void>): 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,12 +34,17 @@ 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;
         }
-        if (Utils.isString(prop.formula)) {
-            const formula = prop.formula; // tmp var is needed here
+        if (typeof prop.formula === 'string') {
+            const formula = prop.formula;
             prop.formula = () => formula;
         }
         if (prop.formula) {
@@ -75,7 +79,7 @@ export class EntitySchema {
     }
     addSerializedPrimaryKey(name, type, options = {}) {
         this._meta.serializedPrimaryKey = name;
-        this.addProperty(name, type, options);
+        this.addProperty(name, type, { serializedPrimaryKey: true, ...options });
     }
     addEmbedded(name, options) {
         this.renameCompositeOptions(name, options);
@@ -85,8 +89,8 @@ export class EntitySchema {
         }
         this._meta.properties[name] = {
             name,
-            type: this.normalizeType(options),
             kind: ReferenceKind.EMBEDDED,
+            ...this.normalizeType(options),
             ...options,
         };
     }
@@ -151,21 +155,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) {
-            const tokens = Utils.tokenize(proto);
-            this._meta.constructorParams = Utils.getParamNames(tokens, 'constructor');
-            this._meta.toJsonParams = Utils.getParamNames(tokens, 'toJSON').filter(p => p !== '...args');
+            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() {
@@ -174,6 +186,18 @@ export class EntitySchema {
     get name() {
         return this._meta.className;
     }
+    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
      */
@@ -181,19 +205,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();
@@ -202,6 +223,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)) {
@@ -259,12 +298,20 @@ export class EntitySchema {
     }
     normalizeType(options, type) {
         if ('entity' in options) {
-            if (Utils.isString(options.entity)) {
-                type = options.type = options.entity;
+            /* v8 ignore next */
+            if (typeof options.entity === 'string') {
+                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);
+                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) {
@@ -273,7 +320,7 @@ export class EntitySchema {
         if (['String', 'Number', 'Boolean', 'Array'].includes(type)) {
             type = type.toLowerCase();
         }
-        return type;
+        return { type };
     }
     createProperty(kind, options) {
         return {
@@ -303,4 +350,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 Constructor, 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';
@@ -9,26 +9,24 @@ export declare class MetadataDiscovery {
     private readonly config;
     private readonly namingStrategy;
     private readonly metadataProvider;
-    private readonly cache;
     private readonly logger;
     private readonly schemaHelper;
     private readonly validator;
     private readonly discovered;
     constructor(metadata: MetadataStorage, platform: Platform, config: Configuration);
     discover(preferTs?: boolean): Promise<MetadataStorage>;
-    discoverSync(preferTs?: boolean): MetadataStorage;
+    discoverSync(): MetadataStorage;
     private mapDiscoveredEntities;
+    private initAccessors;
     processDiscoveredEntities(discovered: EntityMetadata[]): EntityMetadata[];
     private findEntities;
     private discoverMissingTargets;
     private tryDiscoverTargets;
-    private discoverDirectories;
-    discoverReferences<T>(refs: (Constructor<T> | EntitySchema<T>)[]): EntityMetadata<T>[];
-    reset(className: string): void;
-    private prepare;
+    discoverReferences<T>(refs: Iterable<EntityClass<T> | EntitySchema<T>>, validate?: boolean): EntityMetadata<T>[];
+    reset<T>(entityName: EntityName<T>): void;
     private getSchema;
+    private getRootEntity;
     private discoverEntity;
-    private saveToCache;
     private initNullability;
     private applyNamingStrategy;
     private initOwnColumns;
@@ -36,6 +34,7 @@ export declare class MetadataDiscovery {
     private initManyToOneFieldName;
     private initManyToManyFieldName;
     private initManyToManyFields;
+    private isExplicitTableName;
     private initManyToOneFields;
     private initOneToManyFields;
     private processEntity;
@@ -43,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;
@@ -66,6 +122,5 @@ export declare class MetadataDiscovery {
     private getPrefix;
     private initUnsigned;
     private initIndexes;
-    private getEntityClassOrSchema;
     private shouldForceConstructorUsage;
 }