@mikro-orm/core 7.1.0-dev.43 → 7.1.0-dev.45

package/EntityManager.d.ts

@@ -7,7 +7,8 @@ import { EntityLoader, type EntityLoaderOptions } from './entity/EntityLoader.js
 import { Reference } from './entity/Reference.js';
 import { UnitOfWork } from './unit-of-work/UnitOfWork.js';
 import type { CountByOptions, CountOptions, DeleteOptions, FilterOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, IDatabaseDriver, LockOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from './drivers/IDatabaseDriver.js';
-import type { AnyString, ArrayElement, AutoPath, ConnectionType, Dictionary, EntityClass, EntityData, EntityDictionary, EntityDTO, EntityKey, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MergeLoaded, MergeSelected, ObjectQuery, PopulateOptions, Primary, Ref, RequiredEntityData, UnboxArray, IndexFilterQuery, WithUsingOptions } from './typings.js';
+import type { AnyString, ArrayElement, AutoPath, ConnectionType, Dictionary, EntityClass, EntityData, EntityDictionary, EntityDTO, EntityKey, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MergeLoaded, MergeSelected, ObjectQuery, PopulateOptions, Primary, Ref, RequiredEntityData, RoutineArgs, RoutineReturn, UnboxArray, IndexFilterQuery, WithUsingOptions } from './typings.js';
+import type { Routine } from './metadata/Routine.js';
 import { FlushMode, LockMode, PopulatePath, type TransactionOptions } from './enums.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
 import type { AbortQueryOptions, InflightQueryAbortStrategy, Transaction } from './connections/Connection.js';
@@ -346,6 +347,29 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Fires native update query. Calling this has no side effects on the context (identity map).
      */
     nativeUpdate<Entity extends object>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, data: EntityData<Entity>, options?: UpdateOptions<Entity>): Promise<number>;
+    /**
+     * Invokes a stored procedure or function declared via the {@link Routine} class. Arg and return
+     * types are inferred from the literal config; use {@link Routine.create} to refine when needed.
+     *
+     * Procedures emitting result sets (MySQL `SELECT`s, PG/Oracle refcursor OUT params) return
+     * `Dictionary[][]`; MSSQL multi-result procs aren't exposed here, use `em.getConnection().execute()`.
+     *
+     * Mongo throws. SQLite bridges `bodyJs` functions via better-sqlite3 UDFs (procedures and
+     * function-without-bodyJs throw); libSQL throws unconditionally. Oracle calls run on their own
+     * pool connection with `autoCommit: true`, so wrapping in `em.transactional(...)` throws.
+     *
+     * @example
+     * ```ts
+     * const hash = await em.callRoutine(HashUser, { name: 'jon', salt: 'pepper' });
+     *
+     * const hashRef = new ScalarReference<string>();
+     * await em.callRoutine(AddRecord, { p_name: 'jon', p_age: 30, p_hash: hashRef });
+     *
+     * const TwoCursors = Routine.create<Record<string, never>, unknown[][]>({ ... });
+     * const [users, books] = await em.transactional(em => em.callRoutine(TwoCursors, {}));
+     * ```
+     */
+    callRoutine<R extends Routine>(routine: R, args: RoutineArgs<R>): Promise<RoutineReturn<R>>;
     /**
      * Fires native delete query. Calling this has no side effects on the context (identity map).
      */

package/EntityManager.js

@@ -1345,6 +1345,37 @@ export class EntityManager {
         });
         return res.affectedRows;
     }
+    /**
+     * Invokes a stored procedure or function declared via the {@link Routine} class. Arg and return
+     * types are inferred from the literal config; use {@link Routine.create} to refine when needed.
+     *
+     * Procedures emitting result sets (MySQL `SELECT`s, PG/Oracle refcursor OUT params) return
+     * `Dictionary[][]`; MSSQL multi-result procs aren't exposed here, use `em.getConnection().execute()`.
+     *
+     * Mongo throws. SQLite bridges `bodyJs` functions via better-sqlite3 UDFs (procedures and
+     * function-without-bodyJs throw); libSQL throws unconditionally. Oracle calls run on their own
+     * pool connection with `autoCommit: true`, so wrapping in `em.transactional(...)` throws.
+     *
+     * @example
+     * ```ts
+     * const hash = await em.callRoutine(HashUser, { name: 'jon', salt: 'pepper' });
+     *
+     * const hashRef = new ScalarReference<string>();
+     * await em.callRoutine(AddRecord, { p_name: 'jon', p_age: 30, p_hash: hashRef });
+     *
+     * const TwoCursors = Routine.create<Record<string, never>, unknown[][]>({ ... });
+     * const [users, books] = await em.transactional(em => em.callRoutine(TwoCursors, {}));
+     * ```
+     */
+    async callRoutine(routine, args) {
+        const em = this.getContext(false);
+        // Identity by reference so the user-held import survives bundling and tree-shakes unused routines.
+        if (!em.config.hasRoutine(routine)) {
+            throw new Error(`Routine '${routine.name}' is not registered in the 'routines' config option.`);
+        }
+        const conn = em.driver.getConnection('write');
+        return conn.callRoutine(routine, args, em.#transactionContext);
+    }
     /**
      * Fires native delete query. Calling this has no side effects on the context (identity map).
      */

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. */

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

@@ -3,7 +3,7 @@
  * @module core
  */
 export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName, IndexHints, } from './typings.js';
