@mikro-orm/core 7.1.0-dev.2 → 7.1.0-dev.20

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;
     }>;
@@ -104,8 +118,16 @@ export interface 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>;
+    /** 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>;
     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;
@@ -117,7 +139,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;
@@ -127,9 +151,13 @@ export interface PropertyChain<Value, Options> {
     pivotEntity(pivotEntity: () => EntityName): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     fixedOrder(fixedOrder?: boolean): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     fixedOrderColumn(fixedOrderColumn: string): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
-    array(): HasKind<Options, 'embedded' | 'enum'> extends true ? PropertyChain<Value, Omit<Options, 'array'> & {
+    array(): Options extends {
+        kind: infer K extends string;
+    } ? K extends 'embedded' | 'enum' ? PropertyChain<Value, Omit<Options, 'array'> & {
         array: true;
-    }> : never;
+    }> : never : PropertyChain<Value, Omit<Options, 'array'> & {
+        array: true;
+    }>;
     prefix(prefix: string | boolean): HasKind<Options, 'embedded'> extends true ? PropertyChain<Value, Options> : never;
     prefixMode(prefixMode: EmbeddedPrefixMode): HasKind<Options, 'embedded'> extends true ? PropertyChain<Value, Options> : never;
     object(object?: boolean): HasKind<Options, 'embedded'> extends true ? PropertyChain<Value, Options> : never;
@@ -313,9 +341,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}.
      */
@@ -334,12 +377,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)
      *
@@ -492,7 +543,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. */
@@ -536,7 +589,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';
     }>;
@@ -556,7 +609,7 @@ 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> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminatorColumn' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
     name: TName;
     tableName?: TTableName;
     extends?: {
@@ -591,6 +644,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;
@@ -603,12 +657,22 @@ 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>;
@@ -665,7 +729,9 @@ export type InferEntityFromProperties<Properties extends Record<string, any>, PK
     [Config]?: DefineConfig<{
         forceObject: true;
     }>;
-} : {});
+} : {}) & {
+    [IndexHints]?: [Properties];
+};
 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;
@@ -707,6 +773,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 });
     }

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/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, FormulaTable, SchemaTable, SchemaColumns, 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;

package/metadata/MetadataDiscovery.js

@@ -159,6 +159,7 @@ export class MetadataDiscovery {
         forEachProp((m, p) => this.initGeneratedColumn(m, p));
         filtered.forEach(meta => this.initAutoincrement(meta)); // once again after we init custom types
         filtered.forEach(meta => this.initCheckConstraints(meta));
+        filtered.forEach(meta => this.initTriggers(meta));
         forEachProp((_m, p) => {
             this.initDefaultValue(p);
             this.inferTypeFromDefault(p);
@@ -479,17 +480,28 @@ export class MetadataDiscovery {
             prop.polymorphic = prop2.polymorphic;
             prop.discriminator = prop2.discriminator;
             prop.discriminatorColumn = prop2.discriminatorColumn;
-            prop.discriminatorValue = prop2.discriminatorValue;
+            // For a union-target pivot each inverse side sits on one specific target class, so its
+            // discriminator value is that class's tableName. For Rails-style, prop2 has a single fixed value.
+            prop.discriminatorValue = QueryHelper.isUnionTargetPolymorphic(prop2) ? meta.tableName : prop2.discriminatorValue;
         }
         prop.referencedColumnNames ??= Utils.flatten(meta.primaryKeys.map(primaryKey => meta.properties[primaryKey].fieldNames));
-        // For polymorphic M:N, use discriminator base name for FK column (e.g., taggable_id instead of post_id)
-        if (prop.polymorphic && prop.discriminator) {
+        // Union-target polymorphic M:N: owner side is fixed (real FK), target side uses discriminator-derived names.
+        const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
+        if (prop.polymorphic && prop.discriminator && !isUnionTargetMN) {
+            // Rails-style: owner side is polymorphic, uses discriminator base name (e.g. taggable_id instead of post_id)
             prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, referencedColumnName, prop.referencedColumnNames.length > 1));
         }
         else {
             prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.#namingStrategy.joinKeyColumnName(meta.root.className, referencedColumnName, meta.compositePK));
         }
-        prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className);
+        if (isUnionTargetMN) {
+            // Target side uses discriminator base name (e.g. attachable_id — shared across Image/Video)
+            const targetPkCols = Utils.flatten(meta2.primaryKeys.map(pk => meta2.properties[pk].fieldNames));
+            prop.inverseJoinColumns ??= targetPkCols.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, fieldName, targetPkCols.length > 1));
+        }
+        else {
+            prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className);
+        }
     }
     isExplicitTableName(meta) {
         return meta.tableName !== this.#namingStrategy.classToTableName(meta.className);
@@ -556,6 +568,12 @@ export class MetadataDiscovery {
             }
         }
         meta.forceConstructor ??= this.shouldForceConstructorUsage(meta);
