@mikro-orm/core 7.0.0-dev.1 → 7.0.0-dev.100

package/EntityManager.d.ts

@@ -1,16 +1,18 @@
-import { inspect } from 'node:util';
-import DataLoader from 'dataloader';
-import { type Configuration } from './utils/Configuration';
-import { Cursor } from './utils/Cursor';
-import { type AssignOptions, EntityFactory, type EntityLoaderOptions, type EntityRepository, EntityValidator, Reference } from './entity';
-import { UnitOfWork } from './unit-of-work';
-import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, IDatabaseDriver, LockOptions, NativeInsertUpdateOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from './drivers';
-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';
-import { FlushMode, LockMode, PopulatePath, type TransactionOptions } from './enums';
-import type { MetadataStorage } from './metadata';
-import type { Transaction } from './connections';
-import { EventManager } from './events';
-import type { EntityComparator } from './utils/EntityComparator';
+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 { 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, 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, EntityData, EntityDictionary, EntityDTO, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, 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';
+import { EventManager } from './events/EventManager.js';
+import type { EntityComparator } from './utils/EntityComparator.js';
 /**
  * The EntityManager is the central access point to ORM functionality. It is a facade to all different ORM subsystems
  * such as UnitOfWork, Query Language, and Repository API.
@@ -22,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").LoadReferenceOptions<any, any, "*", never>, "dataloader"> | undefined)?], any, [Reference<any>, (Omit<import("./entity").LoadReferenceOptions<any, any, "*", never>, "dataloader"> | undefined)?]>;
-    protected readonly colLoader: DataLoader<[import("./entity").Collection<any, object>, (Omit<import("./entity").InitCollectionOptions<any, any, "*", never>, "dataloader"> | undefined)?], any, [import("./entity").Collection<any, object>, (Omit<import("./entity").InitCollectionOptions<any, any, "*", never>, "dataloader"> | undefined)?]>;
-    private readonly validator;
+    private readonly loaders;
     private readonly repositoryMap;
     private readonly entityLoader;
     protected readonly comparator: EntityComparator;
@@ -67,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.
      */
@@ -83,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<any> | readonly EntityName<any>[]>(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.
@@ -112,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;
+    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: 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.
@@ -166,6 +175,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
@@ -175,7 +188,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,
@@ -183,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>(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
@@ -258,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>;
     /**
@@ -375,11 +411,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.
@@ -387,11 +418,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.
@@ -414,7 +440,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
      */
@@ -427,6 +453,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.
      */
@@ -474,7 +504,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
      */
@@ -483,15 +513,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.
@@ -515,13 +545,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 */
@@ -534,11 +564,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 */
@@ -552,7 +590,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? */