@mikro-orm/core 7.1.0-dev.1 → 7.1.0-dev.10

package/entity/EntityFactory.js

@@ -316,11 +316,30 @@ export class EntityFactory {
             else if (!onCreateOnly && prop.default != null && !isRaw(prop.default) && entity[prop.name] === undefined) {
                 entity[prop.name] = prop.default;
             }
+            else if (!onCreateOnly &&
+                this.#config.get('initNullableProperties') &&
+                prop.nullable &&
+                prop.default == null &&
+                !prop.defaultRaw &&
+                entity[prop.name] === undefined) {
+                entity[prop.name] = (this.#config.get('forceUndefined') ? undefined : null);
+            }
             if (prop.kind === ReferenceKind.EMBEDDED && entity[prop.name]) {
                 const items = prop.array ? entity[prop.name] : [entity[prop.name]];
                 for (const item of items) {
                     // Embedded sub-properties need all defaults since the DB can't apply them within JSON columns.
-                    this.assignDefaultValues(item, prop.targetMeta);
+                    // For polymorphic embeddables, resolve the actual subtype to avoid setting
+                    // properties from other subtypes (e.g. Cat's canMeow on a Dog instance).
+                    let targetMeta = prop.targetMeta;
+                    if (targetMeta.polymorphs && targetMeta.discriminatorColumn) {
+                        const discValue = item[targetMeta.discriminatorColumn];
+                        // eslint-disable-next-line eqeqeq
+                        const resolved = targetMeta.polymorphs.find(m => m.discriminatorValue == discValue);
+                        if (resolved) {
+                            targetMeta = resolved;
+                        }
+                    }
+                    this.assignDefaultValues(item, targetMeta);
                 }
             }
         }

package/entity/EntityLoader.d.ts

@@ -1,4 +1,4 @@
-import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, PopulateOptions } from '../typings.js';
+import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, PopulateHintOptions, PopulateOptions } from '../typings.js';
 import type { EntityManager } from '../EntityManager.js';
 import { LoadStrategy, type LockMode, type PopulateHint, PopulatePath, type QueryOrderMap } from '../enums.js';
 import type { FilterOptions } from '../drivers/IDatabaseDriver.js';
@@ -37,6 +37,8 @@ export interface EntityLoaderOptions<Entity, Fields extends string = never, Excl
     connectionType?: ConnectionType;
     /** Logging options for the query. */
     logging?: LoggingOptions;
+    /** Per-relation populate overrides (limit, offset, orderBy). */
+    populateHints?: Record<string, PopulateHintOptions>;
 }
 /** Responsible for batch-loading entity relations using either select-in or joined loading strategies. */
 export declare class EntityLoader {

package/entity/EntityLoader.js

@@ -177,8 +177,9 @@ export class EntityLoader {
             Utils.isObject(orderBy[prop.name]))
             .flatMap(orderBy => orderBy[prop.name]);
         const where = await this.extractChildCondition(options, prop);
+        const mergedOrderBy = populate.orderBy ? Utils.asArray(populate.orderBy) : innerOrderBy;
         if (prop.kind === ReferenceKind.MANY_TO_MANY && this.#driver.getPlatform().usesPivotTable()) {
-            const pivotOrderBy = QueryHelper.mergeOrderBy(innerOrderBy, prop.orderBy, prop.targetMeta?.orderBy);
+            const pivotOrderBy = QueryHelper.mergeOrderBy(mergedOrderBy, prop.orderBy, prop.targetMeta?.orderBy);
             const res = await this.findChildrenFromPivotTable(filtered, prop, options, pivotOrderBy, populate, !!ref);
             return Utils.flatten(res);
         }
@@ -188,10 +189,12 @@ export class EntityLoader {
         const { items, partial } = await this.findChildren(options.filtered ?? entities, prop, populate, {
             ...options,
             where,
-            orderBy: innerOrderBy,
+            orderBy: mergedOrderBy,
         }, !!(ref || prop.mapToPk));
-        const customOrder = innerOrderBy.length > 0 || !!prop.orderBy || !!prop.targetMeta?.orderBy;
-        this.initializeCollections(filtered, prop, field, items, customOrder, partial);
+        const hasLimit = populate.limit != null;
+        const isPartial = partial || hasLimit;
+        const customOrder = mergedOrderBy.length > 0 || !!prop.orderBy || !!prop.targetMeta?.orderBy;
+        this.initializeCollections(filtered, prop, field, items, customOrder, isPartial, hasLimit);
         return items;
     }
     async populateScalar(meta, filtered, options) {
@@ -269,15 +272,15 @@ export class EntityLoader {
         }));
         return allItems;
     }
