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

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
@@ -307,6 +320,25 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Fires native insert query. Calling this has no side effects on the context (identity map).
      */
     insert<Entity extends object>(entityNameOrEntity: EntityName<Entity> | Entity, data?: RequiredEntityData<Entity> | Entity, options?: NativeInsertUpdateOptions<Entity>): Promise<Primary<Entity>>;
+    /**
+     * Clones rows matching the condition at the database level via INSERT...SELECT.
+     * Automatically excludes auto-increment PKs, generated columns, and resets version properties.
+     * Returns the cloned entity, registered in the identity map.
+     *
+     * @example
+     * ```ts
+     * // Clone by entity class + where + overrides
+     * const cloned = await em.clone(Author, { id: 1 }, { email: 'new@email.com' });
+     *
+     * // Pure clone (all non-PK fields copied)
+     * const cloned = await em.clone(Author, { id: 1 });
+     *
+     * // Clone a loaded entity
+     * const author = await em.findOneOrFail(Author, 1);
+     * const cloned = await em.clone(author, { email: 'new@email.com' });
+     * ```
+     */
+    clone<Entity extends object>(entityNameOrEntity: EntityName<Entity> | Entity, whereOrOverrides?: FilterQuery<NoInfer<Entity>> | EntityData<Entity>, overridesOrOptions?: EntityData<Entity> | NativeInsertUpdateOptions<Entity>, options?: NativeInsertUpdateOptions<Entity>): Promise<Entity>;
     /**
      * Fires native multi-insert query. Calling this has no side effects on the context (identity map).
      */
@@ -315,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).
      */
@@ -414,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.
@@ -484,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.
      */
@@ -505,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
      */
@@ -556,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.
@@ -609,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;
 }

package/EntityManager.js

