@mikro-orm/core 7.0.0-dev.29 → 7.0.0-dev.291

package/hydration/ObjectHydrator.js

@@ -1,42 +1,47 @@
 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: new Map(),
-        reference: new Map(),
+        'full~true': new Map(),
+        'full~false': new Map(),
+        'reference~true': new Map(),
+        'reference~false': new Map(),
     };
     tmpIndex = 0;
     /**
      * @inheritDoc
      */
-    hydrate(entity, meta, data, factory, type, newEntity = false, convertCustomTypes = false, schema, parentSchema) {
-        const hydrate = this.getEntityHydrator(meta, type);
+    hydrate(entity, meta, data, factory, type, newEntity = false, convertCustomTypes = false, schema, parentSchema, normalizeAccessors) {
+        const hydrate = this.getEntityHydrator(meta, type, normalizeAccessors);
         const running = this.running;
         // the running state is used to consider propagation as hydration, saving the values directly to the entity data,
         // but we don't want that for new entities, their propagation should result in entity updates when flushing
         this.running = !newEntity;
-        Utils.callCompiledFunction(hydrate, entity, data, factory, newEntity, convertCustomTypes, schema, parentSchema);
+        Utils.callCompiledFunction(hydrate, entity, data, factory, newEntity, convertCustomTypes, schema, parentSchema, normalizeAccessors);
         this.running = running;
     }
     /**
      * @inheritDoc
      */
-    hydrateReference(entity, meta, data, factory, convertCustomTypes = false, schema, parentSchema) {
-        const hydrate = this.getEntityHydrator(meta, 'reference');
+    hydrateReference(entity, meta, data, factory, convertCustomTypes = false, schema, parentSchema, normalizeAccessors) {
+        const hydrate = this.getEntityHydrator(meta, 'reference', normalizeAccessors);
         const running = this.running;
         this.running = true;
-        Utils.callCompiledFunction(hydrate, entity, data, factory, false, convertCustomTypes, schema, parentSchema);
+        Utils.callCompiledFunction(hydrate, entity, data, factory, false, convertCustomTypes, schema, parentSchema, normalizeAccessors);
         this.running = running;
     }
     /**
      * @internal Highly performance-sensitive method.
      */
-    getEntityHydrator(meta, type) {
-        const exists = this.hydrators[type].get(meta.className);
+    getEntityHydrator(meta, type, normalizeAccessors = false) {
+        const key = `${type}~${normalizeAccessors}`;
+        const exists = this.hydrators[key].get(meta.class);
         if (exists) {
             return exists;
         }
@@ -46,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 3 */
-                if (RawQueryFragment.isKnownFragment(val)) {
+                /* v8 ignore next */
+                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('_');
@@ -131,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, 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, 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, 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, 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)}) {`);
@@ -166,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(`  }`);
@@ -249,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 });`);
+                    ret.push(`        entity${entityKey} = factory.createEmbeddable(${childMeta.className}, embeddedData, { newEntity, convertCustomTypes, normalizeAccessors });`);
                     ret.push(`      }`);
                     meta.props
                         .filter(p => p.embedded?.[0] === prop.name)
@@ -272,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 });`);
+                ret.push(`      entity${entityKey} = factory.createEmbeddable(${targetKey}, embeddedData, { newEntity, convertCustomTypes, normalizeAccessors });`);
                 ret.push(`    }`);
                 meta.props
                     .filter(p => p.embedded?.[0] === prop.name)
@@ -311,7 +353,7 @@ export class ObjectHydrator extends Hydrator {
         };
         const hydrateProperty = (prop, object = prop.object, path = [prop.name], dataKey) => {
             const entityKey = path.map(k => this.wrap(k)).join('');
-            dataKey = dataKey ?? (object ? entityKey : this.wrap(prop.name));
+            dataKey = dataKey ?? (object ? entityKey : this.wrap(normalizeAccessors ? (prop.accessor ?? prop.name) : prop.name));
             const ret = [];
             if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && !prop.mapToPk) {
                 ret.push(...hydrateToOne(prop, dataKey, entityKey));
@@ -331,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;`);
@@ -341,15 +383,16 @@ export class ObjectHydrator extends Hydrator {
         for (const prop of props) {
             lines.push(...hydrateProperty(prop));
         }
-        const code = `// compiled hydrator for entity ${meta.className} (${type})\n`
-            + `return function(entity, data, factory, newEntity, convertCustomTypes, schema) {\n`
+        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[type].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];
@@ -358,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, 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, merge: true });`);
+        lines.push(`    return factory.create(${targetKey}, value, { newEntity, convertCustomTypes, schema, normalizeAccessors, merge: true });`);
         lines.push(`  }`);
         return lines;
     }

package/index.d.ts

@@ -2,7 +2,8 @@
  * @packageDocumentation
  * @module core
  */
-export { Constructor, ConnectionType, Dictionary, PrimaryKeyProp, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, EntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, EntityMetadata, QBFilterQuery, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, EntityRepositoryType, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, MigrationDiff, GenerateOptions, FilterObject, IEntityGenerator, ISeedManager, EntityClassGroup, OptionalProps, EagerProps, HiddenProps, RequiredEntityData, CheckCallback, IndexCallback, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, UmzugMigration, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, Opt, EntityType, FromEntityType, Selected, IsSubset, NoInfer, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, Hidden, FilterValue, MergeLoaded, MergeSelected, Config, DefineConfig, TypeConfig, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, } from './typings.js';
+export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName } from './typings.js';
+export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, InferEntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, EntityDTOFlat, EntityDTOProp, SerializeDTO, MigrationDiff, GenerateOptions, FilterObject, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, IndexCallback, FormulaCallback, FormulaTable, SchemaTable, SchemaColumns, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, MigrationInfo, 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';
@@ -22,4 +23,3 @@ export * from './types/index.js';
 export * from './naming-strategy/index.js';
 export * from './metadata/index.js';
 export * from './cache/index.js';
-export * from './decorators/index.js';

package/index.js

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * @module core
  */
-export { PrimaryKeyProp, EntityMetadata, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Opt, Hidden, Config, DefineConfig, RequiredNullable, } from './typings.js';
+export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName } from './typings.js';
 export * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';
@@ -22,4 +22,3 @@ export * from './types/index.js';
 export * from './naming-strategy/index.js';
 export * from './metadata/index.js';
 export * from './cache/index.js';
-export * from './decorators/index.js';

package/logging/DefaultLogger.d.ts

@@ -29,5 +29,5 @@ export declare class DefaultLogger implements Logger {
     logQuery(context: {
         query: string;
     } & LogContext): void;
-    static create(options: LoggerOptions): DefaultLogger;
+    static create(this: void, options: LoggerOptions): DefaultLogger;
 }

package/logging/DefaultLogger.js

@@ -60,6 +60,7 @@ export class DefaultLogger {
         if (namespace === 'deprecated') {
             const { ignoreDeprecations = false } = this.options;
             return Array.isArray(ignoreDeprecations)
+                /* v8 ignore next */
                 ? !ignoreDeprecations.includes(context?.label ?? '')
                 : !ignoreDeprecations;
         }

package/logging/SimpleLogger.d.ts

@@ -14,5 +14,5 @@ export declare class SimpleLogger extends DefaultLogger {
     logQuery(context: {
         query: string;
     } & LogContext): void;
-    static create(options: LoggerOptions): SimpleLogger;
+    static create(this: void, options: LoggerOptions): SimpleLogger;
 }

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/index.d.ts

@@ -2,3 +2,4 @@ export * from './colors.js';
 export * from './Logger.js';
 export * from './DefaultLogger.js';
 export * from './SimpleLogger.js';
+export * from './inspect.js';

package/logging/index.js

@@ -2,3 +2,4 @@ export * from './colors.js';
 export * from './Logger.js';
 export * from './DefaultLogger.js';
 export * from './SimpleLogger.js';
+export * from './inspect.js';

package/logging/inspect.d.ts

@@ -0,0 +1,2 @@
+/** @internal */
+export declare function inspect(value: unknown, options?: Record<string, any>): string;

package/logging/inspect.js

@@ -0,0 +1,11 @@
+let nodeInspect;
+/** @internal */
+export function inspect(value, options) {
+    nodeInspect ??= globalThis.process?.getBuiltinModule?.('node:util').inspect;
+    /* v8 ignore else */
+    if (nodeInspect) {
+        return nodeInspect(value, options);
+    }
+    /* v8 ignore next */
+    return JSON.stringify(value, null, 2);
+}

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 {};