@mikro-orm/core 6.4.17-dev.94 → 6.4.17-dev.96

package/EntityManager.js

@@ -13,6 +13,7 @@ const enums_1 = require("./enums");
 const events_1 = require("./events");
 const errors_1 = require("./errors");
 const utils_2 = require("./entity/utils");
+const TransactionManager_1 = require("./utils/TransactionManager");
 /**
  * The EntityManager is the central access point to ORM functionality. It is a facade to all different ORM subsystems
  * such as UnitOfWork, Query Language, and Repository API.
@@ -970,38 +971,8 @@ class EntityManager {
         if (this.disableTransactions || em.disableTransactions) {
             return cb(em);
         }
-        const fork = em.fork({
-            clear: options.clear ?? false, // state will be merged once resolves
-            flushMode: options.flushMode,
-            cloneEventManager: true,
-            disableTransactions: options.ignoreNestedTransactions,
-            loggerContext: options.loggerContext,
-        });
-        options.ctx ??= em.transactionContext;
-        const propagateToUpperContext = !em.global || this.config.get('allowGlobalContext');
-        return utils_1.TransactionContext.create(fork, async () => {
-            return fork.getConnection().transactional(async (trx) => {
-                fork.transactionContext = trx;
-                if (propagateToUpperContext) {
-                    fork.eventManager.registerSubscriber({
-                        afterFlush(args) {
-                            args.uow.getChangeSets()
-                                .filter(cs => [unit_of_work_1.ChangeSetType.DELETE, unit_of_work_1.ChangeSetType.DELETE_EARLY].includes(cs.type))
-                                .forEach(cs => em.unitOfWork.unsetIdentity(cs.entity));
-                        },
-                    });
-                }
-                const ret = await cb(fork);
-                await fork.flush();
-                if (propagateToUpperContext) {
-                    // ensure all entities from inner context are merged to the upper one
-                    for (const entity of fork.unitOfWork.getIdentityMap()) {
-                        em.merge(entity, { disableContextResolution: true, keepIdentity: true, refresh: true });
-                    }
-                }
-                return ret;
-            }, { ...options, eventBroadcaster: new events_1.TransactionEventBroadcaster(fork, undefined, { topLevelTransaction: !options.ctx }) });
-        });
+        const manager = new TransactionManager_1.TransactionManager(this);
+        return manager.handle(cb, options);
     }
     /**
      * Starts new transaction bound to this EntityManager. Use `ctx` parameter to provide the parent when nesting transactions.

package/entity/defineEntity.d.ts

@@ -14,7 +14,8 @@ import type { Collection } from './Collection';
 import type { IType, Type } from '../types/Type';
 import { types } from '../types';
 import { EntitySchema } from '../metadata/EntitySchema';
-declare class PropertyOptionsBuilder<Value> {
+/** @internal */
+export declare class PropertyOptionsBuilder<Value> {
     '~options': PropertyOptions<any>;
     '~type'?: {
         value: Value;
@@ -262,7 +263,8 @@ declare class PropertyOptionsBuilder<Value> {
      */
     $type<Runtime, Raw, Serialized = Raw>(): PropertyOptionsBuilder<IType<Runtime, Raw, Serialized>>;
 }
-declare class EnumOptionsBuilder<Value> extends PropertyOptionsBuilder<Value> {
+/** @internal */
+export declare class EnumOptionsBuilder<Value> extends PropertyOptionsBuilder<Value> {
     '~options': {
         enum: true;
     } & EnumOptions<any>;
@@ -271,7 +273,8 @@ declare class EnumOptionsBuilder<Value> extends PropertyOptionsBuilder<Value> {
     /** for postgres, by default it uses text column with check constraint */
     nativeEnumName(nativeEnumName: string): EnumOptionsBuilder<Value>;
 }
-declare class EmbeddedOptionsBuilder<Value> extends PropertyOptionsBuilder<Value> {
+/** @internal */
+export declare class EmbeddedOptionsBuilder<Value> extends PropertyOptionsBuilder<Value> {
     '~options': ({
         kind: 'embedded';
         entity: () => EntitySchema<any, any> | EntitySchema<any, any>[];
@@ -282,7 +285,8 @@ declare class EmbeddedOptionsBuilder<Value> extends PropertyOptionsBuilder<Value
     object(object?: boolean): EmbeddedOptionsBuilder<Value>;
     array<T extends boolean = true>(array?: T): EmbeddedOptionsBuilder<T extends true ? Value[] : UnwrapArray<Value>>;
 }
-declare class ReferenceOptionsBuilder<Value extends object> extends PropertyOptionsBuilder<Value> {
+/** @internal */
+export declare class ReferenceOptionsBuilder<Value extends object> extends PropertyOptionsBuilder<Value> {
     '~options': ReferenceOptions<any, any>;
     constructor(options: ReferenceOptionsBuilder<Value>['~options']);
     /** Set what actions on owning entity should be cascaded to the relationship. Defaults to [Cascade.PERSIST, Cascade.MERGE] (see {@doclink cascading}). */
@@ -302,7 +306,8 @@ declare class ReferenceOptionsBuilder<Value extends object> extends PropertyOpti
      */
     primary(primary?: boolean): ReferenceOptionsBuilder<any>;
 }
-declare class ManyToManyOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
+/** @internal */
+export declare class ManyToManyOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
     '~options': ({
         kind: 'm:n';
         entity: () => EntitySchema<any, any>;
@@ -343,7 +348,8 @@ declare class ManyToManyOptionsBuilder<TargetValue extends object> extends Refer
     /** What to do when the reference to the target entity gets updated. */
     updateRule(updateRule: 'cascade' | 'no action' | 'set null' | 'set default' | AnyString): ManyToManyOptionsBuilder<TargetValue>;
 }
-declare class ManyToOneOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
+/** @internal */
+export declare class ManyToOneOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
     '~options': ({
         kind: 'm:1';
         entity: () => EntitySchema<any, any>;
@@ -374,7 +380,8 @@ declare class ManyToOneOptionsBuilder<TargetValue extends object> extends Refere
     /** Set the constraint type. Immediate constraints are checked for each statement, while deferred ones are only checked at the end of the transaction. Only for postgres unique constraints. */
     deferMode(deferMode: DeferMode | `${DeferMode}`): ManyToOneOptionsBuilder<TargetValue>;
 }
-declare class OneToManyOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
+/** @internal */
+export declare class OneToManyOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
     '~options': ({
         kind: '1:m';
         entity: () => EntitySchema<TargetValue>;
@@ -399,7 +406,8 @@ declare class OneToManyOptionsBuilder<TargetValue extends object> extends Refere
     /** Override the default database column name on the target entity (see {@doclink naming-strategy | Naming Strategy}). This option is suitable for composite keys, where one property is represented by multiple columns. */
     referencedColumnNames(...referencedColumnNames: string[]): OneToManyOptionsBuilder<TargetValue>;
 }
-declare class OneToManyOptionsBuilderOnlyMappedBy<TargetValue extends object> {
+/** @internal */
+export declare class OneToManyOptionsBuilderOnlyMappedBy<TargetValue extends object> {
     '~options': ({
         kind: '1:m';
         entity: () => EntitySchema<TargetValue>;
@@ -408,7 +416,8 @@ declare class OneToManyOptionsBuilderOnlyMappedBy<TargetValue extends object> {
     /** Point to the owning side property name. */
     mappedBy(mappedBy: (AnyString & keyof UnwrapCollection<TargetValue>) | ((e: UnwrapCollection<TargetValue>) => any)): OneToManyOptionsBuilder<TargetValue>;
 }
-declare class OneToOneOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
+/** @internal */
+export declare class OneToOneOptionsBuilder<TargetValue extends object> extends ReferenceOptionsBuilder<TargetValue> {
     '~options': ({
         kind: '1:1';
         entity: () => EntitySchema<any, any>;
@@ -510,7 +519,7 @@ type InferPropertyValueType<T extends PropertyValueType> = T extends string ? In
 type InferTypeByString<T extends string> = T extends keyof typeof types ? InferJSType<typeof types[T]> : InferColumnType<T>;
 type InferJSType<T> = T extends typeof Type<infer TValue, any> ? NonNullable<TValue> : never;
 type InferColumnType<T extends string> = T extends 'int' | 'int4' | 'integer' | 'bigint' | 'int8' | 'int2' | 'tinyint' | 'smallint' | 'mediumint' ? number : T extends 'double' | 'double precision' | 'real' | 'float8' | 'decimal' | 'numeric' | 'float' | 'float4' ? number : T extends 'datetime' | 'time' | 'time with time zone' | 'timestamp' | 'timestamp with time zone' | 'timetz' | 'timestamptz' | 'date' | 'interval' ? Date : T extends 'ObjectId' | 'objectId' | 'character varying' | 'varchar' | 'char' | 'character' | 'uuid' | 'text' | 'tinytext' | 'mediumtext' | 'longtext' | 'enum' ? string : T extends 'boolean' | 'bool' | 'bit' ? boolean : T extends 'blob' | 'tinyblob' | 'mediumblob' | 'longblob' | 'bytea' ? Buffer : T extends 'point' | 'line' | 'lseg' | 'box' | 'circle' | 'path' | 'polygon' | 'geometry' ? number[] : T extends 'tsvector' | 'tsquery' ? string[] : T extends 'json' | 'jsonb' ? any : any;
-type InferEntityFromProperties<Properties extends Record<string, any>> = {
+export type InferEntityFromProperties<Properties extends Record<string, any>> = {
     -readonly [K in keyof Properties]: Properties[K] extends (() => any) ? InferBuilderValue<ReturnType<Properties[K]>> : InferBuilderValue<Properties[K]>;
 };
 type InferBuilderValue<Builder> = Builder extends {

package/entity/defineEntity.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OneToOneOptionsBuilder = exports.OneToManyOptionsBuilderOnlyMappedBy = exports.OneToManyOptionsBuilder = exports.ManyToOneOptionsBuilder = exports.ManyToManyOptionsBuilder = exports.ReferenceOptionsBuilder = exports.EmbeddedOptionsBuilder = exports.EnumOptionsBuilder = exports.PropertyOptionsBuilder = void 0;
 exports.defineEntity = defineEntity;
 const types_1 = require("../types");
 const EntitySchema_1 = require("../metadata/EntitySchema");
+/** @internal */
 class PropertyOptionsBuilder {
     '~options';
     '~type';
@@ -325,6 +327,8 @@ class PropertyOptionsBuilder {
         return new PropertyOptionsBuilder({ ...this['~options'] });
     }
 }
+exports.PropertyOptionsBuilder = PropertyOptionsBuilder;
+/** @internal */
 class EnumOptionsBuilder extends PropertyOptionsBuilder {
     constructor(options) {
         super(options);
@@ -338,6 +342,8 @@ class EnumOptionsBuilder extends PropertyOptionsBuilder {
         return new EnumOptionsBuilder({ ...this['~options'], nativeEnumName });
     }
 }
+exports.EnumOptionsBuilder = EnumOptionsBuilder;
+/** @internal */
 class EmbeddedOptionsBuilder extends PropertyOptionsBuilder {
     constructor(options) {
         super(options);
@@ -356,6 +362,8 @@ class EmbeddedOptionsBuilder extends PropertyOptionsBuilder {
         return new EmbeddedOptionsBuilder({ ...this['~options'], array });
     }
 }
+exports.EmbeddedOptionsBuilder = EmbeddedOptionsBuilder;
+/** @internal */
 class ReferenceOptionsBuilder extends PropertyOptionsBuilder {
     constructor(options) {
         super(options);
@@ -390,6 +398,8 @@ class ReferenceOptionsBuilder extends PropertyOptionsBuilder {
         return new ReferenceOptionsBuilder({ ...this['~options'], primary });
     }
 }
+exports.ReferenceOptionsBuilder = ReferenceOptionsBuilder;
+/** @internal */
 class ManyToManyOptionsBuilder extends ReferenceOptionsBuilder {
     constructor(options) {
         super(options);
@@ -464,6 +474,8 @@ class ManyToManyOptionsBuilder extends ReferenceOptionsBuilder {
         return new ManyToManyOptionsBuilder({ ...this['~options'], updateRule });
     }
 }
+exports.ManyToManyOptionsBuilder = ManyToManyOptionsBuilder;
+/** @internal */
 class ManyToOneOptionsBuilder extends ReferenceOptionsBuilder {
     constructor(options) {
         super(options);
@@ -518,6 +530,8 @@ class ManyToOneOptionsBuilder extends ReferenceOptionsBuilder {
         return new ManyToOneOptionsBuilder({ ...this['~options'], deferMode });
     }
 }
+exports.ManyToOneOptionsBuilder = ManyToOneOptionsBuilder;
+/** @internal */
 class OneToManyOptionsBuilder extends ReferenceOptionsBuilder {
     constructor(options) {
         super(options);
@@ -560,6 +574,8 @@ class OneToManyOptionsBuilder extends ReferenceOptionsBuilder {
         return new OneToManyOptionsBuilder({ ...this['~options'], referencedColumnNames });
     }
 }
+exports.OneToManyOptionsBuilder = OneToManyOptionsBuilder;
+/** @internal */
 class OneToManyOptionsBuilderOnlyMappedBy {
     constructor(options) {
         this['~options'] = options;
@@ -569,6 +585,8 @@ class OneToManyOptionsBuilderOnlyMappedBy {
         return new OneToManyOptionsBuilder({ ...this['~options'], mappedBy });
     }
 }
+exports.OneToManyOptionsBuilderOnlyMappedBy = OneToManyOptionsBuilderOnlyMappedBy;
+/** @internal */
 class OneToOneOptionsBuilder extends ReferenceOptionsBuilder {
     constructor(options) {
         super(options);
@@ -611,6 +629,7 @@ class OneToOneOptionsBuilder extends ReferenceOptionsBuilder {
         return new OneToOneOptionsBuilder({ ...this['~options'], deferMode });
     }
 }
+exports.OneToOneOptionsBuilder = OneToOneOptionsBuilder;
 function createPropertyBuilders(options) {
     return Object.fromEntries(Object.entries(options).map(([key, value]) => [key, () => new PropertyOptionsBuilder({ type: value })]));
 }

package/enums.d.ts

@@ -158,8 +158,18 @@ export declare enum EventType {
 }
 export declare const EventTypeMap: Record<EventType, number>;
 export type TransactionEventType = EventType.beforeTransactionStart | EventType.afterTransactionStart | EventType.beforeTransactionCommit | EventType.afterTransactionCommit | EventType.beforeTransactionRollback | EventType.afterTransactionRollback;
+export declare enum TransactionPropagation {
+    REQUIRED = "required",
+    REQUIRES_NEW = "requires_new",
+    NESTED = "nested",
+    NOT_SUPPORTED = "not_supported",
+    SUPPORTS = "supports",
+    MANDATORY = "mandatory",
+    NEVER = "never"
+}
 export interface TransactionOptions {
     ctx?: Transaction;
+    propagation?: TransactionPropagation;
     isolationLevel?: IsolationLevel;
     readOnly?: boolean;
     clear?: boolean;

package/enums.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeferMode = exports.PlainObject = exports.EventTypeMap = exports.EventType = exports.IsolationLevel = exports.LockMode = exports.DataloaderType = exports.LoadStrategy = exports.Cascade = exports.ReferenceKind = exports.SCALAR_TYPES = exports.QueryFlag = exports.QueryOrderNumeric = exports.QueryOrder = exports.JSON_KEY_OPERATORS = exports.ARRAY_OPERATORS = exports.QueryOperator = exports.GroupOperator = exports.PopulatePath = exports.PopulateHint = exports.FlushMode = void 0;
+exports.DeferMode = exports.PlainObject = exports.TransactionPropagation = exports.EventTypeMap = exports.EventType = exports.IsolationLevel = exports.LockMode = exports.DataloaderType = exports.LoadStrategy = exports.Cascade = exports.ReferenceKind = exports.SCALAR_TYPES = exports.QueryFlag = exports.QueryOrderNumeric = exports.QueryOrder = exports.JSON_KEY_OPERATORS = exports.ARRAY_OPERATORS = exports.QueryOperator = exports.GroupOperator = exports.PopulatePath = exports.PopulateHint = exports.FlushMode = void 0;
 var FlushMode;
 (function (FlushMode) {
     /** The `EntityManager` delays the flush until the current Transaction is committed. */
@@ -180,6 +180,16 @@ exports.EventTypeMap = Object.keys(EventType).reduce((a, b, i) => {
     a[b] = i;
     return a;
 }, {});
+var TransactionPropagation;
+(function (TransactionPropagation) {
+    TransactionPropagation["REQUIRED"] = "required";
+    TransactionPropagation["REQUIRES_NEW"] = "requires_new";
+    TransactionPropagation["NESTED"] = "nested";
+    TransactionPropagation["NOT_SUPPORTED"] = "not_supported";
+    TransactionPropagation["SUPPORTS"] = "supports";
+    TransactionPropagation["MANDATORY"] = "mandatory";
+    TransactionPropagation["NEVER"] = "never";
+})(TransactionPropagation || (exports.TransactionPropagation = TransactionPropagation = {}));
 class PlainObject {
 }
 exports.PlainObject = PlainObject;

package/errors.d.ts

@@ -67,3 +67,8 @@ export declare class NotFoundError<T extends AnyEntity = AnyEntity> extends Vali
     static findOneFailed(name: string, where: Dictionary | IPrimaryKey): NotFoundError;
     static findExactlyOneFailed(name: string, where: Dictionary | IPrimaryKey): NotFoundError;
 }
+export declare class TransactionStateError extends ValidationError {
+    static requiredTransactionNotFound(propagation: string): TransactionStateError;
+    static transactionNotAllowed(propagation: string): TransactionStateError;
+    static invalidPropagation(propagation: string): TransactionStateError;
+}

package/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NotFoundError = exports.MetadataError = exports.OptimisticLockError = exports.CursorError = exports.ValidationError = void 0;
+exports.TransactionStateError = exports.NotFoundError = exports.MetadataError = exports.OptimisticLockError = exports.CursorError = exports.ValidationError = void 0;
 const node_util_1 = require("node:util");
 class ValidationError extends Error {
     entity;
@@ -232,3 +232,15 @@ class NotFoundError extends ValidationError {
     }
 }
 exports.NotFoundError = NotFoundError;
+class TransactionStateError extends ValidationError {
+    static requiredTransactionNotFound(propagation) {
+        return new TransactionStateError(`No existing transaction found for transaction marked with propagation "${propagation}"`);
+    }
+    static transactionNotAllowed(propagation) {
+        return new TransactionStateError(`Existing transaction found for transaction marked with propagation "${propagation}"`);
+    }
+    static invalidPropagation(propagation) {
+        return new TransactionStateError(`Unsupported transaction propagation type: ${propagation}`);
+    }
+}
+exports.TransactionStateError = TransactionStateError;

package/index.mjs

@@ -55,6 +55,7 @@ export const DriverException = mod.DriverException;
 export const EagerProps = mod.EagerProps;
 export const Embeddable = mod.Embeddable;
 export const Embedded = mod.Embedded;
+export const EmbeddedOptionsBuilder = mod.EmbeddedOptionsBuilder;
 export const EnsureRequestContext = mod.EnsureRequestContext;
 export const Entity = mod.Entity;
 export const EntityAssigner = mod.EntityAssigner;
@@ -75,6 +76,7 @@ export const EntityTransformer = mod.EntityTransformer;
 export const EntityValidator = mod.EntityValidator;
 export const Enum = mod.Enum;
 export const EnumArrayType = mod.EnumArrayType;
+export const EnumOptionsBuilder = mod.EnumOptionsBuilder;
 export const EnumType = mod.EnumType;
 export const EventManager = mod.EventManager;
 export const EventType = mod.EventType;
@@ -103,7 +105,9 @@ export const LoadStrategy = mod.LoadStrategy;
 export const LockMode = mod.LockMode;
 export const LockWaitTimeoutException = mod.LockWaitTimeoutException;
 export const ManyToMany = mod.ManyToMany;
+export const ManyToManyOptionsBuilder = mod.ManyToManyOptionsBuilder;
 export const ManyToOne = mod.ManyToOne;
+export const ManyToOneOptionsBuilder = mod.ManyToOneOptionsBuilder;
 export const MediumIntType = mod.MediumIntType;
 export const MemoryCacheAdapter = mod.MemoryCacheAdapter;
 export const MetadataDiscovery = mod.MetadataDiscovery;
@@ -124,7 +128,10 @@ export const ObjectHydrator = mod.ObjectHydrator;
 export const OnInit = mod.OnInit;
 export const OnLoad = mod.OnLoad;
 export const OneToMany = mod.OneToMany;
+export const OneToManyOptionsBuilder = mod.OneToManyOptionsBuilder;
+export const OneToManyOptionsBuilderOnlyMappedBy = mod.OneToManyOptionsBuilderOnlyMappedBy;
 export const OneToOne = mod.OneToOne;
+export const OneToOneOptionsBuilder = mod.OneToOneOptionsBuilder;
 export const OptimisticLockError = mod.OptimisticLockError;
 export const OptionalProps = mod.OptionalProps;
 export const PlainObject = mod.PlainObject;
@@ -134,6 +141,7 @@ export const PopulatePath = mod.PopulatePath;
 export const PrimaryKey = mod.PrimaryKey;
 export const PrimaryKeyProp = mod.PrimaryKeyProp;
 export const Property = mod.Property;
+export const PropertyOptionsBuilder = mod.PropertyOptionsBuilder;
 export const QueryFlag = mod.QueryFlag;
 export const QueryHelper = mod.QueryHelper;
 export const QueryOperator = mod.QueryOperator;
@@ -144,6 +152,7 @@ export const ReadOnlyException = mod.ReadOnlyException;
 export const Ref = mod.Ref;
 export const Reference = mod.Reference;
 export const ReferenceKind = mod.ReferenceKind;
+export const ReferenceOptionsBuilder = mod.ReferenceOptionsBuilder;
 export const ReflectMetadataProvider = mod.ReflectMetadataProvider;
 export const RequestContext = mod.RequestContext;
 export const SCALAR_TYPES = mod.SCALAR_TYPES;
@@ -162,6 +171,9 @@ export const TimeType = mod.TimeType;
 export const TinyIntType = mod.TinyIntType;
 export const TransactionContext = mod.TransactionContext;
 export const TransactionEventBroadcaster = mod.TransactionEventBroadcaster;
+export const TransactionManager = mod.TransactionManager;
+export const TransactionPropagation = mod.TransactionPropagation;
+export const TransactionStateError = mod.TransactionStateError;
 export const Transactional = mod.Transactional;
 export const Type = mod.Type;
 export const Uint8ArrayType = mod.Uint8ArrayType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "6.4.17-dev.94",
+  "version": "6.4.17-dev.96",
   "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.",
   "main": "index.js",
   "module": "index.mjs",
@@ -64,7 +64,7 @@
     "esprima": "4.0.1",
     "fs-extra": "11.3.1",
     "globby": "11.1.0",
-    "mikro-orm": "6.4.17-dev.94",
+    "mikro-orm": "6.4.17-dev.96",
     "reflect-metadata": "0.2.2"
   }
 }

package/utils/TransactionManager.d.ts

@@ -0,0 +1,65 @@
+import type { EntityManager } from '../EntityManager';
+import { type TransactionOptions } from '../enums';
+/**
+ * Manages transaction lifecycle and propagation for EntityManager.
+ */
+export declare class TransactionManager {
+    private readonly em;
+    constructor(em: EntityManager);
+    /**
+     * Main entry point for handling transactional operations with propagation support.
+     */
+    handle<T>(cb: (em: EntityManager) => T | Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Executes the callback with the specified propagation type.
+     */
+    private executeWithPropagation;
+    /**
+     * Suspends the current transaction and returns the suspended resources.
+     */
+    private suspendTransaction;
+    /**
+     * Resumes a previously suspended transaction.
+     */
+    private resumeTransaction;
+    /**
+     * Executes operation without transaction context.
+     */
+    private executeWithoutTransaction;
+    /**
+     * Creates new independent transaction, suspending any existing one.
+     */
+    private executeWithNewTransaction;
+    /**
+     * Creates new transaction context.
+     */
+    private createNewTransaction;
+    /**
+     * Executes nested transaction with savepoint.
+     */
+    private executeNestedTransaction;
+    /**
+     * Creates a fork of the EntityManager with the given options.
+     */
+    private createFork;
+    /**
+     * Determines if changes should be propagated to the upper context.
+     */
+    private shouldPropagateToUpperContext;
+    /**
+     * Merges entities from fork to parent EntityManager.
+     */
+    private mergeEntitiesToParent;
+    /**
+     * Registers a deletion handler to unset entity identities after flush.
+     */
+    private registerDeletionHandler;
+    /**
+     * Processes transaction execution.
+     */
+    private processTransaction;
+    /**
+     * Executes transaction workflow with entity synchronization.
+     */
+    private executeTransactionFlow;
+}

package/utils/TransactionManager.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionManager = void 0;
+const enums_1 = require("../enums");
+const events_1 = require("../events");
+const TransactionContext_1 = require("../utils/TransactionContext");
+const unit_of_work_1 = require("../unit-of-work");
+const errors_1 = require("../errors");
+/**
+ * Manages transaction lifecycle and propagation for EntityManager.
+ */
+class TransactionManager {
+    em;
+    constructor(em) {
+        this.em = em;
+    }
+    /**
+     * Main entry point for handling transactional operations with propagation support.
+     */
+    async handle(cb, options = {}) {
+        const em = this.em.getContext(false);
+        // Set NESTED as the default propagation type
+        options.propagation ??= enums_1.TransactionPropagation.NESTED;
+        // Set the context to the current transaction context if not already set
+        options.ctx ??= em.getTransactionContext();
+        const hasExistingTransaction = !!em.getTransactionContext();
+        return this.executeWithPropagation(options.propagation, em, cb, options, hasExistingTransaction);
+    }
+    /**
+     * Executes the callback with the specified propagation type.
+     */
+    async executeWithPropagation(propagation, em, cb, options, hasExistingTransaction) {
+        switch (propagation) {
+            case enums_1.TransactionPropagation.NOT_SUPPORTED:
+                return this.executeWithoutTransaction(em, cb, options);
+            case enums_1.TransactionPropagation.REQUIRES_NEW:
+                return this.executeWithNewTransaction(em, cb, options, hasExistingTransaction);
+            case enums_1.TransactionPropagation.REQUIRED:
+                if (hasExistingTransaction) {
+                    return cb(em);
+                }
+                return this.createNewTransaction(em, cb, options);
+            case enums_1.TransactionPropagation.NESTED:
+                if (hasExistingTransaction) {
+                    return this.executeNestedTransaction(em, cb, options);
+                }
+                return this.createNewTransaction(em, cb, options);
+            case enums_1.TransactionPropagation.SUPPORTS:
+                if (hasExistingTransaction) {
+                    return cb(em);
+                }
+                return this.executeWithoutTransaction(em, cb, options);
+            case enums_1.TransactionPropagation.MANDATORY:
+                if (!hasExistingTransaction) {
+                    throw errors_1.TransactionStateError.requiredTransactionNotFound(propagation);
+                }
+                return cb(em);
+            case enums_1.TransactionPropagation.NEVER:
+                if (hasExistingTransaction) {
+                    throw errors_1.TransactionStateError.transactionNotAllowed(propagation);
+                }
+                return this.executeWithoutTransaction(em, cb, options);
+            default:
+                throw errors_1.TransactionStateError.invalidPropagation(propagation);
+        }
+    }
+    /**
+     * Suspends the current transaction and returns the suspended resources.
+     */
+    suspendTransaction(em) {
+        const suspended = em.getTransactionContext();
+        em.resetTransactionContext();
+        return suspended;
+    }
+    /**
+     * Resumes a previously suspended transaction.
+     */
+    resumeTransaction(em, suspended) {
+        if (suspended != null) {
+            em.setTransactionContext(suspended);
+        }
+    }
+    /**
+     * Executes operation without transaction context.
+     */
+    async executeWithoutTransaction(em, cb, options) {
+        const suspended = this.suspendTransaction(em);
+        const fork = this.createFork(em, { ...options, disableTransactions: true });
+        const propagateToUpperContext = this.shouldPropagateToUpperContext(em);
+        try {
+            return await this.executeTransactionFlow(fork, cb, propagateToUpperContext, em);
+        }
+        finally {
+            this.resumeTransaction(em, suspended);
+        }
+    }
+    /**
+     * Creates new independent transaction, suspending any existing one.
+     */
+    async executeWithNewTransaction(em, cb, options, hasExistingTransaction) {
+        const fork = this.createFork(em, options);
+        let suspended = null;
+        // Suspend existing transaction if present
+        if (hasExistingTransaction) {
+            suspended = this.suspendTransaction(em);
+        }
+        const newOptions = { ...options, ctx: undefined };
+        try {
+            return await this.processTransaction(em, fork, cb, newOptions);
+        }
+        finally {
+            if (suspended != null) {
+                this.resumeTransaction(em, suspended);
+            }
+        }
+    }
+    /**
+     * Creates new transaction context.
+     */
+    async createNewTransaction(em, cb, options) {
+        const fork = this.createFork(em, options);
+        return this.processTransaction(em, fork, cb, options);
+    }
+    /**
+     * Executes nested transaction with savepoint.
+     */
+    async executeNestedTransaction(em, cb, options) {
+        const fork = this.createFork(em, options);
+        // Pass existing context to create savepoint
+        const nestedOptions = { ...options, ctx: em.getTransactionContext() };
+        return this.processTransaction(em, fork, cb, nestedOptions);
+    }
+    /**
+     * Creates a fork of the EntityManager with the given options.
+     */
+    createFork(em, options) {
+        return em.fork({
+            clear: options.clear ?? false,
+            flushMode: options.flushMode,
+            cloneEventManager: true,
+            disableTransactions: options.ignoreNestedTransactions,
+            loggerContext: options.loggerContext,
+        });
+    }
+    /**
+     * Determines if changes should be propagated to the upper context.
+     */
+    shouldPropagateToUpperContext(em) {
+        return !em.global || this.em.config.get('allowGlobalContext');
+    }
+    /**
+     * Merges entities from fork to parent EntityManager.
+     */
+    mergeEntitiesToParent(fork, parent) {
+        for (const entity of fork.getUnitOfWork(false).getIdentityMap()) {
+            parent.merge(entity, { disableContextResolution: true, keepIdentity: true, refresh: true });
+        }
+    }
+    /**
+     * Registers a deletion handler to unset entity identities after flush.
+     */
+    registerDeletionHandler(fork, parent) {
+        fork.getEventManager().registerSubscriber({
+            afterFlush: (args) => {
+                const deletionChangeSets = args.uow.getChangeSets()
+                    .filter(cs => cs.type === unit_of_work_1.ChangeSetType.DELETE || cs.type === unit_of_work_1.ChangeSetType.DELETE_EARLY);
+                for (const cs of deletionChangeSets) {
+                    parent.getUnitOfWork(false).unsetIdentity(cs.entity);
+                }
+            },
+        });
+    }
+    /**
+     * Processes transaction execution.
+     */
+    async processTransaction(em, fork, cb, options) {
+        const propagateToUpperContext = this.shouldPropagateToUpperContext(em);
+        const eventBroadcaster = new events_1.TransactionEventBroadcaster(fork, undefined, { topLevelTransaction: !options.ctx });
+        return TransactionContext_1.TransactionContext.create(fork, () => fork.getConnection().transactional(async (trx) => {
+            fork.setTransactionContext(trx);
+            return this.executeTransactionFlow(fork, cb, propagateToUpperContext, em);
+        }, { ...options, eventBroadcaster }));
+    }
+    /**
+     * Executes transaction workflow with entity synchronization.
+     */
+    async executeTransactionFlow(fork, cb, propagateToUpperContext, parentEm) {
+        if (!propagateToUpperContext) {
+            const ret = await cb(fork);
+            await fork.flush();
+            return ret;
+        }
+        // Setup: Register deletion handler before execution
+        this.registerDeletionHandler(fork, parentEm);
+        // Execute callback and flush
+        const ret = await cb(fork);
+        await fork.flush();
+        // Synchronization: Merge entities back to the parent
+        this.mergeEntitiesToParent(fork, parentEm);
+        return ret;
+    }
+}
+exports.TransactionManager = TransactionManager;

package/utils/index.d.ts

@@ -5,6 +5,7 @@ export * from './DataloaderUtils';
 export * from './Utils';
 export * from './RequestContext';
 export * from './TransactionContext';
+export * from './TransactionManager';
 export * from './QueryHelper';
 export * from './NullHighlighter';
 export * from './EntityComparator';

package/utils/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./DataloaderUtils"), exports);
 __exportStar(require("./Utils"), exports);
 __exportStar(require("./RequestContext"), exports);
 __exportStar(require("./TransactionContext"), exports);
+__exportStar(require("./TransactionManager"), exports);
 __exportStar(require("./QueryHelper"), exports);
 __exportStar(require("./NullHighlighter"), exports);
 __exportStar(require("./EntityComparator"), exports);