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

package/entity/BaseEntity.d.ts

@@ -1,4 +1,4 @@
-import { type Ref } from './Reference.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';
@@ -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 {
+}

package/entity/Collection.d.ts

@@ -37,6 +37,7 @@ export declare class Collection<T extends object, O extends object = object> {
     /**
      * Gets the count of collection items from database instead of counting loaded items.
      * The value is cached (unless you use the `where` option), use `refresh: true` to force reload it.
+     * When the dataloader is enabled (globally or per-query), multiple calls are batched into a single grouped query.
      */
     loadCount(options?: LoadCountOptions<T> | boolean): Promise<number>;
     /** Queries a subset of the collection items from the database with custom filtering, ordering, and pagination. */
@@ -48,14 +49,14 @@ export declare class Collection<T extends object, O extends object = object> {
     /** Serializes the collection items to plain JSON objects. Returns an empty array if not initialized. */
     toJSON<TT extends T>(): EntityDTO<TT>[];
     /** Adds one or more items to the collection, propagating the change to the inverse side. Returns the number of items added. */
-    add<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>>, ...entities: (TT | Reference<TT>)[]): number;
+    add<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>>, ...entities: (T | Reference<T>)[]): number;
     /**
      * Remove specified item(s) from the collection. Note that removing item from collection does not necessarily imply deleting the target entity,
      * it means we are disconnecting the relation - removing items from collection, not removing entities from database - `Collection.remove()`
      * is not the same as `em.remove()`. If we want to delete the entity by removing it from collection, we need to enable `orphanRemoval: true`,
      * which tells the ORM we don't want orphaned entities to exist, so we know those should be removed.
      */
-    remove<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>> | ((item: TT) => boolean), ...entities: (TT | Reference<TT>)[]): number;
+    remove<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>> | ((item: T) => boolean), ...entities: (T | Reference<T>)[]): number;
     /** Checks whether the collection contains the given item. */
     contains<TT extends T>(item: TT | Reference<TT>, check?: boolean): boolean;
     /** Returns the number of items in the collection. Throws if the collection is not initialized. */
@@ -93,7 +94,7 @@ export declare class Collection<T extends object, O extends object = object> {
     /**
      * @internal
      */
-    hydrate(items: T[], forcePropagate?: boolean, partial?: boolean): void;
+    hydrate(items: T[], forcePropagate?: boolean, partial?: boolean, readonly?: boolean): void;
     /**
      * Remove all items from the collection. Note that removing items from collection does not necessarily imply deleting the target entity,
      * it means we are disconnecting the relation - removing items from collection, not removing entities from database - `Collection.remove()`
@@ -193,4 +194,6 @@ export interface LoadCountOptions<T extends object> extends CountOptions<T, '*'>
     refresh?: boolean;
     /** Additional filtering conditions for the count query. */
     where?: FilterQuery<T>;
+    /** Whether to use the dataloader for batching count operations. */
+    dataloader?: boolean;
 }

package/entity/Collection.js

