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

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
@@ -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');
@@ -319,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
@@ -355,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,
@@ -424,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;
                     }
                 }
@@ -442,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);
+                            }
+                        }
+                    }
+                }
             }
         }
     }
@@ -494,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);
@@ -631,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);
@@ -653,10 +675,11 @@ 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);
-        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);
         }
@@ -701,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;
@@ -803,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,
@@ -852,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)) {
@@ -918,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;
@@ -931,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 {
@@ -978,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,
@@ -1078,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 });
         }
@@ -1171,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 });
     }
     /**
@@ -1192,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;
@@ -1283,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);
@@ -1471,6 +1493,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.
@@ -1576,7 +1621,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;
     }
@@ -1609,6 +1654,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);
@@ -1684,6 +1731,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.
      */
@@ -1727,6 +1790,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, {
@@ -1761,8 +1897,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 = [];
@@ -1796,7 +1941,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);
@@ -1836,9 +1993,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
@@ -1870,6 +2039,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);
     }
     /**
@@ -1878,7 +2049,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];
@@ -1971,6 +2150,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

@@ -104,3 +104,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;
+}

package/drivers/IDatabaseDriver.d.ts

@@ -1,5 +1,5 @@
-import type { ConnectionType, Constructor, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName, PopulateHintOptions, Prefixes } from '../typings.js';
-import type { Connection, QueryResult, Transaction } from '../connections/Connection.js';
+import type { ConnectionType, Constructor, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName, PopulateHintOptions, Prefixes, IndexName } from '../typings.js';
+import type { AbortQueryOptions, Connection, QueryResult, Transaction } from '../connections/Connection.js';
 import type { FlushMode, LockMode, QueryOrderMap, QueryFlag, LoadStrategy, PopulateHint, PopulatePath } from '../enums.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
@@ -110,6 +110,20 @@ export interface FindAllOptions<T, P extends string = never, F extends string =
 }
 /** Options for streaming query results via `em.stream()`. */
 export interface StreamOptions<Entity, Populate extends string = never, Fields extends string = never, Exclude extends string = never> extends Omit<FindAllOptions<Entity, Populate, Fields, Exclude>, 'cache' | 'before' | 'after' | 'first' | 'last' | 'overfetch' | 'strategy'> {
+    /**
+     * How many rows to fetch in one round-trip.
+     * Lower values will result in more queries and network bandwidth, but less memory usage.
+     * Higher values will result in fewer queries and network bandwidth, but higher memory usage.
+     * Note that the results are iterated one row at a time regardless of this value.
+     *
+     * Honored on PostgreSQL (cursor-based fetch), MSSQL (tedious stream chunk size),
+     * Oracle (mapped to `fetchArraySize`) and MongoDB (mapped to `batchSize`). Ignored
+     * on MySQL, MariaDB, SQLite and libSQL, where the underlying driver already streams
+     * row-by-row with no batching knob.
+     *
+     * @default 100 (on dialects that honor it)
+     */
+    chunkSize?: number;
     /**
      * When populating to-many relations, the ORM streams fully merged entities instead of yielding every row.
      * You can opt out of this behavior by specifying `mergeResults: false`. This will yield every row from
@@ -130,7 +144,7 @@ export interface LoadHint<Entity, Hint extends string = never, Fields extends st
     exclude?: readonly AutoPath<Entity, Excludes>[];
 }
 /** Options for `em.find()` queries, including population, ordering, pagination, and locking. */
-export interface FindOptions<Entity, Hint extends string = never, Fields extends string = never, Excludes extends string = never> extends LoadHint<Entity, Hint, Fields, Excludes> {
+export interface FindOptions<Entity, Hint extends string = never, Fields extends string = never, Excludes extends string = never> extends LoadHint<Entity, Hint, Fields, Excludes>, AbortQueryOptions {
     /**
      * Where condition for populated relations. This will have no effect on the root entity.
      * With `select-in` strategy, this is applied only to the populate queries.
@@ -216,6 +230,20 @@ export interface FindOptions<Entity, Hint extends string = never, Fields extends
     connectionType?: ConnectionType;
     /** SQL: appended to FROM clause (e.g. `'force index(my_index)'`); MongoDB: index name or spec passed as `hint`. */
     indexHint?: string | Dictionary;
+    /**
+     * Named index(es) for this query. When provided:
+     * - Validates that `where` and `orderBy` only reference columns covered by the specified index(es).
+     * - Emits SQL index hints where supported (MySQL/MariaDB: `USE INDEX`, MSSQL: `WITH (INDEX(...))`).
+     * - If `indexHint` is also set, `indexHint` takes precedence for SQL generation.
+     *
+     * Accepts a single index name or an array. For `defineEntity` entities with named indexes
+     * and decorator entities with `[IndexHints]`, index names are autocompleted.
+     *
+     * @example
+     * await em.find(Book, { title: 'foo' }, { using: 'idx_book_title' });
+     * await em.find(Book, { title: 'foo', author: 1 }, { using: ['idx_book_title', 'idx_book_author'] });
+     */
+    using?: IndexName<Entity> | IndexName<Entity>[];
     /** sql only */
     comments?: string | string[];
     /** sql only */
@@ -246,7 +274,7 @@ export interface FindOneOrFailOptions<T extends object, P extends string = never
     strict?: boolean;
 }
 /** Options for native insert and update operations. */
-export interface NativeInsertUpdateOptions<T> {
+export interface NativeInsertUpdateOptions<T> extends AbortQueryOptions {
     convertCustomTypes?: boolean;
     ctx?: Transaction;
     schema?: string;
@@ -280,7 +308,7 @@ export interface UpsertManyOptions<Entity, Fields extends string = never> extend
     batchSize?: number;
 }
 /** Options for `em.count()` queries. */
-export interface CountOptions<T extends object, P extends string = never> {
+export interface CountOptions<T extends object, P extends string = never> extends AbortQueryOptions {
     filters?: FilterOptions;
     schema?: string;
     groupBy?: string | readonly string[];
@@ -311,8 +339,18 @@ export interface CountOptions<T extends object, P extends string = never> {
     /** @internal used to apply filters to the auto-joined relations */
     em?: EntityManager;
 }
+/** Options for `em.countBy()` queries. */
+export interface CountByOptions<T extends object> {
+    where?: FilterQuery<T>;
+    filters?: FilterOptions;
+    having?: FilterQuery<T>;
+    schema?: string;
+    flushMode?: FlushMode | `${FlushMode}`;
+    loggerContext?: LogContext;
+    logging?: LoggingOptions;
+}
 /** Options for `em.qb().update()` operations. */
-export interface UpdateOptions<T> {
+export interface UpdateOptions<T> extends AbortQueryOptions {
     filters?: FilterOptions;
     schema?: string;
     ctx?: Transaction;
@@ -351,7 +389,7 @@ export interface LockOptions extends DriverMethodOptions {
     logging?: LoggingOptions;
 }
 /** Base options shared by all driver methods (transaction context, schema, logging). */
-export interface DriverMethodOptions {
+export interface DriverMethodOptions extends AbortQueryOptions {
     ctx?: Transaction;
     schema?: string;
     loggerContext?: LogContext;