@mikro-orm/core 7.1.0-dev.1 → 7.1.0-dev.11

package/EntityManager.d.ts

@@ -6,8 +6,8 @@ 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, UnboxArray, IndexFilterQuery, WithUsingOptions } from './typings.js';
 import { FlushMode, LockMode, PopulatePath, type TransactionOptions } from './enums.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
 import type { Transaction } from './connections/Connection.js';
@@ -61,7 +61,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 +81,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 +132,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 +191,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 +207,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 +315,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).
      */
@@ -414,6 +441,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.
@@ -505,16 +553,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>): void;
     /**
      * @internal
      */
@@ -556,7 +608,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.

package/EntityManager.js

@@ -103,9 +103,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 +113,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 +201,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');
@@ -494,10 +493,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 +626,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,6 +645,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);
@@ -701,12 +694,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;
@@ -1211,6 +1198,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).
      */
@@ -1423,6 +1458,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.
@@ -1528,7 +1586,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;
     }
@@ -1679,6 +1737,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, {
@@ -1788,9 +1919,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
@@ -1923,6 +2066,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/drivers/DatabaseDriver.d.ts

@@ -28,6 +28,7 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
     abstract nativeUpdate<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
     nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
     abstract nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: DeleteOptions<T>): Promise<QueryResult<T>>;
+    nativeClone<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, overrides?: EntityData<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
     abstract count<T extends object, P extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
     /** Creates a new EntityManager instance bound to this driver. */
     createEntityManager(useContext?: boolean): this[typeof EntityManagerType];

package/drivers/DatabaseDriver.js