+        // Fail fast when the platform rejects the metadata, so users see the platform-specific
+        // error (e.g. "SqlitePlatform does not support partitioned tables") instead of a
+        // downstream core validator message that assumes partitioning is supported.
+        if (meta.partitionBy && !this.#platform.supportsPartitionedTables()) {
+            this.#platform.validateMetadata(meta);
+        }
         this.#validator.validateEntityDefinition(this.#metadata, meta.class, this.#config.get('discovery'));
         for (const prop of Object.values(meta.properties)) {
             this.initNullability(prop);
@@ -583,6 +601,24 @@ export class MetadataDiscovery {
                 if (prop.inversedBy) {
                     prop.targetMeta.properties[prop.inversedBy].pivotEntity = pivotMeta.class;
                 }
+                // Propagate pivotEntity to ALL inverse collections using mappedBy pointing at this
+                // owner prop. Covers three cases:
+                //   - regular inverse (Tag.posts mappedBy Post.tags) — handled by inversedBy above
+                //   - union-target inverse (Image.posts mappedBy Post.attachments) — on each polymorph target
+                //   - merged inverse (Tag.owners mappedBy [Post,Video].tags) — union collection on the target
+                const inverseCandidates = QueryHelper.isUnionTargetPolymorphic(prop)
+                    ? prop.polymorphTargets
+                    : [prop.targetMeta];
+                for (const targetMeta of inverseCandidates) {
+                    for (const inverseProp of Object.values(targetMeta.properties)) {
+                        if (inverseProp.kind === ReferenceKind.MANY_TO_MANY &&
+                            inverseProp.mappedBy === prop.name &&
+                            !inverseProp.pivotEntity) {
+                            inverseProp.pivotEntity = pivotMeta.class;
+                            inverseProp.pivotTable = pivotMeta.tableName;
+                        }
+                    }
+                }
                 return pivotMeta;
             });
         }
@@ -721,8 +757,12 @@ export class MetadataDiscovery {
                 }
             }
         }