-export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, InferEntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, EntityDTOFlat, EntityDTOProp, SerializeDTO, MigrationDiff, GenerateOptions, FilterObject, IndexFilterQuery, ExtractIndexHints, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaColumns, FormulaTable, SchemaTable, SchemaColumns, SchemaColumnRef, EntityDataPropValue, SimpleColumnMeta, Rel, Ref, LazyRef, ScalarRef, EntityRef, ISchemaGenerator, MigrationInfo, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, TriggerDef, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
+export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, InferEntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, EntityDTOFlat, EntityDTOProp, SerializeDTO, MigrationDiff, GenerateOptions, FilterObject, IndexFilterQuery, ExtractIndexHints, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaColumns, FormulaTable, SchemaTable, SchemaColumns, SchemaColumnRef, EntityDataPropValue, SimpleColumnMeta, Rel, Ref, LazyRef, ScalarRef, EntityRef, ISchemaGenerator, MigrationInfo, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, TriggerDef, RoutineReturns, RoutineBodyCallback, RoutineJsBody, RoutineIgnoreField, RoutineParamConfig, RoutineConfig, RoutineRuntimeType, RoutineArgs, RoutineReturn, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
 export * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';

package/metadata/MetadataValidator.d.ts

@@ -1,4 +1,5 @@
 import type { EntityMetadata, EntityName } from '../typings.js';