@@ -79,10 +79,11 @@ export class Collection {
     /**
      * Gets the count of collection items from database instead of counting loaded items.
      * The value is cached (unless you use the `where` option), use `refresh: true` to force reload it.
+     * When the dataloader is enabled (globally or per-query), multiple calls are batched into a single grouped query.
      */
     async loadCount(options = {}) {
         options = typeof options === 'boolean' ? { refresh: options } : options;
-        const { refresh, where, ...countOptions } = options;
+        const { refresh, where, dataloader, ...countOptions } = options;
         if (!refresh && !where && this.#count != null) {
             return this.#count;
         }
@@ -92,8 +93,15 @@ export class Collection {
             this.property.owner) {
             return (this.#count = this.length);
         }
-        const cond = this.createLoadCountCondition(where ?? {});
-        const count = await em.count(this.property.targetMeta.class, cond, countOptions);
+        let count;
+        if (dataloader ?? [DataloaderType.ALL, DataloaderType.COLLECTION].includes(em.config.getDataloaderType())) {
+            const loader = await em.getDataLoader('count');
+            count = await loader.load([this, { where, ...countOptions }]);
+        }
+        else {
+            const cond = this.createLoadCountCondition(where ?? {});
+            count = await em.count(this.property.targetMeta.class, cond, countOptions);
+        }
         if (!where) {
             this.#count = count;
         }
@@ -462,7 +470,7 @@ export class Collection {
     /**
      * @internal
      */
-    hydrate(items, forcePropagate, partial) {
+    hydrate(items, forcePropagate, partial, readonly) {
         for (let i = 0; i < this.#items.size; i++) {
             delete this[i];
         }
@@ -472,6 +480,9 @@ export class Collection {
         this.#count = 0;
         this.add(items);
         this.takeSnapshot(forcePropagate);
+        if (readonly) {
+            this.#readonly = true;
+        }
     }
     /**
      * Remove all items from the collection. Note that removing items from collection does not necessarily imply deleting the target entity,

package/entity/EntityAssigner.js

@@ -99,6 +99,14 @@ export class EntityAssigner {
             return EntityAssigner.assignReference(entity, value, prop, options.em, options);
         }
         if (prop.kind === ReferenceKind.SCALAR && SCALAR_TYPES.has(prop.runtimeType) && (prop.setter || !prop.getter)) {
+            // mirror the hydrator (used by `em.create`) and coerce string/number inputs to `Date` instances,
+            // since `EntityData` already permits `string | Date` for `Date`-typed properties at the type level
+            if (prop.runtimeType === 'Date' &&
+                value != null &&
+                !(value instanceof Date) &&
+                (typeof value === 'string' || typeof value === 'number')) {
+                value = new Date(value);
+            }
             validateProperty(prop, value, entity);
             return (entity[prop.name] = value);
         }

package/entity/EntityFactory.js

@@ -316,11 +316,30 @@ export class EntityFactory {
             else if (!onCreateOnly && prop.default != null && !isRaw(prop.default) && entity[prop.name] === undefined) {
                 entity[prop.name] = prop.default;
             }
+            else if (!onCreateOnly &&
+                this.#config.get('initNullableProperties') &&
+                prop.nullable &&
+                prop.default == null &&
+                !prop.defaultRaw &&
+                entity[prop.name] === undefined) {
+                entity[prop.name] = (this.#config.get('forceUndefined') ? undefined : null);
+            }
             if (prop.kind === ReferenceKind.EMBEDDED && entity[prop.name]) {
                 const items = prop.array ? entity[prop.name] : [entity[prop.name]];
                 for (const item of items) {
                     // Embedded sub-properties need all defaults since the DB can't apply them within JSON columns.
-                    this.assignDefaultValues(item, prop.targetMeta);
+                    // For polymorphic embeddables, resolve the actual subtype to avoid setting
+                    // properties from other subtypes (e.g. Cat's canMeow on a Dog instance).
+                    let targetMeta = prop.targetMeta;
+                    if (targetMeta.polymorphs && targetMeta.discriminatorColumn) {
+                        const discValue = item[targetMeta.discriminatorColumn];
+                        // eslint-disable-next-line eqeqeq
+                        const resolved = targetMeta.polymorphs.find(m => m.discriminatorValue == discValue);
+                        if (resolved) {
+                            targetMeta = resolved;
+                        }
+                    }
+                    this.assignDefaultValues(item, targetMeta);
                 }
             }
         }

package/entity/EntityLoader.d.ts

@@ -1,6 +1,7 @@
-import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, PopulateOptions } from '../typings.js';
+import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, PopulateHintOptions, PopulateOptions } from '../typings.js';
 import type { EntityManager } from '../EntityManager.js';
 import { LoadStrategy, type LockMode, type PopulateHint, PopulatePath, type QueryOrderMap } from '../enums.js';
+import type { InflightQueryAbortStrategy } from '../connections/Connection.js';
 import type { FilterOptions } from '../drivers/IDatabaseDriver.js';
 import type { LoggingOptions } from '../logging/Logger.js';
 /** Options for controlling how relations are loaded by the EntityLoader. */
@@ -37,6 +38,12 @@ export interface EntityLoaderOptions<Entity, Fields extends string = never, Excl
     connectionType?: ConnectionType;
     /** Logging options for the query. */
     logging?: LoggingOptions;
+    /** Per-relation populate overrides (limit, offset, orderBy). */
+    populateHints?: Record<string, PopulateHintOptions>;
+    /** AbortSignal forwarded to populated relation queries. */
+    signal?: AbortSignal;
+    /** Cancellation strategy paired with {@link signal}. */
+    inflightQueryAbortStrategy?: InflightQueryAbortStrategy;
 }
 /** Responsible for batch-loading entity relations using either select-in or joined loading strategies. */
 export declare class EntityLoader {

package/entity/EntityLoader.js

@@ -177,8 +177,9 @@ export class EntityLoader {
             Utils.isObject(orderBy[prop.name]))
             .flatMap(orderBy => orderBy[prop.name]);
         const where = await this.extractChildCondition(options, prop);
+        const mergedOrderBy = populate.orderBy ? Utils.asArray(populate.orderBy) : innerOrderBy;
         if (prop.kind === ReferenceKind.MANY_TO_MANY && this.#driver.getPlatform().usesPivotTable()) {
-            const pivotOrderBy = QueryHelper.mergeOrderBy(innerOrderBy, prop.orderBy, prop.targetMeta?.orderBy);
+            const pivotOrderBy = QueryHelper.mergeOrderBy(mergedOrderBy, prop.orderBy, prop.targetMeta?.orderBy);
             const res = await this.findChildrenFromPivotTable(filtered, prop, options, pivotOrderBy, populate, !!ref);
             return Utils.flatten(res);
         }
@@ -188,10 +189,12 @@ export class EntityLoader {
         const { items, partial } = await this.findChildren(options.filtered ?? entities, prop, populate, {
             ...options,
             where,
-            orderBy: innerOrderBy,
+            orderBy: mergedOrderBy,
         }, !!(ref || prop.mapToPk));
-        const customOrder = innerOrderBy.length > 0 || !!prop.orderBy || !!prop.targetMeta?.orderBy;
-        this.initializeCollections(filtered, prop, field, items, customOrder, partial);
+        const hasLimit = populate.limit != null;
+        const isPartial = partial || hasLimit;
+        const customOrder = mergedOrderBy.length > 0 || !!prop.orderBy || !!prop.targetMeta?.orderBy;
+        this.initializeCollections(filtered, prop, field, items, customOrder, isPartial, hasLimit);
         return items;
     }
     async populateScalar(meta, filtered, options) {
@@ -269,15 +272,15 @@ export class EntityLoader {
         }));
         return allItems;
     }
-    initializeCollections(filtered, prop, field, children, customOrder, partial) {
+    initializeCollections(filtered, prop, field, children, customOrder, partial, readonly) {
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
-            this.initializeOneToMany(filtered, children, prop, field, partial);
+            this.initializeOneToMany(filtered, children, prop, field, partial, readonly);
         }
         if (prop.kind === ReferenceKind.MANY_TO_MANY && !this.#driver.getPlatform().usesPivotTable()) {
-            this.initializeManyToMany(filtered, children, prop, field, customOrder, partial);
+            this.initializeManyToMany(filtered, children, prop, field, customOrder, partial, readonly);
         }
     }
-    initializeOneToMany(filtered, children, prop, field, partial) {
+    initializeOneToMany(filtered, children, prop, field, partial, readonly) {
         const mapToPk = prop.targetMeta.properties[prop.mappedBy].mapToPk;
         const map = {};
         for (const entity of filtered) {
@@ -293,14 +296,14 @@ export class EntityLoader {
         }
         for (const entity of filtered) {
             const key = helper(entity).getSerializedPrimaryKey();
-            entity[field].hydrate(map[key], undefined, partial);
+            entity[field].hydrate(map[key], undefined, partial, readonly);
         }
     }
-    initializeManyToMany(filtered, children, prop, field, customOrder, partial) {
+    initializeManyToMany(filtered, children, prop, field, customOrder, partial, readonly) {
         if (prop.mappedBy) {
             for (const entity of filtered) {
                 const items = children.filter(child => child[prop.mappedBy].contains(entity, false));
-                entity[field].hydrate(items, true, partial);
+                entity[field].hydrate(items, true, partial, readonly);
             }
         }
         else {
@@ -311,12 +314,12 @@ export class EntityLoader {
                 if (!customOrder) {
                     items.sort((a, b) => order.indexOf(a) - order.indexOf(b));
                 }
-                entity[field].hydrate(items, true, partial);
+                entity[field].hydrate(items, true, partial, readonly);
             }
         }
     }
     async findChildren(entities, prop, populate, options, ref) {
-        const children = Utils.unique(this.getChildReferences(entities, prop, options, ref));
+        const children = Utils.unique(this.getChildReferences(entities, prop, options, ref, populate));
         const meta = prop.targetMeta;
         // When targetKey is set, use it for FK lookup instead of the PK
         let fk = prop.targetKey ?? Utils.getPrimaryKeyHash(meta.primaryKeys);
@@ -334,10 +337,10 @@ export class EntityLoader {
                 fk = ownerProp.name;
             }
         }
-        if (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && !ref) {
+        if (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && (!ref || (!prop.mapToPk && !populate.filter))) {
             children.length = 0;
             fk = meta.properties[prop.mappedBy].name;
-            children.push(...this.filterByReferences(entities, prop.name, options.refresh));
+            children.push(...this.filterByReferences(entities, prop, options, ref));
         }
         if (children.length === 0) {
             return { items: [], partial };
@@ -375,7 +378,7 @@ export class EntityLoader {
             where = { $and: [where, prop.where] };
         }
         const orderBy = QueryHelper.mergeOrderBy(options.orderBy, prop.orderBy);
-        const items = await this.#em.find(meta.class, where, {
+        const findOptions = {
             filters,
             convertCustomTypes,
             lockMode,
@@ -390,11 +393,21 @@ export class EntityLoader {
             fields,
             schema,
             connectionType,
+            signal: options.signal,
+            inflightQueryAbortStrategy: options.inflightQueryAbortStrategy,
             // @ts-ignore not a public option, will be propagated to the populate call
             refresh: refresh && !children.every(item => options.visited.has(item)),
             // @ts-ignore not a public option, will be propagated to the populate call
             visited: options.visited,
-        });
+        };
+        if (populate.limit != null) {
+            findOptions._partitionLimit = {
+                partitionBy: fk,
+                limit: populate.limit,
+                offset: populate.offset,
+            };
+        }
+        const items = await this.#em.find(meta.class, where, findOptions);
         // For targetKey relations, wire up loaded entities to parent references
         // This is needed because the references were created under alternate key,
         // but loaded entities are stored under PK, so they don't automatically merge
@@ -582,11 +595,18 @@ export class EntityLoader {
         const options2 = { ...options, fields, exclude, populateFilter };
         ['limit', 'offset', 'first', 'last', 'before', 'after', 'overfetch'].forEach(prop => delete options2[prop]);
         options2.populate = populate?.children ?? [];
+        if (populate?.limit != null) {
+            options2._partitionLimit = {
+                limit: populate.limit,
+                offset: populate.offset,
+            };
+        }
         if (!Utils.isEmpty(prop.where)) {
             where = { $and: [where, prop.where] };
         }
         const map = await this.#driver.loadFromPivotTable(prop, ids, where, orderBy, this.#em.getTransactionContext(), options2, pivotJoin);
         const children = [];
+        const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
         for (let i = 0; i < filtered.length; i++) {
             const entity = filtered[i];
             const items = map[Utils.getPrimaryKeyHash(ids[i])].map(item => {
@@ -596,7 +616,11 @@ export class EntityLoader {
                         schema: options.schema ?? this.#em.config.get('schema'),
                     });
                 }
-                const entity = this.#em.getEntityFactory().create(prop.targetMeta.class, item, {
+                // Union-target items carry their concrete class via `constructor` — dispatch to the right factory call.
+                const targetClass = isUnionTargetMN && item.constructor !== Object
+                    ? item.constructor
+                    : prop.targetMeta.class;
+                const entity = this.#em.getEntityFactory().create(targetClass, item, {
                     refresh,
                     merge: true,
                     convertCustomTypes: true,
@@ -604,7 +628,8 @@ export class EntityLoader {
                 });
                 return this.#em.getUnitOfWork().register(entity, item, { refresh, loaded: true });
             });
-            entity[prop.name].hydrate(items, true);
+            const hasLimit = populate?.limit != null;
+            entity[prop.name].hydrate(items, true, hasLimit, hasLimit);
             children.push(items);
         }
         return children;
@@ -665,8 +690,11 @@ export class EntityLoader {
             }
             return ret;
         }, []);
-        // we need to automatically select the FKs too, e.g. for 1:m relations to be able to wire them with the items
-        if (prop.kind === ReferenceKind.ONE_TO_MANY || prop.kind === ReferenceKind.MANY_TO_MANY) {
+        // we need to automatically select the FKs too, e.g. for 1:m and inverse 1:1 relations
+        // to be able to wire them with the items
+        if (prop.kind === ReferenceKind.ONE_TO_MANY ||
+            prop.kind === ReferenceKind.MANY_TO_MANY ||
+            (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner)) {
             const owner = prop.targetMeta.properties[prop.mappedBy];
             // when the owning FK is lazy, we need to explicitly select it even without user-provided fields,
             // otherwise the driver will exclude it and we won't be able to map children to their parent collections
@@ -679,7 +707,7 @@ export class EntityLoader {
         }
         return ret;
     }
-    getChildReferences(entities, prop, options, ref) {
+    getChildReferences(entities, prop, options, ref, populate) {
         const filtered = this.filterCollections(entities, prop.name, options, ref);
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
             return filtered.map(e => e[prop.name].owner);
@@ -695,7 +723,7 @@ export class EntityLoader {
             return filtered;
         }
         // MANY_TO_ONE or ONE_TO_ONE
-        return this.filterReferences(entities, prop.name, options, ref);
+        return this.filterReferences(entities, prop.name, options, ref, populate);
     }
     filterCollections(entities, field, options, ref) {
         if (options.refresh) {
@@ -721,7 +749,7 @@ export class EntityLoader {
         }
         return this.isPropertyLoaded(entity[f], r.join('.'));
     }
-    filterReferences(entities, field, options, ref) {
+    filterReferences(entities, field, options, ref, populate) {
         if (ref) {
             return [];
         }
@@ -730,13 +758,19 @@ export class EntityLoader {
             return children.map(e => Reference.unwrapReference(e[field]));
         }
         if (options.fields) {
+            // `:ref` populate children are satisfied by FK/PK and will be loaded lazily — they don't force a parent reload
+            const refChildren = new Set((populate?.children ?? [])
+                .map(c => c.field.split(':'))
+                .filter(parts => parts[1] === 'ref')
+                .map(parts => parts[0]));
             return children
                 .map(e => Reference.unwrapReference(e[field]))
                 .filter(target => {
                 const wrapped = helper(target);
                 const childFields = options.fields
                     .filter(f => f.startsWith(`${field}.`))
-                    .map(f => f.substring(field.length + 1));
+                    .map(f => f.substring(field.length + 1))
+                    .filter(cf => !refChildren.has(cf.split('.')[0]));
                 return !wrapped.__initialized || !childFields.every(cf => this.isPropertyLoaded(target, cf));
             });
         }
@@ -744,12 +778,39 @@ export class EntityLoader {
             .filter(e => !e[field].__helper.__initialized)
             .map(e => Reference.unwrapReference(e[field]));
     }
-    filterByReferences(entities, field, refresh) {
+    filterByReferences(entities, prop, options, ref) {
         /* v8 ignore next */
-        if (refresh) {
+        if (options.refresh) {
             return entities;
         }
-        return entities.filter(e => e[field] !== null && !e[field]?.__helper?.__initialized);
+        const field = prop.name;
+        return entities.filter(e => {
+            const value = e[field];
+            if (value === null) {
+                return false;
+            }
+            if (value === undefined || !Utils.isEntity(value, true)) {
+                return true;
+            }
+            const target = Reference.unwrapReference(value);
+            const wrapped = helper(target);
+            if (!wrapped.__initialized) {
+                return true;
+            }
+            if (ref) {
+                return false;
+            }
+            if (options.fields) {
+                const childFields = options.fields
+                    .filter(f => f.startsWith(`${prop.name}.`))
+                    .map(f => f.substring(prop.name.length + 1));
+                return childFields.length > 0 && !childFields.every(f => this.isPropertyLoaded(target, f));
+            }
+            return prop.targetMeta.comparableProps.some(targetProp => {
+                const inlineEmbedded = targetProp.kind === ReferenceKind.EMBEDDED && !targetProp.object;
+                return !inlineEmbedded && !targetProp.lazy && !wrapped.__loadedProperties.has(targetProp.name);
+            });
+        });
     }
     lookupAllRelationships(entityName) {
         const ret = [];

package/entity/EntityRepository.d.ts

@@ -1,8 +1,8 @@
 import type { PopulatePath } from '../enums.js';
 import type { CreateOptions, EntityManager, MergeOptions } from '../EntityManager.js';
 import type { AssignOptions } from './EntityAssigner.js';
-import type { EntityData, EntityName, Primary, Loaded, FilterQuery, EntityDictionary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement } from '../typings.js';
-import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
+import type { Dictionary, EntityData, EntityDictionary, EntityKey, EntityName, FilterQuery, Loaded, Primary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement, IndexFilterQuery, WithUsingOptions } from '../typings.js';
+import type { CountByOptions, CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
 import type { Cursor } from '../utils/Cursor.js';
 /** Repository class providing a type-safe API for querying and persisting a specific entity type. */
@@ -13,13 +13,17 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * Finds first entity matching your `where` query.
      */
-    findOne<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOneOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
+    findOne<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<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 is found, it will throw an error.
      * You can override the factory for creating this method via `options.failHandler` locally
      * or via `Configuration.findOneOrFailHandler` globally.
      */
-    findOneOrFail<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOneOrFailOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>>;
+    findOneOrFail<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<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
@@ -72,24 +76,28 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * Finds all entities matching your `where` query. You can pass additional options via the `options` parameter.
      */
-    find<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    find<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<Entity, Using>, options?: FindOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
     /**
      * Calls `em.find()` and `em.count()` with the same arguments (where applicable) and returns the results as tuple
      * where first element is the array of entities, and the second is the count.
      */
-    findAndCount<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(where: FilterQuery<Entity>, options?: FindOptions<Entity, Hint, Fields, Excludes>): Promise<[Loaded<Entity, Hint, Fields, Excludes>[], number]>;
+    findAndCount<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(where: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<Entity, Using>, options?: FindOptions<Entity, Hint, Fields, Excludes> & {
+        using?: Using | Using[];
+    }): Promise<[Loaded<Entity, Hint, Fields, Excludes>[], number]>;
     /**
      * @inheritDoc EntityManager.findByCursor
      */
-    findByCursor<Hint extends string = never, Fields extends string = never, Excludes extends string = never, IncludeCount extends boolean = true>(options: FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
+    findByCursor<Hint extends string = never, Fields extends string = never, Excludes extends string = never, IncludeCount extends boolean = true, Using extends string = never>(options: WithUsingOptions<FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>, Entity, Using>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
     /**
      * Finds all entities of given type. You can pass additional options via the `options` parameter.
      */
-    findAll<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: FindAllOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    findAll<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(options?: WithUsingOptions<FindAllOptions<Entity, Hint, Fields, Excludes>, Entity, Using>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
     /**
      * @inheritDoc EntityManager.stream
      */
-    stream<Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: StreamOptions<Entity, Hint, Fields, Excludes>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
+    stream<Hint extends string = never, Fields extends string = never, Excludes extends string = never, Using extends string = never>(options?: WithUsingOptions<StreamOptions<Entity, Hint, Fields, Excludes>, Entity, Using>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
     /**
      * @inheritDoc EntityManager.insert
      */
@@ -199,6 +207,16 @@ export declare class EntityRepository<Entity extends object> {
      * Returns total number of entities matching your `where` query.
      */
     count<Hint extends string = never>(where?: FilterQuery<Entity>, options?: CountOptions<Entity, Hint>): Promise<number>;
+    /**
+     * Counts entities grouped by one or more properties.
+     *
+     * @example
+     * ```ts
+     * const counts = await repo.countBy('status');
+     * // { 'active': 5, 'inactive': 2 }
+     * ```
+     */
+    countBy(groupBy: EntityKey<Entity> | readonly EntityKey<Entity>[], options?: CountByOptions<Entity>): Promise<Dictionary<number>>;
     /** Returns the entity class name associated with this repository. */
     getEntityName(): string;
     /**

package/entity/EntityRepository.js

@@ -194,6 +194,18 @@ export class EntityRepository {
     async count(where = {}, options = {}) {
         return this.getEntityManager().count(this.entityName, where, options);
     }
+    /**
+     * Counts entities grouped by one or more properties.
+     *
+     * @example
+     * ```ts
+     * const counts = await repo.countBy('status');
+     * // { 'active': 5, 'inactive': 2 }
+     * ```
+     */
+    async countBy(groupBy, options) {
+        return this.getEntityManager().countBy(this.entityName, groupBy, options);
+    }
     /** Returns the entity class name associated with this repository. */
     getEntityName() {
         return Utils.className(this.entityName);