@mikro-orm/core 7.1.0-dev.4 → 7.1.0-dev.40

package/entity/Reference.d.ts

@@ -1,4 +1,4 @@
-import type { AddEager, AddOptional, Dictionary, EntityClass, EntityKey, EntityProperty, Loaded, LoadedReference, Primary, Ref } from '../typings.js';
+import type { AddEager, AddOptional, Dictionary, EntityClass, EntityKey, EntityProperty, LazyRef, Loaded, LoadedReference, Primary, Ref } from '../typings.js';
 import type { FindOneOptions, FindOneOrFailOptions } from '../drivers/IDatabaseDriver.js';
 /** Wrapper around an entity that provides lazy loading capabilities and identity-preserving reference semantics. */
 export declare class Reference<T extends object> {
@@ -98,6 +98,47 @@ export declare function ref<I extends unknown | Ref<unknown> | undefined | null,
  * shortcut for `Reference.createFromPK(entityType, pk)`
  */
 export declare function ref<I extends unknown | undefined | null, T, PKV extends Primary<T> = Primary<T>>(entityType: EntityClass<T>, pk: I): Ref<T> | AddOptional<typeof pk>;
+/**
+ * Unwraps a reference to its underlying value, returning the entity or scalar. Works on any of:
+ *
+ * - `Ref<T>` / `Reference<T>` (entity) — calls `.unwrap()` to extract the wrapped entity, returns `T`.
+ * - `LazyRef<T>` — type-only marker; runtime value is already `T`, so returned as-is.
+ * - plain entity `T` — returned as-is.
+ * - `ScalarReference<V>` / `ScalarRef<V>` — calls `.unwrap()` to extract the scalar value, returns `V | undefined`
+ *   (a scalar reference may be bound without an initial value).
+ *
+ * Inverse of the {@link ref} helper. Use as a typed escape hatch when you know a relation is populated
+ * but don't want to (or can't) thread `Loaded<T, 'relation'>` through a function signature.
+ *
+ * ```ts
+ * function logAuthor(book: Book) {
+ *   // `book.author` is typed as `LazyRef<Author>`, so `.name` is not directly accessible
+ *   console.log(unref(book.author).name);
+ * }
+ *
+ * // Scalar reference:
+ * const scalar = ref('hello');
+ * unref(scalar); // 'hello' (type: string | undefined)
+ * ```
+ *
+ * Note: `unref` is a compile-time narrowing only for entity refs. On a `LazyRef<T>` or plain entity
+ * relation that is a stub (PK only, never populated), reads of non-PK properties will still return
+ * `undefined` at runtime — same footgun as a plain non-`Ref` relation.
+ */
+export declare function unref<V>(value: ScalarReference<V>): V | undefined;
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T): T;
+/**
+ * Unwraps a reference to its underlying value. Nullable variant — returns `null` unchanged.
+ */
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T | null): T | null;
+/**
+ * Unwraps a reference to its underlying value. Optional variant — returns `undefined` unchanged.
+ */
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T | undefined): T | undefined;
+/**
+ * Unwraps a reference to its underlying value. Nullable variant — returns `null`/`undefined` unchanged.
+ */
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T | null | undefined): T | null | undefined;
 /**
  * shortcut for `Reference.createNakedFromPK(entityType, pk)`
  */

package/entity/Reference.js

@@ -303,6 +303,15 @@ export function ref(entityOrType, pk) {
     }
     return Reference.createFromPK(entityOrType, pk);
 }
+export function unref(value) {
+    if (value == null) {
+        return value;
+    }
+    if (ScalarReference.isScalarReference(value)) {
+        return value.unwrap();
+    }
+    return Reference.unwrapReference(value);
+}
 /**
  * shortcut for `Reference.createNakedFromPK(entityType, pk)`
  */

package/entity/defineEntity.d.ts

