@context-action/core 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,31 +1,23 @@
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function() {
-	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
 //#region src/execution-modes.ts
 /**
+* Create standardized error handling for handlers
+* 
+* @param error - The error that occurred
+* @param registration - The handler registration that failed
+* @returns Standardized HandlerError object
+* 
+* @internal
+*/
+function handleExecutionError(error, registration) {
+	const errorObj = error instanceof Error ? error : new Error(String(error));
+	return {
+		handlerId: registration.id,
+		error: errorObj,
+		timestamp: Date.now(),
+		severity: registration.config.blocking ? "blocking" : "non-blocking"
+	};
+}
+/**
 * Execute handlers in sequential mode (one after another)
 * 
 * Executes action handlers one at a time in priority order (highest first).
@@ -48,6 +40,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 async function executeSequential(context, createController) {
 	let i = 0;
 	const nonBlockingPromises = [];
+	const errors = [];
 	while (i < context.handlers.length) {
 		if (context.aborted || context.terminated) break;
 		const registration = context.handlers[i];
@@ -56,22 +49,24 @@ async function executeSequential(context, createController) {
 		try {
 			if (context.aborted) break;
 			const result = registration.handler(context.payload, controller);
-			/** Wait for async handlers if they're blocking */
-			if (registration.config.blocking && result instanceof Promise) {
-				const handlerResult = await result;
-				/** Collect result if handler returned something and wasn't terminated */
+			if (registration.config.blocking) {
+				const handlerResult = result instanceof Promise ? await result : result;
 				if (handlerResult !== void 0 && !context.terminated) context.results.push(handlerResult);
-			} else if (result !== void 0 && !context.terminated)
- /** Collect synchronous result */
-			if (result instanceof Promise) {
-				const promiseWithHandling = result.then((asyncResult) => {
+			} else if (result instanceof Promise) {
+				const promiseWithErrorHandling = result.then((asyncResult) => {
 					if (asyncResult !== void 0 && !context.terminated) context.results.push(asyncResult);
 					return asyncResult;
 				}).catch((error) => {
-					throw error;
+					const handlerError = handleExecutionError(error, registration);
+					errors.push({
+						handlerId: handlerError.handlerId,
+						error: handlerError.error,
+						timestamp: handlerError.timestamp
+					});
+					return void 0;
 				});
-				nonBlockingPromises.push(promiseWithHandling);
-			} else context.results.push(result);
+				nonBlockingPromises.push(promiseWithErrorHandling);
+			} else if (result !== void 0 && !context.terminated) context.results.push(result);
 			/** Check if pipeline was terminated by controller.return() */
 			if (context.terminated) break;
 			/** Handle jump to priority AFTER handler execution */
@@ -87,11 +82,20 @@ async function executeSequential(context, createController) {
 				}
 			} else i++;
 		} catch (error) {
-			if (registration.config.blocking) throw error;
-			throw error;
+			const handlerError = handleExecutionError(error, registration);
+			throw handlerError.error;
 		}
 	}
-	if (nonBlockingPromises.length > 0) await Promise.all(nonBlockingPromises);
+	if (nonBlockingPromises.length > 0) await Promise.allSettled(nonBlockingPromises);
+	if (errors.length > 0) {
+		const handlerErrors = errors.map((err) => ({
+			handlerId: err.handlerId,
+			error: err.error,
+			timestamp: err.timestamp,
+			severity: "non-blocking"
+		}));
+		context.collectedErrors = handlerErrors;
+	}
 }
 /**
 * Execute handlers in parallel mode (all at once)
@@ -134,11 +138,12 @@ async function executeParallel(context, createController) {
 				terminated: context.terminated
 			};
 		} catch (error) {
-			if (registration.config.blocking) throw error;
+			const handlerError = handleExecutionError(error, registration);
+			if (handlerError.severity === "blocking") throw handlerError.error;
 			return {
 				success: false,
 				handlerId: registration.id,
-				error
+				error: handlerError.error
 			};
 		}
 	});
@@ -206,10 +211,11 @@ async function executeRace(context, createController) {
 				terminated: context.terminated
 			};
 		} catch (error) {
+			const handlerError = handleExecutionError(error, registration);
 			return {
 				success: false,
 				handlerId: registration.id,
-				error,
+				error: handlerError.error,
 				registration
 			};
 		}
@@ -227,67 +233,8 @@ async function executeRace(context, createController) {
 	}
 }
 
-//#endregion
-//#region ../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/typeof.js
-var require_typeof = /* @__PURE__ */ __commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/typeof.js": ((exports, module) => {
-	function _typeof$2(o) {
-		"@babel/helpers - typeof";
-		return module.exports = _typeof$2 = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o$1) {
-			return typeof o$1;
-		} : function(o$1) {
-			return o$1 && "function" == typeof Symbol && o$1.constructor === Symbol && o$1 !== Symbol.prototype ? "symbol" : typeof o$1;
-		}, module.exports.__esModule = true, module.exports["default"] = module.exports, _typeof$2(o);
-	}
-	module.exports = _typeof$2, module.exports.__esModule = true, module.exports["default"] = module.exports;
-}) });
-
-//#endregion
-//#region ../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/toPrimitive.js
-var require_toPrimitive = /* @__PURE__ */ __commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/toPrimitive.js": ((exports, module) => {
-	var _typeof$1 = require_typeof()["default"];
-	function toPrimitive$1(t, r) {
-		if ("object" != _typeof$1(t) || !t) return t;
-		var e = t[Symbol.toPrimitive];
-		if (void 0 !== e) {
-			var i = e.call(t, r || "default");
-			if ("object" != _typeof$1(i)) return i;
-			throw new TypeError("@@toPrimitive must return a primitive value.");
-		}
-		return ("string" === r ? String : Number)(t);
-	}
-	module.exports = toPrimitive$1, module.exports.__esModule = true, module.exports["default"] = module.exports;
-}) });
-
-//#endregion
-//#region ../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/toPropertyKey.js
-var require_toPropertyKey = /* @__PURE__ */ __commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/toPropertyKey.js": ((exports, module) => {
-	var _typeof = require_typeof()["default"];
-	var toPrimitive = require_toPrimitive();
-	function toPropertyKey$1(t) {
-		var i = toPrimitive(t, "string");
-		return "symbol" == _typeof(i) ? i : i + "";
-	}
-	module.exports = toPropertyKey$1, module.exports.__esModule = true, module.exports["default"] = module.exports;
-}) });
-
-//#endregion
-//#region ../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/defineProperty.js
-var require_defineProperty = /* @__PURE__ */ __commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.82.2/node_modules/@oxc-project/runtime/src/helpers/defineProperty.js": ((exports, module) => {
-	var toPropertyKey = require_toPropertyKey();
-	function _defineProperty$3(e, r, t) {
-		return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
-			value: t,
-			enumerable: !0,
-			configurable: !0,
-			writable: !0
-		}) : e[r] = t, e;
-	}
-	module.exports = _defineProperty$3, module.exports.__esModule = true, module.exports["default"] = module.exports;
-}) });
-
 //#endregion
 //#region src/action-guard.ts
