@mikro-orm/core 7.1.0-dev.5 → 7.1.0-dev.50

package/EntityManager.d.ts

@@ -6,11 +6,12 @@ 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, EntityClass, EntityData, EntityDictionary, EntityDTO, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MergeLoaded, MergeSelected, ObjectQuery, PopulateOptions, Primary, Ref, RequiredEntityData, UnboxArray } from './typings.js';
+import type { CountByOptions, 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, EntityKey, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MergeLoaded, MergeSelected, ObjectQuery, PopulateOptions, Primary, Ref, RequiredEntityData, RoutineArgs, RoutineReturn, UnboxArray, IndexFilterQuery, WithUsingOptions } from './typings.js';
+import type { Routine } from './metadata/Routine.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 type { AbortQueryOptions, InflightQueryAbortStrategy, Transaction } from './connections/Connection.js';
 import { EventManager } from './events/EventManager.js';
 import type { EntityComparator } from './utils/EntityComparator.js';
 /**
@@ -33,6 +34,10 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /** The context name of this EntityManager, derived from the ORM configuration. */
     readonly name: string;
     protected loggerContext?: Dictionary;
+    /** @internal */
+    protected signal?: AbortSignal;
+    /** @internal */
+    protected inflightQueryAbortStrategy?: InflightQueryAbortStrategy;
     /**
      * @internal
      */
@@ -61,7 +66,9 @@ 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 = never, Excludes extends string = never>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options?: FindOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    find<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(entityName: EntityName<Entity>, where: [Using] extends [never] ? FilterQuery<NoInfer<Entity>> : IndexFilterQuery<NoInfer<Entity>, Using>, options?: FindOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): 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.
@@ -79,11 +86,11 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * }
      * ```
      */
-    stream<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(entityName: EntityName<Entity>, options?: StreamOptions<NoInfer<Entity>, Hint, Fields, Excludes>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
+    stream<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(entityName: EntityName<Entity>, options?: WithUsingOptions<StreamOptions<NoInfer<Entity>, Hint, Fields, Excludes>, NoInfer<Entity>, Using>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
     /**
      * Finds all entities of given type, optionally matching the `where` condition provided in the `options` parameter.
      */
-    findAll<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(entityName: EntityName<Entity>, options?: FindAllOptions<NoInfer<Entity>, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    findAll<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(entityName: EntityName<Entity>, options?: WithUsingOptions<FindAllOptions<NoInfer<Entity>, Hint, Fields, Excludes>, NoInfer<Entity>, Using>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
     private getPopulateWhere;
     /**
      * Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
@@ -130,7 +137,9 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * 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.
      */
-    findAndCount<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options?: FindOptions<Entity, Hint, Fields, Excludes>): Promise<[Loaded<Entity, Hint, Fields, Excludes>[], number]>;
+    findAndCount<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(entityName: EntityName<Entity>, where: [Using] extends [never] ? FilterQuery<NoInfer<Entity>> : IndexFilterQuery<NoInfer<Entity>, Using>, options?: FindOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): Promise<[Loaded<Entity, Hint, Fields, Excludes>[], number]>;
     /**
      * Calls `em.find()` and `em.count()` with the same arguments (where applicable) and returns the results as {@apilink Cursor} object.
      * Supports `before`, `after`, `first` and `last` options while disallowing `limit` and `offset`. Explicit `orderBy` option
@@ -187,7 +196,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * }
      * ```
      */
-    findByCursor<Entity extends object, Hint extends string = never, Fields extends string = never, 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>>;
+    findByCursor<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never, IncludeCount extends boolean = true, Using extends string = never>(entityName: EntityName<Entity>, options: WithUsingOptions<FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>, Entity, Using>): 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
@@ -203,14 +212,18 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Finds first entity matching your `where` query.
      */
