@mikro-orm/core 7.1.0-dev.8 → 7.1.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, IndexFilterQuery, WithUsingOptions } 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
      */
@@ -342,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).
      */
@@ -441,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.
@@ -511,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.
      */
@@ -538,12 +594,14 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     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
      */
@@ -585,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.
@@ -638,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

@@ -1,4 +1,4 @@
-import { getOnConflictReturningFields, getWhereCondition } from './utils/upsert-utils.js';
+import { getOnConflictReturningFields, getWhereCondition, resetUntouchedCollections } from './utils/upsert-utils.js';
 import { Utils } from './utils/Utils.js';
 import { Cursor } from './utils/Cursor.js';
 import { QueryHelper } from './utils/QueryHelper.js';
@@ -49,6 +49,10 @@ export class EntityManager {
     #disableTransactions;
     #flushMode;
     #schema;
+    /** @internal */
+    signal;
+    /** @internal */
+    inflightQueryAbortStrategy;
     #useContext;
     /**
      * @internal
@@ -318,13 +322,13 @@ export class EntityManager {
         }
         const types = Object.values(meta.root.discriminatorMap).map(cls => this.metadata.get(cls));
         const children = [];
-        const lookUpChildren = (ret, type) => {
-            const children = types.filter(meta2 => meta2.extends === type);
-            children.forEach(m => lookUpChildren(ret, m.class));
+        const lookUpChildren = (ret, parent) => {
+            const children = types.filter(meta2 => meta2.extends && this.metadata.find(meta2.extends) === parent);
+            children.forEach(m => lookUpChildren(ret, m));
             ret.push(...children.filter(c => c.discriminatorValue));
             return children;
         };
-        lookUpChildren(children, meta.class);
+        lookUpChildren(children, meta);
         /* v8 ignore next */
         where[meta.root.discriminatorColumn] =
             children.length > 0
@@ -354,10 +358,18 @@ export class EntityManager {
             const field = hint.field.split(':')[0];
             const prop = meta.properties[field];
             const strategy = getLoadingStrategy(prop.strategy || hint.strategy || options.strategy || this.config.get('loadStrategy'), prop.kind);
-            const joined = strategy === LoadStrategy.JOINED && prop.kind !== ReferenceKind.SCALAR;
+            const joined = (strategy === LoadStrategy.JOINED || (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner)) &&
+                prop.kind !== ReferenceKind.SCALAR;
             if (!joined && !hint.filter) {
                 continue;
             }
+            // Polymorphic to-one relations are already filtered via per-target LEFT JOINs created
+            // for the `:ref filter` hint; emitting a populate-filter entry here would auto-join only
+            // the first target meta and either drop rows pointing to other targets or reference
+            // parent-table-only columns on the child sub-table alias for TPT children.
+            if (prop.polymorphic && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+                continue;
+            }
             const filters = QueryHelper.mergePropertyFilters(prop.filters, options.filters);
             const where = await this.applyFilters(prop.targetMeta.class, {}, filters, 'read', {
                 ...options,
@@ -423,11 +435,13 @@ export class EntityManager {
                 const populated = options.populate.filter(({ field }) => field.split(':')[0] === prop.name);
                 let found = false;
                 for (const hint of populated) {
-                    if (!hint.all) {
+                    const strategy = getLoadingStrategy(prop.strategy || hint.strategy || options.strategy || this.config.get('loadStrategy'), prop.kind);
+                    // inverse 1:1 always produces a JOIN (forced by `joinedProps()`), regardless of strategy
+                    const willJoin = strategy === LoadStrategy.JOINED || (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner);
+                    if (!hint.all || willJoin) {
                         hint.filter = true;
                     }
-                    const strategy = getLoadingStrategy(prop.strategy || hint.strategy || options.strategy || this.config.get('loadStrategy'), prop.kind);
-                    if (hint.field === `${prop.name}:ref` || (hint.filter && strategy === LoadStrategy.JOINED)) {
+                    if (hint.field === `${prop.name}:ref` || (hint.filter && willJoin)) {
                         found = true;
                     }
                 }
@@ -441,7 +455,23 @@ export class EntityManager {
             const prop = meta?.properties[field];
             if (prop && !ref) {
                 hint.children ??= [];
-                await this.autoJoinRefsForFilters(prop.targetMeta, { ...options, populate: hint.children }, { class: meta.root.class, propName: prop.name });
+                const targets = prop.polymorphic && prop.polymorphTargets?.length ? prop.polymorphTargets : [prop.targetMeta];
+                for (const targetMeta of targets) {
+                    const before = hint.children.length;
+                    await this.autoJoinRefsForFilters(targetMeta, { ...options, populate: hint.children }, { class: meta.root.class, propName: prop.name });
+                    // For polymorphic relations, `hint.children` is applied to every polymorph target during
+                    // population, so drop any auto-added hint whose field does not exist on every target —
+                    // otherwise the shared `:ref` would crash when applied to a target lacking it (GH #7722).
+                    if (targets.length > 1 && hint.children.length > before) {
+                        const added = hint.children.splice(before);
+                        for (const h of added) {
+                            const f = h.field.split(':')[0];
+                            if (targets.every(t => f in t.properties)) {
+                                hint.children.push(h);
+                            }
+                        }
+                    }
+                }
             }
         }
     }
@@ -649,7 +679,7 @@ export class EntityManager {
         where = await em.processWhere(entityName, where, options, 'read');
         validateEmptyWhere(where);
         em.checkLockRequirements(options.lockMode, meta);
-        const isOptimisticLocking = options.lockMode == null || options.lockMode === LockMode.OPTIMISTIC;
+        const isOptimisticLocking = options.lockMode == null || options.lockMode === LockMode.NONE || options.lockMode === LockMode.OPTIMISTIC;
         if (entity && !em.shouldRefresh(meta, entity, options) && isOptimisticLocking) {
             return em.lockAndPopulate(meta, entity, where, options);
         }
@@ -790,7 +820,10 @@ export class EntityManager {
         data = QueryHelper.processObjectParams(data);
         validateParams(data, 'insert data');
         if (em.eventManager.hasListeners(EventType.beforeUpsert, meta)) {
-            await em.eventManager.dispatchEvent(EventType.beforeUpsert, { entity: data, em, meta }, meta);
+            await em.eventManager.dispatchEvent(EventType.beforeUpsert, { entity: entity ?? data, em, meta }, meta);
+            if (entity) {
+                data = em.#comparator.prepareEntity(entity);
+            }
         }
         const ret = await em.driver.nativeUpdate(entityName, where, data, {
             ctx: em.#transactionContext,
@@ -839,6 +872,7 @@ export class EntityManager {
             em.getHydrator().hydrate(entity, meta, data2, em.#entityFactory, 'full', false, true);
         }
         // recompute the data as there might be some values missing (e.g. those with db column defaults)
+        resetUntouchedCollections(meta, entity);
         const snapshot = this.#comparator.prepareEntity(entity);
         em.#unitOfWork.register(entity, snapshot, { refresh: true });
         if (em.eventManager.hasListeners(EventType.afterUpsert, meta)) {
@@ -905,6 +939,7 @@ export class EntityManager {
         const allWhere = [];
         const entities = new Map();
         const entitiesByData = new Map();
+        const entitiesByAllDataIdx = new Map();
         for (let i = 0; i < data.length; i++) {
             let row = data[i];
             let where;
@@ -918,6 +953,7 @@ export class EntityManager {
                 }
                 where = helper(entity).getPrimaryKey();
                 em.#entityFactory.assignDefaultValues(entity, meta);
+                entitiesByAllDataIdx.set(allData.length, entity);
                 row = em.#comparator.prepareEntity(entity);
             }
             else {
@@ -965,6 +1001,9 @@ export class EntityManager {
                 const entity = entitiesByData.get(dto) ?? dto;
                 await em.eventManager.dispatchEvent(EventType.beforeUpsert, { entity, em, meta }, meta);
             }
+            for (const [idx, entity] of entitiesByAllDataIdx) {
+                allData[idx] = em.#comparator.prepareEntity(entity);
+            }
         }
         const res = await em.driver.nativeUpdateMany(entityName, allWhere, allData, {
             ctx: em.#transactionContext,
@@ -1065,6 +1104,7 @@ export class EntityManager {
         }
         for (const [entity] of entities) {
             // recompute the data as there might be some values missing (e.g. those with db column defaults)
+            resetUntouchedCollections(meta, entity);
             const snapshot = this.#comparator.prepareEntity(entity);
             em.#unitOfWork.register(entity, snapshot, { refresh: true });
         }
@@ -1158,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 });
     }
     /**
@@ -1179,9 +1220,6 @@ export class EntityManager {
                 helper(data).setSchema(options.schema);
             }
             if (!helper(data).__managed) {
-                // the entity might have been created via `em.create()`, which adds it to the persist stack automatically
-                em.#unitOfWork.getPersistStack().delete(data);
-                // it can be also in the identity map if it had a PK value already
                 em.#unitOfWork.unsetIdentity(data);
             }
             const meta = helper(data).__meta;
@@ -1270,9 +1308,6 @@ export class EntityManager {
                     helper(row).setSchema(options.schema);
                 }
                 if (!helper(row).__managed) {
-                    // the entity might have been created via `em.create()`, which adds it to the persist stack automatically
-                    em.#unitOfWork.getPersistStack().delete(row);
-                    // it can be also in the identity map if it had a PK value already
                     em.#unitOfWork.unsetIdentity(row);
                 }
                 const payload = em.#comparator.prepareEntity(row);
@@ -1310,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).
      */
@@ -1458,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.
@@ -1563,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;
     }
@@ -1596,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);
@@ -1671,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.
      */
@@ -1821,8 +1928,17 @@ export class EntityManager {
             return [];
         }
         const meta = this.metadata.find(entityName);
-        // infer populate hint if only `fields` are available
-        if (!options.populate && options.fields) {
+        // infer populate hints from `fields` when present; merge with explicit `populate` if both are set.
+        // `populateArray` is only kept when the entries are user-provided strings — when this method runs a
+        // second time (e.g. from `lockAndPopulate`) the populate is already normalized and merging would be a no-op.
+        const fields = options.fields ? this.buildFields(options.fields) : undefined;
+        const populateArray = Array.isArray(options.populate) && options.populate.every(p => typeof p === 'string')
+            ? options.populate
+            : undefined;
+        const hasNestedFields = fields?.some(f => f.includes('.')) ?? false;
+        const shouldInfer = fields !== undefined && options.populate === undefined;
+        const shouldMerge = fields !== undefined && populateArray !== undefined && populateArray.length > 0 && hasNestedFields;
+        if (shouldInfer || shouldMerge) {
             // we need to prune the `populate` hint from to-one relations, as partially loading them does not require their population, we want just the FK
             const pruneToOneRelations = (meta, fields) => {
                 const ret = [];
@@ -1856,7 +1972,19 @@ export class EntityManager {
                 }
                 return Utils.unique(ret);
             };
-            options.populate = pruneToOneRelations(meta, this.buildFields(options.fields));
+            const fromFields = pruneToOneRelations(meta, fields);
+            if (shouldInfer) {
+                options.populate = fromFields;
+            }
+            else {
+                // with an explicit populate, only nested paths (e.g. `item.id`) need to be merged in — they
+                // require a JOIN to access sub-fields, whereas bare names are already handled by the driver.
+                // skip paths already in user's `populate` (regardless of `:ref` modifier) to avoid producing
+                // both a `:ref` and a non-`:ref` entry for the same relation
+                const existing = new Set(populateArray.map(p => p.split(':')[0]));
+                const extras = fromFields.filter(f => f.includes('.') && !existing.has(f));
+                options.populate = [...populateArray, ...extras];
+            }
         }
         if (!options.populate) {
             const populate = this.#entityLoader.normalizePopulate(entityName, [], options.strategy, true, options.exclude);
@@ -1896,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
@@ -1930,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);
     }
     /**
@@ -1938,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];
@@ -2031,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/README.md

@@ -2,7 +2,7 @@
   <a href="https://mikro-orm.io"><img src="https://raw.githubusercontent.com/mikro-orm/mikro-orm/master/docs/static/img/logo-readme.svg?sanitize=true" alt="MikroORM" /></a>
 </h1>
 
-TypeScript ORM for Node.js based on Data Mapper, [Unit of Work](https://mikro-orm.io/docs/unit-of-work/) and [Identity Map](https://mikro-orm.io/docs/identity-map/) patterns. Supports MongoDB, MySQL, MariaDB, PostgreSQL, SQLite (including libSQL), MSSQL and Oracle databases.
+TypeScript ORM for Node.js based on Data Mapper, [Unit of Work](https://mikro-orm.io/docs/unit-of-work/) and [Identity Map](https://mikro-orm.io/docs/identity-map/) patterns. Supports MongoDB, MySQL, MariaDB, PostgreSQL (including CockroachDB and PGlite), SQLite (including libSQL), MSSQL and Oracle databases.
 
 > Heavily inspired by [Doctrine](https://www.doctrine-project.org/) and [Hibernate](https://hibernate.org/).
 
@@ -19,6 +19,7 @@ Install a driver package for your database:
 
 ```sh
 npm install @mikro-orm/postgresql   # PostgreSQL
+npm install @mikro-orm/pglite       # PGlite (embedded PostgreSQL in WASM)
 npm install @mikro-orm/mysql        # MySQL
 npm install @mikro-orm/mariadb      # MariaDB
 npm install @mikro-orm/sqlite       # SQLite

package/connections/Connection.d.ts

@@ -1,8 +1,10 @@
 import { type Configuration, type ConnectionOptions } from '../utils/Configuration.js';
 import type { LogContext, Logger } from '../logging/Logger.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
-import type { ConnectionType, Dictionary, MaybePromise, Primary } from '../typings.js';
+import type { ConnectionType, Dictionary, MaybePromise, Primary, RoutineProperty } from '../typings.js';
+import type { Routine } from '../metadata/Routine.js';
 import type { Platform } from '../platforms/Platform.js';
+import type { Type } from '../types/Type.js';
 import type { TransactionEventBroadcaster } from '../events/TransactionEventBroadcaster.js';
 import type { IsolationLevel } from '../enums.js';
 /** Abstract base class for database connections, providing transaction and query execution support. */
@@ -72,6 +74,41 @@ export declare abstract class Connection {
     rollback(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;
     /** Executes a raw query and returns the result. */
     abstract execute<T>(query: string, params?: any[], method?: 'all' | 'get' | 'run', ctx?: Transaction): Promise<QueryResult<T> | any | any[]>;
+    /** @internal — public callers go through {@link EntityManager.callRoutine}. */
+    callRoutine<T>(routine: Routine, args: Record<string, unknown>, ctx?: Transaction): Promise<T>;
+    /**
+     * Unwraps a routine argument (resolving any `ScalarReference` wrapper) and, when the param
+     * declares a `customType`, marshals it through `convertToDatabaseValue`. `undefined` is
+     * normalised to `null` so every driver sees the same shape.
+     *
+     * @internal
+     */
+    protected convertRoutineInbound(value: unknown, param: RoutineProperty | undefined): unknown;
+    /**
+     * Converts a raw database value to its JS representation via the supplied `customType`, when
+     * one is declared. Used to marshal scalar function returns and OUT/INOUT values back to the
+     * caller before they land in a `ScalarReference` or `em.callRoutine`'s return value.
+     *
+     * @internal
+     */
+    protected convertRoutineOutbound<T>(value: unknown, customType: Type<unknown> | undefined): T;
+    /**
+     * Executes a scalar function routine as `select <qualified>(?, ?, ...) as value`, marshalling
+     * IN params on the way in and the return value on the way out. The qualified name is built
+     * from `routine.schema`, falling back to the platform's default schema (e.g. `dbo` on MSSQL),
+     * which gives MySQL/SQLite a bare name and MSSQL/Oracle the mandatory `schema.name` form.
+     *
+     * @internal
+     */
+    protected callRoutineFunction<T>(routine: Routine, args: Record<string, unknown>, ctx?: Transaction): Promise<T>;
+    /**
+     * Walks a result row produced by an OUT/INOUT-param SELECT and writes each value into the
+     * caller's `ScalarReference` slot. Non-reference args are ignored (the user opted out of
+     * receiving the OUT value).
+     *
+     * @internal
+     */
+    protected applyRoutineOutParams(row: Dictionary, outParams: RoutineProperty[], args: Record<string, unknown>): void;
     /** Parses and returns the resolved connection configuration (host, port, user, etc.). */
     getConnectionOptions(): ConnectionConfig;
     /** Sets the metadata storage on this connection. */
@@ -104,3 +141,32 @@ export interface ConnectionConfig {
 }
 /** Opaque transaction context type, wrapping the driver-specific transaction object. */
 export type Transaction<T = any> = T & {};
+/**
+ * Strategy applied when an `AbortSignal` fires while a query is in flight.
+ *
+ * - `'ignore query'` — stop awaiting; the query keeps running on the server until it settles
+ *   (the connection returns to the pool only when the database replies).
+ * - `'cancel query'` — ask the database to cancel the running query (e.g. `pg_cancel_backend`,
+ *   `KILL QUERY`). Falls back to `'ignore query'` if the dialect cannot cancel.
+ *   Most engines do not cancel writes; partial commits are possible.
+ * - `'kill session'` — terminate the database session/process the query runs in
+ *   (`pg_terminate_backend` etc.). Falls back to `'cancel query'` if not supported.
+ *
+ * Default: `'ignore query'`.
+ *
+ * **Streaming queries (`em.stream()` / `qb.stream()`):** the strategy is silently treated as
+ * `'ignore query'` because the underlying driver only accepts a plain `AbortSignal` for
+ * streamed reads — there is no server-side cancel for an open cursor. The MongoDB driver also
+ * has no notion of strategies; only the signal is honored there.
+ */
+export type InflightQueryAbortStrategy = 'ignore query' | 'cancel query' | 'kill session';
+/** Per-query cancellation controls forwarded to the underlying driver. */
+export interface AbortQueryOptions {
+    /** AbortSignal that cancels the query when fired. */
+    signal?: AbortSignal;
+    /**
+     * Strategy used when the signal fires while the query is in flight. See
+     * {@apilink InflightQueryAbortStrategy} for caveats around streams and MongoDB.
+     */
+    inflightQueryAbortStrategy?: InflightQueryAbortStrategy;
+}