-var import_defineProperty$2 = /* @__PURE__ */ __toESM(require_defineProperty(), 1);
 /**
 * Action Guard system for managing action execution timing
 * 
@@ -317,8 +264,31 @@ var import_defineProperty$2 = /* @__PURE__ */ __toESM(require_defineProperty(),
 * @internal
 */
 var ActionGuard = class {
-	constructor() {
-		(0, import_defineProperty$2.default)(this, "guards", /* @__PURE__ */ new Map());
+	constructor(autoCleanup = true) {
+		this.guards = /* @__PURE__ */ new Map();
+		this.maxIdleTime = 6e4;
+		this.cleanupIntervalMs = 3e4;
+		if (autoCleanup) this.startAutoCleanup();
+	}
+	/**
+	* Start automatic cleanup of idle guard states
+	* 
+	* @internal
+	*/
+	startAutoCleanup() {
+		this.cleanupInterval = setInterval(() => {
+			const now = Date.now();
+			const keysToDelete = [];
+			this.guards.forEach((state, key) => {
+				const isIdle = now - state.lastExecuted > this.maxIdleTime;
+				const hasActiveTimers = state.debounceTimer || state.throttleTimer;
+				if (isIdle && !hasActiveTimers) keysToDelete.push(key);
+			});
+			if (keysToDelete.length > 0) {
+				keysToDelete.forEach((key) => this.guards.delete(key));
+				if (typeof process !== "undefined" && process.env?.DEBUG_CONTEXT_ACTION) console.debug(`[ActionGuard] Cleaned up ${keysToDelete.length} idle guards`);
+			}
+		}, this.cleanupIntervalMs);
 	}
 	/**
 	* Apply debouncing to an action
@@ -448,10 +418,17 @@ var ActionGuard = class {
 			/** Clear debounce timer if active to prevent memory leaks */
 			if (state.debounceTimer) {
 				clearTimeout(state.debounceTimer);
-				if (state.debounceResolve) state.debounceResolve(false);
+				if (state.debounceResolve) {
+					state.debounceResolve(false);
+					state.debounceResolve = void 0;
+				}
+				state.debounceTimer = void 0;
 			}
 			/** Clear throttle timer if active to prevent memory leaks */
-			if (state.throttleTimer) clearTimeout(state.throttleTimer);
+			if (state.throttleTimer) {
+				clearTimeout(state.throttleTimer);
+				state.throttleTimer = void 0;
+			}
 			/** Remove guard state from memory */
 			this.guards.delete(actionKey);
 		}
@@ -506,11 +483,42 @@ var ActionGuard = class {
 	getAllGuardStates() {
 		return new Map(this.guards);
 	}
+	/**
+	* 🆕 Explicit destroy method for comprehensive cleanup
+	* 
+	* Cleans up all timers, promises, and intervals to prevent memory leaks.
+	* Should be called when ActionGuard is no longer needed.
+	* 
+	* @internal
+	*/
+	destroy() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = void 0;
+		}
+		this.clearAll();
+	}
+	/**
+	* 🆕 Get statistics about active guards
+	* 
+	* @returns Statistics about guard usage
+	* 
+	* @internal
+	*/
+	getStats() {
+		let withTimers = 0;
+		this.guards.forEach((state) => {
+			if (state.debounceTimer || state.throttleTimer) withTimers++;
+		});
+		return {
+			activeGuards: this.guards.size,
+			withTimers
+		};
+	}
 };
 
 //#endregion
 //#region src/concurrency/OperationQueue.ts