@@ -49,6 +49,10 @@ export class EntityManager {
     #disableTransactions;
     #flushMode;
     #schema;
+    /** @internal */
+    signal;
+    /** @internal */
+    inflightQueryAbortStrategy;
     #useContext;
     /**
      * @internal
@@ -103,9 +107,6 @@ export class EntityManager {
     repo(entityName) {
         return this.getRepository(entityName);
     }
-    /**
-     * Finds all entities matching your `where` query. You can pass additional options via the `options` parameter.
-     */
     async find(entityName, where, options = {}) {
         if (options.disableIdentityMap ?? this.config.get('disableIdentityMap')) {
             const em = this.getContext(false);
@@ -116,10 +117,11 @@ export class EntityManager {
         }
         const em = this.getContext();
         em.prepareOptions(options);
+        const meta = this.metadata.get(entityName);
+        em.validateIndexUsage(meta, where, options);
         await em.tryFlush(entityName, options);
         where = await em.processWhere(entityName, where, options, 'read');
         validateParams(where);
-        const meta = this.metadata.get(entityName);
         if (meta.orderBy) {
             options.orderBy = QueryHelper.mergeOrderBy(options.orderBy, meta.orderBy);
         }
@@ -203,6 +205,7 @@ export class EntityManager {
         options.orderBy = options.orderBy || {};
         options.populate = (await em.preparePopulate(entityName, options));
         const meta = this.metadata.get(entityName);
+        em.validateIndexUsage(meta, options.where ?? {}, options);
         options = { ...options };
         // save the original hint value so we know it was infer/all
         options._populateWhere = options.populateWhere ?? this.config.get('populateWhere');
@@ -520,10 +523,6 @@ export class EntityManager {
         const conds = [...ret, where].filter(c => Utils.hasObjectKeys(c) || Raw.hasObjectFragments(c));
         return conds.length > 1 ? { $and: conds } : conds[0];
     }
-    /**
-     * 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.
-     */
     async findAndCount(entityName, where, options = {}) {
         const em = this.getContext(false);
         await em.tryFlush(entityName, options);
@@ -657,9 +656,6 @@ export class EntityManager {
         }
         return entity;
     }
-    /**
-     * Finds first entity matching your `where` query.
-     */
     async findOne(entityName, where, options = {}) {
         if (options.disableIdentityMap ?? this.config.get('disableIdentityMap')) {
             const em = this.getContext(false);
@@ -679,6 +675,7 @@ export class EntityManager {
         }
         await em.tryFlush(entityName, options);
         const meta = em.metadata.get(entityName);
+        em.validateIndexUsage(meta, where, options);
         where = await em.processWhere(entityName, where, options, 'read');
         validateEmptyWhere(where);
         em.checkLockRequirements(options.lockMode, meta);
@@ -727,12 +724,6 @@ export class EntityManager {
         await em.storeCache(options.cache, cached, () => helper(entity).toPOJO());
         return entity;
     }
-    /**
-     * 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.
-     */
     async findOneOrFail(entityName, where, options = {}) {
         let entity;
         let isStrictViolation = false;
@@ -1207,6 +1198,7 @@ export class EntityManager {
      */
     async lock(entity, lockMode, options = {}) {
         options = Utils.isPlainObject(options) ? options : { lockVersion: options };
+        this.getContext(false).prepareOptions(options);
         await this.getUnitOfWork().lock(entity, { lockMode, ...options });
     }
     /**
@@ -1244,6 +1236,54 @@ export class EntityManager {
         });
         return res.insertId;
     }
+    /**
+     * Clones rows matching the condition at the database level via INSERT...SELECT.
+     * Automatically excludes auto-increment PKs, generated columns, and resets version properties.
+     * Returns the cloned entity, registered in the identity map.
+     *
+     * @example
+     * ```ts
+     * // Clone by entity class + where + overrides
+     * const cloned = await em.clone(Author, { id: 1 }, { email: 'new@email.com' });
+     *
+     * // Pure clone (all non-PK fields copied)
+     * const cloned = await em.clone(Author, { id: 1 });
+     *
+     * // Clone a loaded entity
+     * const author = await em.findOneOrFail(Author, 1);
+     * const cloned = await em.clone(author, { email: 'new@email.com' });
+     * ```
+     */
+    async clone(entityNameOrEntity, whereOrOverrides, overridesOrOptions, options) {
+        const em = this.getContext(false);
+        let entityName;
+        let where;
+        let overrides;
+        if (Utils.isEntity(entityNameOrEntity)) {
+            // clone(entity, overrides?, options?)
+            entityName = entityNameOrEntity.constructor;
+            where = helper(entityNameOrEntity).getPrimaryKey();
+            overrides = whereOrOverrides;
+            options = overridesOrOptions;
+        }
+        else {
+            // clone(EntityClass, where, overrides?, options?)
+            entityName = entityNameOrEntity;
+            where = whereOrOverrides;
+            overrides = overridesOrOptions;
+        }
+        options ??= {};
+        em.prepareOptions(options);
+        const meta = em.metadata.get(entityName);
+        const res = await em.driver.nativeClone(entityName, where, overrides, {
+            ctx: em.#transactionContext,
+            ...options,
+        });
+        const pk = res.insertId ?? res.row?.[meta.primaryKeys[0]];
+        return em.findOneOrFail(entityName, pk, {
+            schema: options.schema,
+        });
+    }
     /**
      * Fires native multi-insert query. Calling this has no side effects on the context (identity map).
      */
@@ -1305,6 +1345,37 @@ export class EntityManager {
         });
         return res.affectedRows;
     }
+    /**
+     * 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, {}));
+     * ```
+     */
+    async callRoutine(routine, args) {
+        const em = this.getContext(false);
+        // Identity by reference so the user-held import survives bundling and tree-shakes unused routines.
+        if (!em.config.hasRoutine(routine)) {
+            throw new Error(`Routine '${routine.name}' is not registered in the 'routines' config option.`);
+        }
+        const conn = em.driver.getConnection('write');
+        return conn.callRoutine(routine, args, em.#transactionContext);
+    }
     /**
      * Fires native delete query. Calling this has no side effects on the context (identity map).
      */
@@ -1453,6 +1524,29 @@ export class EntityManager {
         await em.storeCache(options.cache, cached, () => +count);
         return +count;
     }
+    /**
+     * 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 }
+     * ```
+     */
+    async countBy(entityName, groupBy, options) {
+        throw new Error(`${this.constructor.name}.countBy() is not supported by the current driver`);
+    }
     /**
      * 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.
@@ -1558,7 +1652,7 @@ export class EntityManager {
         const em = this.getContext();
         em.prepareOptions(options);
         const entityName = arr[0].constructor;
-        const preparedPopulate = await em.preparePopulate(entityName, { populate: populate, filters: options.filters }, options.validate);
+        const preparedPopulate = await em.preparePopulate(entityName, { populate: populate, filters: options.filters, populateHints: options.populateHints }, options.validate);
         await em.#entityLoader.populate(entityName, arr, preparedPopulate, options);
         return entities;
     }
@@ -1591,6 +1685,8 @@ export class EntityManager {
         fork.#filterParams = Utils.copy(em.#filterParams);
         fork.loggerContext = Utils.merge({}, em.loggerContext, options.loggerContext);
         fork.#schema = options.schema ?? em.#schema;
+        fork.signal = options.signal ?? em.signal;
+        fork.inflightQueryAbortStrategy = options.inflightQueryAbortStrategy ?? em.inflightQueryAbortStrategy;
         if (!options.clear) {
             for (const entity of em.#unitOfWork.getIdentityMap()) {
                 fork.#unitOfWork.register(entity);
@@ -1666,6 +1762,22 @@ export class EntityManager {
     getTransactionContext() {
         return this.getContext(false).#transactionContext;
     }
+    /**
+     * 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.
+     */
+    getAbortOptions() {
+        const em = this.getContext(false);
+        if (em.signal == null && em.inflightQueryAbortStrategy == null) {
+            return undefined;
+        }
+        return {
+            signal: em.signal,
+            inflightQueryAbortStrategy: em.inflightQueryAbortStrategy,
+        };
+    }
     /**
      * Sets the transaction context.
      */
@@ -1709,6 +1821,79 @@ export class EntityManager {
             throw ValidationError.transactionRequired();
         }
     }
+    validateIndexUsage(meta, where, options) {
+        if (!options.using) {
+            return;
+        }
+        const indexNames = Utils.asArray(options.using);
+        const allIndexes = [...meta.indexes, ...meta.uniques];
+        const indexMap = new Map();
+        for (const idx of allIndexes) {
+            if (idx.name) {
+                indexMap.set(idx.name, Utils.asArray(idx.properties ?? []));
+            }
+        }
+        for (const prop of meta.props) {
+            if (typeof prop.index === 'string') {
+                indexMap.set(prop.index, [prop.name]);
+            }
+            if (typeof prop.unique === 'string') {
+                indexMap.set(prop.unique, [prop.name]);
+            }
+        }
+        const allowedProps = new Set();
+        for (const name of indexNames) {
+            const props = indexMap.get(name);
+            if (!props) {
+                const available = [...indexMap.keys()];
+                throw new Error(`Index '${name}' not found on entity '${meta.className}'. ` +
+                    (available.length > 0 ? `Available indexes: ${available.join(', ')}` : 'No named indexes defined.'));
+            }
+            for (const prop of props) {
+                allowedProps.add(prop);
+            }
+        }
+        this.validateWhereKeysForIndex(where, allowedProps, indexNames);
+        if (options.orderBy) {
+            const orderMaps = Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy];
+            for (const orderMap of orderMaps) {
+                for (const key of Object.keys(orderMap)) {
+                    if (!allowedProps.has(key)) {
+                        throw new Error(`Property '${key}' in orderBy is not covered by index '${indexNames.join("', '")}'. ` +
+                            `Allowed properties: ${[...allowedProps].join(', ')}`);
+                    }
+                }
+            }
+        }
+    }
+    validateWhereKeysForIndex(where, allowedProps, indexNames) {
+        if (typeof where !== 'object' || where === null) {
+            return;
+        }
+        if (Array.isArray(where)) {
+            for (const item of where) {
+                this.validateWhereKeysForIndex(item, allowedProps, indexNames);
+            }
+            return;
+        }
+        for (const key of Object.keys(where)) {
+            if (key === '$and' || key === '$or') {
+                for (const item of Utils.asArray(where[key])) {
+                    this.validateWhereKeysForIndex(item, allowedProps, indexNames);
+                }
+            }
+            else if (key === '$not') {
+                this.validateWhereKeysForIndex(where[key], allowedProps, indexNames);
+            }
+            else if (key.startsWith('$')) {
+                continue;
+            }
+            else if (!allowedProps.has(key)) {
+                throw new Error(`Property '${key}' in where clause is not covered by index '${indexNames.join("', '")}'. ` +
+                    `Allowed properties: ${[...allowedProps].join(', ')}`);
+            }
+        }
+    }
     async lockAndPopulate(meta, entity, where, options) {
         if (!meta.virtual && options.lockMode === LockMode.OPTIMISTIC) {
             await this.lock(entity, options.lockMode, {
@@ -1839,9 +2024,21 @@ export class EntityManager {
         }
         if (options.populateHints) {
             applyPopulateHints(populate, options.populateHints);
+            this.forceSelectInForLimitedPopulate(populate);
         }
         return populate;
     }
+    /** Force SELECT_IN strategy on populate entries with `limit`, since JOINED cannot do per-parent limiting. */
+    forceSelectInForLimitedPopulate(populate) {
+        for (const entry of populate) {
+            if (entry.limit != null) {
+                entry.strategy = LoadStrategy.SELECT_IN;
+            }
+            if (entry.children?.length) {
+                this.forceSelectInForLimitedPopulate(entry.children);
+            }
+        }
+    }
     /**
      * 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
@@ -1873,6 +2070,8 @@ export class EntityManager {
             throw new ValidationError(`Cannot combine 'fields' and 'exclude' option.`);
         }
         options.schema ??= this.#schema;
+        options.signal ??= this.signal;
+        options.inflightQueryAbortStrategy ??= this.inflightQueryAbortStrategy;
         options.logging = options.loggerContext = Utils.merge({ id: this.id }, this.loggerContext, options.loggerContext, options.logging);
     }
     /**
@@ -1881,7 +2080,15 @@ export class EntityManager {
     cacheKey(entityName, options, method, where) {
         const { ...opts } = options;
         // ignore some irrelevant options, e.g. logger context can contain dynamic data for the same query
-        for (const k of ['ctx', 'strategy', 'flushMode', 'logging', 'loggerContext']) {
+        for (const k of [
+            'ctx',
+            'strategy',
+            'flushMode',
+            'logging',
+            'loggerContext',
+            'signal',
+            'inflightQueryAbortStrategy',
+        ]) {
             delete opts[k];
         }
         return [Utils.className(entityName), method, opts, where];
@@ -1974,6 +2181,8 @@ export class EntityManager {
                 return (em.#loaders[type] ??= new DataLoader(DataloaderUtils.getColBatchLoadFn(em)));
             case 'm:n':
                 return (em.#loaders[type] ??= new DataLoader(DataloaderUtils.getManyToManyColBatchLoadFn(em)));
+            case 'count':
+                return (em.#loaders[type] ??= new DataLoader(DataloaderUtils.getCountBatchLoadFn(em)));
         }
     }
     /**

package/MikroORM.d.ts

@@ -5,7 +5,7 @@ import { Configuration, type Options } from './utils/Configuration.js';
 import type { EntityManager } from './EntityManager.js';
 import type { AnyEntity, Constructor, EntityClass, EntityMetadata, EntityName, IEntityGenerator, IMigrator, ISeedManager } from './typings.js';
 /** @internal */
-export declare function loadOptionalDependencies(options: Partial<Options>): Promise<void>;
+export declare function loadOptionalDependencies(options: Partial<Options<any, any, any>>): Promise<void>;
 /**
  * The main class used to configure and bootstrap the ORM.
  *
@@ -34,7 +34,7 @@ export declare function loadOptionalDependencies(options: Partial<Options>): Pro
  * await em.flush();
  * ```
  */
-export declare class MikroORM<Driver extends IDatabaseDriver = IDatabaseDriver, EM extends Driver[typeof EntityManagerType] & EntityManager<Driver> = Driver[typeof EntityManagerType] & EntityManager<Driver>, Entities extends (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]> {
+export declare class MikroORM<Driver extends IDatabaseDriver = IDatabaseDriver, EM extends Driver[typeof EntityManagerType] & EntityManager<Driver> = Driver[typeof EntityManagerType] & EntityManager<Driver>, Entities extends readonly (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]> {
     #private;
     /** The global EntityManager instance. If you are using `RequestContext` helper, it will automatically pick the request specific context under the hood */
     em: EM & {
@@ -48,7 +48,7 @@ export declare class MikroORM<Driver extends IDatabaseDriver = IDatabaseDriver,
      * Initialize the ORM, load entity metadata, create EntityManager and connect to the database.
      * If you omit the `options` parameter, your CLI config will be used.
      */
-    static init<D extends IDatabaseDriver = IDatabaseDriver, EM extends D[typeof EntityManagerType] & EntityManager<D> = D[typeof EntityManagerType] & EntityManager<D>, Entities extends (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]>(options: Partial<Options<D, EM, Entities>>): Promise<MikroORM<D, EM, Entities>>;
+    static init<D extends IDatabaseDriver = IDatabaseDriver, EM extends D[typeof EntityManagerType] & EntityManager<D> = D[typeof EntityManagerType] & EntityManager<D>, Entities extends readonly (string | EntityClass<AnyEntity> | EntitySchema)[] = (string | EntityClass<AnyEntity> | EntitySchema)[]>(options: Partial<Options<D, EM, Entities>>): Promise<MikroORM<D, EM, Entities>>;
     /**
      * Synchronous variant of the `init` method with some limitations:
      * - folder-based discovery not supported