@@ -1,6 +1,6 @@
 import type { EntityManager } from '../EntityManager.js';
 import type { ColumnType, PropertyOptions, ReferenceOptions, EnumOptions, EmbeddedOptions, ManyToOneOptions, OneToManyOptions, OneToOneOptions, ManyToManyOptions, IndexColumnOptions } from '../metadata/types.js';
-import type { AnyString, GeneratedColumnCallback, Constructor, CheckCallback, FilterQuery, EntityName, Dictionary, EntityMetadata, PrimaryKeyProp, EntityRepositoryType, Hidden, Opt, Primary, EntityClass, EntitySchemaWithMeta, InferEntity, MaybeReturnType, Ref, IndexCallback, FormulaCallback, EntityCtor, IsNever, IWrappedEntity, DefineConfig, Config, MaybePromise } from '../typings.js';
+import type { AnyString, GeneratedColumnCallback, Constructor, CheckCallback, FilterQuery, EntityName, Dictionary, EntityMetadata, PrimaryKeyProp, EntityRepositoryType, Hidden, Opt, Primary, EntityClass, EntitySchemaWithMeta, InferEntity, MaybeReturnType, Ref, LazyRef, IndexCallback, TriggerCallback, FormulaCallback, EntityCtor, IsNever, IWrappedEntity, DefineConfig, Config, MaybePromise, IndexHints } from '../typings.js';
 import type { Raw } from '../utils/RawQueryFragment.js';
 import type { ScalarReference } from './Reference.js';
 import type { SerializeOptions } from '../serialization/EntitySerializer.js';
@@ -12,7 +12,7 @@ import type { Collection } from './Collection.js';
 import type { FilterOptions, FindOptions, FindOneOptions } from '../drivers/IDatabaseDriver.js';
 /** Union of all option keys supported across all property definition types (scalar, enum, embedded, relations). */
 export type UniversalPropertyKeys = keyof PropertyOptions<any> | keyof EnumOptions<any> | keyof EmbeddedOptions<any, any> | keyof ReferenceOptions<any, any> | keyof ManyToOneOptions<any, any> | keyof OneToManyOptions<any, any> | keyof OneToOneOptions<any, any> | keyof ManyToManyOptions<any, any>;
-type BuilderExtraKeys = '~options' | '~type' | '$type' | 'strictNullable';
+type BuilderExtraKeys = '~options' | '~type' | '$type' | 'strictNullable' | 'lazyRef';
 type ExcludeKeys = 'entity' | 'items';
 type BuilderKeys = Exclude<UniversalPropertyKeys, ExcludeKeys> | BuilderExtraKeys;
 type IncludeKeysForProperty = Exclude<keyof PropertyOptions<any>, ExcludeKeys> | BuilderExtraKeys;
@@ -36,9 +36,23 @@ export interface PropertyChain<Value, Options> {
         nullable: true;
         strictNullable: true;
     }>;