-        // For polymorphic M:N, create discriminator column and polymorphic FK
-        if (prop.polymorphic && prop.discriminatorColumn) {
+        // Union-target polymorphic M:N: discriminator + target FK share the pivot across multiple target types
+        if (prop.discriminatorColumn && QueryHelper.isUnionTargetPolymorphic(prop)) {
+            this.defineUnionTargetPolymorphicPivotProperties(pivotMeta2, meta, prop);
+        }
+        else if (prop.polymorphic && prop.discriminatorColumn) {
+            // Rails-style polymorphic M:N: multiple owners share the pivot, single target type
             this.definePolymorphicPivotProperties(pivotMeta2, meta, prop, targetMeta);
         }
         else {
@@ -809,6 +849,33 @@ export class MetadataDiscovery {
         pivotMeta.polymorphicDiscriminatorMap ??= {};
         pivotMeta.polymorphicDiscriminatorMap[prop.discriminatorValue] = meta.class;
     }
+    /**
+     * 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
+     */
+    defineUnionTargetPolymorphicPivotProperties(pivotMeta, meta, prop) {
+        const discriminatorColumn = prop.discriminatorColumn;
+        const targets = prop.polymorphTargets;
+        pivotMeta.properties[meta.name + '_owner'] = this.definePivotProperty(prop, meta.name + '_owner', meta.class, prop.discriminator, true, false);
+        const discriminatorProp = this.createPivotScalarProperty(discriminatorColumn, [this.#platform.getVarcharTypeDeclarationSQL(prop)], [discriminatorColumn], { type: 'string', primary: true, nullable: false });
+        this.initFieldName(discriminatorProp);
+        pivotMeta.properties[discriminatorColumn] = discriminatorProp;
+        const firstTargetColumnTypes = this.getPrimaryKeyColumnTypes(targets[0]);
+        pivotMeta.properties[prop.discriminator] = this.createPivotScalarProperty(prop.discriminator, firstTargetColumnTypes, [...prop.inverseJoinColumns], { type: targets[0].className, primary: true, nullable: false });
+        pivotMeta.polymorphicDiscriminatorMap ??= {};
+        for (const targetMeta of targets) {
+            const relationName = `${prop.discriminator}_${targetMeta.tableName}`;
+            const relation = this.definePolymorphicOwnerRelation(prop, relationName, targetMeta);
+            relation.joinColumns = relation.fieldNames = relation.ownColumns = [...prop.inverseJoinColumns];
+            pivotMeta.properties[relationName] = relation;
+            pivotMeta.polymorphicDiscriminatorMap[targetMeta.tableName] = targetMeta.class;
+        }
+    }
     /**
      * 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.
@@ -961,6 +1028,7 @@ export class MetadataDiscovery {
         meta.indexes = Utils.unique([...base.indexes, ...meta.indexes]);
         meta.uniques = Utils.unique([...base.uniques, ...meta.uniques]);
         meta.checks = Utils.unique([...base.checks, ...meta.checks]);
+        meta.triggers = Utils.unique([...base.triggers, ...meta.triggers]);
         const pks = Object.values(meta.properties)
             .filter(p => p.primary)
             .map(p => p.name);
@@ -1045,11 +1113,15 @@ export class MetadataDiscovery {
         prop.discriminatorColumn ??= this.#namingStrategy.discriminatorColumnName(prop.discriminator);
         prop.createForeignKeyConstraint = false;
         const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
-        if (isToOne) {
+        const isUnionTargetMN = prop.kind === ReferenceKind.MANY_TO_MANY && Array.isArray(prop.target);
+        if (isToOne || isUnionTargetMN) {
             const types = prop.type.split(/ ?\| ?/);
             prop.polymorphTargets = discovered.filter(m => types.includes(m.className) && !m.embeddable);
             prop.targetMeta = prop.polymorphTargets[0];
             prop.referencedPKs = prop.targetMeta?.primaryKeys;
+            if (isUnionTargetMN && prop.polymorphTargets.length < 2) {
+                throw new MetadataError(`${meta.className}.${prop.name} union-target polymorphic M:N requires at least two target entity types; use a regular M:N relation for a single target.`);
+            }
         }
         if (prop.discriminatorMap) {
             const normalizedMap = {};
@@ -1065,7 +1137,7 @@ export class MetadataDiscovery {
             }
             prop.discriminatorMap = normalizedMap;
         }
-        else if (isToOne) {
+        else if (isToOne || isUnionTargetMN) {
             prop.discriminatorMap = {};
             const tableNameToTarget = new Map();
             for (const target of prop.polymorphTargets) {
@@ -1187,6 +1259,16 @@ export class MetadataDiscovery {
             });
         }
     }
+    sameRelationTargetRoot(rootProp, prop) {
+        if (!rootProp || rootProp.kind !== prop.kind) {
+            return false;
+        }
+        if (prop.kind !== ReferenceKind.MANY_TO_ONE && prop.kind !== ReferenceKind.ONE_TO_ONE) {
+            return false;
+        }
+        const aRoot = this.#metadata.getByClassName(prop.type, false)?.root;
+        return aRoot != null && aRoot === this.#metadata.getByClassName(rootProp.type, false)?.root;
+    }
     initSingleTableInheritance(meta, metadata) {
         if (meta.root !== meta && !meta.__processed) {
             meta.root = metadata.find(m => m.class === meta.root.class);
@@ -1227,11 +1309,16 @@ export class MetadataDiscovery {
         Object.values(meta.properties).forEach(prop => {
             const newProp = { ...prop };
             const rootProp = meta.root.properties[prop.name];
+            // A child that narrows a relation to a subclass of the root's declared
+            // target (same STI hierarchy) shares the FK column with the root; treat
+            // that as matching so the rename branch below doesn't run (which would
+            // crash — `targetMeta` is only populated later, in `initRelation`).
+            const narrowedRelationOverride = rootProp != null && rootProp.type !== prop.type && this.sameRelationTargetRoot(rootProp, prop);
             // stiMerged is set during inlineProperties when a property was merged
             // from multiple polymorphic variants with different types. The flag is
             // cleared implicitly when the first child claims the root property via
             // addProperty below, so subsequent children correctly trigger renaming.
-            const typesMatch = rootProp?.type === prop.type || rootProp?.stiMerged === true;
+            const typesMatch = rootProp?.type === prop.type || rootProp?.stiMerged === true || narrowedRelationOverride;
             if (rootProp &&
                 (!typesMatch ||
                     (rootProp.fieldNames && prop.fieldNames && !compareArrays(rootProp.fieldNames, prop.fieldNames)))) {
@@ -1281,6 +1368,12 @@ export class MetadataDiscovery {
             }
             newProp.nullable = true;
             newProp.inherited = !rootProp;
+            // For narrowed relation overrides, keep the root's declaration intact so
+            // the full target union (e.g. `Food`) is preserved for populates from the
+            // abstract root — otherwise the last child processed would win.
+            if (narrowedRelationOverride) {
+                return;
+            }
             meta.root.addProperty(newProp);
         });
         meta.tableName = meta.root.tableName;
@@ -1520,6 +1613,27 @@ export class MetadataDiscovery {
             }
         }
     }
+    initTriggers(meta) {
+        if (meta.triggers.length === 0) {
+            return;
+        }
+        const columns = meta.createSchemaColumnMappingObject();
+        const table = this.createSchemaTable(meta);
+        for (const trigger of meta.triggers) {
+            if (trigger.body && trigger.expression) {
+                throw new MetadataError(`Trigger "${trigger.name ?? '(unnamed)'}" on entity ${meta.className} defines both 'body' and 'expression'. Use one or the other.`);
+            }
+            if (!trigger.body && !trigger.expression) {
+                throw new MetadataError(`Trigger "${trigger.name ?? '(unnamed)'}" on entity ${meta.className} must define either 'body' or 'expression'.`);
+            }
+            trigger.name ??= this.#namingStrategy.indexName(meta.tableName, trigger.events, 'trigger');
+            trigger.forEach ??= 'row';
+            if (trigger.body instanceof Function) {
+                trigger.body = trigger.body(columns, table);
+            }
+        }
+        meta.hasTriggers = true;
+    }
     initGeneratedColumn(meta, prop) {
         if (!prop.generated && prop.columnTypes) {
             const match = /(.*) generated always as (.*)/i.exec(prop.columnTypes[0]);
@@ -1646,7 +1760,14 @@ export class MetadataDiscovery {
                 return (!Type.getType(t[type]).ensureComparable(meta, prop) && (prop.type === t[type] || brand === type));
             });
             if (type) {
-                prop.type = type === 'datetime' ? 'Date' : type;
+                if (prop.array) {
+                    // built-in type + array: true — force-create instance for ArrayType wrapping
+                    prop.customType = new prop.type();
+                    prop.type = prop.customType.constructor.name;
+                }
+                else {
+                    prop.type = type === 'datetime' ? 'Date' : type;
+                }
             }
             else {
                 prop.customType = new prop.type();
@@ -1656,6 +1777,30 @@ export class MetadataDiscovery {
         if (simple) {
             return;
         }
+        if (prop.array &&
+            prop.customType &&
+            !(prop.customType instanceof t.array) &&
+            !(prop.customType instanceof t.enumArray) &&
+            prop.kind === ReferenceKind.SCALAR) {
+            const innerType = prop.customType;
+            innerType.platform = this.#platform;
+            innerType.meta = meta;
+            innerType.prop = prop;
+            if (!prop.columnTypes) {
+                const arrayDecl = this.#platform.getArrayDeclarationSQL();
+                if (arrayDecl.endsWith('[]')) {
+                    // native array support (e.g. postgres) — use inner type's column type with [] suffix
+                    prop.columnTypes = [innerType.getColumnType(prop, this.#platform) + '[]'];
+                }
+                else {
+                    // non-native (e.g. mysql, sqlite) — store as text/clob
+                    prop.columnTypes = [arrayDecl];
+                }
+            }
+            const platform = this.#platform;
+            prop.customType = new t.array(v => innerType.convertToJSValue(v, platform), v => innerType.convertToDatabaseValue(v, platform));
+            prop.type = prop.customType.constructor.name;
+        }
         if (!prop.customType && ['json', 'jsonb'].includes(prop.type?.toLowerCase())) {
             prop.customType = new t.json();
         }