@mikro-orm/core 7.0.0-dev.4 → 7.0.0-dev.41

package/EntityManager.d.ts

@@ -6,11 +6,11 @@ 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 { type EntityLoaderOptions } from './entity/EntityLoader.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 { AnyEntity, AnyString, ArrayElement, AutoPath, ConnectionType, Dictionary, EntityData, EntityDictionary, EntityDTO, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MaybePromise, MergeLoaded, MergeSelected, NoInfer, ObjectQuery, 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,12 +27,15 @@ 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)?]>;
+    protected readonly colLoaderMtoN: 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 repositoryMap;
     private readonly entityLoader;
@@ -80,6 +83,24 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * 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 +109,19 @@ 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;
+    addFilter<T1>(name: string, cond: FilterQuery<T1> | ((args: Dictionary) => MaybePromise<FilterQuery<T1>>), entityName?: EntityName<T1> | [EntityName<T1>], options?: boolean | Partial<FilterDef>): 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;
+    addFilter<T1, T2>(name: string, cond: FilterQuery<T1 | T2> | ((args: Dictionary) => MaybePromise<FilterQuery<T1 | T2>>), entityName?: [EntityName<T1>, EntityName<T2>], options?: boolean | Partial<FilterDef>): 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;
+    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>], options?: boolean | Partial<FilterDef>): 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(name: string, cond: Dictionary | ((args: Dictionary) => MaybePromise<FilterQuery<AnyEntity>>), entityName?: EntityName<AnyEntity> | EntityName<AnyEntity>[], options?: boolean | Partial<FilterDef>): 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 +138,25 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Gets logger context for this entity manager.
      */
-    getLoggerContext<T extends Dictionary = Dictionary>(): T;
+    getLoggerContext<T extends Dictionary = Dictionary>(options?: {
+        disableContextResolution?: boolean;
+    }): 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>;
     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?: {
+        className: string;
+        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: string, 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.
@@ -171,6 +197,10 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * });
      * ```
      *
+     * The options also support an `includeCount` (true by default) option. If set to false, the `totalCount` is not
+     * returned as part of the cursor. This is useful for performance reason, when you don't care about the total number
+     * of pages.
+     *
      * The `Cursor` object provides the following interface:
      *
      * ```ts
@@ -180,7 +210,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      *     User { ... },
      *     User { ... },
      *   ],
-     *   totalCount: 50,
+     *   totalCount: 50, // not included if `includeCount: false`
      *   startCursor: 'WzRd',
      *   endCursor: 'WzZd',
      *   hasPrevPage: true,
@@ -188,7 +218,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * }
      * ```
      */
-    findByCursor<Entity extends object, Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options: FindByCursorOptions<Entity, Hint, Fields, Excludes>): Promise<Cursor<Entity, Hint, Fields, Excludes>>;
+    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>>;
     /**
      * 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
@@ -263,6 +293,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>;
     /**
@@ -419,7 +472,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Loads specified relations in batch. This will execute one query for each relation, that will populate it on all the specified entities.
      */
-    populate<Entity extends object, Naked extends FromEntityType<UnboxArray<Entity>> = FromEntityType<UnboxArray<Entity>>, Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(entities: Entity, populate: AutoPath<Naked, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Naked, Fields, Excludes>): Promise<Entity extends object[] ? MergeLoaded<ArrayElement<Entity>, Naked, Hint, Fields, Excludes>[] : MergeLoaded<Entity, Naked, Hint, Fields, Excludes>>;
+    populate<Entity extends object, Naked extends FromEntityType<UnboxArray<Entity>> = FromEntityType<UnboxArray<Entity>>, Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(entities: Entity, populate: readonly AutoPath<Naked, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Naked, Fields, Excludes>): Promise<Entity extends object[] ? MergeLoaded<ArrayElement<Entity>, Naked, Hint, Fields, Excludes>[] : MergeLoaded<Entity, Naked, Hint, Fields, Excludes>>;
     /**
      * Returns new EntityManager instance with its own identity map
      */
@@ -432,6 +485,10 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Gets the EntityFactory used by the EntityManager.
      */
     getEntityFactory(): EntityFactory;
+    /**
+     * @internal use `em.populate()` as the user facing API, this is exposed only for internal usage
+     */
+    getEntityLoader(): EntityLoader;
     /**
      * Gets the Hydrator used by the EntityManager.
      */
@@ -479,7 +536,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * 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
      */
@@ -488,15 +545,15 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * @internal
      */
     tryCache<T extends object, R>(entityName: string, config: boolean | number | [string, number] | undefined, key: unknown, refresh?: boolean, merge?: boolean): Promise<{
-        data?: R;
+        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.
@@ -539,11 +596,20 @@ 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;
+    keepIdentity?: boolean;
+    validate?: boolean;
+    cascade?: boolean; /** @default true */
 }
 export interface ForkOptions {
     /** do we want a clear identity map? defaults to true */