-    ref(): PropertyChain<Value, Omit<Options, 'ref'> & {
+    ref(): Options extends {
+        lazyRef: true;
+    } ? never : PropertyChain<Value, Omit<Options, 'ref'> & {
         ref: true;
     }>;
+    /**
+     * Mark a to-one relation (`m:1`/`1:1`) as a {@apilink LazyRef} — direct entity at runtime, type-restricted
+     * until `Loaded<>` narrows it. Type-level only, no `ref: true` wrapping. Not compatible with `.ref()` or
+     * `.mapToPk()` — those chains are rejected in both directions at compile time.
+     */
+    lazyRef(): HasKind<Options, 'm:1' | '1:1'> extends true ? Options extends {
+        ref: true;
+    } | {
+        mapToPk: true;
+    } ? never : PropertyChain<Value, Omit<Options, 'lazyRef'> & {
+        lazyRef: true;
+    }> : never;
     primary(): PropertyChain<Value, Omit<Options, 'primary'> & {
         primary: true;
     }>;
@@ -103,10 +117,19 @@ export interface PropertyChain<Value, Options> {
     groups(...groups: string[]): PropertyChain<Value, Options>;
     customOrder(...customOrder: string[] | number[] | boolean[]): PropertyChain<Value, Options>;
     extra(extra: string): PropertyChain<Value, Options>;
-    ignoreSchemaChanges(...ignoreSchemaChanges: ('type' | 'extra' | 'default')[]): PropertyChain<Value, Options>;
-    index(index?: boolean | string): PropertyChain<Value, Options>;
-    unique(unique?: boolean | string): PropertyChain<Value, Options>;
+    ignoreSchemaChanges(...ignoreSchemaChanges: ('type' | 'extra' | 'default' | 'collation')[]): PropertyChain<Value, Options>;
+    /** Explicitly specify index on a property. When a string name is passed, it enables type-safe `using` in `FindOptions`. */
+    index<N extends string>(name: N): PropertyChain<Value, Omit<Options, 'index'> & {
+        index: N;
+    }>;
+    index(index?: boolean): PropertyChain<Value, Options>;
+    /** Set column as unique. When a string name is passed, it enables type-safe `using` in `FindOptions`. (SQL only) */
+    unique<N extends string>(name: N): PropertyChain<Value, Omit<Options, 'unique'> & {
+        unique: N;
+    }>;
+    unique(unique?: boolean): PropertyChain<Value, Options>;
     comment(comment: string): PropertyChain<Value, Options>;
+    collation(collation: string): PropertyChain<Value, Options>;
     accessor(accessor?: string | boolean): PropertyChain<Value, Options>;
     eager(eager?: boolean): HasKind<Options, 'm:1' | '1:m' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     cascade(...cascade: Cascade[]): HasKind<Options, 'm:1' | '1:m' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
@@ -117,7 +140,9 @@ export interface PropertyChain<Value, Options> {
     owner(): HasKind<Options, '1:1' | 'm:n'> extends true ? PropertyChain<Value, Omit<Options, 'owner'> & {
         owner: true;
     }> : never;
-    mapToPk(): HasKind<Options, 'm:1' | '1:1'> extends true ? PropertyChain<Value, Omit<Options, 'mapToPk'> & {
+    mapToPk(): HasKind<Options, 'm:1' | '1:1'> extends true ? Options extends {
+        lazyRef: true;
+    } ? never : PropertyChain<Value, Omit<Options, 'mapToPk'> & {
         mapToPk: true;
     }> : never;
     orphanRemoval(orphanRemoval?: boolean): HasKind<Options, '1:m' | '1:1'> extends true ? PropertyChain<Value, Options> : never;
@@ -317,9 +342,24 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     /**
      * Enable `ScalarReference` wrapper for lazy values. Use this in combination with `lazy: true` to have a type-safe accessor object in place of the value.
      */
-    ref(): UniversalPropertyOptionsBuilder<Value, Omit<Options, 'ref'> & {
+    ref(): Options extends {
+        lazyRef: true;
+    } ? never : UniversalPropertyOptionsBuilder<Value, Omit<Options, 'ref'> & {
         ref: true;
     }, IncludeKeys>;
+    /**
+     * Mark a to-one relation (`m:1`/`1:1`) as a {@apilink LazyRef} — the runtime value stays a plain entity
+     * (no `Reference` wrapper) but the TypeScript type restricts access to the primary key until `Loaded<>`
+     * narrows it. Type-level only; does not set `ref: true`. Not compatible with `.ref()` or `.mapToPk()` —
+     * those chains are rejected in both directions at compile time.
+     */
+    lazyRef(): HasKind<Options, 'm:1' | '1:1'> extends true ? Options extends {
+        ref: true;
+    } | {
+        mapToPk: true;
+    } ? never : UniversalPropertyOptionsBuilder<Value, Omit<Options, 'lazyRef'> & {
+        lazyRef: true;
+    }, IncludeKeys> : never;
     /**
      * Set to true to omit the property when {@link https://mikro-orm.io/docs/serializing Serializing}.
      */
@@ -338,12 +378,20 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     concurrencyCheck(concurrencyCheck?: boolean): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /**
      * Explicitly specify index on a property.
+     * When a string name is passed, it is captured as a literal type for use with the `using` option in `FindOptions`.
      */
-    index(index?: boolean | string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    index<N extends string>(name: N): Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'index'> & {
+        index: N;
+    }, IncludeKeys>, IncludeKeys>;
+    index(index?: boolean): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /**
      * Set column as unique for {@link https://mikro-orm.io/docs/schema-generator Schema Generator}. (SQL only)
+     * When a string name is passed, it is captured as a literal type for use with the `using` option in `FindOptions`.
      */
-    unique(unique?: boolean | string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    unique<N extends string>(name: N): Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'unique'> & {
+        unique: N;
+    }, IncludeKeys>, IncludeKeys>;
+    unique(unique?: boolean): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /**
      * Specify column with check constraints. (Postgres driver only)
      *
@@ -431,6 +479,11 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
      * Specify comment of column for {@link https://mikro-orm.io/docs/schema-generator Schema Generator}. (SQL only)
      */
     comment(comment: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    /**
+     * Specify column-level collation for {@link https://mikro-orm.io/docs/schema-generator Schema Generator}. (SQL only)
+     * Emits a `COLLATE` clause on the column definition; the accepted collation names are dialect-specific.
+     */
+    collation(collation: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** mysql only */
     extra(extra: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /**
@@ -438,7 +491,7 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
      *
      * @see https://mikro-orm.io/docs/defining-entities#sql-generated-columns
      */
-    ignoreSchemaChanges(...ignoreSchemaChanges: ('type' | 'extra' | 'default')[]): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    ignoreSchemaChanges(...ignoreSchemaChanges: ('type' | 'extra' | 'default' | 'collation')[]): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     array(): Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'array'> & {
         array: true;
     }, IncludeKeys>, IncludeKeys>;
@@ -496,7 +549,9 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     /** What to do when the reference to the target entity gets updated. */
     updateRule(updateRule: 'cascade' | 'no action' | 'set null' | 'set default' | AnyString): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Map this relation to the primary key value instead of an entity. */
-    mapToPk(): Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'mapToPk'> & {
+    mapToPk(): Options extends {
+        lazyRef: true;
+    } ? never : Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'mapToPk'> & {
         mapToPk: true;
     }, IncludeKeys>, IncludeKeys>;
     /** Set the constraint type. Immediate constraints are checked for each statement, while deferred ones are only checked at the end of the transaction. Only for postgres unique constraints. */
@@ -540,7 +595,7 @@ export type PropertyBuilders = {
     datetime: (length?: number) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.datetime>, EmptyOptions, IncludeKeysForProperty>;
     time: (length?: number) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.time>, EmptyOptions, IncludeKeysForProperty>;
     type: <T extends PropertyValueType>(type: T) => UniversalPropertyOptionsBuilder<InferPropertyValueType<T>, EmptyOptions, IncludeKeysForProperty>;
-    enum: <const T extends readonly (number | string)[] | (() => Dictionary)>(items?: T) => UniversalPropertyOptionsBuilder<T extends () => Dictionary ? ValueOf<ReturnType<T>> : T extends readonly (infer Value)[] ? Value : T, EmptyOptions, IncludeKeysForEnumOptions>;
+    enum: <const T extends readonly (number | string)[] | Dictionary | (() => Dictionary)>(items?: T) => UniversalPropertyOptionsBuilder<T extends () => Dictionary ? ValueOf<ReturnType<T>> : T extends readonly (infer Value)[] ? Value : T extends Dictionary ? ValueOf<T> : T, EmptyOptions, IncludeKeysForEnumOptions>;
     embedded: <Target extends EntityTarget | EntityTarget[]>(target: Target) => PropertyChain<InferEntity<Target extends (infer T)[] ? T : Target>, EmptyOptions & {
         kind: 'embedded';
     }>;
@@ -560,12 +615,15 @@ export type PropertyBuilders = {
 /** Own keys + base entity keys (when TBase is not `never`). Guards against `keyof never = string | number | symbol`. */
 type AllKeys<TProperties, TBase> = keyof TProperties | (IsNever<TBase> extends true ? never : keyof TBase);
 /** Metadata descriptor for `defineEntity()`, combining entity options with property definitions. */
-export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminatorColumn' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'repository' | 'filters' | 'orderBy'> {
+export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false, TDiscriminatorColumn extends string | undefined = undefined, TDiscriminatorValue extends string | number | undefined = undefined, TBaseDiscriminatorColumn extends string | undefined = undefined> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminatorColumn' | 'discriminatorValue' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
     name: TName;
     tableName?: TTableName;
     extends?: {
         '~entity': TBase;
-    } | EntityCtor<TBase>;
+        '~discriminatorColumn'?: TBaseDiscriminatorColumn;
+    } | (EntityCtor<TBase> & {
+        '~discriminatorColumn'?: TBaseDiscriminatorColumn;
+    });
     properties: TProperties | ((properties: PropertyBuilders) => TProperties);
     primaryKeys?: TPK & InferPrimaryKeyConstraint<TProperties>[];
     hooks?: DefineEntityHooks;
@@ -585,7 +643,8 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
     } | {
         [K in Extract<AllKeys<TProperties, TBase>, string>]?: QueryOrderKeysFlat;
     }[];
-    discriminatorColumn?: string;
+    discriminatorColumn?: TDiscriminatorColumn;
+    discriminatorValue?: TDiscriminatorValue;
     versionProperty?: AllKeys<TProperties, TBase>;
     concurrencyCheckKeys?: Set<AllKeys<TProperties, TBase>>;
     serializedPrimaryKey?: AllKeys<TProperties, TBase>;
@@ -595,6 +654,7 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         type?: string;
         options?: Dictionary;
         expression?: string | IndexCallback<InferEntityFromProperties<TProperties, TPK, TBase>>;
+        where?: string | FilterQuery<InferEntityFromProperties<TProperties, TPK, TBase>>;
         columns?: IndexColumnOptions[];
         include?: NoInfer<AllKeys<TProperties, TBase>> | NoInfer<AllKeys<TProperties, TBase>>[];
         fillFactor?: number;
@@ -607,15 +667,25 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         name?: string;
         options?: Dictionary;
         expression?: string | IndexCallback<InferEntityFromProperties<TProperties, TPK, TBase>>;
+        where?: string | FilterQuery<InferEntityFromProperties<TProperties, TPK, TBase>>;
         deferMode?: DeferMode | `${DeferMode}`;
         columns?: IndexColumnOptions[];
         include?: NoInfer<AllKeys<TProperties, TBase>> | NoInfer<AllKeys<TProperties, TBase>>[];
         fillFactor?: number;
         disabled?: boolean;
     }[];
+    triggers?: {
+        name?: string;
+        timing: 'before' | 'after' | 'instead of';
+        events: ('insert' | 'update' | 'delete' | 'truncate')[];
+        forEach?: 'row' | 'statement';
+        body?: string | Raw | TriggerCallback<InferEntityFromProperties<TProperties, TPK, TBase>>;
+        when?: string;
+        expression?: string;
+    }[];
 }
 /** Defines an entity schema using property builders, with full type inference from the property definitions. */
-export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject>): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject>, TBase, TProperties>;
+export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false, const TDiscriminatorColumn extends string | undefined = undefined, const TDiscriminatorValue extends string | number | undefined = undefined, const TBaseDiscriminatorColumn extends string | undefined = undefined>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject, TDiscriminatorColumn, TDiscriminatorValue, TBaseDiscriminatorColumn>): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue>, TBase, TProperties, EntityCtor<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue>>, TDiscriminatorColumn>;
 /** Defines an entity schema for an existing class, combining the class with property builders. */
 export declare function defineEntity<const TEntity = any, const TProperties extends Record<string, any> = Record<string, any>, const TClassName extends string = string, const TTableName extends string = string, const TBase = never, const TClass extends EntityCtor = EntityCtor<TEntity>>(meta: Omit<Partial<EntityMetadata<TEntity>>, 'properties' | 'extends' | 'className' | 'tableName' | 'hooks'> & {
     class: TClass;
@@ -651,7 +721,7 @@ type InferJSType<T> = T extends typeof Type<infer TValue, any> ? NonNullable<TVa
 type InferColumnType<T extends string> = T extends 'int' | 'int4' | 'integer' | 'bigint' | 'int8' | 'int2' | 'tinyint' | 'smallint' | 'mediumint' ? number : T extends 'double' | 'double precision' | 'real' | 'float8' | 'decimal' | 'numeric' | 'float' | 'float4' ? number : T extends 'datetime' | 'time' | 'time with time zone' | 'timestamp' | 'timestamp with time zone' | 'timetz' | 'timestamptz' | 'date' | 'interval' ? Date : T extends 'ObjectId' | 'objectId' | 'character varying' | 'varchar' | 'char' | 'character' | 'uuid' | 'text' | 'tinytext' | 'mediumtext' | 'longtext' | 'enum' ? string : T extends 'boolean' | 'bool' | 'bit' ? boolean : T extends 'blob' | 'tinyblob' | 'mediumblob' | 'longblob' | 'bytea' ? Buffer : T extends 'point' | 'line' | 'lseg' | 'box' | 'circle' | 'path' | 'polygon' | 'geometry' ? number[] : T extends 'tsvector' | 'tsquery' ? string[] : T extends 'json' | 'jsonb' ? any : any;
 type BaseEntityMethodKeys = 'toObject' | 'toPOJO' | 'serialize' | 'assign' | 'populate' | 'init' | 'toReference';
 /** Infers the entity type from a `defineEntity()` properties map, resolving builders, base classes, and primary keys. */
-export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false> = (IsNever<Base> extends true ? {} : Base extends {
+export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined> = (IsNever<Base> extends true ? {} : Base extends {
     toObject(...args: any[]): any;
 } ? Pick<IWrappedEntity<{
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
@@ -659,17 +729,22 @@ export type InferEntityFromProperties<Properties extends Record<string, any>, PK
     [PrimaryKeyProp]?: InferCombinedPrimaryKey<Properties, PK, Base>;
 } & (IsNever<Repository> extends true ? {} : {
     [EntityRepositoryType]?: Repository extends Constructor<infer R> ? R : Repository;
-}) & Omit<Base, typeof PrimaryKeyProp>>, BaseEntityMethodKeys> : {}) & {
+}) & NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue>>, BaseEntityMethodKeys> : {}) & {
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
 } & {
     [PrimaryKeyProp]?: InferCombinedPrimaryKey<Properties, PK, Base>;
 } & (IsNever<Repository> extends true ? {} : {
     [EntityRepositoryType]?: Repository extends Constructor<infer R> ? R : Repository;
-}) & (IsNever<Base> extends true ? {} : Omit<Base, typeof PrimaryKeyProp>) & (ForceObject extends true ? {
+}) & (IsNever<Base> extends true ? {} : NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue>) & (ForceObject extends true ? {
     [Config]?: DefineConfig<{
         forceObject: true;
     }>;
-} : {});
+} : {}) & {
+    [IndexHints]?: [Properties];
+};
+type NarrowDiscriminator<Base, DiscColumn extends string | undefined, DiscValue> = DiscColumn extends string ? DiscColumn extends keyof Base ? DiscValue extends string | number ? Omit<Base, DiscColumn> & {
+    [K in DiscColumn]: DiscValue;
+} : Base : Base : Base;
 type InferCombinedPrimaryKey<Properties extends Record<string, any>, PK, Base> = PK extends undefined ? CombinePrimaryKeys<InferPrimaryKey<Properties>, ExtractBasePrimaryKey<Base>> : PK;
 type ExtractBasePrimaryKey<Base> = Base extends {
     [PrimaryKeyProp]?: infer BasePK;
@@ -711,6 +786,9 @@ type MaybeNullable<Value, Options> = Options extends {
 type MaybeRelationRef<Value, Options> = Options extends {
     mapToPk: true;
 } ? Value : Options extends {
+    lazyRef: true;
+    kind: '1:1' | 'm:1';
+} ? Value extends object ? LazyRef<Value> : never : Options extends {
     ref: true;
     kind: '1:1';
 } ? Value extends object ? Ref<Value> : never : Options extends {

package/entity/defineEntity.js

@@ -173,6 +173,16 @@ export class UniversalPropertyOptionsBuilder {
     ref() {
         return this.assignOptions({ ref: true });
     }
+    /**
+     * Mark a to-one relation (`m:1`/`1:1`) as a {@apilink LazyRef} — the runtime value stays a plain entity
+     * (no `Reference` wrapper) but the TypeScript type restricts access to the primary key until `Loaded<>`
+     * narrows it. Type-level only; does not set `ref: true`. Not compatible with `.ref()` or `.mapToPk()` —
+     * those chains are rejected in both directions at compile time.
+     */
+    lazyRef() {
+        // purely type-level — no runtime metadata change
+        return this;
+    }
     /**
      * Set to true to omit the property when {@link https://mikro-orm.io/docs/serializing Serializing}.
      */
@@ -191,15 +201,9 @@ export class UniversalPropertyOptionsBuilder {
     concurrencyCheck(concurrencyCheck = true) {
         return this.assignOptions({ concurrencyCheck });
     }
-    /**
-     * Explicitly specify index on a property.
-     */
     index(index = true) {
         return this.assignOptions({ index });
     }
-    /**
-     * Set column as unique for {@link https://mikro-orm.io/docs/schema-generator Schema Generator}. (SQL only)
-     */
     unique(unique = true) {
         return this.assignOptions({ unique });
     }
@@ -312,6 +316,13 @@ export class UniversalPropertyOptionsBuilder {
     comment(comment) {
         return this.assignOptions({ comment });
     }
+    /**
+     * Specify column-level collation for {@link https://mikro-orm.io/docs/schema-generator Schema Generator}. (SQL only)
+     * Emits a `COLLATE` clause on the column definition; the accepted collation names are dialect-specific.
+     */
+    collation(collation) {
+        return this.assignOptions({ collation });
+    }
     /** mysql only */
     extra(extra) {
         return this.assignOptions({ extra });

package/entity/utils.js

@@ -94,11 +94,10 @@ export function applyPopulateHints(populate, hints) {
         if (!entry) {
             continue;
         }
-        if (hint.strategy != null) {
-            entry.strategy = hint.strategy;
-        }
-        if (hint.joinType != null) {
-            entry.joinType = hint.joinType;
+        for (const key of Object.keys(hint)) {
+            if (hint[key] != null) {
+                entry[key] = hint[key];
+            }
         }
     }
 }

package/enums.d.ts

@@ -1,5 +1,5 @@
 import type { EntityKey, ExpandProperty } from './typings.js';
-import type { Transaction } from './connections/Connection.js';
+import type { InflightQueryAbortStrategy, Transaction } from './connections/Connection.js';
 import type { LogContext } from './logging/Logger.js';
 /** Controls when the `EntityManager` flushes pending changes to the database. */
 export declare enum FlushMode {
@@ -307,6 +307,13 @@ export interface TransactionOptions {
     flushMode?: FlushMode | `${FlushMode}`;
     ignoreNestedTransactions?: boolean;
     loggerContext?: LogContext;
+    /**
+     * `AbortSignal` cancelling every query within the transaction (including the implicit flush).
+     * Cancelling mid-transaction triggers a rollback once the in-flight query settles.
+     */
+    signal?: AbortSignal;
+    /** Cancellation strategy paired with {@link signal}. */
+    inflightQueryAbortStrategy?: InflightQueryAbortStrategy;
 }
 export declare abstract class PlainObject {
 }

package/errors.d.ts

@@ -74,6 +74,8 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static viewEntityWithoutExpression(meta: EntityMetadata): MetadataError;
     static mixedInheritanceStrategies(root: EntityMetadata, child: EntityMetadata): MetadataError;
     static tptNotSupportedByDriver(meta: EntityMetadata): MetadataError;
+    /** Thrown when database triggers are defined on an entity using a driver that does not support them. */
+    static triggersNotSupportedByDriver(meta: EntityMetadata): MetadataError;
     private static fromMessage;
 }
 /** Error thrown when an entity lookup fails to find the expected result. */

package/errors.js

@@ -243,6 +243,10 @@ export class MetadataError extends ValidationError {
     static tptNotSupportedByDriver(meta) {
         return new MetadataError(`Entity ${meta.className} uses TPT (Table-Per-Type) inheritance which is not supported by the current driver. TPT requires SQL JOINs and is only available with SQL drivers.`);
     }
+    /** Thrown when database triggers are defined on an entity using a driver that does not support them. */
+    static triggersNotSupportedByDriver(meta) {
+        return new MetadataError(`Entity ${meta.className} defines database triggers which are not supported by the current driver. Triggers are only available with SQL drivers.`);
+    }
     static fromMessage(meta, prop, message) {
         return new MetadataError(`${meta.className}.${prop.name} ${message}`);
     }

package/index.d.ts

@@ -2,8 +2,8 @@
  * @packageDocumentation
  * @module core
  */
-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 { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName, IndexHints, } 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, IndexFilterQuery, ExtractIndexHints, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaColumns, FormulaTable, SchemaTable, SchemaColumns, SchemaColumnRef, EntityDataPropValue, SimpleColumnMeta, Rel, Ref, LazyRef, 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, TriggerDef, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
 export * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';

package/index.js

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * @module core
  */
-export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName, } from './typings.js';
+export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName, IndexHints, } from './typings.js';
 export * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';

package/metadata/EntitySchema.js

@@ -85,6 +85,9 @@ export class EntitySchema {
         if (options.items instanceof Function) {
             options.items = Utils.extractEnumValues(options.items());
         }
+        else if (options.items && !Array.isArray(options.items) && typeof options.items === 'object') {
+            options.items = Utils.extractEnumValues(options.items);
+        }
         // enum arrays are simple numeric/string arrays, the constraint is enforced in the custom type only
         if (options.array && !options.type) {
             options.type = new EnumArrayType(`${this._meta.className}.${name}`, options.items);

package/metadata/MetadataDiscovery.d.ts

@@ -54,6 +54,16 @@ export declare class MetadataDiscovery {
      * Define properties for a polymorphic pivot table.
      */
     private definePolymorphicPivotProperties;
+    /**
+     * Mirror of definePolymorphicPivotProperties for union-target M:N
+     * (e.g. Post.attachments -> Image | Video via shared pivot with a target-side discriminator).
+     *
+     * Pivot shape:
+     *   (owner_fk..., discriminator_column, target_fk...)
+     *   - owner side is a normal M:1 to the single owner entity
+     *   - target side is a discriminator column + per-target-type virtual M:1 relations
+     */
+    private defineUnionTargetPolymorphicPivotProperties;
     /**
      * Create a virtual M:1 relation from pivot to a polymorphic owner entity.
      * This enables single-query join loading for inverse-side polymorphic M:N.
@@ -66,6 +76,7 @@ export declare class MetadataDiscovery {
     private initPolyEmbeddables;
     private initPolymorphicRelation;
     private initEmbeddables;
+    private sameRelationTargetRoot;
     private initSingleTableInheritance;
     /**
      * First pass of TPT initialization: sets up hierarchy relationships
@@ -105,6 +116,7 @@ export declare class MetadataDiscovery {
     private initAutoincrement;
     private createSchemaTable;
     private initCheckConstraints;
+    private initTriggers;
     private initGeneratedColumn;
     private getDefaultVersionValue;
     private inferDefaultValue;