+import type { Routine } from './Routine.js';
 import { type MetadataDiscoveryOptions } from '../utils/Configuration.js';
 import type { MetadataStorage } from './MetadataStorage.js';
 /**
@@ -6,6 +7,7 @@ import type { MetadataStorage } from './MetadataStorage.js';
  */
 export declare class MetadataValidator {
     validateEntityDefinition<T>(metadata: MetadataStorage, name: EntityName<T>, options: MetadataDiscoveryOptions): void;
+    validateRoutineDefinition(routine: Routine): void;
     validateDiscovered(discovered: EntityMetadata[], options: MetadataDiscoveryOptions): void;
     private validatePartitioning;
     /**

package/metadata/MetadataValidator.js

@@ -62,6 +62,41 @@ export class MetadataValidator {
             }
         }
     }
+    validateRoutineDefinition(routine) {
+        if (typeof routine.name !== 'string' || routine.name.trim() === '') {
+            throw new MetadataError(`Routine is missing the required 'name' option.`);
+        }
+        if (!routine.type) {
+            throw new MetadataError(`Routine ${routine.name} is missing the required 'type' option ('procedure' | 'function').`);
+        }
+        if (routine.body != null && routine.expression != null) {
+            throw new MetadataError(`Routine ${routine.name} defines both 'body' and 'expression'. Use one or the other.`);
+        }
+        if (routine.body == null && routine.expression == null && routine.bodyJs == null) {
+            throw new MetadataError(`Routine ${routine.name} must define a 'body', 'expression', or 'bodyJs'.`);
+        }
+        if (routine.type === 'function' && routine.returns == null) {
+            throw new MetadataError(`Function routine ${routine.name} must declare a 'returns' option.`);
+        }
+        if (routine.type === 'procedure' && routine.bodyJs != null) {
+            throw new MetadataError(`Routine ${routine.name} declares 'bodyJs' on a procedure. JS fallbacks are only supported for functions — SQLite has no analog for stored procedures.`);
+        }
+        for (const param of routine.params) {
+            const dir = param.direction;
+            if (dir !== 'in' && dir !== 'out' && dir !== 'inout') {
+                throw new MetadataError(`Routine ${routine.name}.${param.name} has invalid direction '${dir}'. Expected 'in', 'out', or 'inout'.`);
+            }
+            if ((dir === 'out' || dir === 'inout') && !param.ref) {
+                throw new MetadataError(`Routine ${routine.name}.${param.name} is declared as '${dir}' but missing 'ref: true'. OUT/INOUT parameters must be passed as ScalarReference.`);
+            }
+            if (dir === 'in' && param.ref) {
+                throw new MetadataError(`Routine ${routine.name}.${param.name} declares 'ref: true' on an IN parameter. ScalarReference wrapping is only meaningful for OUT/INOUT parameters.`);
+            }
+            if (routine.type === 'function' && dir !== 'in') {
+                throw new MetadataError(`Function routine ${routine.name}.${param.name} declares direction '${dir}'. Functions only support IN parameters — use a procedure for OUT/INOUT semantics.`);
+            }
+        }
+    }
     validateDiscovered(discovered, options) {
         if (discovered.length === 0 && options.warnWhenNoEntities) {
             throw MetadataError.noEntityDiscovered();

package/metadata/Routine.d.ts

@@ -0,0 +1,74 @@
+import type { RoutineArgsOf, RoutineConfig, RoutineDataAccess, RoutineIgnoreField, RoutineKind, RoutineParamMap, RoutineProperty, RoutineReturnOf, RoutineReturns, RoutineSecurity } from '../typings.js';
+import type { Type } from '../types/Type.js';
+import type { Raw } from '../utils/RawQueryFragment.js';
+/**
+ * Stored procedure or function declaration. Register instances via the `routines` config option
+ * passed to `MikroORM.init`, then call them through `em.callRoutine(routine, args)`.
+ *
+ * `TArgs` and `TReturn` are inferred from the literal config, so `em.callRoutine` is fully typed
+ * without threading generics through the call site. Reach for {@link Routine.create} when the
+ * inferred type is too loose — typically an `object` return that should be a concrete shape
+ * rather than `Dictionary`.
+ *
+ * @example
+ * ```ts
+ * const HashUser = new Routine({
+ *   name: 'hash_user',
+ *   type: 'function',
+ *   params: {
+ *     name: { type: 'varchar(255)' },
+ *     salt: { type: 'varchar(255)' },
+ *   },
+ *   returns: { runtimeType: 'string', columnType: 'char(40)' },
+ *   body: 'SELECT SHA1(CONCAT(name, salt))',
+ * });
+ *
+ * await MikroORM.init({ entities: [User], routines: [HashUser] });
+ *
+ * // args typed as `{ name: string; salt: string }`, result typed as `string`:
+ * const hash = await em.callRoutine(HashUser, { name: 'jon', salt: 'pepper' });
+ * ```
+ */
+export declare class Routine<const TConfig extends RoutineConfig = RoutineConfig, TArgs = RoutineArgsOf<TConfig>, TReturn = RoutineReturnOf<TConfig>> {
+    readonly name: string;
+    readonly type: RoutineKind;
+    readonly schema?: string;
+    readonly comment?: string;
+    readonly security?: RoutineSecurity;
+    readonly definer?: string;
+    readonly deterministic?: boolean;
+    readonly dataAccess?: RoutineDataAccess;
+    readonly language?: string;
+    readonly body?: string | Raw | ((params: RoutineParamMap<any>, em: any) => string | Raw);
+    readonly expression?: string;
+    readonly bodyJs?: (params: any) => unknown;
+    readonly returns?: RoutineReturns;
+    readonly returnCustomType?: Type<unknown>;
+    readonly ignoreSchemaChanges?: RoutineIgnoreField[];
+    readonly params: RoutineProperty[];
+    constructor(config: TConfig);
+    /** @internal */
+    createParamMappingObject(): Record<string, string>;
+    /**
+     * Overrides the inferred TArgs/TReturn. Omit a generic to keep inference; pass `never` in the
+     * args slot to refine only the return type.
+     *
+     * @example
+     * ```ts
+     * interface UserStats { totalOrders: number; lastOrderAt: Date }
+     * const GetStats = Routine.create<never, UserStats>({
+     *   name: 'get_user_stats',
+     *   type: 'function',
+     *   params: { user_id: { type: 'int', runtimeType: 'number' } },
+     *   returns: { runtimeType: 'object', columnType: 'json' },
+     *   body: '...',
+     * });
+     * ```
+     */
+    static create<TArgs = never, TReturn = never, const TConfig extends RoutineConfig = RoutineConfig>(config: TConfig): Routine<TConfig, [
+        TArgs
+    ] extends [never] ? RoutineArgsOf<TConfig> : TArgs, [
+        TReturn
+    ] extends [never] ? RoutineReturnOf<TConfig> : TReturn>;
+    static is(item: unknown): item is Routine;
+}

package/metadata/Routine.js

@@ -0,0 +1,140 @@
+// Resolve a `Type<unknown> | Constructor<Type<unknown>>` to an instance. Each built-in `Type` has
+// `__mappedType` on its prototype so any constructed instance carries it; a missing brand means a
+// raw constructor that we instantiate.
+const toTypeInstance = (value) => {
+    return value.__mappedType ? value : new value();
+};
+/**
+ * Stored procedure or function declaration. Register instances via the `routines` config option
+ * passed to `MikroORM.init`, then call them through `em.callRoutine(routine, args)`.
+ *
+ * `TArgs` and `TReturn` are inferred from the literal config, so `em.callRoutine` is fully typed
+ * without threading generics through the call site. Reach for {@link Routine.create} when the
+ * inferred type is too loose — typically an `object` return that should be a concrete shape
+ * rather than `Dictionary`.
+ *
+ * @example
+ * ```ts
+ * const HashUser = new Routine({
+ *   name: 'hash_user',
+ *   type: 'function',
+ *   params: {
+ *     name: { type: 'varchar(255)' },
+ *     salt: { type: 'varchar(255)' },
+ *   },
+ *   returns: { runtimeType: 'string', columnType: 'char(40)' },
+ *   body: 'SELECT SHA1(CONCAT(name, salt))',
+ * });
+ *
+ * await MikroORM.init({ entities: [User], routines: [HashUser] });
+ *
+ * // args typed as `{ name: string; salt: string }`, result typed as `string`:
+ * const hash = await em.callRoutine(HashUser, { name: 'jon', salt: 'pepper' });
+ * ```
+ */
+export class Routine {
+    name;
+    type;
+    schema;
+    comment;
+    security;
+    definer;
+    deterministic;
+    dataAccess;
+    language;
+    body;
+    expression;
+    bodyJs;
+    returns;
+    returnCustomType;
+    ignoreSchemaChanges;
+    params;
+    constructor(config) {
+        this.name = config.name;
+        this.type = config.type;
+        this.schema = config.schema;
+        this.comment = config.comment;
+        this.security = config.security;
+        this.definer = config.definer;
+        this.deterministic = config.deterministic;
+        this.dataAccess = config.dataAccess;
+        this.language = config.language;
+        this.body = config.body;
+        this.expression = config.expression;
+        this.bodyJs = config.bodyJs;
+        this.returns = config.returns;
+        this.ignoreSchemaChanges = config.ignoreSchemaChanges;
+        this.params = Object.entries(config.params ?? {}).map(([name, opts], index) => {
+            const explicitCustom = opts.customType ? toTypeInstance(opts.customType) : undefined;
+            const rawType = opts.type;
+            let type;
+            let customType;
+            if (rawType == null || typeof rawType === 'string') {
+                type = rawType ?? 'string';
+                customType = explicitCustom;
+            }
+            else {
+                // A `Type` instance or constructor at `type` both defines the column (via
+                // `getColumnType` at schema-gen time) and acts as the default `customType` for
+                // marshalling. An explicit `customType` on the same param overrides the marshalling side.
+                const instance = toTypeInstance(rawType);
+                type = instance;
+                customType = explicitCustom ?? instance;
+            }
+            return {
+                name,
+                direction: opts.direction ?? 'in',
+                type,
+                runtimeType: opts.runtimeType ?? 'any',
+                columnTypes: [typeof type === 'string' ? type : ''],
+                customType,
+                ref: opts.ref,
+                length: opts.length,
+                precision: opts.precision,
+                scale: opts.scale,
+                nullable: opts.nullable,
+                defaultRaw: opts.defaultRaw,
+                index,
+            };
+        });
+        if (config.returns && typeof config.returns === 'object') {
+            // `returns: { type: SomeType }` is the canonical scalar-return shape — the Type drives
+            // both the column type (via `getColumnType` at schema-gen time) and the marshalling.
+            if ('type' in config.returns && config.returns.type) {
+                this.returnCustomType = toTypeInstance(config.returns.type);
+            }
+            else if ('customType' in config.returns && config.returns.customType) {
+                this.returnCustomType = toTypeInstance(config.returns.customType);
+            }
+        }
+    }
+    /** @internal */
+    createParamMappingObject() {
+        return this.params.reduce((o, p) => {
+            o[p.name] = p.name;
+            return o;
+        }, {});
+    }
+    /**
+     * Overrides the inferred TArgs/TReturn. Omit a generic to keep inference; pass `never` in the
+     * args slot to refine only the return type.
+     *
+     * @example
+     * ```ts
+     * interface UserStats { totalOrders: number; lastOrderAt: Date }
+     * const GetStats = Routine.create<never, UserStats>({
+     *   name: 'get_user_stats',
+     *   type: 'function',
+     *   params: { user_id: { type: 'int', runtimeType: 'number' } },
+     *   returns: { runtimeType: 'object', columnType: 'json' },
+     *   body: '...',
+     * });
+     * ```
+     */
+    static create(config) {
+        return new Routine(config);
+    }
+    static is(item) {
+        return item instanceof Routine;
+    }
+}

package/metadata/index.d.ts

@@ -1,5 +1,6 @@
 export type * from './types.js';
 export * from './EntitySchema.js';
+export * from './Routine.js';
 export * from './MetadataDiscovery.js';
 export * from './MetadataStorage.js';
 export * from './MetadataProvider.js';

package/metadata/index.js

@@ -1,4 +1,5 @@
 export * from './EntitySchema.js';
+export * from './Routine.js';
 export * from './MetadataDiscovery.js';
 export * from './MetadataStorage.js';
 export * from './MetadataProvider.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.1.0-dev.43",
+  "version": "7.1.0-dev.45",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",

package/typings.d.ts

@@ -10,6 +10,7 @@ import { Reference, type ScalarReference } from './entity/Reference.js';
 import type { SerializationContext } from './serialization/SerializationContext.js';
 import type { SerializeOptions } from './serialization/EntitySerializer.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
+import type { Routine } from './metadata/Routine.js';
 import type { EntitySchema } from './metadata/EntitySchema.js';
 import type { EntityPartitionBy, IndexColumnOptions } from './metadata/types.js';
 import type { Type, types } from './types/index.js';
@@ -730,6 +731,197 @@ export interface TriggerDef<T = any> {
     /** Raw DDL escape hatch — full CREATE TRIGGER statement. Mutually exclusive with `body`. */
     expression?: string;
 }
+export type RoutineParamDirection = 'in' | 'out' | 'inout';
+/** Mirrors MySQL/MariaDB's `SQL DATA ACCESS` clause; ignored by other dialects. */
+export type RoutineDataAccess = 'contains-sql' | 'no-sql' | 'reads-sql-data' | 'modifies-sql-data';
+export type RoutineSecurity = 'invoker' | 'definer';
+export type RoutineKind = 'procedure' | 'function';
+export type RoutineIgnoreField = 'body' | 'comment' | 'security' | 'deterministic' | 'definer';
+export type RoutineParamMap<T> = Record<PropertyName<T>, string>;
+export type RoutineBodyCallback<T> = (params: RoutineParamMap<T>, em: any) => string | Raw;
+/**
+ * Routine return shape:
+ *  - omitted/`void`: procedures with no result set
+ *  - `() => Entity` (single or tuple): hydrated row arrays, one per result set
+ *  - `{ type: Type<...> }`: scalar function return — runtime/column types both inferred
+ *    from the {@link Type} generics
+ *  - `{ runtimeType, columnType }`: scalar function return with explicit SQL+TS types
+ *  - `{ hydrate }`: fully custom row mapping
+ */
+export type RoutineReturns<T = unknown> = (() => EntityName<any>) | (() => EntityName<any>)[] | {
+    type: Type<unknown> | Constructor<Type<unknown>>;
+    nullable?: boolean;
+} | {
+    runtimeType: RoutineRuntimeType;
+    columnType?: string;
+    nullable?: boolean;
+    customType?: Type<unknown> | Constructor<Type<unknown>>;
+} | {
+    hydrate: (rows: Dictionary[][], args: T, em: any) => unknown;
+};
+/** JS fallback registered as a UDF on SQLite (better-sqlite3). Functions only. */
+export type RoutineJsBody<T> = (params: T) => unknown;
+export interface RoutineDef<T = any> {
+    type: RoutineKind;
+    name?: string;
+    schema?: string;
+    comment?: string;
+    security?: RoutineSecurity;
+    /** User the routine runs as when `security: 'definer'`. */
+    definer?: string;
+    deterministic?: boolean;
+    /** MySQL/MariaDB only. */
+    dataAccess?: RoutineDataAccess;
+    language?: 'sql' | 'plpgsql' | 'tsql' | 'plsql' | AnyString;
+    /** Mutually exclusive with `expression`. */
+    body?: string | Raw | RoutineBodyCallback<T>;
+    /** Raw `CREATE PROCEDURE`/`FUNCTION` escape hatch — schema diff can't detect changes. Prefer `body`. */
+    expression?: string;
+    /** JS fallback registered as a UDF on SQLite (better-sqlite3). Functions only. */
+    bodyJs?: RoutineJsBody<T>;
+    returns?: RoutineReturns<T>;
+    /** Skip selected fields in schema diff; useful when the engine normalises the body differently. */
+    ignoreSchemaChanges?: RoutineIgnoreField[];
+}
+export interface RoutineProperty<Owner = any> {
+    name: EntityKey<Owner>;
+    /** SQL string, or a `Type` instance (resolved to the dialect column type at schema-gen time via `getColumnType`). */
+    type: keyof typeof types | AnyString | Type<unknown>;
+    runtimeType: EntityProperty['runtimeType'];
+    /** Singleton array to align with EntityProperty's `columnTypes`/Type API surface. */
+    columnTypes: string[];
+    customType?: Type<unknown>;
+    direction: RoutineParamDirection;
+    /** Required for OUT/INOUT params — wraps the JS-side value in `ScalarReference`. */
+    ref?: boolean;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    nullable?: boolean;
+    /** Default expression used when the caller omits the parameter, where the dialect supports it. */
+    defaultRaw?: string;
+    /** Original declaration order, used to rebuild positional argument lists. */
+    index: number;
+}
+export interface RoutineParamConfig {
+    runtimeType?: RoutineRuntimeType;
+    type?: keyof typeof types | AnyString | Type<any> | Constructor<Type<any>>;
+    direction?: RoutineParamDirection;
+    ref?: boolean;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    nullable?: boolean;
+    defaultRaw?: string;
+    /** Marshals the param via `Type.convertToDatabaseValue` inbound and `convertToJSValue` outbound. */
+    customType?: Type<unknown> | Constructor<Type<unknown>>;
+}
+/** Routine declaration shape accepted by the {@link Routine} class. */
+export interface RoutineConfig<T = any> extends Omit<RoutineDef<T>, 'name'> {
+    name: string;
+    /** Order is preserved from `Object.keys`. */
+    params?: Record<string, RoutineParamConfig>;
+}
+export type RoutineRuntimeTypeMap = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    bigint: bigint;
+    Buffer: Buffer;
+    Date: Date;
+    object: Dictionary;
+    any: any;
+};
+/** Narrow union (vs `EntityProperty['runtimeType']`) so literals survive `const` inference and feed args/return inference. */
+export type RoutineRuntimeType = keyof RoutineRuntimeTypeMap;
+type RoutineRuntimeOf<R> = R extends keyof RoutineRuntimeTypeMap ? RoutineRuntimeTypeMap[R] : unknown;
+type Nullify<P, V> = P extends {
+    nullable: true;
+} ? V | null : V;
+type StripSqlTypeArgs<S extends string> = S extends `${infer Base}(${string}` ? Base : S;
+type SqlStringTypes = 'varchar' | 'char' | 'character' | 'nvarchar' | 'nchar' | 'text' | 'mediumtext' | 'longtext' | 'tinytext' | 'ntext' | 'clob' | 'nclob' | 'citext' | 'xml' | 'uuid' | 'string' | 'decimal' | 'numeric' | 'money' | 'bigint' | 'int8' | 'bigserial';
+type SqlNumberTypes = 'int' | 'integer' | 'smallint' | 'tinyint' | 'mediumint' | 'int2' | 'int4' | 'serial' | 'smallserial' | 'real' | 'float' | 'float4' | 'float8' | 'double';
+type SqlBooleanTypes = 'boolean' | 'bool' | 'bit';
+type SqlDateTypes = 'date' | 'datetime' | 'datetime2' | 'smalldatetime' | 'timestamp' | 'timestamptz' | 'time' | 'timetz';
+type SqlJsonTypes = 'json' | 'jsonb';
+type SqlBufferTypes = 'blob' | 'tinyblob' | 'mediumblob' | 'longblob' | 'binary' | 'varbinary' | 'bytea' | 'bytes' | 'image' | 'raw';
+type SqlTypeMap = {
+    [K in SqlStringTypes]: string;
+} & {
+    [K in SqlNumberTypes]: number;
+} & {
+    [K in SqlBooleanTypes]: boolean;
+} & {
+    [K in SqlDateTypes]: Date;
+} & {
+    [K in SqlJsonTypes]: Dictionary;
+} & {
+    [K in SqlBufferTypes]: Buffer;
+} & {
+    'character varying': string;
+    'double precision': number;
+    'time with time zone': Date;
+    'timestamp with time zone': Date;
+    'long raw': Buffer;
+};
+type LookupSqlType<K> = K extends keyof SqlTypeMap ? SqlTypeMap[K] : any;
+/**
+ * Maps a SQL-flavoured `type` string (e.g. `'varchar(255)'`, `'int'`, `'timestamp'`) to a TS
+ * runtime type, used as a fallback when {@link RoutineParamConfig} does not declare an explicit
+ * `runtimeType`. Length/precision arguments are stripped, the lowercase token is matched
+ * against {@link SqlTypeMap}. `decimal`/`numeric`/`money`/`bigint` default to `string` since
+ * drivers typically return them as strings to preserve precision; opt in to `number` or
+ * `bigint` via `runtimeType` when the value range is safe. Unrecognised or genuinely
+ * ambiguous types (`refcursor`, `sys_refcursor`, …) fall through to `any`.
+ */
+export type SqlTypeToTs<S> = S extends string ? Lowercase<S> extends `tinyint(1)${string}` ? boolean : LookupSqlType<StripSqlTypeArgs<Lowercase<S>>> : any;
+/** Strips `null | undefined` from a `Type<JSType, _>` JSType, so e.g. `StringType extends Type<string | null | undefined>` resolves to `string`. */
+type TypeJsType<T> = T extends Type<infer J, any> ? Exclude<J, null | undefined> : T extends new (...args: any[]) => Type<infer J, any> ? Exclude<J, null | undefined> : never;
+/**
+ * TS value type for a single routine parameter. Resolution order:
+ *
+ * 1. explicit `runtimeType`
+ * 2. `type` set to a {@link Type} class or instance — JSType is extracted from the Type generic
+ * 3. `type` set to a SQL string — mapped via {@link SqlTypeToTs}
+ * 4. fallback `any`
+ *
+ * `ref: true` wraps the result in `ScalarReference`; `nullable: true` adds `| null`.
+ */
+export type RoutineParamValue<P> = P extends {
+    runtimeType: infer R;
+} ? P extends {
+    ref: true;
+} ? ScalarReference<Nullify<P, RoutineRuntimeOf<R>>> : Nullify<P, RoutineRuntimeOf<R>> : P extends {
+    type: infer T;
+} ? [TypeJsType<T>] extends [never] ? T extends string ? P extends {
+    ref: true;
+} ? ScalarReference<Nullify<P, SqlTypeToTs<T>>> : Nullify<P, SqlTypeToTs<T>> : P extends {
+    ref: true;
+} ? ScalarReference<any> : any : P extends {
+    ref: true;
+} ? ScalarReference<Nullify<P, TypeJsType<T>>> : Nullify<P, TypeJsType<T>> : P extends {
+    ref: true;
+} ? ScalarReference<any> : any;
+/** Default `TArgs` for {@link Routine}; consumers use {@link RoutineArgs}, which honours overrides from {@link Routine.create}. */
+export type RoutineArgsOf<Config> = Config extends {
+    params: infer P;
+} ? P extends Record<string, RoutineParamConfig> ? {
+    [K in keyof P]: RoutineParamValue<P[K]>;
+} : Record<string, unknown> : Record<string, unknown>;
+/** Default `TReturn` for {@link Routine}; consumers use {@link RoutineReturn}, which honours overrides from {@link Routine.create}. */
+export type RoutineReturnOf<Config> = Config extends {
+    returns: infer R;
+} ? R extends {
+    runtimeType: infer RT;
+} ? Nullify<R, RoutineRuntimeOf<RT>> : R extends {
+    type: infer T;
+} ? [TypeJsType<T>] extends [never] ? unknown : Nullify<R, TypeJsType<T>> : R extends readonly (() => EntityName<any>)[] ? {
+    [K in keyof R]: R[K] extends () => EntityName<infer E> ? E[] : never;
+} : R extends () => EntityName<infer E> ? E[] : R extends {
+    hydrate: (...args: any[]) => infer H;
+} ? Awaited<H> : void : void;
+export type RoutineArgs<R> = R extends Routine<any, infer A, any> ? A : Record<string, unknown>;
+export type RoutineReturn<R> = R extends Routine<any, any, infer Re> ? Re : unknown;
 /** Branded string that accepts any string value while preserving autocompletion for known literals. */
 export type AnyString = string & {};
 /** Describes a single property (column, relation, or embedded) within an entity's metadata. */