-    initializeCollections(filtered, prop, field, children, customOrder, partial) {
+    initializeCollections(filtered, prop, field, children, customOrder, partial, readonly) {
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
-            this.initializeOneToMany(filtered, children, prop, field, partial);
+            this.initializeOneToMany(filtered, children, prop, field, partial, readonly);
         }
         if (prop.kind === ReferenceKind.MANY_TO_MANY && !this.#driver.getPlatform().usesPivotTable()) {
-            this.initializeManyToMany(filtered, children, prop, field, customOrder, partial);
+            this.initializeManyToMany(filtered, children, prop, field, customOrder, partial, readonly);
         }
     }
-    initializeOneToMany(filtered, children, prop, field, partial) {
+    initializeOneToMany(filtered, children, prop, field, partial, readonly) {
         const mapToPk = prop.targetMeta.properties[prop.mappedBy].mapToPk;
         const map = {};
         for (const entity of filtered) {
@@ -293,14 +296,14 @@ export class EntityLoader {
         }
         for (const entity of filtered) {
             const key = helper(entity).getSerializedPrimaryKey();
-            entity[field].hydrate(map[key], undefined, partial);
+            entity[field].hydrate(map[key], undefined, partial, readonly);
         }
     }
-    initializeManyToMany(filtered, children, prop, field, customOrder, partial) {
+    initializeManyToMany(filtered, children, prop, field, customOrder, partial, readonly) {
         if (prop.mappedBy) {
             for (const entity of filtered) {
                 const items = children.filter(child => child[prop.mappedBy].contains(entity, false));
-                entity[field].hydrate(items, true, partial);
+                entity[field].hydrate(items, true, partial, readonly);
             }
         }
         else {
@@ -311,7 +314,7 @@ export class EntityLoader {
                 if (!customOrder) {
                     items.sort((a, b) => order.indexOf(a) - order.indexOf(b));
                 }
-                entity[field].hydrate(items, true, partial);
+                entity[field].hydrate(items, true, partial, readonly);
             }
         }
     }
@@ -375,7 +378,7 @@ export class EntityLoader {
             where = { $and: [where, prop.where] };
         }
         const orderBy = QueryHelper.mergeOrderBy(options.orderBy, prop.orderBy);
-        const items = await this.#em.find(meta.class, where, {
+        const findOptions = {
             filters,
             convertCustomTypes,
             lockMode,
@@ -394,7 +397,15 @@ export class EntityLoader {
             refresh: refresh && !children.every(item => options.visited.has(item)),
             // @ts-ignore not a public option, will be propagated to the populate call
             visited: options.visited,
-        });
+        };
+        if (populate.limit != null) {
+            findOptions._partitionLimit = {
+                partitionBy: fk,
+                limit: populate.limit,
+                offset: populate.offset,
+            };
+        }
+        const items = await this.#em.find(meta.class, where, findOptions);
         // For targetKey relations, wire up loaded entities to parent references
         // This is needed because the references were created under alternate key,
         // but loaded entities are stored under PK, so they don't automatically merge
@@ -582,11 +593,18 @@ export class EntityLoader {
         const options2 = { ...options, fields, exclude, populateFilter };
         ['limit', 'offset', 'first', 'last', 'before', 'after', 'overfetch'].forEach(prop => delete options2[prop]);
         options2.populate = populate?.children ?? [];
+        if (populate?.limit != null) {
+            options2._partitionLimit = {
+                limit: populate.limit,
+                offset: populate.offset,
+            };
+        }
         if (!Utils.isEmpty(prop.where)) {
             where = { $and: [where, prop.where] };
         }
         const map = await this.#driver.loadFromPivotTable(prop, ids, where, orderBy, this.#em.getTransactionContext(), options2, pivotJoin);
         const children = [];
+        const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
         for (let i = 0; i < filtered.length; i++) {
             const entity = filtered[i];
             const items = map[Utils.getPrimaryKeyHash(ids[i])].map(item => {
@@ -596,7 +614,11 @@ export class EntityLoader {
                         schema: options.schema ?? this.#em.config.get('schema'),
                     });
                 }
-                const entity = this.#em.getEntityFactory().create(prop.targetMeta.class, item, {
+                // Union-target items carry their concrete class via `constructor` — dispatch to the right factory call.
+                const targetClass = isUnionTargetMN && item.constructor !== Object
+                    ? item.constructor
+                    : prop.targetMeta.class;
+                const entity = this.#em.getEntityFactory().create(targetClass, item, {
                     refresh,
                     merge: true,
                     convertCustomTypes: true,
@@ -604,7 +626,8 @@ export class EntityLoader {
                 });
                 return this.#em.getUnitOfWork().register(entity, item, { refresh, loaded: true });
             });
-            entity[prop.name].hydrate(items, true);
+            const hasLimit = populate?.limit != null;
+            entity[prop.name].hydrate(items, true, hasLimit, hasLimit);
             children.push(items);
         }
         return children;

