@mikro-orm/core 7.0.17 → 7.0.18-dev.1

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,
@@ -390,11 +393,21 @@ export class EntityLoader {
             fields,
             schema,
             connectionType,
+            signal: options.signal,
+            inflightQueryAbortStrategy: options.inflightQueryAbortStrategy,
             // @ts-ignore not a public option, will be propagated to the populate call
             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 +595,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 +616,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 +628,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/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/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, 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;
@@ -127,9 +152,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 +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}.
      */
@@ -334,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)
      *
@@ -427,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>;
     /**
@@ -434,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>;
@@ -492,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. */
@@ -536,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';
     }>;
@@ -556,7 +615,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, 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' | '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?: {
@@ -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,12 +667,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, 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>;
@@ -669,7 +739,9 @@ export type InferEntityFromProperties<Properties extends Record<string, any>, PK
     [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;
@@ -714,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 });