package/utils/Configuration.d.ts

@@ -6,6 +6,7 @@ import { type Logger, type LoggerNamespace, type LoggerOptions } from '../loggin
 import type { EntityManager } from '../EntityManager.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { EntitySchema } from '../metadata/EntitySchema.js';
+import { Routine } from '../metadata/Routine.js';
 import { MetadataProvider } from '../metadata/MetadataProvider.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
 import type { EventSubscriber } from '../events/EventSubscriber.js';
@@ -27,6 +28,10 @@ export declare class Configuration<D extends IDatabaseDriver = IDatabaseDriver,
     get<T extends keyof Options<D, EM>, U extends Options<D, EM>[T]>(key: T, defaultValue?: U): U;
     /** Returns all configuration options. */
     getAll(): Options<D, EM>;
+    /** Validates the `routines` config option on first access and throws on duplicate `(schema, name)` pairs or non-Routine entries. */
+    getRoutines(): readonly Routine[];
+    hasRoutine(routine: Routine): boolean;
+    private normaliseRoutines;
     /**
      * Overrides specified configuration value.
      */
@@ -408,6 +413,13 @@ export interface Options<Driver extends IDatabaseDriver = IDatabaseDriver, EM ex
      * Can be class references or instances.
      */
     subscribers: Iterable<EventSubscriber | Constructor<EventSubscriber>>;