-var import_defineProperty$1 = /* @__PURE__ */ __toESM(require_defineProperty(), 1);
 /**
 * 작업 큐 관리자
 * 
@@ -519,13 +527,17 @@ var import_defineProperty$1 = /* @__PURE__ */ __toESM(require_defineProperty(),
 * 2. 우선순위 지원 - 중요한 작업 우선 처리
 * 3. 에러 처리 - 개별 작업 실패가 전체에 영향 주지 않음
 * 4. 메모리 관리 - 완료된 작업 자동 정리
+* 5. 🆕 동시성 제어 - maxConcurrency로 동시 실행 제한
 */
 var OperationQueue = class {
-	constructor(name = "OperationQueue") {
+	constructor(name = "OperationQueue", maxConcurrency = 1) {
 		this.name = name;
-		(0, import_defineProperty$1.default)(this, "queue", []);
-		(0, import_defineProperty$1.default)(this, "isProcessing", false);
-		(0, import_defineProperty$1.default)(this, "operationCounter", 0);
+		this.queue = [];
+		this.processingPromise = null;
+		this.operationCounter = 0;
+		this.activeOperations = 0;
+		this.runningOperations = /* @__PURE__ */ new Set();
+		this.maxConcurrency = Math.max(1, maxConcurrency);
 	}
 	/**
 	* 작업을 큐에 추가하고 실행 결과를 반환
@@ -554,35 +566,56 @@ var OperationQueue = class {
 		});
 	}
 	/**
-	* 큐 처리 메인 로직
+	* 🆕 큐 처리 메인 로직 - 동시성 제어 지원
 	* 
-	* 한 번에 하나씩 순서대로 작업을 실행하여 동시성 문제 방지
+	* maxConcurrency에 따라 동시 실행 작업 수를 제한하여 동시성 문제 방지
 	*/
 	async processQueue() {
-		if (this.isProcessing || this.queue.length === 0) return;
-		this.isProcessing = true;
+		if (this.processingPromise) return this.processingPromise;
+		this.processingPromise = this._doProcess();
 		try {
-			while (this.queue.length > 0) {
+			await this.processingPromise;
+		} finally {
+			this.processingPromise = null;
+		}
+	}
+	async _doProcess() {
+		while (this.queue.length > 0 || this.runningOperations.size > 0) {
+			while (this.queue.length > 0 && this.activeOperations < this.maxConcurrency) {
 				const operation = this.queue.shift();
-				try {
-					const result = await Promise.resolve(operation.operation());
-					operation.resolve(result);
-				} catch (error) {
-					operation.reject(error);
-				}
+				this.activeOperations++;
+				const operationPromise = this.executeOperation(operation);
+				this.runningOperations.add(operationPromise);
+				operationPromise.finally(() => {
+					this.activeOperations--;
+					this.runningOperations.delete(operationPromise);
+				});
 			}
-		} finally {
-			this.isProcessing = false;
+			if (this.runningOperations.size > 0) await Promise.race(this.runningOperations);
 		}
 	}
 	/**
-	* 현재 큐 상태 조회 (디버깅용)
+	* 🆕 개별 작업 실행 로직
+	*/
+	async executeOperation(operation) {
+		try {
+			const result = await Promise.resolve(operation.operation());
+			operation.resolve(result);
+		} catch (error) {
+			operation.reject(error);
+		}
+	}
+	/**
+	* 🆕 현재 큐 상태 조회 (디버깅용) - 동시성 정보 포함
 	*/
 	getQueueInfo() {
 		return {
 			name: this.name,
 			queueLength: this.queue.length,
-			isProcessing: this.isProcessing,
+			isProcessing: Boolean(this.processingPromise),
+			activeOperations: this.activeOperations,
+			maxConcurrency: this.maxConcurrency,
+			runningOperationsCount: this.runningOperations.size,
 			operations: this.queue.map((op) => ({
 				id: op.id,
 				priority: op.priority,
@@ -591,6 +624,18 @@ var OperationQueue = class {
 		};
 	}
 	/**
+	* 🆕 동시성 설정 조회
+	*/
+	getConcurrencyInfo() {
+		return {
+			maxConcurrency: this.maxConcurrency,
+			activeOperations: this.activeOperations,
+			availableSlots: this.maxConcurrency - this.activeOperations,
+			queuedOperations: this.queue.length,
+			efficiency: this.activeOperations / this.maxConcurrency
+		};
+	}
+	/**
 	* 큐 비우기 (테스트용)
 	*/
 	clear() {
@@ -598,7 +643,7 @@ var OperationQueue = class {
 			operation.reject(/* @__PURE__ */ new Error("Queue cleared"));
 		});
 		this.queue = [];
-		this.isProcessing = false;
+		this.processingPromise = null;
 	}
 	/**
 	* 큐 크기 조회
@@ -610,13 +655,12 @@ var OperationQueue = class {
 	* 처리 중 여부 조회  
 	*/
 	get processing() {
-		return this.isProcessing;
+		return Boolean(this.processingPromise);
 	}
 };
 
 //#endregion
 //#region src/ActionRegister.ts
-var import_defineProperty = /* @__PURE__ */ __toESM(require_defineProperty(), 1);
 /**
 * Action Register for managing action handlers with priority-based execution
 * 
@@ -634,27 +678,23 @@ var import_defineProperty = /* @__PURE__ */ __toESM(require_defineProperty(), 1)
 */
 var ActionRegister = class {
 	constructor(config = {}) {
-		(0, import_defineProperty.default)(this, "pipelines", /* @__PURE__ */ new Map());
-		(0, import_defineProperty.default)(this, "handlerCounter", 0);
-		(0, import_defineProperty.default)(this, "actionGuard", void 0);
-		(0, import_defineProperty.default)(this, "executionMode", "sequential");
-		(0, import_defineProperty.default)(this, "actionExecutionModes", /* @__PURE__ */ new Map());
-		(0, import_defineProperty.default)(this, "name", void 0);
-		(0, import_defineProperty.default)(this, "registryConfig", void 0);
-		(0, import_defineProperty.default)(this, "executionStats", /* @__PURE__ */ new Map());
-		(0, import_defineProperty.default)(this, "registrationQueue", void 0);
-		(0, import_defineProperty.default)(this, "dispatchQueue", void 0);
+		this.pipelines = /* @__PURE__ */ new Map();
+		this.executionMode = "sequential";
+		this.actionExecutionModes = /* @__PURE__ */ new Map();
+		this.filterCache = /* @__PURE__ */ new Map();
+		this.filterCacheMaxSize = 100;
 		this.name = config.name || "ActionRegister";
 		this.registryConfig = config.registry;
-		this.actionGuard = new ActionGuard();
-		this.registrationQueue = new OperationQueue(`${this.name}-Registration`);
-		this.dispatchQueue = new OperationQueue(`${this.name}-Dispatch`);
+		this.maxHandlersPerAction = config.registry?.maxHandlersPerAction ?? 1e3;
+		this.isDebugMode = Boolean(this.registryConfig?.debug && process.env.NODE_ENV === "development");
+		this.actionGuard = new ActionGuard(this.registryConfig?.autoCleanup !== false);
+		if (config.registry?.useConcurrencyQueue !== false) this.dispatchQueue = new OperationQueue(`${this.name}-Dispatch`);
 		if (this.registryConfig?.defaultExecutionMode) this.executionMode = this.registryConfig.defaultExecutionMode;
-		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 ActionRegister created: ${this.name}`, {
+		this.log("ActionRegister initialized", {
 			defaultExecutionMode: this.executionMode,
-			maxHandlers: this.registryConfig.maxHandlers,
-			autoCleanup: this.registryConfig.autoCleanup ?? true,
-			concurrencyProtection: true
+			autoCleanup: this.registryConfig?.autoCleanup !== false,
+			concurrencyQueue: Boolean(this.dispatchQueue),
+			debugMode: this.isDebugMode
 		});
 	}
 	/**
@@ -673,12 +713,82 @@ var ActionRegister = class {
 	* @public
 	*/
 	register(action, handler, config = {}) {
-		const handlerId = config.id || `handler_${++this.handlerCounter}_${Math.random().toString(36).substr(2, 5)}`;
+		const handlerId = config.id || this.generateHandlerId(action);
 		const unregisterFn = this._performRegistrationSync(action, handler, config, handlerId);
 		return unregisterFn;
 	}
 	/**
-	* 🆕 동기적 등록 수행 (개선된 버전)
+	* 🆕 Unified logging method with cached debug mode check
+	*/
+	log(message, data, level = "log") {
+		if (this.isDebugMode) {
+			const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+			console[level](`🎯 [${timestamp}] [${this.name}] ${message}`, data || "");
+		}
+	}
+	/**
+	* 🆕 Generate unique handler ID using crypto
+	*/
+	generateHandlerId(action) {
+		const uuid = crypto.randomUUID();
+		return `${String(action)}_${uuid.slice(0, 8)}`;
+	}
+	/**
+	* 🔧 Create and merge AbortSignal instances with proper cleanup
+	* 
+	* @param options Dispatch options containing signal and autoAbort configuration
+	* @returns [effectiveSignal, autoAbortController, cleanupFunction]
+	*/
+	createAbortSignal(options) {
+		const signals = [];
+		const cleanups = [];
+		let autoAbortController;
+		if (options?.signal) signals.push(options.signal);
+		if (options?.autoAbort?.enabled) {
+			autoAbortController = new AbortController();
+			signals.push(autoAbortController.signal);
+		}
+		if (signals.length === 0) return [
+			void 0,
+			autoAbortController,
+			() => {}
+		];
+		if (signals.length === 1) return [
+			signals[0],
+			autoAbortController,
+			() => cleanups.forEach((c) => c())
+		];
+		let effectiveSignal;
+		if (typeof AbortSignal.any === "function") effectiveSignal = AbortSignal.any(signals);
+		else {
+			const mergedController = new AbortController();
+			effectiveSignal = mergedController.signal;
+			signals.forEach((signal) => {
+				if (signal.aborted) mergedController.abort();
+				else {
+					const abortHandler = () => mergedController.abort();
+					signal.addEventListener("abort", abortHandler, { once: true });
+					cleanups.push(() => signal.removeEventListener("abort", abortHandler));
+				}
+			});
+		}
+		const cleanup = () => {
+			cleanups.forEach((c) => {
+				try {
+					c();
+				} catch (error) {
+					this.log("Cleanup error during AbortSignal cleanup", error, "warn");
+				}
+			});
+		};
+		return [
+			effectiveSignal,
+			autoAbortController,
+			cleanup
+		];
+	}
+	/**
+	* 🆕 Perform synchronous handler registration
 	*/
 	_performRegistrationSync(action, handler, config, handlerId) {
 		const registration = {
@@ -689,31 +799,74 @@ var ActionRegister = class {
 				blocking: config.blocking ?? false,
 				once: config.once ?? false,
 				debounce: config.debounce ?? void 0,
-				throttle: config.throttle ?? void 0
+				throttle: config.throttle ?? void 0,
+				replaceExisting: config.replaceExisting ?? false
 			},
 			id: handlerId
 		};
 		if (!this.pipelines.has(action)) this.pipelines.set(action, []);
 		const pipeline = this.pipelines.get(action);
+		if (pipeline.length >= this.maxHandlersPerAction) {
+			console.warn(`Handler limit (${this.maxHandlersPerAction}) reached for action "${String(action)}". Registration ignored.`);
+			return () => {};
+		}
 		const existingIndex = pipeline.findIndex((reg) => reg.id === handlerId);
-		if (existingIndex !== -1) return () => {};
-		if (this.registryConfig?.maxHandlers && pipeline.length >= this.registryConfig.maxHandlers) throw new Error(`Maximum number of handlers (${this.registryConfig.maxHandlers}) reached for action '${String(action)}' in registry '${this.name}'`);
+		if (existingIndex !== -1) if (config.replaceExisting) {
+			const oldRegistration = pipeline[existingIndex];
+			if (oldRegistration && typeof oldRegistration.cleanup === "function") try {
+				oldRegistration.cleanup();
+			} catch (cleanupError) {
+				this.log(`Cleanup error for replaced handler: ${String(action)}`, cleanupError, "warn");
+			}
+			pipeline[existingIndex] = registration;
+			pipeline.sort((a, b) => b.config.priority - a.config.priority);
+			this.invalidateFilterCache();
+			this.log(`Handler replaced: ${String(action)}`, {
+				handlerId,
+				priority: config.priority,
+				totalHandlers: pipeline.length,
+				oldHandlerCleaned: Boolean(oldRegistration.cleanup)
+			});
+			return () => {
+				const index = pipeline.findIndex((reg) => reg.id === handlerId && reg === registration);
+				if (index !== -1) {
+					pipeline.splice(index, 1);
+					this.invalidateFilterCache();
+					this.log(`Replaced handler unregistered: ${String(action)}`, { handlerId });
+				}
+			};
+		} else {
+			this.log(`Handler duplicate ignored: ${String(action)}`, {
+				handlerId,
+				note: "Use replaceExisting:true to replace"
+			}, "warn");
+			return () => {};
+		}
 		pipeline.push(registration);
 		pipeline.sort((a, b) => b.config.priority - a.config.priority);
-		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Handler registered: ${String(action)}`, {
+		this.invalidateFilterCache();
+		this.log(`Handler registered: ${String(action)}`, {
 			handlerId,
 			priority: config.priority,
+			totalHandlers: pipeline.length
+		});
+		console.log(`🔍 [DEBUG] Action '${String(action)}' pipeline after registration:`, {
 			totalHandlers: pipeline.length,
-			registry: this.name
+			handlers: pipeline.map((h) => ({
+				id: h.config.id,
+				priority: h.config.priority
+			})),
+			pipelineExists: this.pipelines.has(action),
+			canDispatch: this.hasHandlers(action)
 		});
 		return () => {
 			const index = pipeline.findIndex((reg) => reg.id === handlerId && reg === registration);
 			if (index !== -1) {
 				pipeline.splice(index, 1);
-				if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Handler unregistered: ${String(action)}`, {
+				this.invalidateFilterCache();
+				this.log(`Handler unregistered: ${String(action)}`, {
 					handlerId,
-					remainingHandlers: pipeline.length,
-					registry: this.name
+					remainingHandlers: pipeline.length
 				});
 			}
 		};
@@ -734,7 +887,8 @@ var ActionRegister = class {
 	* @public
 	*/
 	async dispatch(action, payload, options) {
-		return this.dispatchQueue.enqueue(async () => {
+		if (options?.immediate || !this.dispatchQueue) return this._performDispatch(action, payload, options);
+		else return this.dispatchQueue.enqueue(async () => {
 			return this._performDispatch(action, payload, options);
 		});
 	}
@@ -742,47 +896,31 @@ var ActionRegister = class {
 	* 🆕 실제 디스패치 작업 수행 (큐에서 호출됨)
 	*/
 	async _performDispatch(action, payload, options) {
-		if (payload && typeof payload === "object" && payload !== null && typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
-			payload instanceof Event;
-			payload instanceof Element;
-			payload.preventDefault;
-			payload.stopPropagation;
-			payload.currentTarget;
-			const hasTarget = payload.target !== void 0;
-			hasTarget && payload.target;
-			hasTarget && payload.target instanceof Element;
-			if (typeof process !== "undefined" && process.env?.DEBUG_CONTEXT_ACTION || typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
-				const nestedDOMProperties = [];
-				Object.keys(payload).forEach((key) => {
-					const prop = payload[key];
-					if (prop instanceof Element || prop instanceof Event) nestedDOMProperties.push(`${key}: ${prop instanceof Element ? "Element" : "Event"}`);
-				});
-				if (nestedDOMProperties.length > 0) console.debug(`[Context-Action] 📋 Nested DOM objects in action "${String(action)}":`, {
-					registry: this.name,
-					nestedDOMProperties,
-					note: "This is informational - usually not a problem"
-				});
-			}
-		}
-		let autoAbortController;
-		let effectiveSignal = options?.signal;
-		if (options?.autoAbort?.enabled) {
-			autoAbortController = new AbortController();
-			effectiveSignal = autoAbortController.signal;
-			if (options.autoAbort.onControllerCreated) options.autoAbort.onControllerCreated(autoAbortController);
-			if (options?.signal) {
-				const originalSignal = options.signal;
-				if (originalSignal.aborted) autoAbortController.abort();
-				else {
-					const abortHandler$1 = () => autoAbortController.abort();
-					originalSignal.addEventListener("abort", abortHandler$1, { once: true });
-				}
-			}
+		console.log(`🚀 [DEBUG] Starting dispatch for action '${String(action)}':`, {
+			hasPayload: payload !== void 0,
+			payloadType: payload?.constructor?.name || typeof payload,
+			options: options ? Object.keys(options) : "none",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		if (payload instanceof Event && process.env.NODE_ENV === "development") console.warn(`Event object passed to action "${String(action)}"`, payload.type);
+		const [effectiveSignal, autoAbortController, cleanup] = this.createAbortSignal(options);
+		if (options?.autoAbort?.onControllerCreated && autoAbortController) options.autoAbort.onControllerCreated(autoAbortController);
+		if (effectiveSignal?.aborted) {
+			console.log(`🚫 [DEBUG] Dispatch aborted before execution for '${String(action)}'`);
+			return;
 		}
-		if (effectiveSignal?.aborted) return;
 		const pipeline = this.pipelines.get(action);
-		if (!pipeline || pipeline.length === 0) return;
-		const filteredHandlers = this.filterHandlers([...pipeline], options?.filter);
+		console.log(`🔍 [DEBUG] Pipeline lookup for '${String(action)}':`, {
+			pipelineExists: Boolean(pipeline),
+			handlersCount: pipeline?.length || 0,
+			allRegisteredActions: Array.from(this.pipelines.keys()),
+			pipelineMap: Object.fromEntries(Array.from(this.pipelines.entries()).map(([k, v]) => [k, v.length]))
+		});
+		if (!pipeline || pipeline.length === 0) {
+			console.log(`⚠️ [DEBUG] No handlers found for action '${String(action)}', dispatch cancelled`);
+			return;
+		}
+		const filteredHandlers = options?.filter ? this.filterHandlers(pipeline, options.filter) : pipeline;
 		const actionKey = String(action);
 		let throttleMs;
 		let debounceMs;
@@ -822,8 +960,6 @@ var ActionRegister = class {
 			terminated: false,
 			terminationResult: void 0
 		};
-		const startTime = Date.now();
-		let executionSuccess = true;
 		const abortHandler = effectiveSignal ? () => {
 			context.aborted = true;
 			context.abortReason = "Action dispatch aborted by signal";
@@ -831,15 +967,12 @@ var ActionRegister = class {
 		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler);
 		try {
 			await this.executePipeline(context, autoAbortController, options?.autoAbort);
-			console.log(`[ActionRegister] Pipeline execution succeeded for ${String(action)}`);
+			this.log(`Pipeline execution succeeded for ${String(action)}`);
 		} catch (error) {
-			console.log(`[ActionRegister] Pipeline execution failed for ${String(action)}:`, error);
-			executionSuccess = false;
+			this.log(`Pipeline execution failed for ${String(action)}`, error, "error");
 			throw error;
 		} finally {
-			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
-			const duration = Date.now() - startTime;
-			this.updateExecutionStats(action, executionSuccess, duration);
+			cleanup();
 		}
 	}
 	/**
@@ -856,36 +989,25 @@ var ActionRegister = class {
 	* @public
 	*/
 	async dispatchWithResult(action, payload, options) {
-		const startTime = Date.now();
-		let autoAbortController;
-		let effectiveSignal = options?.signal;
-		if (options?.autoAbort?.enabled) {
-			autoAbortController = new AbortController();
-			effectiveSignal = autoAbortController.signal;
-			if (options.autoAbort.onControllerCreated) options.autoAbort.onControllerCreated(autoAbortController);
-			if (options?.signal) {
-				const originalSignal = options.signal;
-				if (originalSignal.aborted) autoAbortController.abort();
-				else {
-					const abortHandler$1 = () => autoAbortController.abort();
-					originalSignal.addEventListener("abort", abortHandler$1, { once: true });
-				}
-			}
-		}
+		const _startTime = Date.now();
+		const [effectiveSignal, autoAbortController, cleanup] = this.createAbortSignal(options);
+		if (options?.autoAbort?.onControllerCreated && autoAbortController) options.autoAbort.onControllerCreated(autoAbortController);
 		if (effectiveSignal?.aborted) return {
 			success: false,
 			aborted: true,
 			abortReason: "Action dispatch aborted by signal",
 			terminated: false,
 			result: void 0,
+			successResults: [],
 			results: [],
+			failedResults: [],
 			execution: {
 				duration: 0,
 				handlersExecuted: 0,
 				handlersSkipped: 0,
 				handlersFailed: 0,
-				startTime,
-				endTime: startTime
+				startTime: _startTime,
+				endTime: _startTime
 			},
 			handlers: [],
 			errors: []
@@ -896,19 +1018,21 @@ var ActionRegister = class {
 			aborted: false,
 			terminated: false,
 			result: void 0,
+			successResults: [],
 			results: [],
+			failedResults: [],
 			execution: {
 				duration: 0,
 				handlersExecuted: 0,
 				handlersSkipped: 0,
 				handlersFailed: 0,
-				startTime,
-				endTime: startTime
+				startTime: _startTime,
+				endTime: _startTime
 			},
 			handlers: [],
 			errors: []
 		};
-		const filteredHandlers = this.filterHandlers([...pipeline], options?.filter);
+		const filteredHandlers = options?.filter ? this.filterHandlers(pipeline, options.filter) : pipeline;
 		const actionKey = String(action);
 		let throttleMs;
 		let debounceMs;
@@ -934,13 +1058,15 @@ var ActionRegister = class {
 				abortReason: "Debounced execution",
 				terminated: false,
 				result: void 0,
+				successResults: [],
 				results: [],
+				failedResults: [],
 				execution: {
-					duration: Date.now() - startTime,
+					duration: Date.now() - _startTime,
 					handlersExecuted: 0,
 					handlersSkipped: pipeline.length,
 					handlersFailed: 0,
-					startTime,
+					startTime: _startTime,
 					endTime: Date.now()
 				},
 				handlers: [],
@@ -955,13 +1081,15 @@ var ActionRegister = class {
 				abortReason: "Throttled execution",
 				terminated: false,
 				result: void 0,
+				successResults: [],
 				results: [],
+				failedResults: [],
 				execution: {
-					duration: Date.now() - startTime,
+					duration: Date.now() - _startTime,
 					handlersExecuted: 0,
 					handlersSkipped: pipeline.length,
 					handlersFailed: 0,
-					startTime,
+					startTime: _startTime,
 					endTime: Date.now()
 				},
 				handlers: [],
@@ -985,6 +1113,12 @@ var ActionRegister = class {
 		let executionError;
 		const handlerResults = [];
 		const errors = [];
+		filteredHandlers.forEach((handler) => {
+			handlerResults.push({
+				id: handler.config.id,
+				executed: false
+			});
+		});
 		const abortHandler = effectiveSignal ? () => {
 			context.aborted = true;
 			context.abortReason = "Action dispatch aborted by signal";
@@ -992,6 +1126,11 @@ var ActionRegister = class {
 		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler);
 		try {
 			await this.executePipeline(context, autoAbortController, options?.autoAbort);
+			const executedCount = Math.min(context.currentIndex + (context.aborted ? 0 : 1), filteredHandlers.length);
+			for (let i = 0; i < executedCount; i++) {
+				const handlerResult = handlerResults.find((hr) => hr.id === filteredHandlers[i].config.id);
+				if (handlerResult) handlerResult.executed = true;
+			}
 		} catch (error) {
 			executionError = error instanceof Error ? error : new Error(String(error));
 			errors.push({
@@ -999,48 +1138,97 @@ var ActionRegister = class {
 				error: executionError,
 				timestamp: Date.now()
 			});
+			const executedCount = Math.min(context.currentIndex + 1, filteredHandlers.length);
+			for (let i = 0; i < executedCount; i++) {
+				const handlerResult = handlerResults.find((hr) => hr.id === filteredHandlers[i].config.id);
+				if (handlerResult) handlerResult.executed = true;
+			}
 		} finally {
-			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
+			cleanup();
 		}
 		const endTime = Date.now();
-		const executionSuccess = !executionError && !context.aborted;
-		this.updateExecutionStats(action, executionSuccess, endTime - startTime);
 		const processedResult = this.processResults(context, options?.result);
+		const successResults = context.results.filter((result) => result !== void 0);
+		const failedResults = errors.map((err) => ({
+			handlerId: err.handlerId,
+			error: err.error,
+			expectedType: typeof processedResult
+		}));
 		const executionResult = {
 			success: !executionError && !context.aborted,
 			aborted: context.aborted,
 			abortReason: context.abortReason,
 			terminated: context.terminated,
 			result: processedResult,
+			successResults,
 			results: context.results,
+			failedResults,
 			execution: {
-				duration: endTime - startTime,
+				duration: endTime - _startTime,
 				handlersExecuted: context.currentIndex + (context.aborted ? 0 : 1),
 				handlersSkipped: Math.max(0, filteredHandlers.length - (context.currentIndex + 1)),
 				handlersFailed: errors.length,
-				startTime,
+				startTime: _startTime,
 				endTime
 			},
 			handlers: handlerResults,
-			errors
+			errors: errors.map((err) => ({
+				handlerId: err.handlerId,
+				error: err.error,
+				timestamp: err.timestamp,
+				severity: "non-blocking"
+			}))
 		};
 		/** Clean up one-time handlers after execution */
 		this.cleanupOneTimeHandlers(action, context.handlers);
 		return executionResult;
 	}
+	/**
+	* 🔧 Generate cache key for filter options
+	*/
+	generateFilterCacheKey(filterOptions) {
+		if (!filterOptions) return "no-filter";
+		const key = [
+			filterOptions.handlerIds?.sort().join(",") || "none",
+			filterOptions.excludeHandlerIds?.sort().join(",") || "none",
+			filterOptions.priority?.min?.toString() || "none",
+			filterOptions.priority?.max?.toString() || "none",
+			filterOptions.custom ? "custom" : "none"
+		].join("|");
+		return key;
+	}
+	/**
+	* 🔧 Clear filter cache when pipelines change
+	*/
+	invalidateFilterCache() {
+		this.filterCache.clear();
+	}
 	filterHandlers(handlers, filterOptions) {
 		if (!filterOptions) return handlers;
-		return handlers.filter((registration) => {
+		const cacheKey = this.generateFilterCacheKey(filterOptions);
+		if (!filterOptions.custom) {
+			const cached = this.filterCache.get(cacheKey);
+			if (cached) return cached;
+		}
+		const filtered = handlers.filter((registration) => {
 			const config = registration.config;
-			if (filterOptions.handlerIds && filterOptions.handlerIds.length > 0) {
-				if (!filterOptions.handlerIds.includes(config.id)) return false;
-			}
-			if (filterOptions.excludeHandlerIds && filterOptions.excludeHandlerIds.length > 0) {
-				if (filterOptions.excludeHandlerIds.includes(config.id)) return false;
+			if (filterOptions.handlerIds?.length && !filterOptions.handlerIds.includes(config.id)) return false;
+			if (filterOptions.excludeHandlerIds?.length && filterOptions.excludeHandlerIds.includes(config.id)) return false;
+			if (filterOptions.priority) {
+				if (filterOptions.priority.min !== void 0 && config.priority < filterOptions.priority.min) return false;
+				if (filterOptions.priority.max !== void 0 && config.priority > filterOptions.priority.max) return false;
 			}
 			if (filterOptions.custom && !filterOptions.custom(config)) return false;
 			return true;
 		});
+		if (!filterOptions.custom) {
+			if (this.filterCache.size >= this.filterCacheMaxSize) {
+				const firstKey = this.filterCache.keys().next().value;
+				if (firstKey) this.filterCache.delete(firstKey);
+			}
+			this.filterCache.set(cacheKey, filtered);
+		}
+		return filtered;
 	}
 	processResults(context, resultOptions) {
 		if (!resultOptions || !resultOptions.collect) return void 0;
@@ -1126,26 +1314,6 @@ var ActionRegister = class {
 		});
 	}
 	/**
-	* Update execution statistics for an action
-	* 
-	* @param action Action name
-	* @param success Whether execution was successful
-	* @param duration Execution duration in milliseconds
-	*/
-	updateExecutionStats(action, success, duration) {
-		if (!this.executionStats.has(action)) this.executionStats.set(action, {
-			totalExecutions: 0,
-			totalDuration: 0,
-			successCount: 0,
-			errorCount: 0
-		});
-		const stats = this.executionStats.get(action);
-		stats.totalExecutions++;
-		stats.totalDuration += duration;
-		if (success) stats.successCount++;
-		else stats.errorCount++;
-	}
-	/**
 	* Get the number of registered handlers for an action
 	* 
 	* @param action - The action type to count handlers for
@@ -1197,6 +1365,7 @@ var ActionRegister = class {
 	*/
 	clearAction(action) {
 		this.pipelines.delete(action);
+		this.invalidateFilterCache();
 	}
 	/**
 	* Remove all handlers for all actions
@@ -1207,6 +1376,7 @@ var ActionRegister = class {
 	*/
 	clearAll() {
 		this.pipelines.clear();
+		this.invalidateFilterCache();
 	}
 	/**
 	* Get the name of this action register
@@ -1254,13 +1424,7 @@ var ActionRegister = class {
 			priority,
 			handlers: handlers.map((h) => ({ id: h.config.id }))
 		}));
-		const stats = this.executionStats.get(action);
-		const executionStats = stats ? {
-			totalExecutions: stats.totalExecutions,
-			averageDuration: stats.totalExecutions > 0 ? stats.totalDuration / stats.totalExecutions : 0,
-			successRate: stats.totalExecutions > 0 ? stats.successCount / stats.totalExecutions * 100 : 0,
-			errorCount: stats.errorCount
-		} : void 0;
+		const executionStats = void 0;
 		return {
 			action,
 			handlerCount: pipeline.length,
@@ -1306,22 +1470,6 @@ var ActionRegister = class {
 		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Execution mode reset for action '${String(action)}' to default: ${this.executionMode}`);
 	}
 	/**
-	* Clear execution statistics for all actions
-	*/
-	clearExecutionStats() {
-		this.executionStats.clear();
-		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Execution statistics cleared for registry: ${this.name}`);
-	}
-	/**
-	* Clear execution statistics for a specific action
-	* 
-	* @param action Action name
-	*/
-	clearActionExecutionStats(action) {
-		this.executionStats.delete(action);
-		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Execution statistics cleared for action: ${String(action)}`);
-	}
-	/**
 	* Get registry configuration (for debugging and inspection)
 	* 
 	* @returns Current registry configuration
@@ -1335,10 +1483,283 @@ var ActionRegister = class {
 	* @returns Whether debug mode is enabled
 	*/
 	isDebugEnabled() {
-		return Boolean(this.registryConfig?.debug && process.env.NODE_ENV === "development");
+		return this.isDebugMode;
+	}
+	/**
+	* 🆕 Destroy method for comprehensive cleanup
+	* 
+	* Cleans up all internal resources including pipelines, guards, queues, and statistics.
+	* Should be called when the ActionRegister is no longer needed to prevent memory leaks.
+	* 
+	* @public
+	*/
+	destroy() {
+		this.pipelines.clear();
+		this.actionGuard.destroy();
+		this.dispatchQueue?.clear?.();
+		this.actionExecutionModes.clear();
+		this.filterCache.clear();
+		this.log("ActionRegister destroyed");
+	}
+};
+
+//#endregion
+//#region src/react-helpers.ts
+/**
+* 🔧 Create action handler registration configuration for React components
+* 
+* Creates a configuration object that can be used with React's useEffect to properly
+* register and unregister action handlers with lifecycle management and cleanup.
+* This is NOT a hook - it's a factory function for React hook integration.
+* 
+* @template T - ActionPayloadMap type
+* @template K - Action key type
+* 
+* @param registry - ActionRegister instance
+* @param action - Action name to register handler for
+* @param handler - Handler function (should be memoized with useCallback)
+* @param config - Handler configuration
+* 
+* @returns Configuration object with register/unregister functions
+* 
+* @example Basic Usage with useEffect
+* ```tsx
+* import { useCallback, useEffect } from 'react';
+* import { createActionHandler } from '@context-action/core/react-helpers';
+* 
+* function MyComponent() {
+*   const registry = useActionRegister();
+*   
+*   const handleUserUpdate = useCallback(async (payload, controller) => {
+*     // Handler logic here
+*   }, []);
+*   
+*   useEffect(() => {
+*     const { register, unregister } = createActionHandler(
+*       registry,
+*       'updateUser',
+*       handleUserUpdate,
+*       { priority: 10 }
+*     );
+*     
+*     const cleanup = register();
+*     return () => {
+*       cleanup();
+*       unregister();
+*     };
+*   }, [registry, handleUserUpdate]);
+* }
+* ```
+* 
+* @example With Automatic Cleanup
+* ```tsx
+* const [userId, setUserId] = useState('123');
+* 
+* const handleUserUpdate = useCallback(async (payload, controller) => {
+*   console.log('Updating user:', userId, payload);
+* }, [userId]);
+* 
+* useEffect(() => {
+*   const handlerManager = createActionHandler(
+*     registry,
+*     'updateUser',
+*     handleUserUpdate,
+*     { priority: 10 }
+*   );
+*   
+*   // Simplified registration with automatic cleanup
+*   return handlerManager.registerWithCleanup();
+* }, [registry, handleUserUpdate, userId]);
+* ```
+* 
+* @public
+*/
+function createActionHandler(registry, action, handler, config) {
+	const finalConfig = createReactHandlerConfig(String(action), void 0, config);
+	let currentUnregister;
+	let isRegistered = false;
+	return {
+		register() {
+			if (isRegistered && currentUnregister) currentUnregister();
+			currentUnregister = registry.register(action, handler, finalConfig);
+			isRegistered = true;
+			return currentUnregister;
+		},
+		unregister() {
+			if (isRegistered && currentUnregister) {
+				currentUnregister();
+				currentUnregister = void 0;
+				isRegistered = false;
+			}
+		},
+		registerWithCleanup() {
+			const unregisterFn = this.register();
+			return () => {
+				unregisterFn();
+				this.unregister();
+			};
+		},
+		config: finalConfig
+	};
+}
+/**
+* 🆕 React handler configuration factory
+* 
+* Creates optimized handler configurations for React environments with
+* proper cleanup and unique ID generation.
+* 
+* @template T - ActionPayloadMap type
+* @template K - Action key type
+* 
+* @param action - Action name
+* @param componentId - Optional component identifier for debugging
+* @param config - Base handler configuration
+* 
+* @returns Optimized configuration for React environments
+* 
+* @example
+* ```tsx
+* function MyComponent({ userId }: { userId: string }) {
+*   const registry = useActionRegister();
+*   
+*   useEffect(() => {
+*     const config = createReactHandlerConfig('updateUser', 'MyComponent', {
+*       priority: 10
+*     });
+*     
+*     const unregister = registry.register('updateUser', handler, config);
+*     return unregister;
+*   }, [registry, handler]);
+* }
+* ```
+* 
+* @public
+*/
+function createReactHandlerConfig(action, componentId, config = {}) {
+	const timestamp = Date.now();
+	const random = Math.random().toString(36).substr(2, 5);
+	return {
+		priority: config.priority ?? 0,
+		id: config.id || `${componentId || "react"}_${action}_${timestamp}_${random}`,
+		blocking: config.blocking ?? false,
+		once: config.once ?? false,
+		debounce: config.debounce ?? void 0,
+		throttle: config.throttle ?? void 0,
+		replaceExisting: true
+	};
+}
+/**
+* 🆕 React action dispatcher factory
+* 
+* Creates a dispatcher function optimized for React component usage
+* with proper error boundaries and async handling.
+* 
+* @template T - ActionPayloadMap type
+* 
+* @param registry - ActionRegister instance
+* @param errorHandler - Optional error handler for unhandled dispatch errors
+* 
+* @returns Optimized dispatch function for React components
+* 
+* @example
+* ```tsx
+* function MyComponent() {
+*   const registry = useActionRegister();
+*   
+*   const dispatch = createReactDispatcher(registry, (error, action, payload) => {
+*     console.error(`Failed to dispatch ${action}:`, error);
+*   });
+*   
+*   const handleClick = useCallback(() => {
+*     dispatch('userClick', { buttonId: 'submit' });
+*   }, [dispatch]);
+* }
+* ```
+* 
+* @public
+*/
+function createReactDispatcher(registry, errorHandler) {
+	return async (action, payload, options) => {
+		try {
+			await registry.dispatch(action, payload, {
+				immediate: false,
+				...options
+			});
+		} catch (error) {
+			const errorObj = error instanceof Error ? error : new Error(String(error));
+			if (errorHandler) errorHandler(errorObj, action, payload);
+			else console.error(`[ActionRegister] Dispatch failed for action '${String(action)}':`, errorObj);
+		}
+	};
+}
+/**
+* 🆕 React development utilities
+* 
+* Provides debugging and development helpers specifically for React environments.
+*/
+const ReactDevUtils = {
+	enableDebugMode() {
+		if (typeof window !== "undefined") window.__CONTEXT_ACTION_REACT_DEBUG__ = true;
+	},
+	disableDebugMode() {
+		if (typeof window !== "undefined") window.__CONTEXT_ACTION_REACT_DEBUG__ = false;
+	},
+	isDebugMode() {
+		return typeof window !== "undefined" && Boolean(window.__CONTEXT_ACTION_REACT_DEBUG__);
+	},
+	log(component, action, message, data) {
+		if (this.isDebugMode()) console.log(`🎯 [React-ActionRegister] [${component}] ${action}: ${message}`, data || "");
+	},
+	getStats(registry) {
+		const registryInfo = registry.getRegistryInfo();
+		let reactHandlers = 0;
+		registry.getRegisteredActions().forEach((action) => {
+			const stats = registry.getActionStats(action);
+			if (stats) stats.handlersByPriority.forEach((priorityGroup) => {
+				priorityGroup.handlers.forEach((handler) => {
+					if (handler.id.includes("react")) reactHandlers++;
+				});
+			});
+		});
+		return {
+			totalHandlers: registryInfo.totalHandlers,
+			reactHandlers,
+			registryInfo
+		};
 	}
 };
+/**
+* 🆕 React Error Boundary integration
+* 
+* Utilities for integrating ActionRegister errors with React Error Boundaries.
+*/
+var ReactActionError = class ReactActionError extends Error {
+	constructor(message, action, payload, handlerId, originalError) {
+		super(message);
+		this.name = "ReactActionError";
+		this.action = action;
+		this.payload = payload;
+		this.handlerId = handlerId;
+		this.timestamp = Date.now();
+		if (originalError && originalError.stack) this.stack = originalError.stack;
+	}
+	/**
+	* Create a React Error Boundary compatible error
+	*/
+	static fromActionError(originalError, action, payload, handlerId) {
+		return new ReactActionError(`Action '${action}' failed: ${originalError.message}`, action, payload, handlerId, originalError);
+	}
+};
+/**
+* 🆕 Type guard for React Action Errors
+* 
+* @param error - Error to check
+* @returns True if error is a ReactActionError
+*/
+function isReactActionError(error) {
+	return error instanceof ReactActionError;
+}
 
 //#endregion
-export { ActionGuard, ActionRegister, executeParallel, executeRace, executeSequential };
+export { ActionGuard, ActionRegister, ReactActionError, ReactDevUtils, createActionHandler, createReactDispatcher, createReactHandlerConfig, executeParallel, executeRace, executeSequential, isReactActionError };
 //# sourceMappingURL=index.js.map