@@ -27,6 +27,9 @@ export class DatabaseDriver {
     async nativeUpdateMany(entityName, where, data, options) {
         throw new Error(`Batch updates are not supported by ${this.constructor.name} driver`);
     }
+    async nativeClone(entityName, where, overrides, options) {
+        throw new Error(`${this.constructor.name} does not support nativeClone`);
+    }
     /** Creates a new EntityManager instance bound to this driver. */
     createEntityManager(useContext) {
         const EntityManagerClass = this.config.get('entityManager', EntityManager);

package/drivers/IDatabaseDriver.d.ts

@@ -1,4 +1,4 @@
-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 { ConnectionType, Constructor, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName, PopulateHintOptions, Prefixes, IndexName } from '../typings.js';
 import type { 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';
@@ -52,6 +52,11 @@ export interface IDatabaseDriver<C extends Connection = Connection> {
     nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
     /** Deletes rows matching the given condition. */
     nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: NativeDeleteOptions<T>): Promise<QueryResult<T>>;
+    /**
+     * Clones rows matching the condition at the database level via INSERT...SELECT.
+     * Automatically excludes auto-increment PKs, generated columns, and resets version properties.
+     */
+    nativeClone<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, overrides?: EntityData<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
     /** Persists changes to M:N collections (inserts/deletes pivot table rows). */
     syncCollections<T extends object, O extends object>(collections: Iterable<Collection<T, O>>, options?: DriverMethodOptions): Promise<void>;
     /** Counts entities matching the given condition. */
@@ -211,6 +216,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 */
@@ -306,6 +325,16 @@ 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> {
     filters?: FilterOptions;

package/entity/BaseEntity.d.ts

@@ -1,5 +1,5 @@
-import { type Ref } from './Reference.js';
-import type { AutoPath, EntityData, EntityDTO, Loaded, LoadedReference, AddEager, EntityKey, FromEntityType, IsSubset, MergeSelected, SerializeDTO } from '../typings.js';
+import { type LoadReferenceOptions, type LoadReferenceOrFailOptions, type Ref } from './Reference.js';
+import type { AutoPath, EntityData, EntityDTO, ExtractFieldsHint, Loaded, LoadedReference, AddEager, EntityKey, FromEntityType, IsSubset, MergeSelected, ResolveSerializeFields, SerializeDTO, SerializeFieldsKeepPK } from '../typings.js';
 import { type AssignOptions } from './EntityAssigner.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
 import { type SerializeOptions } from '../serialization/EntitySerializer.js';
@@ -80,7 +80,7 @@ export declare abstract class BaseEntity {
     /** Converts the entity to a plain object, including all properties regardless of serialization rules. */
     toPOJO<Entity extends this = this>(): EntityDTO<Entity>;
     /** Serializes the entity with control over which relations and fields to include or exclude. */
-    serialize<Entity extends this = this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude>): SerializeDTO<Naked, Hint, Exclude>;
+    serialize<Entity extends this = this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never, Fields extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude, Fields>): SerializeDTO<Naked, Hint, Exclude, never, ResolveSerializeFields<Fields, ExtractFieldsHint<Entity>>, SerializeFieldsKeepPK<Fields>>;
     /** Assigns the given data to this entity, updating its properties and relations. */
     assign<Entity extends this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Convert extends boolean = false, Data extends EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>>(data: Data & IsSubset<EntityData<Naked>, Data>, options?: AssignOptions<Convert>): MergeSelected<Entity, Naked, keyof Data & string>;
     /** Initializes (refreshes) the entity by reloading it from the database. Returns null if not found. */
@@ -90,3 +90,70 @@ export declare abstract class BaseEntity {
     /** Sets the database schema for this entity. */
     setSchema(schema?: string): void;
 }
+type EntityConstructor<T extends object = object> = abstract new (...args: any[]) => T;
+/**
+ * The `load()` / `loadOrFail()` methods added by the {@link Loadable} mixin. Declared as an interface so the
+ * mixin function can have an explicit return type (required by JSR fast-check).
+ */
+export interface LoadableEntity {
+    /**
+     * Ensures this entity is loaded (without reloading it if it already is). Returns the entity, or `null` if it
+     * was not found in the database (e.g. it was deleted in the meantime, or active filters disallow loading it).
+     * Use `loadOrFail()` if you want an error to be thrown in such a case.
+     */
+    load<Entity extends this = this, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: LoadReferenceOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
+    /**
+     * Ensures this entity is loaded (without reloading it if it already is). Returns the entity, or throws an error
+     * just like `em.findOneOrFail()` (and respects the same config options) if it was not found.
+     */
+    loadOrFail<Entity extends this = this, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: LoadReferenceOrFailOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>>;
+}
+/** Return-type shape of {@link Loadable} — a constructor that produces instances of `TBase` enriched with {@link LoadableEntity}. */
+export type LoadableConstructor<TBase extends EntityConstructor> = abstract new (...args: any[]) => InstanceType<TBase> & LoadableEntity;
+/** Internal: rejects a base class that already defines `load` or `loadOrFail` to prevent silent override. */
+type EnsureNoLoadConflict<TBase extends EntityConstructor> = InstanceType<TBase> extends {
+    load: any;
+} ? 'Loadable: base class already defines `load` — remove it or do not apply the mixin' : InstanceType<TBase> extends {
+    loadOrFail: any;
+} ? 'Loadable: base class already defines `loadOrFail` — remove it or do not apply the mixin' : TBase;
+/** Empty base for {@link Loadable} when called without arguments — standalone mixin, no inherited base. */
+declare abstract class EmptyBase {
+}
+/**
+ * Mixin that adds `load()` / `loadOrFail()` methods to an entity class. These methods ensure the entity is loaded
+ * from the database without reloading it if it already is — unlike `init()`, which always refreshes.
+ *
+ * Useful when migrating from a non-`Ref`-based codebase where lazy loading support is desired without the
+ * `.$` / `.get()` indirection that the `Reference` wrapper requires. Opt-in so it does not conflict with entities
+ * that already define a `load` or `loadOrFail` property — applying the mixin to a base class that already has
+ * either method is a compile error to prevent silent override.
+ *
+ * Call without arguments (`Loadable()`) for a standalone base with no other inheritance, or pass a base class
+ * (`Loadable(BaseEntity)`) to compose. The convenience alias {@link LoadableBaseEntity} is shorthand for the
+ * latter.
+ *
+ * @example
+ * ```ts
+ * // compose with BaseEntity
+ * class User extends Loadable(BaseEntity) {
+ *   ＠PrimaryKey()
+ *   id!: number;
+ * }
+ *
+ * // standalone — no inherited base
+ * class Product extends Loadable() {
+ *   ＠PrimaryKey()
+ *   id!: number;
+ * }
+ *
+ * const user = orm.em.getReference(User, 1);
+ * await user.load();
+ * ```
+ */
+export declare function Loadable(): LoadableConstructor<typeof EmptyBase> & typeof EmptyBase;
+export declare function Loadable<TBase extends EntityConstructor>(Base: EnsureNoLoadConflict<TBase> extends TBase ? TBase : never): LoadableConstructor<TBase> & TBase;
+declare const LoadableBaseEntityBase: LoadableConstructor<typeof BaseEntity> & typeof BaseEntity;
+/** Convenience: `BaseEntity` pre-composed with the `Loadable` mixin. */
+export declare abstract class LoadableBaseEntity extends LoadableBaseEntityBase {
+}
+export {};

package/entity/BaseEntity.js

@@ -49,3 +49,21 @@ export class BaseEntity {
     }
 }
 Object.defineProperty(BaseEntity.prototype, '__baseEntity', { value: true, writable: false, enumerable: false });
+/** Empty base for {@link Loadable} when called without arguments — standalone mixin, no inherited base. */
+class EmptyBase {
+}
+export function Loadable(Base = EmptyBase) {
+    class LoadableMixin extends Base {
+        async load(options) {
+            return Reference.create(this).load(options);
+        }
+        async loadOrFail(options) {
+            return Reference.create(this).loadOrFail(options);
+        }
+    }
+    return LoadableMixin;
+}
+const LoadableBaseEntityBase = Loadable(BaseEntity);
+/** Convenience: `BaseEntity` pre-composed with the `Loadable` mixin. */
+export class LoadableBaseEntity extends LoadableBaseEntityBase {
+}