+    /**
+     * Stored procedures and functions, declared as {@link Routine} instances.
+     *
+     * @example
+     * routines: [HashUser, AddRecord]
+     */
+    routines: Iterable<Routine>;
     /**
      * Global entity filters to apply.
      * Filters are applied by default unless explicitly disabled.

package/utils/Configuration.js

@@ -4,6 +4,8 @@ import { NullHighlighter } from '../utils/NullHighlighter.js';
 import { DefaultLogger } from '../logging/DefaultLogger.js';
 import { colors } from '../logging/colors.js';
 import { Utils } from '../utils/Utils.js';
+import { Routine } from '../metadata/Routine.js';
+import { MetadataValidator } from '../metadata/MetadataValidator.js';
 import { MetadataProvider } from '../metadata/MetadataProvider.js';
 import { NotFoundError } from '../errors.js';
 import { RequestContext } from './RequestContext.js';
@@ -17,6 +19,7 @@ const DEFAULTS = {
     entitiesTs: [],
     extensions: [],
     subscribers: [],
+    routines: [],
     filters: {},
     discovery: {
         warnWhenNoEntities: true,
@@ -137,6 +140,8 @@ export class Configuration {
     #platform;
     #cache = new Map();
     #extensions = new Map();
+    #routines = [];
+    #routinesNormalised = false;
     constructor(options, validate = true) {
         if (options.dynamicImportProvider) {
             globalThis.dynamicImportProvider = options.dynamicImportProvider;
@@ -181,6 +186,42 @@ export class Configuration {
     getAll() {
         return this.#options;
     }
+    /** Validates the `routines` config option on first access and throws on duplicate `(schema, name)` pairs or non-Routine entries. */
+    getRoutines() {
+        this.normaliseRoutines();
+        return this.#routines;
+    }
+    hasRoutine(routine) {
+        this.normaliseRoutines();
+        return this.#routines.includes(routine);
+    }
+    normaliseRoutines() {
+        if (this.#routinesNormalised) {
+            return;
+        }
+        const validator = new MetadataValidator();
+        const seenKeys = new Set();
+        // Stage in a local array so a mid-loop throw doesn't leave `#routines` partially populated;
+        // a retry after the user fixes the offending entry would otherwise duplicate earlier ones.
+        const collected = [];
+        for (const item of this.#options.routines ?? []) {
+            if (!Routine.is(item)) {
+                throw new Error(`'routines' entry is not a stored routine declaration. Use a Routine class instance.`);
+            }
+            validator.validateRoutineDefinition(item);
+            // Case-fold to match `SchemaComparator.compareRoutines`, which lower-cases the key so
+            // dialect-specific folding (Oracle uppercases, PG lowercases) round-trips; otherwise a
+            // user could register `'Foo'` and `'foo'` here and have the comparator silently collapse them.
+            const key = ((item.schema ? `${item.schema}.` : '') + item.name).toLowerCase();
+            if (seenKeys.has(key)) {
+                throw new Error(`Duplicate routine '${key}' declared more than once in the 'routines' config. Routine names must be unique within a schema.`);
+            }
+            seenKeys.add(key);
+            collected.push(item);
+        }
+        this.#routines.push(...collected);
+        this.#routinesNormalised = true;
+    }
     /**
      * Overrides specified configuration value.
      */
@@ -324,6 +365,10 @@ export class Configuration {
         metadataCache.enabled ??= useCache;
         this.#options.clientUrl ??= this.#platform.getDefaultClientUrl();
         this.#options.implicitTransactions ??= this.#platform.usesImplicitTransactions();
+        // Eagerly trigger routine validation so errors surface at init time, not on first call.
+        if (validate) {
+            this.getRoutines();
+        }
         if (validate && metadataCache.enabled && !metadataCache.adapter) {
             throw new Error('No metadata cache adapter specified, please fill in `metadataCache.adapter` option or use the async MikroORM.init() method which can autoload it.');
         }

package/utils/Utils.js

@@ -141,7 +141,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.1.0-dev.43';
+    static #ORM_VERSION = '7.1.0-dev.45';
     /**
      * Checks if the argument is instance of `Object`. Returns false for arrays.
      */