package/entity/EntityRepository.d.ts

@@ -1,8 +1,8 @@
 import type { PopulatePath } from '../enums.js';
 import type { CreateOptions, EntityManager, MergeOptions } from '../EntityManager.js';
 import type { AssignOptions } from './EntityAssigner.js';
-import type { EntityData, EntityName, Primary, Loaded, FilterQuery, EntityDictionary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement } from '../typings.js';
-import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
+import type { Dictionary, EntityData, EntityDictionary, EntityKey, EntityName, FilterQuery, Loaded, Primary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement, IndexFilterQuery, WithUsingOptions } from '../typings.js';
+import type { CountByOptions, CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
 import type { Cursor } from '../utils/Cursor.js';
 /** Repository class providing a type-safe API for querying and persisting a specific entity type. */
@@ -13,13 +13,17 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * Finds first entity matching your `where` query.
      */
-    findOne<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOneOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
+    findOne<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<Entity, Using>, options?: FindOneOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
     /**
      * Finds first entity matching your `where` query. If nothing is found, it will throw an error.
      * You can override the factory for creating this method via `options.failHandler` locally
      * or via `Configuration.findOneOrFailHandler` globally.
      */
-    findOneOrFail<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOneOrFailOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>>;
+    findOneOrFail<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<Entity, Using>, options?: FindOneOrFailOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): Promise<Loaded<Entity, Hint, Fields, Excludes>>;
     /**
      * Creates or updates the entity, based on whether it is already present in the database.
      * This method performs an `insert on conflict merge` query ensuring the database is in sync, returning a managed
@@ -72,24 +76,28 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * Finds all entities matching your `where` query. You can pass additional options via the `options` parameter.
      */
-    find<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    find<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<Entity, Using>, options?: FindOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
     /**
      * Calls `em.find()` and `em.count()` with the same arguments (where applicable) and returns the results as tuple
      * where first element is the array of entities, and the second is the count.
      */
-    findAndCount<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOptions<Entity, Hint, Fields, Excludes>): Promise<[Loaded<Entity, Hint, Fields, Excludes>[], number]>;
+    findAndCount<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<Entity, Using>, options?: FindOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): Promise<[Loaded<Entity, Hint, Fields, Excludes>[], number]>;
     /**
      * @inheritDoc EntityManager.findByCursor
      */
