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

package/typings.d.ts

@@ -11,17 +11,20 @@ import type { SerializationContext } from './serialization/SerializationContext.
 import type { SerializeOptions } from './serialization/EntitySerializer.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
 import type { EntitySchema } from './metadata/EntitySchema.js';
+import type { IndexColumnOptions } from './metadata/types.js';
 import type { Type, types } from './types/index.js';
 import type { Platform } from './platforms/Platform.js';
 import type { Configuration } from './utils/Configuration.js';
-import type { RawQueryFragment } from './utils/RawQueryFragment.js';
+import type { Raw } from './utils/RawQueryFragment.js';
 import type { EntityManager } from './EntityManager.js';
 import type { EventSubscriber } from './events/EventSubscriber.js';
 import type { FilterOptions, FindOneOptions, FindOptions, LoadHint } from './drivers/IDatabaseDriver.js';
+export type { Raw };
 export type Constructor<T = unknown> = new (...args: any[]) => T;
 export type Dictionary<T = any> = {
     [k: string]: T;
 };
+export type CompiledFunctions = Record<string, (...args: any[]) => any>;
 export type EntityKey<T = unknown, B extends boolean = false> = string & {
     [K in keyof T]-?: CleanKeys<T, K, B> extends never ? never : K;
 }[keyof T];
@@ -40,7 +43,64 @@ export type IsUnknown<T> = T extends unknown ? unknown extends T ? true : never
 export type IsAny<T> = 0 extends (1 & T) ? true : false;
 export type IsNever<T, True = true, False = false> = [T] extends [never] ? True : False;
 export type MaybePromise<T> = T | Promise<T>;
-export type NoInfer<T> = [T][T extends any ? 0 : never];
+/**
+ * Structural type for matching Collection without triggering full interface evaluation.
+ * Using `T extends CollectionShape` instead of `T extends Collection<any, any>` avoids
+ * forcing TypeScript to evaluate Collection's 30+ methods, preventing instantiation explosion
+ * (~133k → ~2k instantiations).
+ *
+ * Usage:
+ * - Matching only: `T extends CollectionShape`
+ * - With inference: `T extends CollectionShape<infer U>`
+ */
+type CollectionShape<T = any> = {
+    [k: number]: T;
+    readonly owner: object;
+};
+/**
+ * Structural type for matching LoadedCollection (extends CollectionShape with `$` property).
+ *
+ * Usage:
+ * - Matching only: `T extends LoadedCollectionShape`
+ * - With inference: `T extends LoadedCollectionShape<infer U>`
+ */
+type LoadedCollectionShape<T = any> = CollectionShape<T> & {
+    $: any;
+};
+/**
+ * Structural type for matching Reference without triggering full class evaluation.
+ * Using `T extends ReferenceShape` instead of `T extends Reference<any>` avoids
+ * forcing TypeScript to evaluate Reference's methods, preventing instantiation overhead
+ * (~800 → ~15 instantiations).
+ *
+ * Usage:
+ * - Matching only: `T extends ReferenceShape`
+ * - With inference: `T extends ReferenceShape<infer U>`
+ */
+type ReferenceShape<T = any> = {
+    unwrap(): T;
+};
+/**
+ * Structural type for matching LoadedReference (Reference with `$` property).
+ * Note: We don't parameterize ReferenceShape here because for loaded relations,
+ * the Reference unwrap() returns the base type while $ returns the Loaded type.
+ * We infer T from $ to get the full Loaded type for EntityDTO.
+ */
+type LoadedReferenceShape<T = any> = ReferenceShape & {
+    $: T;
+};
+/**
+ * Structural type for matching any loadable relation (Collection, Reference, or array).
+ * Using this instead of `Loadable<any>` in conditional type checks prevents
+ * TypeScript from evaluating the full Collection/Reference interfaces.
+ */
+type LoadableShape = CollectionShape | ReferenceShape | readonly any[];
+export type UnionKeys<T> = T extends any ? keyof T : never;
+export type UnionPropertyType<T, K extends PropertyKey> = T extends any ? (K extends keyof T ? T[K] : never) : never;
+type IsUnion<T, U = T> = T extends any ? ([U] extends [T] ? false : true) : false;
+export type MergeUnion<T> = [T] extends [object] ? (T extends Scalar ? T : IsUnion<T> extends true ? {
+    [K in UnionKeys<T>]: UnionPropertyType<T, K>;
+} : T) : T;
 export type DeepPartial<T> = T & {
     [P in keyof T]?: T[P] extends (infer U)[] ? DeepPartial<U>[] : T[P] extends Readonly<infer U>[] ? Readonly<DeepPartial<U>>[] : DeepPartial<T[P]>;
 };
@@ -82,7 +142,17 @@ export type CleanTypeConfig<T> = Compute<Pick<T, Extract<keyof T, keyof TypeConf
 export interface TypeConfig {
     forceObject?: boolean;
 }
-export type UnwrapPrimary<T> = T extends Scalar ? T : T extends Reference<infer U> ? Primary<U> : Primary<T>;
+declare const __selectedType: unique symbol;
+declare const __loadedType: unique symbol;
+declare const __loadHint: unique symbol;
+/**
+ * Expands a populate hint into all its prefixes.
+ * e.g., Prefixes<'a.b.c'> = 'a' | 'a.b' | 'a.b.c'
+ * This reflects that loading 'a.b.c' means 'a' and 'a.b' are also loaded.
+ * Special case: '*' returns string to ensure Loaded<T, '*'> is assignable to any Loaded<T, Hint>.
+ */
+export type Prefixes<S extends string> = S extends '*' ? string : S extends `${infer H}.${infer T}` ? H | `${H}.${Prefixes<T>}` : S;
+export type UnwrapPrimary<T> = T extends Scalar ? T : T extends ReferenceShape<infer U> ? Primary<U> : Primary<T>;
 type PrimaryPropToType<T, Keys extends (keyof T)[]> = {
     [Index in keyof Keys]: UnwrapPrimary<T[Keys[Index]]>;
 };
@@ -115,22 +185,35 @@ export type IPrimaryKey<T extends IPrimaryKeyValue = IPrimaryKeyValue> = T;
 export type Scalar = boolean | number | string | bigint | symbol | Date | RegExp | Uint8Array | {
     toHexString(): string;
 };
+type Primitive = boolean | number | string | bigint | symbol;
 export type ExpandScalar<T> = null | (T extends string ? T | RegExp : T extends Date ? Date | string : T extends bigint ? bigint | string | number : T);
