@mikro-orm/core 7.1.0-dev.9 → 7.1.0

package/typings.d.ts

@@ -10,8 +10,9 @@ import { Reference, type ScalarReference } from './entity/Reference.js';
 import type { SerializationContext } from './serialization/SerializationContext.js';
 import type { SerializeOptions } from './serialization/EntitySerializer.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
+import type { Routine } from './metadata/Routine.js';
 import type { EntitySchema } from './metadata/EntitySchema.js';
-import type { IndexColumnOptions } from './metadata/types.js';
+import type { EntityPartitionBy, 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';
@@ -113,7 +114,7 @@ type LoadedReferenceShape<T = any> = ReferenceShape & {
  * 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[];
+type LoadableShape = CollectionShape | ReferenceShape | LazyRef.Brand<any> | readonly any[];
 /** Gets all keys from all members of a union type (distributes over the union). */
 export type UnionKeys<T> = T extends any ? keyof T : never;
 /** Gets the type of a property from all union members that have it (distributes over the union). */
@@ -467,12 +468,12 @@ type NonArrayObject = object & {
 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 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>;
+} ? C extends true ? Raw : Runtime : T extends LazyRef.Brand<infer U> ? EntityDataNested<U, C> : 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>;
 /** Like `EntityDataProp` but used in `RequiredEntityData` context with required/optional key distinction. */
 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 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>;
+} ? C extends true ? Raw : Runtime : T extends LazyRef.Brand<infer U> ? RequiredEntityDataNested<U, O, C> : 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>;
 /** Nested entity data shape for embedded or related entities within `EntityData`. */
 export type EntityDataNested<T, C extends boolean = false> = T extends undefined ? never : T extends any[] ? Readonly<T> : EntityData<T, C> | ExpandEntityProp<T, C>;
 type UnwrapScalarRef<T> = T extends ScalarReference<infer U> ? U : T;
@@ -521,6 +522,35 @@ type Relation<T> = {
 export type Rel<T> = T;
 /** Alias for `ScalarReference` (see {@apilink Ref}). */
 export type ScalarRef<T> = ScalarReference<T>;
+/**
+ * Type-level marker for a to-one relation that is **direct at runtime** (no `Reference` wrapper) but
+ * **restricted at compile time** until narrowed via `Loaded<>`.
+ *
+ * Use as the property type on a `@ManyToOne`/`@OneToOne` relation that does **not** have `ref: true`:
+ *
+ * ```ts
+ * @ManyToOne(() => User)
+ * author!: LazyRef<User>;
+ * ```
+ *
+ * Semantics:
+ * - **Runtime**: identical to a plain direct relation — `article.author` is a `User` instance (stub or hydrated),
+ *   `article.author instanceof User` is `true`, no `Reference` object is created.
+ * - **Type (unloaded view)**: only the primary key is accessible. Accessing other properties is a compile error.
+ * - **Type (loaded view)**: once the relation is in the populate hint of a `Loaded<Entity, 'author'>`, it narrows
+ *   back to the full entity — no `.$` or `.get()` indirection needed.
+ *
+ * Note: the safety is purely compile-time. JS code or `as any` casts bypass it.
+ */
+export type LazyRef<T extends object> = IsAny<T> extends true ? LazyRef.Brand<T> : {
+    [K in PrimaryProperty<T> & keyof T]: T[K];
+} & LazyRef.Brand<T>;
+export declare namespace LazyRef {
+    const __lazyRef: unique symbol;
+    interface Brand<T> {
+        [__lazyRef]?: (arg: T) => T;
+    }
+}
 /** Alias for `Reference<T> & { id: number }` (see {@apilink Ref}). */
 export type EntityRef<T extends object> = true extends IsUnknown<PrimaryProperty<T>> ? Reference<T> : IsAny<T> extends true ? Reference<T> : {
     [K in PrimaryProperty<T> & keyof T]: T[K];
@@ -644,21 +674,39 @@ export type SchemaTable = {
 export type FormulaColumns<T> = Record<PropertyName<T>, string> & {
     toString(): string;
 };
+/**
+ * Column reference for schema callbacks. Behaves like a string (coercible via `toString()`),
+ * with arbitrary nested property access for embedded sub-columns (e.g. `cols.address.city`).
+ */
+export type SchemaColumnRef = string & {
+    readonly [key: string]: SchemaColumnRef;
+};
 /**
  * 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).
+ * Embedded properties expose their sub-columns via nested access (e.g. `cols.address.city`),
+ * while coercing to the embedded property's own column name via `toString()` (matches the
+ * pre-7712 behaviour, regardless of any custom `prefix`).
+ */
+export type SchemaColumns<T> = Record<PropertyName<T>, SchemaColumnRef>;
+/**
+ * Callback for custom index expressions. Receives column mappings, table info, and the index name.
+ * The runtime `columns` object includes nested entries for embedded properties (see `SchemaColumnRef`);
+ * cast to `SchemaColumns<T>` if you need typed nested access.
  */
-export type SchemaColumns<T> = Record<PropertyName<T>, string>;
-/** Callback for custom index expressions. Receives column mappings, table info, and the index name. */
 export type IndexCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable, indexName: string) => string | Raw;
 /** Callback for computed (formula) properties. Receives column mappings and table info, returns a SQL expression. */
 export type FormulaCallback<T> = (columns: FormulaColumns<T>, table: FormulaTable) => string | Raw;
 /** Callback for CHECK constraint expressions. Receives column mappings and table info. */
-export type CheckCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
+export type CheckCallback<T> = (columns: SchemaColumns<T>, table: SchemaTable) => string | Raw;
 /** Callback for trigger body expressions. Receives column mappings and table info. */
 export type TriggerCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
-/** Callback for generated (computed) column expressions. Receives column mappings and table info. */
+/**
+ * Callback for generated (computed) column expressions. Receives column mappings and table info.
+ * The runtime `columns` object includes nested entries for embedded properties (see `SchemaColumnRef`);
+ * cast to `SchemaColumns<T>` if you need typed nested access.
+ */
 export type GeneratedColumnCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
 /** Definition of a CHECK constraint on a table or property. */
 export interface CheckConstraint<T = any> {
@@ -683,6 +731,197 @@ export interface TriggerDef<T = any> {
     /** Raw DDL escape hatch — full CREATE TRIGGER statement. Mutually exclusive with `body`. */
     expression?: string;
 }
+export type RoutineParamDirection = 'in' | 'out' | 'inout';
+/** Mirrors MySQL/MariaDB's `SQL DATA ACCESS` clause; ignored by other dialects. */
+export type RoutineDataAccess = 'contains-sql' | 'no-sql' | 'reads-sql-data' | 'modifies-sql-data';
+export type RoutineSecurity = 'invoker' | 'definer';
+export type RoutineKind = 'procedure' | 'function';
+export type RoutineIgnoreField = 'body' | 'comment' | 'security' | 'deterministic' | 'definer';
+export type RoutineParamMap<T> = Record<PropertyName<T>, string>;
+export type RoutineBodyCallback<T> = (params: RoutineParamMap<T>, em: any) => string | Raw;
+/**
+ * Routine return shape:
+ *  - omitted/`void`: procedures with no result set
+ *  - `() => Entity` (single or tuple): hydrated row arrays, one per result set
+ *  - `{ type: Type<...> }`: scalar function return — runtime/column types both inferred
+ *    from the {@link Type} generics
+ *  - `{ runtimeType, columnType }`: scalar function return with explicit SQL+TS types
+ *  - `{ hydrate }`: fully custom row mapping
+ */
+export type RoutineReturns<T = unknown> = (() => EntityName<any>) | (() => EntityName<any>)[] | {
+    type: Type<unknown> | Constructor<Type<unknown>>;
+    nullable?: boolean;
+} | {
+    runtimeType: RoutineRuntimeType;
+    columnType?: string;
+    nullable?: boolean;
+    customType?: Type<unknown> | Constructor<Type<unknown>>;
+} | {
+    hydrate: (rows: Dictionary[][], args: T, em: any) => unknown;
+};
+/** JS fallback registered as a UDF on SQLite (better-sqlite3). Functions only. */
+export type RoutineJsBody<T> = (params: T) => unknown;
+export interface RoutineDef<T = any> {
+    type: RoutineKind;
+    name?: string;
+    schema?: string;
+    comment?: string;
+    security?: RoutineSecurity;
+    /** User the routine runs as when `security: 'definer'`. */
+    definer?: string;
+    deterministic?: boolean;
+    /** MySQL/MariaDB only. */
+    dataAccess?: RoutineDataAccess;
+    language?: 'sql' | 'plpgsql' | 'tsql' | 'plsql' | AnyString;
+    /** Mutually exclusive with `expression`. */
+    body?: string | Raw | RoutineBodyCallback<T>;
+    /** Raw `CREATE PROCEDURE`/`FUNCTION` escape hatch — schema diff can't detect changes. Prefer `body`. */
+    expression?: string;
+    /** JS fallback registered as a UDF on SQLite (better-sqlite3). Functions only. */
+    bodyJs?: RoutineJsBody<T>;
+    returns?: RoutineReturns<T>;
+    /** Skip selected fields in schema diff; useful when the engine normalises the body differently. */
+    ignoreSchemaChanges?: RoutineIgnoreField[];
+}
+export interface RoutineProperty<Owner = any> {
+    name: EntityKey<Owner>;
+    /** SQL string, or a `Type` instance (resolved to the dialect column type at schema-gen time via `getColumnType`). */
+    type: keyof typeof types | AnyString | Type<unknown>;
+    runtimeType: EntityProperty['runtimeType'];
+    /** Singleton array to align with EntityProperty's `columnTypes`/Type API surface. */
+    columnTypes: string[];
+    customType?: Type<unknown>;
+    direction: RoutineParamDirection;
+    /** Required for OUT/INOUT params — wraps the JS-side value in `ScalarReference`. */
+    ref?: boolean;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    nullable?: boolean;
+    /** Default expression used when the caller omits the parameter, where the dialect supports it. */
+    defaultRaw?: string;
+    /** Original declaration order, used to rebuild positional argument lists. */
+    index: number;
+}
+export interface RoutineParamConfig {
+    runtimeType?: RoutineRuntimeType;
+    type?: keyof typeof types | AnyString | Type<any> | Constructor<Type<any>>;
+    direction?: RoutineParamDirection;
+    ref?: boolean;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    nullable?: boolean;
+    defaultRaw?: string;
+    /** Marshals the param via `Type.convertToDatabaseValue` inbound and `convertToJSValue` outbound. */
+    customType?: Type<unknown> | Constructor<Type<unknown>>;
+}
+/** Routine declaration shape accepted by the {@link Routine} class. */
+export interface RoutineConfig<T = any> extends Omit<RoutineDef<T>, 'name'> {
+    name: string;
+    /** Order is preserved from `Object.keys`. */
+    params?: Record<string, RoutineParamConfig>;
+}
+export type RoutineRuntimeTypeMap = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    bigint: bigint;
+    Buffer: Buffer;
+    Date: Date;
+    object: Dictionary;
+    any: any;
+};
+/** Narrow union (vs `EntityProperty['runtimeType']`) so literals survive `const` inference and feed args/return inference. */
+export type RoutineRuntimeType = keyof RoutineRuntimeTypeMap;
+type RoutineRuntimeOf<R> = R extends keyof RoutineRuntimeTypeMap ? RoutineRuntimeTypeMap[R] : unknown;
+type Nullify<P, V> = P extends {
+    nullable: true;
+} ? V | null : V;
+type StripSqlTypeArgs<S extends string> = S extends `${infer Base}(${string}` ? Base : S;
+type SqlStringTypes = 'varchar' | 'char' | 'character' | 'nvarchar' | 'nchar' | 'text' | 'mediumtext' | 'longtext' | 'tinytext' | 'ntext' | 'clob' | 'nclob' | 'citext' | 'xml' | 'uuid' | 'string' | 'decimal' | 'numeric' | 'money' | 'bigint' | 'int8' | 'bigserial';
+type SqlNumberTypes = 'int' | 'integer' | 'smallint' | 'tinyint' | 'mediumint' | 'int2' | 'int4' | 'serial' | 'smallserial' | 'real' | 'float' | 'float4' | 'float8' | 'double';
+type SqlBooleanTypes = 'boolean' | 'bool' | 'bit';
+type SqlDateTypes = 'date' | 'datetime' | 'datetime2' | 'smalldatetime' | 'timestamp' | 'timestamptz' | 'time' | 'timetz';
+type SqlJsonTypes = 'json' | 'jsonb';
+type SqlBufferTypes = 'blob' | 'tinyblob' | 'mediumblob' | 'longblob' | 'binary' | 'varbinary' | 'bytea' | 'bytes' | 'image' | 'raw';
+type SqlTypeMap = {
+    [K in SqlStringTypes]: string;
+} & {
+    [K in SqlNumberTypes]: number;
+} & {
+    [K in SqlBooleanTypes]: boolean;
+} & {
+    [K in SqlDateTypes]: Date;
+} & {
+    [K in SqlJsonTypes]: Dictionary;
+} & {
+    [K in SqlBufferTypes]: Buffer;
+} & {
+    'character varying': string;
+    'double precision': number;
+    'time with time zone': Date;
+    'timestamp with time zone': Date;
+    'long raw': Buffer;
+};
+type LookupSqlType<K> = K extends keyof SqlTypeMap ? SqlTypeMap[K] : any;
+/**
+ * Maps a SQL-flavoured `type` string (e.g. `'varchar(255)'`, `'int'`, `'timestamp'`) to a TS
+ * runtime type, used as a fallback when {@link RoutineParamConfig} does not declare an explicit
+ * `runtimeType`. Length/precision arguments are stripped, the lowercase token is matched
+ * against {@link SqlTypeMap}. `decimal`/`numeric`/`money`/`bigint` default to `string` since
+ * drivers typically return them as strings to preserve precision; opt in to `number` or
+ * `bigint` via `runtimeType` when the value range is safe. Unrecognised or genuinely
+ * ambiguous types (`refcursor`, `sys_refcursor`, …) fall through to `any`.
+ */
+export type SqlTypeToTs<S> = S extends string ? Lowercase<S> extends `tinyint(1)${string}` ? boolean : LookupSqlType<StripSqlTypeArgs<Lowercase<S>>> : any;
+/** Strips `null | undefined` from a `Type<JSType, _>` JSType, so e.g. `StringType extends Type<string | null | undefined>` resolves to `string`. */
+type TypeJsType<T> = T extends Type<infer J, any> ? Exclude<J, null | undefined> : T extends new (...args: any[]) => Type<infer J, any> ? Exclude<J, null | undefined> : never;
+/**
+ * TS value type for a single routine parameter. Resolution order:
+ *
+ * 1. explicit `runtimeType`
+ * 2. `type` set to a {@link Type} class or instance — JSType is extracted from the Type generic
+ * 3. `type` set to a SQL string — mapped via {@link SqlTypeToTs}
+ * 4. fallback `any`
+ *
+ * `ref: true` wraps the result in `ScalarReference`; `nullable: true` adds `| null`.
+ */
+export type RoutineParamValue<P> = P extends {
+    runtimeType: infer R;
+} ? P extends {
+    ref: true;
+} ? ScalarReference<Nullify<P, RoutineRuntimeOf<R>>> : Nullify<P, RoutineRuntimeOf<R>> : P extends {
+    type: infer T;
+} ? [TypeJsType<T>] extends [never] ? T extends string ? P extends {
+    ref: true;
+} ? ScalarReference<Nullify<P, SqlTypeToTs<T>>> : Nullify<P, SqlTypeToTs<T>> : P extends {
+    ref: true;
+} ? ScalarReference<any> : any : P extends {
+    ref: true;
+} ? ScalarReference<Nullify<P, TypeJsType<T>>> : Nullify<P, TypeJsType<T>> : P extends {
+    ref: true;
+} ? ScalarReference<any> : any;
+/** Default `TArgs` for {@link Routine}; consumers use {@link RoutineArgs}, which honours overrides from {@link Routine.create}. */
+export type RoutineArgsOf<Config> = Config extends {
+    params: infer P;
+} ? P extends Record<string, RoutineParamConfig> ? {
+    [K in keyof P]: RoutineParamValue<P[K]>;
+} : Record<string, unknown> : Record<string, unknown>;
+/** Default `TReturn` for {@link Routine}; consumers use {@link RoutineReturn}, which honours overrides from {@link Routine.create}. */
+export type RoutineReturnOf<Config> = Config extends {
+    returns: infer R;
+} ? R extends {
+    runtimeType: infer RT;
+} ? Nullify<R, RoutineRuntimeOf<RT>> : R extends {
+    type: infer T;
+} ? [TypeJsType<T>] extends [never] ? unknown : Nullify<R, TypeJsType<T>> : R extends readonly (() => EntityName<any>)[] ? {
+    [K in keyof R]: R[K] extends () => EntityName<infer E> ? E[] : never;
+} : R extends () => EntityName<infer E> ? E[] : R extends {
+    hydrate: (...args: any[]) => infer H;
+} ? Awaited<H> : void : void;
+export type RoutineArgs<R> = R extends Routine<any, infer A, any> ? A : Record<string, unknown>;
+export type RoutineReturn<R> = R extends Routine<any, any, infer Re> ? Re : unknown;
 /** Branded string that accepts any string value while preserving autocompletion for known literals. */
 export type AnyString = string & {};
 /** Describes a single property (column, relation, or embedded) within an entity's metadata. */
@@ -780,11 +1019,12 @@ export interface EntityProperty<Owner = any, Target = any> {
     serializer?: (value: any, options?: SerializeOptions<any>) => any;
     serializedName?: string;
     comment?: string;
+    collation?: string;
     /** mysql only */
     extra?: string;
     userDefined?: boolean;
     optional?: boolean;
-    ignoreSchemaChanges?: ('type' | 'extra' | 'default')[];
+    ignoreSchemaChanges?: ('type' | 'extra' | 'default' | 'collation')[];
     deferMode?: DeferMode;
     createForeignKeyConstraint: boolean;
     foreignKeyName?: string;
@@ -812,8 +1052,12 @@ export declare class EntityMetadata<Entity = any, Class extends EntityCtor<Entit
     /**
      * Creates a column mapping for schema callbacks (indexes, checks, generated columns).
      * For TPT entities, only includes properties that belong to the current table (ownProps).
+     * Embedded properties expose their sub-columns via nested access (e.g. `cols.address.city`),
+     * while still coercing to the embedded column prefix when used as a string (GH #7712).
      */
     createSchemaColumnMappingObject(): SchemaColumns<Entity>;
+    /** @internal Recursively builds a column mapping for an embedded property's sub-columns. */
+    private static buildEmbeddedColumnMapping;
     get tableName(): string;
     set tableName(name: string);
     get uniqueName(): string;
@@ -832,7 +1076,6 @@ 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;
@@ -845,8 +1088,15 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     materialized?: boolean;
     /** For materialized views, whether data is populated on creation. Defaults to true. */
     withData?: boolean;
+    /** PostgreSQL partitioning definition for this table. */
+    partitionBy?: EntityPartitionBy<Entity>;
     expression?: string | ((em: any, where: ObjectQuery<Entity>, options: FindOptions<Entity, any, any, any>, stream?: boolean) => MaybePromise<Raw | object | string>);
+    /** Property name on the entity that stores the discriminator value. */
+    discriminator?: EntityKey<Entity> | AnyString;
+    /** Internally holds the discriminator property name (legacy) or a column-name override (when different from `discriminator`); normalized in `EntitySchema.init()`. */
     discriminatorColumn?: EntityKey<Entity> | AnyString;
+    /** Explicit column-name override for the auto-managed discriminator property. Set when both `discriminator` and `discriminatorColumn` are provided and differ. */
+    discriminatorFieldName?: string;
     discriminatorValue?: number | string;
     discriminatorMap?: Dictionary<EntityClass>;
     embeddable: boolean;
@@ -883,6 +1133,7 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
         type?: string;
         options?: Dictionary;
         expression?: string | IndexCallback<Entity>;
+        where?: string | FilterQuery<Entity>;
         columns?: IndexColumnOptions[];
         include?: EntityKey<Entity> | EntityKey<Entity>[];
         fillFactor?: number;
@@ -895,6 +1146,7 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
         name?: string;
         options?: Dictionary;
         expression?: string | IndexCallback<Entity>;
+        where?: string | FilterQuery<Entity>;
         deferMode?: DeferMode | `${DeferMode}`;
         columns?: IndexColumnOptions[];
         include?: EntityKey<Entity> | EntityKey<Entity>[];
@@ -923,6 +1175,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     polymorphicDiscriminatorMap?: Dictionary<EntityClass>;
     /** Inheritance type: 'sti' (Single Table Inheritance) or 'tpt' (Table-Per-Type). Only set on root entities. */
     inheritanceType?: 'sti' | 'tpt';
+    /** Legacy alias populated from `EntityOptions.inheritance`; mirrored to `inheritanceType` during discovery. */
+    inheritance?: 'tpt';
     /** For TPT: direct parent entity metadata (the entity this one extends). */
     tptParent?: EntityMetadata;
     /** For TPT: direct child entities (entities that extend this one). */
@@ -950,6 +1204,11 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
 export interface CreateSchemaOptions {
     wrap?: boolean;
     schema?: string;
+    /**
+     * When true, entities with a wildcard schema (`schema: '*'`) are included in the generated DDL.
+     * Without this, wildcard tables are skipped.
+     */
+    includeWildcardSchema?: boolean;
 }
 /** Options for `ISchemaGenerator.clear()` to truncate/clear database tables. */
 export interface ClearDatabaseOptions {
@@ -979,6 +1238,13 @@ export interface UpdateSchemaOptions<DatabaseSchema = unknown> {
     dropTables?: boolean;
     schema?: string;
     fromSchema?: DatabaseSchema;
+    /**
+     * When true, entities with a wildcard schema (`schema: '*'`) are included in the diff so migrations
+     * can be generated for them. The emitted SQL is unqualified — and therefore safe to apply against
+     * any schema at runtime — only when neither `options.schema` nor `config.schema` is set; otherwise
+     * wildcard tables inherit that schema qualifier.
+     */
+    includeWildcardSchema?: boolean;
 }
 /** Options for `ISchemaGenerator.refresh()` which drops and recreates the schema. */
 export interface RefreshDatabaseOptions extends CreateSchemaOptions {
@@ -1059,6 +1325,12 @@ export type MigrateOptions = {
     to?: string | number;
     migrations?: string[];
     transaction?: Transaction;
+    /**
+     * Target schema to run migrations against. Issues a driver-specific "set current schema"
+     * statement (e.g. `SET search_path` on PostgreSQL) before each migration, and places the
+     * tracking table in this schema. Overrides `migrations.schema` from config. Not supported on MSSQL.
+     */
+    schema?: string;
 };
 /** Result of creating a new migration file, including the generated code and schema diff. */
 export type MigrationResult = {
@@ -1076,21 +1348,25 @@ export type MigrationRow = {
  * @internal
  */
 export interface IMigrationRunner {
-    run(migration: Migration, method: 'up' | 'down'): Promise<void>;
+    run(migration: Migration, method: 'up' | 'down', afterRun?: (tx?: Transaction) => Promise<void>): Promise<void>;
     setMasterMigration(trx: Transaction): void;
     unsetMasterMigration(): void;
+    setRunSchema?(schema?: string): void;
+    unsetRunSchema?(): void;
 }
 /**
  * @internal
  */
 export interface IMigratorStorage {
     executed(): Promise<string[]>;
-    logMigration(params: Dictionary): Promise<void>;
-    unlogMigration(params: Dictionary): Promise<void>;
+    logMigration(params: Dictionary, tx?: Transaction): Promise<void>;
+    unlogMigration(params: Dictionary, tx?: Transaction): Promise<void>;
     getExecutedMigrations(): Promise<MigrationRow[]>;
     ensureTable?(): Promise<void>;
     setMasterMigration(trx: Transaction): void;
     unsetMasterMigration(): void;
+    setRunSchema?(schema?: string): void;
+    unsetRunSchema?(): void;
     getMigrationName(name: string): string;
     getTableName?(): {
         schemaName?: string;
@@ -1117,11 +1393,15 @@ export interface IMigrator {
     /**
      * Returns list of already executed migrations.
      */
-    getExecuted(): Promise<MigrationRow[]>;
+    getExecuted(options?: {
+        schema?: string;
+    }): Promise<MigrationRow[]>;
     /**
      * Returns list of pending (not yet executed) migrations found in the migration directory.
      */
-    getPending(): Promise<MigrationInfo[]>;
+    getPending(options?: {
+        schema?: string;
+    }): Promise<MigrationInfo[]>;
     /**
      * Executes specified migrations. Without parameter it will migrate up to the latest version.
      */
@@ -1217,13 +1497,32 @@ export type PopulateOptions<T> = {
     children?: PopulateOptions<T[keyof T]>[];
     /** When true, ignores `mapToPk` on the property and returns full entity data instead of just PKs. */
     dataOnly?: boolean;
+    /** Limit the number of items loaded per parent entity. Collections will be marked as partial and readonly. */
+    limit?: number;
+    /** Offset for per-parent limiting (used with `limit`). */
+    offset?: number;
+    /** Order by clause for per-parent limiting. Takes precedence over nested `FindOptions.orderBy`. */
+    orderBy?: QueryOrderMap<T[keyof T]>;
 };
 /** Inline options that can be appended to populate hint strings (e.g., strategy, join type). */
 export type PopulateHintOptions = {
     strategy?: LoadStrategy.JOINED | LoadStrategy.SELECT_IN | 'joined' | 'select-in';
     joinType?: 'inner join' | 'left join';
+    /** Limit the number of items loaded per parent entity. Collections will be marked as partial and readonly. */
+    limit?: number;
+    /** Offset for per-parent limiting (used with `limit`). */
+    offset?: number;
+    /** Order by clause for per-parent limiting. Takes precedence over nested `FindOptions.orderBy`. */
+    orderBy?: QueryOrderMap<any>;
 };
 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;
+/**
+ * Like {@link ExtractType} but also unwraps {@link LazyRef}. Kept separate so {@link ExtractType}'s
+ * hot path (used by `IsOptional`, `EntityData`, `RequiredEntityData`) doesn't pay the cost of the
+ * extra branch — those contexts handle `LazyRef` in their own earlier branches (see
+ * `EntityDataProp` / `RequiredEntityDataProp`) before delegating to `ExtractType`.
+ */
+type ExtractTypeWithLazyRef<T> = T extends LazyRef.Brand<infer U> ? U : ExtractType<T>;
 type ExtractStringKeys<T> = {
     [K in keyof T]-?: CleanKeys<T, K>;
 }[keyof T] & {};
@@ -1231,8 +1530,8 @@ type ExtractStringKeys<T> = {
  * 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 StringKeys<T, E extends string = never> = T extends object ? ExtractStringKeys<ExtractTypeWithLazyRef<T>> | E : never;
+type GetStringKey<T, K extends StringKeys<T, string>, E extends string> = K extends keyof T ? ExtractTypeWithLazyRef<T[K]> : K extends E ? keyof T : never;
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 type RelationKeys<T> = T extends object ? {
     [K in keyof T]-?: CleanKeys<T, K, true>;
@@ -1247,8 +1546,8 @@ export type UnboxArray<T> = T extends any[] ? ArrayElement<T> : T;
 /** Extracts the element type from an array type. */
 export type ArrayElement<ArrayType extends unknown[]> = ArrayType extends (infer ElementType)[] ? ElementType : never;
 /** Unwraps a property type from its wrapper (Reference, Collection, or array) to the inner entity type. */
-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;
+export type ExpandProperty<T> = T extends LazyRef.Brand<infer U> ? NonNullable<U> : 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 LazyRef.Brand<any> ? E : 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;
@@ -1282,7 +1581,7 @@ export type MergeSelected<T, U, F extends string> = IsLoadedType<T> extends true
 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>;
 /** Extracts the nullability modifiers (`null`, `undefined`, or both) from a type `T`. */
 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>>;
+type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractTypeWithLazyRef<T>, L, F, E>>;
 /** Extracts the eager-loaded property names declared via `[EagerProps]` as a string union. */
 export type AddEager<T> = ExtractEagerProps<T> & string;
 /** Combines an explicit populate hint `L` with the entity's eagerly loaded properties. */
@@ -1397,15 +1696,18 @@ export type MaybeReturnType<T> = T extends (...args: any[]) => infer R ? R : T;
  * Extended `EntitySchema` interface that carries additional type-level metadata (entity name, properties, table name).
  * Returned by `defineEntity()` to provide strong type inference without explicit generics.
  */
-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> {
+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>, TDiscriminatorColumn extends string | undefined = undefined> 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;
+    /** @internal Type-level marker carrying the discriminator column name, used by `defineEntity()` to narrow inherited discriminator properties to the literal `discriminatorValue` of each child schema. */
+    readonly '~discriminatorColumn'?: TDiscriminatorColumn;
     /** @internal */
     readonly class: TClass & {
         '~entityName'?: TName;
+        '~discriminatorColumn'?: TDiscriminatorColumn;
     };
 }
 /**

package/typings.js

@@ -133,16 +133,37 @@ export class EntityMetadata {
     /**
      * Creates a column mapping for schema callbacks (indexes, checks, generated columns).
      * For TPT entities, only includes properties that belong to the current table (ownProps).
+     * Embedded properties expose their sub-columns via nested access (e.g. `cols.address.city`),
+     * while still coercing to the embedded column prefix when used as a string (GH #7712).
      */
     createSchemaColumnMappingObject() {
         // For TPT entities, only include properties that belong to this entity's table
         const props = this.inheritanceType === 'tpt' && this.ownProps ? this.ownProps : Object.values(this.properties);
-        return props.reduce((o, prop) => {
-            if (prop.fieldNames) {
-                o[prop.name] = prop.fieldNames[0];
+        const result = {};
+        for (const prop of props) {
+            if (!prop.fieldNames) {
+                continue;
             }
-            return o;
-        }, {});
+            if (prop.kind === ReferenceKind.EMBEDDED && prop.embeddedProps) {
+                result[prop.name] = EntityMetadata.buildEmbeddedColumnMapping(prop);
+                continue;
+            }
+            result[prop.name] = prop.fieldNames[0];
+        }
+        return result;
+    }
+    /** @internal Recursively builds a column mapping for an embedded property's sub-columns. */
+    static buildEmbeddedColumnMapping(embeddedProp) {
+        const result = {};
+        for (const [name, sub] of Object.entries(embeddedProp.embeddedProps)) {
+            result[name] =
+                sub.kind === ReferenceKind.EMBEDDED && sub.embeddedProps
+                    ? EntityMetadata.buildEmbeddedColumnMapping(sub)
+                    : sub.fieldNames[0];
+        }
+        const prefix = embeddedProp.fieldNames[0];
+        Object.defineProperty(result, 'toString', { value: () => prefix, enumerable: false });
+        return result;
     }
     get tableName() {
         return this.collection;
@@ -166,7 +187,7 @@ export class EntityMetadata {
             if (prop.inherited || (prop.persist === false && prop.userDefined !== false)) {
                 return false;
             }
-            return prop.kind === ReferenceKind.SCALAR && ['string', 'number', 'boolean', 'Date'].includes(prop.type);
+            return (prop.kind === ReferenceKind.SCALAR && !prop.array && ['string', 'number', 'boolean', 'Date'].includes(prop.type));
         });
         this.hydrateProps = this.props.filter(prop => {
             // `prop.userDefined` is either `undefined` or `false`
@@ -193,9 +214,10 @@ export class EntityMetadata {
         // Virtual entities evaluate expressions at query time, view entities create actual database views.
         this.virtual = !!this.expression && !this.view;
         if (config) {
+            const platform = config.getPlatform();
             for (const prop of this.props) {
                 if (prop.enum && !prop.nativeEnumName && prop.items?.every(item => typeof item === 'string')) {
-                    const name = config.getNamingStrategy().indexName(this.tableName, prop.fieldNames, 'check');
+                    const name = platform.getIndexName(this.tableName, prop.fieldNames, 'check');
                     const exists = this.checks.findIndex(check => check.name === name);
                     if (exists !== -1) {
                         this.checks.splice(exists, 1);
@@ -203,9 +225,7 @@ export class EntityMetadata {
                     this.checks.push({
                         name,
                         property: prop.name,
-                        expression: config
-                            .getPlatform()
-                            .getEnumCheckConstraintExpression(prop.fieldNames[0], prop.items),
+                        expression: platform.getEnumCheckConstraintExpression(prop.fieldNames[0], prop.items),
                     });
                 }
             }
@@ -261,8 +281,8 @@ export class EntityMetadata {
         }, { __gettersDefined: { value: true, enumerable: false } });
     }
     initIndexes(prop) {
-        const simpleIndex = this.indexes.find(index => index.properties === prop.name && !index.options && !index.type && !index.expression);
-        const simpleUnique = this.uniques.find(index => index.properties === prop.name && !index.options);
+        const simpleIndex = this.indexes.find(index => index.properties === prop.name && !index.options && !index.type && !index.expression && index.where == null);
+        const simpleUnique = this.uniques.find(index => index.properties === prop.name && !index.options && !index.expression && index.where == null);
         const owner = prop.kind === ReferenceKind.MANY_TO_ONE;
         if (!prop.index && simpleIndex) {
             Utils.defaultValue(simpleIndex, 'name', true);