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

package/README.md

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

package/connections/Connection.d.ts

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

package/connections/Connection.js

@@ -1,4 +1,5 @@
 import { Utils } from '../utils/Utils.js';
+import { ScalarReference } from '../entity/Reference.js';
 /** Abstract base class for database connections, providing transaction and query execution support. */
 export class Connection {
     config;
@@ -92,6 +93,69 @@ export class Connection {
     async rollback(ctx, eventBroadcaster, loggerContext) {
         throw new Error(`Transactions are not supported by current driver`);
     }
+    /** @internal — public callers go through {@link EntityManager.callRoutine}. */
+    async callRoutine(routine, args, ctx) {
+        throw new Error(`Stored routines are not supported by the current driver`);
+    }
+    /**
+     * Unwraps a routine argument (resolving any `ScalarReference` wrapper) and, when the param
+     * declares a `customType`, marshals it through `convertToDatabaseValue`. `undefined` is
+     * normalised to `null` so every driver sees the same shape.
+     *
+     * @internal
+     */
+    convertRoutineInbound(value, param) {
+        const resolved = value instanceof ScalarReference ? value.unwrap() : value;
+        const coerced = resolved === undefined ? null : resolved;
+        if (coerced === null || !param?.customType) {
+            return coerced;
+        }
+        return param.customType.convertToDatabaseValue(coerced, this.platform);
+    }
+    /**
+     * Converts a raw database value to its JS representation via the supplied `customType`, when
+     * one is declared. Used to marshal scalar function returns and OUT/INOUT values back to the
+     * caller before they land in a `ScalarReference` or `em.callRoutine`'s return value.
+     *
+     * @internal
+     */
+    convertRoutineOutbound(value, customType) {
+        if (value === null || value === undefined || !customType) {
+            return value;
+        }
+        return customType.convertToJSValue(value, this.platform);
+    }
+    /**
+     * Executes a scalar function routine as `select <qualified>(?, ?, ...) as value`, marshalling
+     * IN params on the way in and the return value on the way out. The qualified name is built
+     * from `routine.schema`, falling back to the platform's default schema (e.g. `dbo` on MSSQL),
+     * which gives MySQL/SQLite a bare name and MSSQL/Oracle the mandatory `schema.name` form.
+     *
+     * @internal
+     */
+    async callRoutineFunction(routine, args, ctx) {
+        const schema = routine.schema ?? this.platform.getDefaultSchemaName();
+        const qualified = (schema ? `${this.platform.quoteIdentifier(schema)}.` : '') + this.platform.quoteIdentifier(routine.name);
+        const placeholders = routine.params.map(() => '?').join(', ');
+        const positional = routine.params.map(p => this.convertRoutineInbound(args[p.name], p));
+        const rows = (await this.execute(`select ${qualified}(${placeholders}) as value`, positional, 'all', ctx));
+        return this.convertRoutineOutbound(rows[0]?.value, routine.returnCustomType);
+    }
+    /**
+     * Walks a result row produced by an OUT/INOUT-param SELECT and writes each value into the
+     * caller's `ScalarReference` slot. Non-reference args are ignored (the user opted out of
+     * receiving the OUT value).
+     *
+     * @internal
+     */
+    applyRoutineOutParams(row, outParams, args) {
+        for (const param of outParams) {
+            const ref = args[param.name];
+            if (ref instanceof ScalarReference) {
+                ref.set(this.convertRoutineOutbound(row[param.name], param.customType));
+            }
+        }
+    }
     /** Parses and returns the resolved connection configuration (host, port, user, etc.). */
     getConnectionOptions() {
         const ret = {};

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,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';
@@ -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. */
@@ -105,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
@@ -125,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.
@@ -211,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 */
@@ -241,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;
@@ -275,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[];
@@ -306,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;
@@ -346,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;

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 {
+}

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

@@ -318,11 +318,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 {