+/** Marker interface for query builders that can be used as subqueries */
+export interface Subquery {
+    readonly __subquery: true;
+}
 export type OperatorMap<T> = {
     $and?: ExpandQuery<T>[];
     $or?: ExpandQuery<T>[];
-    $eq?: ExpandScalar<T> | readonly ExpandScalar<T>[];
-    $ne?: ExpandScalar<T>;
-    $in?: readonly ExpandScalar<T>[];
-    $nin?: readonly ExpandScalar<T>[];
+    $eq?: ExpandScalar<T> | readonly ExpandScalar<T>[] | Subquery;
+    $ne?: ExpandScalar<T> | readonly ExpandScalar<T>[] | Subquery;
+    $in?: readonly ExpandScalar<T>[] | readonly Primary<T>[] | Raw | Subquery;
+    $nin?: readonly ExpandScalar<T>[] | readonly Primary<T>[] | Raw | Subquery;
     $not?: ExpandQuery<T>;
     $none?: ExpandQuery<T>;
     $some?: ExpandQuery<T>;
     $every?: ExpandQuery<T>;
-    $gt?: ExpandScalar<T>;
-    $gte?: ExpandScalar<T>;
-    $lt?: ExpandScalar<T>;
-    $lte?: ExpandScalar<T>;
+    $size?: number | {
+        $eq?: number;
+        $ne?: number;
+        $gt?: number;
+        $gte?: number;
+        $lt?: number;
+        $lte?: number;
+    };
+    $gt?: ExpandScalar<T> | readonly ExpandScalar<T>[] | Subquery;
+    $gte?: ExpandScalar<T> | readonly ExpandScalar<T>[] | Subquery;
+    $lt?: ExpandScalar<T> | readonly ExpandScalar<T>[] | Subquery;
+    $lte?: ExpandScalar<T> | readonly ExpandScalar<T>[] | Subquery;
     $like?: string;
     $re?: string;
     $ilike?: string;
@@ -143,10 +226,12 @@ export type OperatorMap<T> = {
     $hasKeys?: readonly string[];
     $hasSomeKeys?: readonly string[];
 };
-export type FilterItemValue<T> = T | ExpandScalar<T> | Primary<T>;
+export type FilterItemValue<T> = T | ExpandScalar<T> | Primary<T> | Raw;
 export type FilterValue<T> = OperatorMap<FilterItemValue<T>> | FilterItemValue<T> | FilterItemValue<T>[] | null;
+type FilterObjectProp<T, K extends PropertyKey> = K extends keyof MergeUnion<T> ? MergeUnion<T>[K] : K extends keyof T ? T[K] : never;
+type ExpandQueryMerged<T> = [T] extends [object] ? [T] extends [Scalar] ? never : FilterQuery<MergeUnion<T>> : FilterValue<T>;
 export type FilterObject<T> = {
-    -readonly [K in EntityKey<T>]?: ExpandQuery<ExpandProperty<T[K]>> | FilterValue<ExpandProperty<T[K]>> | null;
+    -readonly [K in EntityKey<T>]?: ExpandQuery<ExpandProperty<FilterObjectProp<T, K>>> | ExpandQueryMerged<ExpandProperty<FilterObjectProp<T, K>>> | FilterValue<ExpandProperty<FilterObjectProp<T, K>>> | null;
 };
 export type ExpandQuery<T> = T extends object ? T extends Scalar ? never : FilterQuery<T> : FilterValue<T>;
 export type EntityProps<T> = {
@@ -154,12 +239,11 @@ export type EntityProps<T> = {
 };
 export type ObjectQuery<T> = OperatorMap<T> & FilterObject<T>;
 export type FilterQuery<T> = ObjectQuery<T> | NonNullable<ExpandScalar<Primary<T>>> | NonNullable<EntityProps<T> & OperatorMap<T>> | FilterQuery<T>[];
-export type QBFilterQuery<T = any> = ObjectQuery<T> | Dictionary;
 export interface IWrappedEntity<Entity extends object> {
     isInitialized(): boolean;
     isManaged(): boolean;
     populated(populated?: boolean): void;
-    populate<Hint extends string = never>(populate: AutoPath<Entity, Hint>[] | false, options?: EntityLoaderOptions<Entity>): Promise<Loaded<Entity, Hint>>;
+    populate<Hint extends string = never>(populate: readonly AutoPath<Entity, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Entity>): Promise<Loaded<Entity, Hint>>;
     init<Hint extends string = never, Fields extends string = '*', Exclude extends string = never>(options?: FindOneOptions<Entity, Hint, Fields, Exclude>): Promise<Loaded<Entity, Hint, Fields, Exclude> | null>;
     toReference(): Ref<Entity> & LoadedReference<Loaded<Entity, AddEager<Entity>>>;
     toObject(): EntityDTO<Entity>;
@@ -206,16 +290,21 @@ export interface IWrappedEntityInternal<Entity extends object> extends IWrappedE
     };
 }
 export type AnyEntity<T = any> = Partial<T>;
-export type EntityClass<T> = Function & {
+export type EntityClass<T = any> = Function & {
     prototype: T;
 };
-export type EntityName<T> = string | EntityClass<T> | EntitySchema<T, any> | {
-    name: string;
-};
+export type EntityName<T = any> = EntityClass<T> | EntityCtor<T> | EntitySchema<T, any>;
 export type GetRepository<Entity extends {
     [k: PropertyKey]: any;
 }, Fallback> = Entity[typeof EntityRepositoryType] extends EntityRepository<any> | undefined ? NonNullable<Entity[typeof EntityRepositoryType]> : Fallback;
-export type EntityDataPropValue<T> = T | Primary<T>;
+type PolymorphicPrimaryInner<T> = T extends object ? Primary<T> extends readonly [infer First, infer Second, ...infer Rest] ? readonly [string, First, Second, ...Rest] | [string, First, Second, ...Rest] : readonly [string, Primary<T>] | [string, Primary<T>] : never;
+/**
+ * Tuple format for polymorphic FK values: [discriminator, ...pkValues]
+ * Distributes over unions, so `Post | Comment` becomes `['post', number] | ['comment', number]`
+ * For composite keys like [tenantId, orgId], becomes ['discriminator', tenantId, orgId]
+ */
+export type PolymorphicPrimary<T> = true extends IsUnion<T> ? PolymorphicPrimaryInner<T> : never;
+export type EntityDataPropValue<T> = T | Primary<T> | PolymorphicPrimary<T>;
 type ExpandEntityProp<T, C extends boolean = false> = T extends Record<string, any> ? {
     [K in keyof T as CleanKeys<T, K>]?: EntityDataProp<ExpandProperty<T[K]>, C> | EntityDataPropValue<ExpandProperty<T[K]>> | null;
 } | EntityDataPropValue<ExpandProperty<T>> : T;
@@ -228,16 +317,17 @@ type ExpandRequiredEntityPropObject<T, I = never, C extends boolean = false> = {
 type NonArrayObject = object & {
     [Symbol.iterator]?: never;
 };
-export type EntityDataProp<T, C extends boolean> = T extends Date ? string | Date : T extends Scalar ? T : T extends {
+export type EntityDataProp<T, C extends boolean> = T extends Date ? string | Date : T extends Scalar ? T : T extends ScalarReference<infer U> ? EntityDataProp<U, C> : T extends {
     __runtime?: infer Runtime;
     __raw?: infer Raw;
-} ? (C extends true ? Raw : Runtime) : T extends Reference<infer U> ? EntityDataNested<U, C> : T extends ScalarReference<infer U> ? EntityDataProp<U, C> : T extends Collection<infer U, any> ? U | U[] | EntityDataNested<U, C> | EntityDataNested<U, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | EntityDataNested<U, C> | EntityDataNested<U, C>[] : U[] | EntityDataNested<U, C>[] : EntityDataNested<T, C>;
-export type RequiredEntityDataProp<T, O, C extends boolean> = T extends Date ? string | Date : Exclude<T, null> extends RequiredNullable.Brand ? T | null : T extends Scalar ? T : T extends {
+} ? (C extends true ? Raw : Runtime) : T extends ReferenceShape<infer U> ? EntityDataNested<U, C> : T extends CollectionShape<infer U> ? U | U[] | EntityDataNested<U & object, C> | EntityDataNested<U & object, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | EntityDataNested<U, C> | EntityDataNested<U, C>[] : U[] | EntityDataNested<U, C>[] : EntityDataNested<T, C>;
+export type RequiredEntityDataProp<T, O, C extends boolean> = T extends Date ? string | Date : Exclude<T, null> extends RequiredNullable.Brand ? T | null : T extends Scalar ? T : T extends ScalarReference<infer U> ? RequiredEntityDataProp<U, O, C> : T extends {
     __runtime?: infer Runtime;
     __raw?: infer Raw;
-} ? (C extends true ? Raw : Runtime) : T extends Reference<infer U> ? RequiredEntityDataNested<U, O, C> : T extends ScalarReference<infer U> ? RequiredEntityDataProp<U, O, C> : T extends Collection<infer U, any> ? U | U[] | RequiredEntityDataNested<U, O, C> | RequiredEntityDataNested<U, O, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | RequiredEntityDataNested<U, O, C> | RequiredEntityDataNested<U, O, C>[] : U[] | RequiredEntityDataNested<U, O, C>[] : RequiredEntityDataNested<T, O, C>;
+} ? (C extends true ? Raw : Runtime) : T extends ReferenceShape<infer U> ? RequiredEntityDataNested<U, O, C> : T extends CollectionShape<infer U> ? U | U[] | RequiredEntityDataNested<U & object, O, C> | RequiredEntityDataNested<U & object, O, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | RequiredEntityDataNested<U, O, C> | RequiredEntityDataNested<U, O, C>[] : U[] | RequiredEntityDataNested<U, O, C>[] : RequiredEntityDataNested<T, O, C>;
 export type EntityDataNested<T, C extends boolean = false> = T extends undefined ? never : T extends any[] ? Readonly<T> : EntityData<T, C> | ExpandEntityProp<T, C>;
-type EntityDataItem<T, C extends boolean> = C extends false ? T | EntityDataProp<T, C> | null : EntityDataProp<T, C> | null;
+type UnwrapScalarRef<T> = T extends ScalarReference<infer U> ? U : T;
+type EntityDataItem<T, C extends boolean> = C extends false ? UnwrapScalarRef<T> | EntityDataProp<T, C> | Raw | null : EntityDataProp<T, C> | Raw | null;
 export type RequiredEntityDataNested<T, O, C extends boolean> = T extends any[] ? Readonly<T> : RequiredEntityData<T, O> | ExpandRequiredEntityProp<T, O, C>;
 type ExplicitlyOptionalProps<T> = (T extends {
     [OptionalProps]?: infer K;
@@ -245,22 +335,22 @@ type ExplicitlyOptionalProps<T> = (T extends {
     [K in keyof T]: T[K] extends Opt ? K : never;
 }[keyof T] & {});
 type NullableKeys<T, V = null> = {
-    [K in keyof T]: V extends T[K] ? K : never;
+    [K in keyof T]: unknown extends T[K] ? never : V extends T[K] ? K : never;
 }[keyof T];
 type RequiredNullableKeys<T> = {
     [K in keyof T]: Exclude<T[K], null> extends RequiredNullable.Brand ? K : never;
 }[keyof T];
 type ProbablyOptionalProps<T> = PrimaryProperty<T> | ExplicitlyOptionalProps<T> | Exclude<NonNullable<NullableKeys<T, null | undefined>>, RequiredNullableKeys<T>>;
-type IsOptional<T, K extends keyof T, I> = T[K] extends Collection<any, any> ? true : ExtractType<T[K]> extends I ? true : K extends ProbablyOptionalProps<T> ? true : false;
+type IsOptional<T, K extends keyof T, I> = T[K] extends CollectionShape ? true : ExtractType<T[K]> extends I ? true : K extends ProbablyOptionalProps<T> ? true : false;
 type RequiredKeys<T, K extends keyof T, I> = IsOptional<T, K, I> extends false ? CleanKeys<T, K> : never;
 type OptionalKeys<T, K extends keyof T, I> = IsOptional<T, K, I> extends false ? never : CleanKeys<T, K>;
 export type EntityData<T, C extends boolean = false> = {
     [K in EntityKey<T>]?: EntityDataItem<T[K] & {}, C>;
 };
 export type RequiredEntityData<T, I = never, C extends boolean = false> = {
-    [K in keyof T as RequiredKeys<T, K, I>]: T[K] | RequiredEntityDataProp<T[K], T, C> | Primary<T[K]>;
+    [K in keyof T as RequiredKeys<T, K, I>]: T[K] | RequiredEntityDataProp<T[K], T, C> | Primary<T[K]> | PolymorphicPrimary<T[K]> | Raw;
 } & {
-    [K in keyof T as OptionalKeys<T, K, I>]?: T[K] | RequiredEntityDataProp<T[K], T, C> | Primary<T[K]> | null;
+    [K in keyof T as OptionalKeys<T, K, I>]?: T[K] | RequiredEntityDataProp<T[K], T, C> | Primary<T[K]> | PolymorphicPrimary<T[K]> | Raw | null;
 };
 export type EntityDictionary<T> = EntityData<T> & Record<any, any>;
 type ExtractEagerProps<T> = T extends {
@@ -285,7 +375,7 @@ export type Ref<T> = T extends any ? IsAny<T> extends true ? Reference<T & objec
 type ExtractHiddenProps<T> = (T extends {
     [HiddenProps]?: infer K;
 } ? K : never) | ({
-    [K in keyof T]: T[K] extends Hidden ? K : never;
+    [K in keyof T]: T[K] extends Primitive ? (T[K] extends Hidden ? K : never) : never;
 }[keyof T] & {});
 type ExcludeHidden<T, K extends keyof T> = K extends ExtractHiddenProps<T> ? never : K;
 type ExtractConfig<T> = T extends {
@@ -295,11 +385,14 @@ type PreferExplicitConfig<E, I> = IsNever<E, I, E>;
 type PrimaryOrObject<T, U, C extends TypeConfig> = PreferExplicitConfig<C, ExtractConfig<T>>['forceObject'] extends true ? {
     [K in PrimaryProperty<U> & keyof U]: U[K];
 } : Primary<U>;
-export type EntityDTOProp<E, T, C extends TypeConfig = never> = T extends Scalar ? T : T extends {
+export type EntityDTOProp<E, T, C extends TypeConfig = never> = T extends Scalar ? T : T extends ScalarReference<infer U> ? U : T extends {
     __serialized?: infer U;
-} ? (IsUnknown<U> extends false ? U : T) : T extends LoadedReference<infer U> ? EntityDTO<U, C> : T extends Reference<infer U> ? PrimaryOrObject<E, U, C> : T extends ScalarReference<infer U> ? U : T extends LoadedCollection<infer U> ? EntityDTO<U, C>[] : T extends Collection<infer U> ? PrimaryOrObject<E, U, C>[] : T extends readonly (infer U)[] ? (T extends readonly any[] ? T : U[]) : T extends Relation<T> ? EntityDTO<T, C> : T;
-type DTOProbablyOptionalProps<T> = NonNullable<NullableKeys<T, undefined>>;
-type DTOIsOptional<T, K extends keyof T> = T[K] extends LoadedCollection<any> ? false : K extends PrimaryProperty<T> ? false : K extends DTOProbablyOptionalProps<T> ? true : false;
+} ? (IsUnknown<U> extends false ? U : T) : T extends LoadedReferenceShape<infer U> ? EntityDTO<U, C> : T extends ReferenceShape<infer U> ? PrimaryOrObject<E, U, C> : T extends LoadedCollectionShape<infer U> ? EntityDTO<U & object, C>[] : T extends CollectionShape<infer U> ? PrimaryOrObject<E, U & object, C>[] : T extends readonly (infer U)[] ? U extends Scalar ? T : EntityDTOProp<E, U, C>[] : T extends Relation<T> ? EntityDTO<T, C> : T;
+type UnwrapLoadedEntity<T> = T extends {
+    [__loadedType]?: infer U;
+} ? NonNullable<U> : T;
+type DTOProbablyOptionalProps<T> = NonNullable<NullableKeys<UnwrapLoadedEntity<T>, undefined>>;
+type DTOIsOptional<T, K extends keyof T> = T[K] extends LoadedCollectionShape ? false : K extends PrimaryProperty<UnwrapLoadedEntity<T>> ? false : K extends DTOProbablyOptionalProps<T> ? true : false;
 type DTORequiredKeys<T, K extends keyof T> = DTOIsOptional<T, K> extends false ? ExcludeHidden<T, K> & CleanKeys<T, K> : never;
 type DTOOptionalKeys<T, K extends keyof T> = DTOIsOptional<T, K> extends false ? never : ExcludeHidden<T, K> & CleanKeys<T, K>;
 export type EntityDTO<T, C extends TypeConfig = never> = {
@@ -309,28 +402,61 @@ export type EntityDTO<T, C extends TypeConfig = never> = {
 };
 type TargetKeys<T> = T extends EntityClass<infer P> ? keyof P : keyof T;
 type PropertyName<T> = IsUnknown<T> extends false ? TargetKeys<T> : string;
-type TableName = {
+export type FormulaTable = {
+    alias: string;
+    name: string;
+    schema?: string;
+    qualifiedName: string;
+    toString: () => string;
+};
+/**
+ * Table reference for schema callbacks (indexes, checks, generated columns).
+ * Unlike FormulaTable, this has no alias since schema generation doesn't use query aliases.
+ */
+export type SchemaTable = {
     name: string;
     schema?: string;
+    qualifiedName: string;
     toString: () => string;
 };
-export type IndexCallback<T> = (table: TableName, columns: Record<PropertyName<T>, string>, indexName: string) => string | RawQueryFragment;
-export type CheckCallback<T> = (columns: Record<PropertyName<T>, string>) => string;
-export type GeneratedColumnCallback<T> = (columns: Record<keyof T, string>) => string;
+/**
+ * Column mapping for formula callbacks. Maps property names to fully-qualified alias.fieldName.
+ * Has toString() returning the main alias for backwards compatibility with old formula syntax.
+ * @example
+ * // New recommended syntax - use cols.propName for fully-qualified references
+ * formula: cols => `${cols.firstName} || ' ' || ${cols.lastName}`
+ *
+ * // Old syntax still works - cols.toString() returns the alias
+ * formula: cols => `${cols}.first_name || ' ' || ${cols}.last_name`
+ */
+export type FormulaColumns<T> = Record<PropertyName<T>, string> & {
+    toString(): string;
+};
+/**
+ * Column mapping for schema callbacks (indexes, checks, generated columns).
+ * Maps property names to field names. For TPT entities, only includes properties
+ * that belong to the current table (not inherited properties from parent tables).
+ */
+export type SchemaColumns<T> = Record<PropertyName<T>, string>;
+export type IndexCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable, indexName: string) => string | Raw;
+export type FormulaCallback<T> = (columns: FormulaColumns<T>, table: FormulaTable) => string | Raw;
+export type CheckCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
+export type GeneratedColumnCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
 export interface CheckConstraint<T = any> {
     name?: string;
     property?: string;
-    expression: string | CheckCallback<T>;
+    expression: string | Raw | CheckCallback<T>;
 }
 export type AnyString = string & {};
 export interface EntityProperty<Owner = any, Target = any> {
     name: EntityKey<Owner>;
     entity: () => EntityName<Owner>;
+    target: EntityClass<Target>;
     type: keyof typeof types | AnyString;
     runtimeType: 'number' | 'string' | 'boolean' | 'bigint' | 'Buffer' | 'Date' | 'object' | 'any' | AnyString;
     targetMeta?: EntityMetadata<Target>;
     columnTypes: string[];
-    generated?: string | GeneratedColumnCallback<Owner>;
+    generated?: string | Raw | GeneratedColumnCallback<Owner>;
     customType?: Type<any>;
     customTypes: (Type<any> | undefined)[];
     hasConvertToJSValueSQL: boolean;
@@ -351,7 +477,7 @@ export interface EntityProperty<Owner = any, Target = any> {
     fieldNameRaw?: string;
     default?: string | number | boolean | null;
     defaultRaw?: string;
-    formula?: (alias: string) => string;
+    formula?: FormulaCallback<Owner>;
     filters?: FilterOptions;
     prefix?: string | boolean;
     prefixMode?: EmbeddedPrefixMode;
@@ -360,11 +486,19 @@ export interface EntityProperty<Owner = any, Target = any> {
     embeddable: EntityClass<Owner>;
     embeddedProps: Dictionary<EntityProperty>;
     discriminatorColumn?: string;
+    discriminator?: string;
+    polymorphic?: boolean;
+    polymorphTargets?: EntityMetadata[];
+    discriminatorMap?: Dictionary<EntityClass<Target>>;
+    discriminatorValue?: string;
     object?: boolean;
     index?: boolean | string;
     unique?: boolean | string;
     nullable?: boolean;
     inherited?: boolean;
+    renamedFrom?: string;
+    stiFieldNames?: string[];
+    stiFieldNameMap?: Dictionary<string>;
     unsigned?: boolean;
     mapToPk?: boolean;
     persist?: boolean;
@@ -396,13 +530,14 @@ export interface EntityProperty<Owner = any, Target = any> {
     fixedOrder?: boolean;
     fixedOrderColumn?: string;
     pivotTable: string;
-    pivotEntity: string;
+    pivotEntity: EntityClass<Target>;
     joinColumns: string[];
     ownColumns: string[];
     inverseJoinColumns: string[];
     referencedColumnNames: string[];
     referencedTableName: string;
     referencedPKs: EntityKey<Owner>[];
+    targetKey?: string;
     serializer?: (value: any, options?: SerializeOptions<any>) => any;
     serializedName?: string;
     comment?: string;
@@ -415,18 +550,30 @@ export interface EntityProperty<Owner = any, Target = any> {
     createForeignKeyConstraint: boolean;
     foreignKeyName?: string;
 }
-export declare class EntityMetadata<T = any> {
+export declare class EntityMetadata<Entity = any, Class extends EntityCtor<Entity> = EntityCtor<Entity>> {
     private static counter;
     readonly _id: number;
     readonly propertyOrder: Map<string, number>;
     constructor(meta?: Partial<EntityMetadata>);
-    addProperty(prop: Partial<EntityProperty<T>>, sync?: boolean): void;
+    addProperty(prop: Partial<EntityProperty<Entity>>): void;
     removeProperty(name: string, sync?: boolean): void;
-    getPrimaryProps(flatten?: boolean): EntityProperty<T>[];
-    getPrimaryProp(): EntityProperty<T>;
-    createColumnMappingObject(): Dictionary<any>;
+    getPrimaryProps(flatten?: boolean): EntityProperty<Entity>[];
+    getPrimaryProp(): EntityProperty<Entity>;
+    /**
+     * Creates a mapping from property names to field names.
+     * @param alias - Optional alias to prefix field names. Can be a string (same for all) or a function (per-property).
+     *                When provided, also adds toString() returning the alias for backwards compatibility with formulas.
+     * @param toStringAlias - Optional alias to return from toString(). Defaults to `alias` when it's a string.
+     */
+    createColumnMappingObject(alias?: string | ((prop: EntityProperty<Entity>) => string), toStringAlias?: string): FormulaColumns<Entity>;
+    /**
+     * Creates a column mapping for schema callbacks (indexes, checks, generated columns).
+     * For TPT entities, only includes properties that belong to the current table (ownProps).
+     */
+    createSchemaColumnMappingObject(): SchemaColumns<Entity>;
     get tableName(): string;
     set tableName(name: string);
+    get uniqueName(): string;
     sync(initIndexes?: boolean, config?: Configuration): void;
     private initIndexes;
     /** @internal */
@@ -436,67 +583,87 @@ export interface SimpleColumnMeta {
     name: string;
     type: string;
 }
-export interface EntityMetadata<T = any> {
+export type EntityCtor<T = any> = abstract new (...args: any[]) => T;
+export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> = EntityCtor<Entity>> {
     name?: string;
     className: string;
     tableName: string;
     schema?: string;
     pivotTable?: boolean;
     virtual?: boolean;
-    expression?: string | ((em: any, where: ObjectQuery<T>, options: FindOptions<T, any, any, any>, stream?: boolean) => MaybePromise<RawQueryFragment | object | string>);
-    discriminatorColumn?: EntityKey<T> | AnyString;
+    /** True if this entity represents a database view (not a virtual entity). Accepts `{ materialized: true }` as input, normalized to `true` during sync. */
+    view?: boolean | {
+        materialized?: boolean;
+        withData?: boolean;
+    };
+    /** True if this is a materialized view (PostgreSQL only). Requires `view: true`. */
+    materialized?: boolean;
+    /** For materialized views, whether data is populated on creation. Defaults to true. */
+    withData?: boolean;
+    expression?: string | ((em: any, where: ObjectQuery<Entity>, options: FindOptions<Entity, any, any, any>, stream?: boolean) => MaybePromise<Raw | object | string>);
+    discriminatorColumn?: EntityKey<Entity> | AnyString;
     discriminatorValue?: number | string;
-    discriminatorMap?: Dictionary<string>;
+    discriminatorMap?: Dictionary<EntityClass>;
     embeddable: boolean;
-    constructorParams?: (keyof T)[];
+    constructorParams?: (keyof Entity)[];
     forceConstructor: boolean;
-    extends: string;
+    extends?: EntityName<Entity>;
     collection: string;
     path: string;
-    primaryKeys: EntityKey<T>[];
+    primaryKeys: EntityKey<Entity>[];
     simplePK: boolean;
     compositePK: boolean;
-    versionProperty: EntityKey<T>;
-    concurrencyCheckKeys: Set<EntityKey<T>>;
-    serializedPrimaryKey?: EntityKey<T>;
+    versionProperty: EntityKey<Entity>;
+    concurrencyCheckKeys: Set<EntityKey<Entity>>;
+    serializedPrimaryKey?: EntityKey<Entity>;
     properties: {
-        [K in EntityKey<T>]: EntityProperty<T>;
+        [K in EntityKey<Entity>]: EntityProperty<Entity>;
     };
-    props: EntityProperty<T>[];
-    relations: EntityProperty<T>[];
-    bidirectionalRelations: EntityProperty<T>[];
+    props: EntityProperty<Entity>[];
+    relations: EntityProperty<Entity>[];
+    bidirectionalRelations: EntityProperty<Entity>[];
     referencingProperties: {
-        meta: EntityMetadata<T>;
-        prop: EntityProperty<T>;
+        meta: EntityMetadata<Entity>;
+        prop: EntityProperty<Entity>;
     }[];
-    comparableProps: EntityProperty<T>[];
-    trackingProps: EntityProperty<T>[];
-    hydrateProps: EntityProperty<T>[];
-    validateProps: EntityProperty<T>[];
-    uniqueProps: EntityProperty<T>[];
-    getterProps: EntityProperty<T>[];
+    comparableProps: EntityProperty<Entity>[];
+    trackingProps: EntityProperty<Entity>[];
+    hydrateProps: EntityProperty<Entity>[];
+    validateProps: EntityProperty<Entity>[];
+    uniqueProps: EntityProperty<Entity>[];
+    getterProps: EntityProperty<Entity>[];
     indexes: {
-        properties?: EntityKey<T> | EntityKey<T>[];
+        properties?: EntityKey<Entity> | EntityKey<Entity>[];
         name?: string;
         type?: string;
         options?: Dictionary;
-        expression?: string | IndexCallback<T>;
+        expression?: string | IndexCallback<Entity>;
+        columns?: IndexColumnOptions[];
+        include?: EntityKey<Entity> | EntityKey<Entity>[];
+        fillFactor?: number;
+        invisible?: boolean;
+        disabled?: boolean;
+        clustered?: boolean;
     }[];
     uniques: {
-        properties?: EntityKey<T> | EntityKey<T>[];
+        properties?: EntityKey<Entity> | EntityKey<Entity>[];
         name?: string;
         options?: Dictionary;
-        expression?: string | IndexCallback<T>;
+        expression?: string | IndexCallback<Entity>;
         deferMode?: DeferMode | `${DeferMode}`;
+        columns?: IndexColumnOptions[];
+        include?: EntityKey<Entity> | EntityKey<Entity>[];
+        fillFactor?: number;
+        disabled?: boolean;
     }[];
-    checks: CheckConstraint<T>[];
+    checks: CheckConstraint<Entity>[];
     repositoryClass?: string;
     repository: () => EntityClass<EntityRepository<any>>;
     hooks: {
-        [K in EventType]?: (keyof T | EventSubscriber<T>[EventType])[];
+        [K in EventType]?: (keyof Entity | EventSubscriber<Entity>[EventType])[];
     };
-    prototype: T;
-    class: EntityClass<T>;
+    prototype: Entity;
+    class: Class;
     abstract: boolean;
     filters: Dictionary<FilterDef>;
     comment?: string;
@@ -504,9 +671,32 @@ export interface EntityMetadata<T = any> {
     hasUniqueProps?: boolean;
     readonly?: boolean;
     polymorphs?: EntityMetadata[];
-    root: EntityMetadata<T>;
+    root: EntityMetadata<Entity>;
     definedProperties: Dictionary;
+    /** For polymorphic M:N pivot tables, maps discriminator values to entity classes */
+    polymorphicDiscriminatorMap?: Dictionary<EntityClass>;
+    /** Inheritance type: 'sti' (Single Table Inheritance) or 'tpt' (Table-Per-Type). Only set on root entities. */
+    inheritanceType?: 'sti' | 'tpt';
+    /** For TPT: direct parent entity metadata (the entity this one extends). */
+    tptParent?: EntityMetadata;
+    /** For TPT: direct child entities (entities that extend this one). */
+    tptChildren?: EntityMetadata[];
+    /** For TPT: all non-abstract descendants, sorted by depth (deepest first). Precomputed during discovery. */
+    allTPTDescendants?: EntityMetadata[];
+    /** For TPT: synthetic property representing the join to the parent table (child PK → parent PK). */
+    tptParentProp?: EntityProperty;
+    /** For TPT: inverse of tptParentProp, used for joining from parent to child (parent PK → child PK). */
+    tptInverseProp?: EntityProperty;
+    /** For TPT: virtual discriminator property name (computed at query time, not persisted). */
+    tptDiscriminatorColumn?: string;
+    /** For TPT: properties defined only in THIS entity (not inherited from parent). */
+    ownProps?: EntityProperty<Entity>[];
     hasTriggers?: boolean;
+    /**
+     * Default ordering for this entity. Applied when querying this entity directly
+     * or when it's populated as a relation. Combined with other orderings based on precedence.
+     */
+    orderBy?: QueryOrderMap<Entity> | QueryOrderMap<Entity>[];
     /** @internal can be used for computed numeric cache keys */
     readonly _id: number;
 }
@@ -714,13 +904,13 @@ export interface MigrationObject {
 type EntityFromInput<T> = T extends readonly EntityName<infer U>[] ? U : T extends EntityName<infer U> ? U : never;
 type FilterDefResolved<T extends object = any> = {
     name: string;
-    cond: FilterQuery<T> | ((args: Dictionary, type: 'read' | 'update' | 'delete', em: any, options?: FindOptions<T, any, any, any> | FindOneOptions<T, any, any, any>, entityName?: EntityName<T>) => MaybePromise<FilterQuery<T>>);
+    cond: FilterQuery<T> | ((args: Dictionary, type: 'read' | 'update' | 'delete', em: any, options?: FindOptions<T, any, any, any> | FindOneOptions<T, any, any, any>, entityName?: string) => MaybePromise<FilterQuery<T>>);
     default?: boolean;
     entity?: EntityName<T> | EntityName<T>[];
     args?: boolean;
     strict?: boolean;
 };
-export type FilterDef<T extends EntityName<any> | readonly EntityName<any>[] = any> = FilterDefResolved<EntityFromInput<T>> & {
+export type FilterDef<T extends EntityName | readonly EntityName[] = any> = FilterDefResolved<EntityFromInput<T>> & {
     entity?: T;
 };
 export type Populate<T, P extends string = never> = readonly AutoPath<T, P, `${PopulatePath}`>[] | false;
@@ -731,39 +921,61 @@ export type PopulateOptions<T> = {
     filter?: boolean;
     joinType?: 'inner join' | 'left join';
     children?: PopulateOptions<T[keyof T]>[];
+    /** When true, ignores `mapToPk` on the property and returns full entity data instead of just PKs. */
+    dataOnly?: boolean;
+};
+export type PopulateHintOptions = {
+    strategy?: LoadStrategy.JOINED | LoadStrategy.SELECT_IN | 'joined' | 'select-in';
+    joinType?: 'inner join' | 'left join';
 };
-type Loadable<T extends object> = Collection<T, any> | Reference<T> | Ref<T> | readonly T[];
-type ExtractType<T> = T extends Loadable<infer U> ? U : T;
+type ExtractType<T> = T extends CollectionShape<infer U> ? U : T extends ReferenceShape<infer U> ? U : T extends Ref<infer U> ? U : T extends readonly (infer U)[] ? U : T;
 type ExtractStringKeys<T> = {
-    [K in keyof T]: CleanKeys<T, K>;
+    [K in keyof T]-?: CleanKeys<T, K>;
 }[keyof T] & {};
-type StringKeys<T, E extends string = never> = T extends Collection<any, any> ? ExtractStringKeys<ExtractType<T>> | E : T extends Reference<any> ? ExtractStringKeys<ExtractType<T>> | E : T extends object ? ExtractStringKeys<ExtractType<T>> | E : never;
+/**
+ * Extracts string keys from an entity type, handling Collection/Reference wrappers.
+ * Simplified to just check `T extends object` since ExtractType handles the unwrapping.
+ */
+type StringKeys<T, E extends string = never> = T extends object ? ExtractStringKeys<ExtractType<T>> | E : never;
 type GetStringKey<T, K extends StringKeys<T, string>, E extends string> = K extends keyof T ? ExtractType<T[K]> : (K extends E ? keyof T : never);
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
-type CollectionKeys<T> = T extends object ? {
-    [K in keyof T]: T[K] extends Collection<any> ? IsAny<T[K]> extends true ? never : K & string : never;
+type RelationKeys<T> = T extends object ? {
+    [K in keyof T]-?: CleanKeys<T, K, true>;
 }[keyof T] & {} : never;
-export type AutoPath<O, P extends string | boolean, E extends string = never, D extends Prev[number] = 9> = P extends boolean ? P : [D] extends [never] ? never : P extends any ? P extends string ? (P & `${string}.` extends never ? P : P & `${string}.`) extends infer Q ? Q extends `${infer A}.${infer B}` ? A extends StringKeys<O, E> ? `${A}.${AutoPath<NonNullable<GetStringKey<O, A, E>>, B, E, Prev[D]>}` : never : Q extends StringKeys<O, E> ? (NonNullable<GetStringKey<O, Q, E>> extends unknown ? Exclude<P, `${string}.`> : never) | (StringKeys<NonNullable<GetStringKey<O, Q, E>>, E> extends never ? never : `${Q & string}.`) : StringKeys<O, E> | `${CollectionKeys<O>}:ref` : never : never : never;
+export type AutoPath<O, P extends string | boolean, E extends string = never, D extends Prev[number] = 9> = P extends boolean ? P : [D] extends [never] ? never : P extends any ? P extends string ? P extends `${infer A}.${infer B}` ? A extends StringKeys<O, E> ? `${A}.${AutoPath<NonNullable<GetStringKey<O, A, E>>, B, E, Prev[D]>}` : never : P extends StringKeys<O, E> ? (NonNullable<GetStringKey<O, P & StringKeys<O, E>, E>> extends unknown ? Exclude<P, `${string}.`> : never) | (StringKeys<NonNullable<GetStringKey<O, P & StringKeys<O, E>, E>>, E> extends never ? never : `${P & string}.`) : StringKeys<O, E> | `${RelationKeys<O>}:ref` : never : never;
 export type UnboxArray<T> = T extends any[] ? ArrayElement<T> : T;
 export type ArrayElement<ArrayType extends unknown[]> = ArrayType extends (infer ElementType)[] ? ElementType : never;
-export type ExpandProperty<T> = T extends Reference<infer U> ? NonNullable<U> : T extends Collection<infer U, any> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
-type LoadedLoadable<T, E extends object> = T extends Collection<any, any> ? LoadedCollection<E> : T extends Reference<any> ? T & LoadedReference<E> : T extends ScalarReference<infer U> ? LoadedScalarReference<U> : T extends Scalar | any[] ? T : E;
+export type ExpandProperty<T> = T extends ReferenceShape<infer U> ? NonNullable<U> : T extends CollectionShape<infer U> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
+type LoadedLoadable<T, E extends object> = T extends CollectionShape ? LoadedCollection<E> : T extends ScalarReference<infer U> ? LoadedScalarReference<U> : T extends ReferenceShape ? T & LoadedReference<E> : T extends Scalar ? T : T extends (infer U)[] ? U extends Scalar ? T : E[] : E;
 type IsTrue<T> = IsNever<T> extends true ? false : T extends boolean ? T extends true ? true : false : false;
 type StringLiteral<T> = T extends string ? string extends T ? never : T : never;
 type Prefix<T, K> = K extends `${infer S}.${string}` ? S : (K extends '*' ? keyof T : K);
 type IsPrefixedExclude<T, K extends keyof T, E extends string> = K extends E ? never : K;
-export type IsPrefixed<T, K extends keyof T, L extends string, E extends string = never> = IsNever<E> extends false ? IsPrefixedExclude<T, K, E> : K extends symbol ? never : IsTrue<L> extends true ? (T[K] & {} extends Loadable<any> ? K : never) : IsNever<StringLiteral<L>> extends true ? never : K extends Prefix<T, L> ? K : K extends PrimaryProperty<T> ? K : never;
+export type IsPrefixed<T, K extends keyof T, L extends string, E extends string = never> = IsNever<E> extends false ? IsPrefixedExclude<T, K, E> : K extends symbol ? never : IsTrue<L> extends true ? (T[K] & {} extends LoadableShape ? K : never) : IsNever<StringLiteral<L>> extends true ? never : L extends '*' ? K : K extends Prefix<T, L> ? K : K extends PrimaryProperty<T> ? K : never;
 type Suffix<Key, Hint extends string, All = true | '*'> = Hint extends `${infer Pref}.${infer Suf}` ? (Pref extends Key ? Suf : never) : Hint extends All ? Hint : never;
-export type IsSubset<T, U> = keyof U extends keyof T ? {} : Dictionary extends U ? {} : {
+export type IsSubset<T, U> = keyof U extends keyof T ? {} : string extends keyof U ? {} : {
     [K in keyof U as K extends keyof T ? never : CleanKeys<U, K>]: never;
 };
-declare const __selectedType: unique symbol;
-declare const __loadedType: unique symbol;
-type AnyStringToNever<T> = string extends T ? never : T;
-export type MergeSelected<T, U, F extends string> = T extends Loaded<infer TT, infer P, infer FF, infer E> ? IsNever<Exclude<E, F>> extends true ? Loaded<TT, P, AnyStringToNever<F> | AnyStringToNever<FF>> : Loaded<TT, AnyStringToNever<P>, AnyStringToNever<FF>, AnyStringToNever<Exclude<E, F>>> : T;
-type MergeFields<F1 extends string, F2 extends string, P1, P2> = P1 | P2 extends '*' ? '*' : F1 | F2;
-type MergeExcludes<F extends string, E extends string> = F extends E ? never : Exclude<E, F>;
-export type MergeLoaded<T, U, P extends string, F extends string, E extends string, R extends boolean = false> = T extends Loaded<U, infer PP, infer FF, infer EE> ? string extends FF ? Loaded<T, P, F, AnyStringToNever<EE> | E> : string extends P ? Loaded<U, never, F | (FF & string), MergeExcludes<F | (FF & string), EE | E>> : Loaded<U, P | AnyStringToNever<PP>, MergeFields<F, AnyStringToNever<FF>, P, PP>, MergeExcludes<MergeFields<F, AnyStringToNever<FF>, P, PP>, (R extends true ? never : EE) | E>> : Loaded<T, P, F>;
+/**
+ * Fast check if T is a Loaded type by looking for the marker symbol.
+ * This is much cheaper than matching against the full Loaded structure.
+ */
+type IsLoadedType<T> = T extends {
+    [__loadedType]?: any;
+} ? true : false;
+/**
+ * Optimized MergeSelected using intersection instead of extraction.
+ * When T is already Loaded, we intersect with a new Loaded type for the selected fields.
+ * This avoids the expensive pattern matching needed to extract hints from Loaded types.
+ */
+export type MergeSelected<T, U, F extends string> = IsLoadedType<T> extends true ? T & Loaded<U, never, F, never> : T;
+/**
+ * Optimized MergeLoaded using intersection instead of extraction.
+ * When T is already Loaded, we intersect with a new Loaded type for the additional hints.
+ * This avoids the expensive pattern matching needed to extract hints from Loaded types.
+ * Used for `em.populate` and `em.refresh`.
+ */
+export type MergeLoaded<T, U, P extends string, F extends string, E extends string, R extends boolean = false> = IsLoadedType<T> extends true ? T & Loaded<U, P, F, E> : Loaded<T, P, F, E>;
 export type AddOptional<T> = undefined | null extends T ? null | undefined : null extends T ? null : undefined extends T ? undefined : never;
 type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractType<T>, L, F, E>>;
 export type AddEager<T> = ExtractEagerProps<T> & string;
@@ -782,18 +994,18 @@ type LoadedEntityType<T> = {
 };
 export type EntityType<T> = T | LoadedEntityType<T>;
 export type FromEntityType<T> = T extends LoadedEntityType<infer U> ? U : T;
-type LoadedInternal<T, L extends string = never, F extends string = '*', E extends string = never> = [
-    F
-] extends ['*'] ? IsNever<E> extends true ? T & {
+type LoadedInternal<T, L extends string = never, F extends string = '*', E extends string = never> = [F] extends ['*'] ? IsNever<E> extends true ? T & {
     [K in keyof T as IsPrefixed<T, K, ExpandHint<T, L>>]: LoadedProp<NonNullable<T[K]>, Suffix<K, L>, Suffix<K, F>, Suffix<K, E>> | AddOptional<T[K]>;
 } : {
     [K in keyof T as IsPrefixed<T, K, ExpandHint<T, L>, E>]: LoadedProp<NonNullable<T[K]>, Suffix<K, L>, Suffix<K, F>, Suffix<K, E>> | AddOptional<T[K]>;
 } : Selected<T, L, F>;
 /**
  * Represents entity with its loaded relations (`populate` hint) and selected properties (`fields` hint).
+ * The __loadHint marker uses contravariance to ensure Loaded<A, 'b'> is NOT assignable to Loaded<A, 'b.c'>.
  */
 export type Loaded<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedInternal<T, L, F, E> & {
     [__loadedType]?: T;
+    [__loadHint]?: (hint: Prefixes<L>) => void;
 };
 export interface LoadedReference<T> extends Reference<NonNullable<T>> {
     $: NonNullable<T>;
@@ -813,12 +1025,12 @@ export interface Highlighter {
     highlight(text: string): string;
 }
 export interface IMetadataStorage {
-    getAll(): Dictionary<EntityMetadata>;
-    get<T = any>(entity: string, init?: boolean, validate?: boolean): EntityMetadata<T>;
-    find<T = any>(entity: string): EntityMetadata<T> | undefined;
-    has(entity: string): boolean;
-    set(entity: string, meta: EntityMetadata): EntityMetadata;
-    reset(entity: string): void;
+    getAll(): Map<EntityName, EntityMetadata>;
+    get<T = any>(entity: EntityName<T>, init?: boolean, validate?: boolean): EntityMetadata<T>;
+    find<T = any>(entity: EntityName<T>): EntityMetadata<T> | undefined;
+    has<T>(entity: EntityName<T>): boolean;
+    set<T>(entity: EntityName<T>, meta: EntityMetadata): EntityMetadata;
+    reset<T>(entity: EntityName<T>): void;
 }
 export interface IHydrator {
     /**
@@ -847,10 +1059,13 @@ export interface Seeder<T extends Dictionary = Dictionary> {
 export type ConnectionType = 'read' | 'write';
 export type MetadataProcessor = (metadata: EntityMetadata[], platform: Platform) => MaybePromise<void>;
 export type MaybeReturnType<T> = T extends (...args: any[]) => infer R ? R : T;
-export interface EntitySchemaWithMeta<TName extends string = string, TTableName extends string = string, TEntity = any, TBase = never, TProperties extends Record<string, any> = Record<string, any>> extends EntitySchema<TEntity, TBase> {
+export interface EntitySchemaWithMeta<TName extends string = string, TTableName extends string = string, TEntity = any, TBase = never, TProperties extends Record<string, any> = Record<string, any>, TClass extends EntityCtor = EntityCtor<TEntity>> extends EntitySchema<TEntity, TBase, TClass> {
     readonly name: TName;
     readonly properties: TProperties;
     readonly tableName: TTableName;
+    /** @internal Direct entity type access - avoids expensive pattern matching */
+    readonly '~entity': TEntity;
 }
-export type InferEntity<Schema> = Schema extends EntitySchemaWithMeta<any, any, infer Entity, any, any> ? Entity : Schema extends EntitySchema<infer Entity> ? Entity : Schema extends EntityClass<infer Entity> ? Entity : Schema;
-export {};
+export type InferEntity<Schema> = Schema extends {
+    '~entity': infer E;
+} ? E : Schema extends EntitySchema<infer Entity> ? Entity : Schema extends EntityClass<infer Entity> ? Entity : Schema;