-    findByCursor<Hint extends string = never, Fields extends string = never, Excludes extends string = never, IncludeCount extends boolean = true>(options: FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
+    findByCursor<Hint extends string = never, Fields extends string = never, Excludes extends string = never, IncludeCount extends boolean = true, Using extends string = never>(options: WithUsingOptions<FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>, Entity, Using>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
     /**
      * Finds all entities of given type. You can pass additional options via the `options` parameter.
      */
-    findAll<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: FindAllOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    findAll<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(options?: WithUsingOptions<FindAllOptions<Entity, Hint, Fields, Excludes>, Entity, Using>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
     /**
      * @inheritDoc EntityManager.stream
      */
-    stream<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: StreamOptions<Entity, Hint, Fields, Excludes>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
+    stream<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(options?: WithUsingOptions<StreamOptions<Entity, Hint, Fields, Excludes>, Entity, Using>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
     /**
      * @inheritDoc EntityManager.insert
      */
@@ -199,6 +207,16 @@ export declare class EntityRepository<Entity extends object> {
      * Returns total number of entities matching your `where` query.
      */
     count<Hint extends string = never>(where?: FilterQuery<Entity>, options?: CountOptions<Entity, Hint>): Promise<number>;
+    /**
+     * Counts entities grouped by one or more properties.
+     *
+     * @example
+     * ```ts
+     * const counts = await repo.countBy('status');
+     * // { 'active': 5, 'inactive': 2 }
+     * ```
+     */
+    countBy(groupBy: EntityKey<Entity> | readonly EntityKey<Entity>[], options?: CountByOptions<Entity>): Promise<Dictionary<number>>;
     /** Returns the entity class name associated with this repository. */
     getEntityName(): string;
     /**

package/entity/EntityRepository.js

@@ -194,6 +194,18 @@ export class EntityRepository {
     async count(where = {}, options = {}) {
         return this.getEntityManager().count(this.entityName, where, options);
     }
+    /**
+     * Counts entities grouped by one or more properties.
+     *
+     * @example
+     * ```ts
+     * const counts = await repo.countBy('status');
+     * // { 'active': 5, 'inactive': 2 }
+     * ```
+     */
+    async countBy(groupBy, options) {
+        return this.getEntityManager().countBy(this.entityName, groupBy, options);
+    }
     /** Returns the entity class name associated with this repository. */
     getEntityName() {
         return Utils.className(this.entityName);

package/entity/WrappedEntity.d.ts

@@ -1,6 +1,6 @@
 import type { PopulatePath } from '../enums.js';
 import type { EntityManager } from '../EntityManager.js';
-import type { Dictionary, EntityData, EntityDictionary, EntityMetadata, IHydrator, EntityKey, PopulateOptions, Primary, AutoPath, Ref, AddEager, LoadedReference, EntityDTO, Loaded, SerializeDTO, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
+import type { Dictionary, EntityData, EntityDictionary, EntityMetadata, IHydrator, EntityKey, PopulateOptions, Primary, AutoPath, Ref, AddEager, LoadedReference, EntityDTO, Loaded, ExtractFieldsHint, ResolveSerializeFields, SerializeDTO, SerializeFieldsKeepPK, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
 import { Reference } from './Reference.js';
 import { type AssignOptions } from './EntityAssigner.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
@@ -54,7 +54,7 @@ export declare class WrappedEntity<Entity extends object> {
     /** Converts the entity to a plain object representation, optionally excluding specified fields. */
     toObject<Ignored extends EntityKey<Entity> = never>(ignoreFields?: Ignored[]): Omit<EntityDTO<Entity>, Ignored>;
     /** Serializes the entity with control over which relations and fields to include or exclude. */
-    serialize<Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Entity, Hint, Exclude>): SerializeDTO<Entity, Hint, Exclude>;
+    serialize<Hint extends string = never, Exclude extends string = never, Fields extends string = never>(options?: SerializeOptions<FromEntityType<Entity>, Hint, Exclude, Fields>): SerializeDTO<FromEntityType<Entity>, Hint, Exclude, never, ResolveSerializeFields<Fields, ExtractFieldsHint<Entity>>, SerializeFieldsKeepPK<Fields>>;
     /** Converts the entity to a plain object, including all properties regardless of serialization rules. */
     toPOJO(): EntityDTO<Entity>;
     /** Serializes the entity using its `toJSON` method (supports `JSON.stringify`). */

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, 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';
@@ -104,8 +104,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;
@@ -127,9 +135,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;
@@ -334,12 +346,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)
      *
@@ -556,7 +576,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?: {
@@ -609,6 +629,15 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         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 +694,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;

package/entity/defineEntity.js

@@ -191,15 +191,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, 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/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.
@@ -105,6 +115,7 @@ export declare class MetadataDiscovery {
     private initAutoincrement;
     private createSchemaTable;
     private initCheckConstraints;
+    private initTriggers;
     private initGeneratedColumn;
     private getDefaultVersionValue;
     private inferDefaultValue;