@mikro-orm/core 7.1.0-dev.5 → 7.1.0-dev.50

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/IDatabaseDriver.d.ts

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

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

@@ -161,13 +161,15 @@ export class EntityFactory {
             return diff2[key] === undefined;
         })
             .forEach(key => delete diff2[key]);
-        // but always add collection properties, formulas, generated columns, and version properties if they
-        // are part of the `data`, as these are excluded from `comparableProps` and won't appear in the diff
+        // but always add collection properties, formulas, generated columns, version properties, and the
+        // user-declared STI discriminator if they are part of the `data`, as these are excluded from
+        // `comparableProps` and won't appear in the diff
         Utils.keys(data)
             .filter(key => meta.properties[key]?.formula ||
             meta.properties[key]?.version ||
             (meta.properties[key]?.generated && !meta.properties[key]?.primary) ||
-            [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(meta.properties[key]?.kind))
+            [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(meta.properties[key]?.kind) ||
+            (key === meta.root.discriminatorColumn && meta.properties[key]?.userDefined !== false))
             .forEach(key => (diff2[key] = data[key]));
         // rehydrated with the new values, skip those changed by user
         // use full hydration if the entity is already initialized, even if the caller used `initialized: false`

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 {