@mikro-orm/core 7.0.0-dev.20 → 7.0.0-dev.201

package/EntityManager.d.ts

@@ -1,16 +1,13 @@
-import { inspect } from 'node:util';
-import DataLoader from 'dataloader';
 import { type Configuration } from './utils/Configuration.js';
 import { Cursor } from './utils/Cursor.js';
 import { EntityFactory } from './entity/EntityFactory.js';
 import { type AssignOptions } from './entity/EntityAssigner.js';
-import { EntityValidator } from './entity/EntityValidator.js';
 import { type EntityRepository } from './entity/EntityRepository.js';
 import { EntityLoader, type EntityLoaderOptions } from './entity/EntityLoader.js';
 import { Reference } from './entity/Reference.js';
 import { UnitOfWork } from './unit-of-work/UnitOfWork.js';
-import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, IDatabaseDriver, LockOptions, NativeInsertUpdateOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from './drivers/IDatabaseDriver.js';
-import type { AnyEntity, AnyString, ArrayElement, AutoPath, ConnectionType, Dictionary, EntityData, EntityDictionary, EntityDTO, EntityMetadata, EntityName, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MaybePromise, MergeLoaded, MergeSelected, NoInfer, ObjectQuery, Primary, Ref, RequiredEntityData, UnboxArray } from './typings.js';
+import type { CountOptions, DeleteOptions, FilterOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, IDatabaseDriver, LockOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from './drivers/IDatabaseDriver.js';
+import type { AnyString, ArrayElement, AutoPath, ConnectionType, Dictionary, EntityClass, EntityData, EntityDictionary, EntityDTO, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MergeLoaded, MergeSelected, NoInfer, ObjectQuery, PopulateOptions, Primary, Ref, RequiredEntityData, UnboxArray } from './typings.js';
 import { FlushMode, LockMode, PopulatePath, type TransactionOptions } from './enums.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
 import type { Transaction } from './connections/Connection.js';
@@ -27,13 +24,13 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     protected readonly metadata: MetadataStorage;
     protected readonly useContext: boolean;
     protected readonly eventManager: EventManager;
+    /** @internal */
+    readonly '~entities'?: unknown;
     private static counter;
     readonly _id: number;
     readonly global = false;
     readonly name: string;
-    protected readonly refLoader: DataLoader<[Reference<any>, (Omit<import("./entity/Reference.js").LoadReferenceOptions<any, any, "*", never>, "dataloader"> | undefined)?], any, [Reference<any>, (Omit<import("./entity/Reference.js").LoadReferenceOptions<any, any, "*", never>, "dataloader"> | undefined)?]>;
-    protected readonly colLoader: DataLoader<[import("./index.js").Collection<any, object>, (Omit<import("./index.js").InitCollectionOptions<any, any, "*", never>, "dataloader"> | undefined)?], any, [import("./index.js").Collection<any, object>, (Omit<import("./index.js").InitCollectionOptions<any, any, "*", never>, "dataloader"> | undefined)?]>;
-    private readonly validator;
+    private readonly loaders;
     private readonly repositoryMap;
     private readonly entityLoader;
     protected readonly comparator: EntityComparator;
@@ -72,14 +69,28 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Shortcut for `em.getRepository()`.
      */
     repo<Entity extends object, Repository extends EntityRepository<Entity> = EntityRepository<Entity>>(entityName: EntityName<Entity>): GetRepository<Entity, Repository>;
-    /**
-     * Gets EntityValidator instance
-     */
-    getValidator(): EntityValidator;
     /**
      * Finds all entities matching your `where` query. You can pass additional options via the `options` parameter.
      */
     find<Entity extends object, Hint extends string = never, Fields extends string = PopulatePath.ALL, Excludes extends string = never>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options?: FindOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    /**
+     * Finds all entities and returns an async iterable (async generator) that yields results one by one.
+     * The results are merged and mapped to entity instances, without adding them to the identity map.
+     * You can disable merging by passing the options `{ mergeResults: false }`.
+     * With `mergeResults` disabled, to-many collections will contain at most one item, and you will get duplicate
+     * root entities when there are multiple items in the populated collection.
+     * This is useful for processing large datasets without loading everything into memory at once.
+     *
+     * ```ts
+     * const stream = em.stream(Book, { populate: ['author'] });
+     *
+     * for await (const book of stream) {
+     *   // book is an instance of Book entity
+     *   console.log(book.title, book.author.name);
+     * }
+     * ```
+     */
+    stream<Entity extends object, Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(entityName: EntityName<Entity>, options?: StreamOptions<NoInfer<Entity>, Hint, Fields, Excludes>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
     /**
      * Finds all entities of given type, optionally matching the `where` condition provided in the `options` parameter.
      */
@@ -88,19 +99,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
      */
-    addFilter<T1>(name: string, cond: FilterQuery<T1> | ((args: Dictionary) => MaybePromise<FilterQuery<T1>>), entityName?: EntityName<T1> | [EntityName<T1>], enabled?: boolean): void;
-    /**
-     * Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
-     */
-    addFilter<T1, T2>(name: string, cond: FilterQuery<T1 | T2> | ((args: Dictionary) => MaybePromise<FilterQuery<T1 | T2>>), entityName?: [EntityName<T1>, EntityName<T2>], enabled?: boolean): void;
-    /**
-     * Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
-     */
-    addFilter<T1, T2, T3>(name: string, cond: FilterQuery<T1 | T2 | T3> | ((args: Dictionary) => MaybePromise<FilterQuery<T1 | T2 | T3>>), entityName?: [EntityName<T1>, EntityName<T2>, EntityName<T3>], enabled?: boolean): void;
-    /**
-     * Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
-     */
-    addFilter(name: string, cond: Dictionary | ((args: Dictionary) => MaybePromise<FilterQuery<AnyEntity>>), entityName?: EntityName<AnyEntity> | EntityName<AnyEntity>[], enabled?: boolean): void;
+    addFilter<T extends EntityName | readonly EntityName[]>(options: FilterDef<T>): void;
     /**
      * Sets filter parameter values globally inside context defined by this entity manager.
      * If you want to set shared value for all contexts, be sure to use the root entity manager.
@@ -117,20 +116,25 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Gets logger context for this entity manager.
      */
-    getLoggerContext<T extends Dictionary = Dictionary>(): T;
-    setFlushMode(flushMode?: FlushMode): void;
-    protected processWhere<Entity extends object, Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(entityName: string, where: FilterQuery<Entity>, options: FindOptions<Entity, Hint, Fields, Excludes> | FindOneOptions<Entity, Hint, Fields, Excludes>, type: 'read' | 'update' | 'delete'): Promise<FilterQuery<Entity>>;
-    protected applyDiscriminatorCondition<Entity extends object>(entityName: string, where: FilterQuery<Entity>): FilterQuery<Entity>;
+    getLoggerContext<T extends Dictionary = Dictionary>(options?: {
+        disableContextResolution?: boolean;
+    }): T;
+    setFlushMode(flushMode?: FlushMode | `${FlushMode}`): void;
+    protected processWhere<Entity extends object, Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(entityName: EntityName<Entity>, where: FilterQuery<Entity>, options: FindOptions<Entity, Hint, Fields, Excludes> | FindOneOptions<Entity, Hint, Fields, Excludes>, type: 'read' | 'update' | 'delete'): Promise<FilterQuery<Entity>>;
+    protected applyDiscriminatorCondition<Entity extends object>(entityName: EntityName<Entity>, where: FilterQuery<Entity>): FilterQuery<Entity>;
     protected createPopulateWhere<Entity extends object>(cond: ObjectQuery<Entity>, options: FindOptions<Entity, any, any, any> | FindOneOptions<Entity, any, any, any> | CountOptions<Entity, any>): ObjectQuery<Entity>;
-    protected getJoinedFilters<Entity extends object>(meta: EntityMetadata<Entity>, cond: ObjectQuery<Entity>, options: FindOptions<Entity, any, any, any> | FindOneOptions<Entity, any, any, any>): Promise<ObjectQuery<Entity>>;
+    protected getJoinedFilters<Entity extends object>(meta: EntityMetadata<Entity>, options: FindOptions<Entity, any, any, any> | FindOneOptions<Entity, any, any, any>): Promise<ObjectQuery<Entity> | undefined>;
     /**
      * When filters are active on M:1 or 1:1 relations, we need to ref join them eagerly as they might affect the FK value.
      */
-    protected autoJoinRefsForFilters<T extends object>(meta: EntityMetadata<T>, options: FindOptions<T, any, any, any> | FindOneOptions<T, any, any, any>): Promise<void>;
+    protected autoJoinRefsForFilters<T extends object>(meta: EntityMetadata<T>, options: FindOptions<T, any, any, any> | FindOneOptions<T, any, any, any>, parent?: {
+        class: EntityClass;
+        propName: string;
+    }): Promise<void>;
     /**
      * @internal
      */
-    applyFilters<Entity extends object>(entityName: string, where: FilterQuery<Entity> | undefined, options: Dictionary<boolean | Dictionary> | string[] | boolean, type: 'read' | 'update' | 'delete', findOptions?: FindOptions<any, any, any, any> | FindOneOptions<any, any, any, any>): Promise<FilterQuery<Entity> | undefined>;
+    applyFilters<Entity extends object>(entityName: EntityName<Entity>, where: FilterQuery<Entity> | undefined, options: FilterOptions | undefined, type: 'read' | 'update' | 'delete', findOptions?: FindOptions<any, any, any, any> | FindOneOptions<any, any, any, any>): Promise<FilterQuery<Entity> | undefined>;
     /**
      * Calls `em.find()` and `em.count()` with the same arguments (where applicable) and returns the results as tuple
      * where the first element is the array of entities, and the second is the count.
@@ -150,21 +154,21 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      *     - POJO/entity instance
      *
      * ```ts
-     * const currentCursor = await em.findByCursor(User, {}, {
+     * const currentCursor = await em.findByCursor(User, {
      *   first: 10,
      *   after: previousCursor, // cursor instance
      *   orderBy: { id: 'desc' },
      * });
      *
      * // to fetch next page
-     * const nextCursor = await em.findByCursor(User, {}, {
+     * const nextCursor = await em.findByCursor(User, {
      *   first: 10,
      *   after: currentCursor.endCursor, // opaque string
      *   orderBy: { id: 'desc' },
      * });
      *
      * // to fetch next page
-     * const nextCursor2 = await em.findByCursor(User, {}, {
+     * const nextCursor2 = await em.findByCursor(User, {
      *   first: 10,
      *   after: { id: lastSeenId }, // entity-like POJO
      *   orderBy: { id: 'desc' },
@@ -192,7 +196,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * }
      * ```
      */
-    findByCursor<Entity extends object, Hint extends string = never, Fields extends string = '*', Excludes extends string = never, IncludeCount extends boolean = true>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options: FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
+    findByCursor<Entity extends object, Hint extends string = never, Fields extends string = '*', Excludes extends string = never, IncludeCount extends boolean = true>(entityName: EntityName<Entity>, options: FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
     /**
      * Refreshes the persistent state of an entity from the database, overriding any local changes that have not yet been
      * persisted. Returns the same entity instance (same object reference), but re-hydrated. If the entity is no longer
@@ -267,6 +271,29 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     upsertMany<Entity extends object, Fields extends string = any>(entityNameOrEntity: EntityName<Entity> | Entity[], data?: (EntityData<Entity> | NoInfer<Entity>)[], options?: UpsertManyOptions<Entity, Fields>): Promise<Entity[]>;
     /**
      * Runs your callback wrapped inside a database transaction.
+     *
+     * If a transaction is already active, a new savepoint (nested transaction) will be created by default. This behavior
+     * can be controlled via the `propagation` option. Use the provided EntityManager instance for all operations that
+     * should be part of the transaction. You can safely use a global EntityManager instance from a DI container, as this
+     * method automatically creates an async context for the transaction.
+     *
+     * **Concurrency note:** When running multiple transactions concurrently (e.g. in parallel requests or jobs), use the
+     * `clear: true` option. This ensures the callback runs in a clear fork of the EntityManager, providing full isolation
+     * between concurrent transactional handlers. Using `clear: true` is an alternative to forking explicitly and calling
+     * the method on the new fork – it already provides the necessary isolation for safe concurrent usage.
+     *
+     * **Propagation note:** Changes made within a transaction (whether top-level or nested) are always propagated to the
+     * parent context, unless the parent context is a global one. If you want to avoid that, fork the EntityManager first
+     * and then call this method on the fork.
+     *
+     * **Example:**
+     * ```ts
+     * await em.transactional(async (em) => {
+     *   const author = new Author('Jon');
+     *   em.persist(author);
+     *   // flush is called automatically at the end of the callback
+     * });
+     * ```
      */
     transactional<T>(cb: (em: this) => T | Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
@@ -355,10 +382,26 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Shortcut for `wrap(entity).assign(data, { em })`
      */
     assign<Entity extends object, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Convert extends boolean = false, Data extends EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>>(entity: Entity | Partial<Entity>, data: Data & IsSubset<EntityData<Naked, Convert>, Data>, options?: AssignOptions<Convert>): MergeSelected<Entity, Naked, keyof Data & string>;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<Entity extends object, K extends string & keyof Entity>(entityName: EntityName<Entity>, id: Entity[K], options: Omit<GetReferenceOptions, 'key' | 'wrapped'> & {
+        key: K;
+        wrapped: true;
+    }): Ref<Entity>;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<Entity extends object, K extends string & keyof Entity>(entityName: EntityName<Entity>, id: Entity[K], options: Omit<GetReferenceOptions, 'key'> & {
+        key: K;
+        wrapped?: false;
+    }): Entity;
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: true;
     }): Ref<Entity>;
     /**
@@ -368,7 +411,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: false;
     }): Entity;
     /**
@@ -384,11 +427,6 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * The entity will be entered into the database at or before transaction commit or as a result of the flush operation.
      */
     persist<Entity extends object>(entity: Entity | Reference<Entity> | Iterable<Entity | Reference<Entity>>): this;
-    /**
-     * Persists your entity immediately, flushing all not yet persisted changes to the database too.
-     * Equivalent to `em.persist(e).flush()`.
-     */
-    persistAndFlush(entity: AnyEntity | Reference<AnyEntity> | Iterable<AnyEntity | Reference<AnyEntity>>): Promise<void>;
     /**
      * Marks entity for removal.
      * A removed entity will be removed from the database at or before transaction commit or as a result of the flush operation.
@@ -396,11 +434,6 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * To remove entities by condition, use `em.nativeDelete()`.
      */
     remove<Entity extends object>(entity: Entity | Reference<Entity> | Iterable<Entity | Reference<Entity>>): this;
-    /**
-     * Removes an entity instance immediately, flushing all not yet persisted changes to the database too.
-     * Equivalent to `em.remove(e).flush()`
-     */
-    removeAndFlush(entity: AnyEntity | Reference<AnyEntity> | Iterable<AnyEntity | Reference<AnyEntity>>): Promise<void>;
     /**
      * Flushes all changes to objects that have been queued up to now to the database.
      * This effectively synchronizes the in-memory state of managed objects with the database.
@@ -481,30 +514,31 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     private checkLockRequirements;
     private lockAndPopulate;
     private buildFields;
-    private preparePopulate;
+    /** @internal */
+    preparePopulate<Entity extends object>(entityName: EntityName<Entity>, options: Pick<FindOptions<Entity, any, any, any>, 'populate' | 'strategy' | 'fields' | 'flags' | 'filters' | 'exclude'>, validate?: boolean): Promise<PopulateOptions<Entity>[]>;
     /**
      * when the entity is found in identity map, we check if it was partially loaded or we are trying to populate
      * some additional lazy properties, if so, we reload and merge the data from database
      */
     protected shouldRefresh<T extends object, P extends string = never, F extends string = '*', E extends string = never>(meta: EntityMetadata<T>, entity: T, options: FindOneOptions<T, P, F, E>): boolean;
-    protected prepareOptions(options: FindOptions<any, any, any, any> | FindOneOptions<any, any, any, any>): void;
+    protected prepareOptions(options: FindOptions<any, any, any, any> | FindOneOptions<any, any, any, any> | CountOptions<any, any>): void;
     /**
      * @internal
      */
-    cacheKey<T extends object>(entityName: string, options: FindOptions<T, any, any, any> | FindOneOptions<T, any, any, any> | CountOptions<T, any>, method: string, where: FilterQuery<T>): unknown[];
+    cacheKey<T extends object>(entityName: EntityName<T>, options: FindOptions<T, any, any, any> | FindOneOptions<T, any, any, any> | CountOptions<T, any>, method: string, where: FilterQuery<T>): unknown[];
     /**
      * @internal
      */
-    tryCache<T extends object, R>(entityName: string, config: boolean | number | [string, number] | undefined, key: unknown, refresh?: boolean, merge?: boolean): Promise<{
+    tryCache<T extends object, R>(entityName: EntityName<T>, config: boolean | number | [string, number] | undefined, key: unknown, refresh?: boolean, merge?: boolean): Promise<{
         data?: R | null;
         key: string;
     } | undefined>;
     /**
      * @internal
      */
-    storeCache(config: boolean | number | [string, number] | undefined, key: {
+    storeCache<T>(config: boolean | number | [string, number] | undefined, key: {
         key: string;
-    }, data: unknown | (() => unknown)): Promise<void>;
+    }, data: T | (() => T)): Promise<void>;
     /**
      * Clears result cache for given cache key. If we want to be able to call this method,
      * we need to set the cache key explicitly when storing the cache.
@@ -528,13 +562,13 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * if executed inside request context handler.
      */
     set schema(schema: string | null | undefined);
+    /** @internal */
+    getDataLoader(type: 'ref' | '1:m' | 'm:n'): Promise<any>;
     /**
      * Returns the ID of this EntityManager. Respects the context, so global EM will give you the contextual ID
      * if executed inside request context handler.
      */
     get id(): number;
-    /** @ignore */
-    [inspect.custom](): string;
 }
 export interface CreateOptions<Convert extends boolean> {
     /** creates a managed entity instance instead, bypassing the constructor call */
@@ -547,11 +581,19 @@ export interface CreateOptions<Convert extends boolean> {
     partial?: boolean;
     /** convert raw database values based on mapped types (by default, already converted values are expected) */
     convertCustomTypes?: Convert;
+    /**
+     * Property `onCreate` hooks are normally executed during `flush` operation.
+     * With this option, they will be processed early inside `em.create()` method.
+     */
+    processOnCreateHooksEarly?: boolean;
 }
 export interface MergeOptions {
     refresh?: boolean;
     convertCustomTypes?: boolean;
     schema?: string;
+    disableContextResolution?: boolean;
+    validate?: boolean;
+    cascade?: boolean; /** @default true */
 }
 export interface ForkOptions {
     /** do we want a clear identity map? defaults to true */
@@ -565,7 +607,7 @@ export interface ForkOptions {
     /** use this flag to ignore the current async context - this is required if we want to call `em.fork()` inside the `getContext` handler */
     disableContextResolution?: boolean;
     /** set flush mode for this fork, overrides the global option can be overridden locally via FindOptions */
-    flushMode?: FlushMode;
+    flushMode?: FlushMode | `${FlushMode}`;
     /** disable transactions for this fork */
     disableTransactions?: boolean;
     /** should we keep the transaction context of the parent EM? */