-    findOne<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options?: FindOneOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
+    findOne<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(entityName: EntityName<Entity>, where: [Using] extends [never] ? FilterQuery<NoInfer<Entity>> : IndexFilterQuery<NoInfer<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 found, it will throw an error.
      * If the `strict` option is specified and nothing is found or more than one matching entity is found, it will throw an error.
      * You can override the factory for creating this method via `options.failHandler` locally
      * or via `Configuration.findOneOrFailHandler` (`findExactlyOneOrFailHandler` when specifying `strict`) globally.
      */
-    findOneOrFail<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options?: FindOneOrFailOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>>;
+    findOneOrFail<Entity extends object, Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(entityName: EntityName<Entity>, where: [Using] extends [never] ? FilterQuery<NoInfer<Entity>> : IndexFilterQuery<NoInfer<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
@@ -334,6 +347,29 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Fires native update query. Calling this has no side effects on the context (identity map).
      */
     nativeUpdate<Entity extends object>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, data: EntityData<Entity>, options?: UpdateOptions<Entity>): Promise<number>;
+    /**
+     * Invokes a stored procedure or function declared via the {@link Routine} class. Arg and return
+     * types are inferred from the literal config; use {@link Routine.create} to refine when needed.
+     *
+     * Procedures emitting result sets (MySQL `SELECT`s, PG/Oracle refcursor OUT params) return
+     * `Dictionary[][]`; MSSQL multi-result procs aren't exposed here, use `em.getConnection().execute()`.
+     *
+     * Mongo throws. SQLite bridges `bodyJs` functions via better-sqlite3 UDFs (procedures and
+     * function-without-bodyJs throw); libSQL throws unconditionally. Oracle calls run on their own
+     * pool connection with `autoCommit: true`, so wrapping in `em.transactional(...)` throws.
+     *
+     * @example
+     * ```ts
+     * const hash = await em.callRoutine(HashUser, { name: 'jon', salt: 'pepper' });
+     *
+     * const hashRef = new ScalarReference<string>();
+     * await em.callRoutine(AddRecord, { p_name: 'jon', p_age: 30, p_hash: hashRef });
+     *
+     * const TwoCursors = Routine.create<Record<string, never>, unknown[][]>({ ... });
+     * const [users, books] = await em.transactional(em => em.callRoutine(TwoCursors, {}));
+     * ```
+     */
+    callRoutine<R extends Routine>(routine: R, args: RoutineArgs<R>): Promise<RoutineReturn<R>>;
     /**
      * Fires native delete query. Calling this has no side effects on the context (identity map).
      */
@@ -433,6 +469,27 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Returns total number of entities matching your `where` query.
      */
     count<Entity extends object, Hint extends string = never>(entityName: EntityName<Entity>, where?: FilterQuery<NoInfer<Entity>>, options?: CountOptions<Entity, Hint>): Promise<number>;
+    /**
+     * Counts entities grouped by one or more properties. Returns a dictionary keyed by the grouped
+     * field value(s), with counts as values. For composite `groupBy`, keys are joined with `~~~`.
+     *
+     * SQL drivers issue a single `GROUP BY` query; MongoDB uses an aggregation pipeline.
+     *
+     * @example
+     * ```ts
+     * // Count books per author
+     * const counts = await em.countBy(Book, 'author');
+     * // { '1': 2, '2': 1, '3': 3 }
+     *
+     * // Count with a filter
+     * const counts = await em.countBy(Book, 'author', { where: { active: true } });
+     *
+     * // Composite groupBy — keys joined with ~~~
+     * const counts = await em.countBy(Order, ['status', 'country']);
+     * // { 'pending~~~US': 5, 'shipped~~~DE': 3 }
+     * ```
+     */
+    countBy<Entity extends object>(entityName: EntityName<Entity>, groupBy: EntityKey<Entity> | readonly EntityKey<Entity>[], options?: CountByOptions<Entity>): Promise<Dictionary<number>>;
     /**
      * Tells the EntityManager to make an instance managed and persistent.
      * The entity will be entered into the database at or before transaction commit or as a result of the flush operation.
@@ -503,6 +560,13 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Gets the transaction context (driver dependent object used to make sure queries are executed on same connection).
      */
     getTransactionContext<T extends Transaction = Transaction>(): T | undefined;
+    /**
+     * Returns the cancellation defaults configured on this EntityManager (via `em.fork({ signal })`
+     * or inherited from a transactional fork). Returns `undefined` when no signal is set.
+     *
+     * @internal — exposed for subclass drivers and `UnitOfWork`; not part of the public API.
+     */
+    protected getAbortOptions(): AbortQueryOptions | undefined;
     /**
      * Sets the transaction context.
      */
@@ -524,16 +588,20 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      */
     getComparator(): EntityComparator;
     private checkLockRequirements;
+    private validateIndexUsage;
+    private validateWhereKeysForIndex;
     private lockAndPopulate;
     private buildFields;
     /** @internal */
     preparePopulate<Entity extends object>(entityName: EntityName<Entity>, options: Pick<FindOptions<Entity, any, any, any>, 'populate' | 'strategy' | 'fields' | 'flags' | 'filters' | 'exclude' | 'populateHints'>, validate?: boolean): Promise<PopulateOptions<Entity>[]>;
+    /** Force SELECT_IN strategy on populate entries with `limit`, since JOINED cannot do per-parent limiting. */
+    private forceSelectInForLimitedPopulate;
     /**
      * 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 = never, 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> | CountOptions<any, any>): void;
+    protected prepareOptions(options: (FindOptions<any, any, any, any> | FindOneOptions<any, any, any, any> | CountOptions<any, any> | CountByOptions<any>) & AbortQueryOptions): void;
     /**
      * @internal
      */
@@ -575,7 +643,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      */
     set schema(schema: string | null | undefined);
     /** @internal */
-    getDataLoader(type: 'ref' | '1:m' | 'm:n'): Promise<any>;
+    getDataLoader(type: 'ref' | '1:m' | 'm:n' | 'count'): 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.
@@ -628,4 +696,11 @@ export interface ForkOptions {
     schema?: string;
     /** default logger context, can be overridden via {@apilink FindOptions} */
     loggerContext?: Dictionary;
+    /**
+     * Default `AbortSignal` applied to every operation on this fork (queries and UoW flushes).
+     * Per-call options.signal still takes precedence.
+     */
+    signal?: AbortSignal;
+    /** Default cancellation strategy paired with {@link signal}. */
+    inflightQueryAbortStrategy?: InflightQueryAbortStrategy;
 }