@context-action/core 0.3.1 → 0.5.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).
@@ -39,64 +31,42 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 * @param context - Pipeline execution context containing handlers and state
 * @param createController - Factory function for creating pipeline controllers
 * 
-* @throws {Error} When a blocking handler fails or validation errors occur
+* @throws {Error} When a blocking handler fails
 * 
-* @example
-* ```typescript
-* // This is called internally by ActionRegister.dispatch()
-* // when executionMode is 'sequential'
-* 
-* // Handlers execute in this order (by priority):
-* // 1. Priority 100: Validation handler
-* // 2. Priority 50: Business logic handler  
-* // 3. Priority 10: Logging handler
-* 
-* await executeSequential(context, (registration, index) => ({
-*   abort: (reason) => { context.aborted = true; context.abortReason = reason },
-*   modifyPayload: (modifier) => { context.payload = modifier(context.payload) },
-*   // ... other controller methods
-* }))
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns
 * 
 * @public
 */
 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];
 		context.currentIndex = i;
-		/** Check condition if provided */
-		if (registration.config.condition && !registration.config.condition()) {
-			i++;
-			continue;
-		}
-		/** Check validation if provided */
-		if (registration.config.validation && !registration.config.validation(context.payload)) {
-			i++;
-			continue;
-		}
 		const controller = createController(registration, i);
 		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 */
@@ -112,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)
@@ -133,46 +112,13 @@ async function executeSequential(context, createController) {
 * 
 * @throws {Error} When any blocking handler fails
 * 
-* @example
-* ```typescript
-* // This is called internally by ActionRegister.dispatch()
-* // when executionMode is 'parallel'
-* 
-* // All handlers execute simultaneously:
-* // - Analytics handler (non-blocking)
-* // - Validation handler (blocking)
-* // - Update handler (blocking)
-* // - Notification handler (non-blocking)
-* 
-* await executeParallel(context, (registration, index) => ({
-*   abort: (reason) => { context.aborted = true },
-*   setResult: (result) => { context.results.push(result) },
-*   // ... other controller methods
-* }))
-* ```
-* 
-* @example Use Case
-* ```typescript
-* // Perfect for independent operations
-* register.setActionExecutionMode('logEvent', 'parallel')
-* 
-* // These can all run simultaneously:
-* register.register('logEvent', analyticsHandler, { blocking: false })
-* register.register('logEvent', metricsHandler, { blocking: false })
-* register.register('logEvent', auditHandler, { blocking: true })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#parallel-execution
 * 
 * @public
 */
 async function executeParallel(context, createController) {
-	/** Filter handlers that should run */
-	const runnableHandlers = context.handlers.filter((registration, _index) => {
-		/** Check condition */
-		if (registration.config.condition && !registration.config.condition()) return false;
-		/** Check validation */
-		if (registration.config.validation && !registration.config.validation(context.payload)) return false;
-		return true;
-	});
+	/** All handlers are runnable */
+	const runnableHandlers = context.handlers;
 	/** Create promises for all handlers */
 	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
 		const controller = createController(registration, _index);
@@ -192,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
 			};
 		}
 	});
@@ -238,52 +185,13 @@ async function executeParallel(context, createController) {
 * 
 * @throws {Error} When the winning handler fails and is blocking
 * 
-* @example
-* ```typescript
-* // This is called internally by ActionRegister.dispatch()
-* // when executionMode is 'race'
-* 
-* // Multiple data sources racing for fastest response:
-* // - Database handler (might be slow)
-* // - Cache handler (usually fast)
-* // - API handler (variable speed)
-* // 
-* // Whichever completes first wins
-* 
-* await executeRace(context, (registration, index) => ({
-*   return: (result) => { 
-*     context.terminated = true
-*     context.terminationResult = result 
-*   },
-*   // ... other controller methods
-* }))
-* ```
-* 
-* @example Use Case
-* ```typescript
-* // Race between multiple data sources
-* register.setActionExecutionMode('fetchUserData', 'race')
-* 
-* // These handlers race for fastest response:
-* register.register('fetchUserData', cacheHandler)     // Usually fastest
-* register.register('fetchUserData', databaseHandler)  // Reliable fallback
-* register.register('fetchUserData', apiHandler)       // External source
-* 
-* // First to complete wins, others are ignored
-* const result = await register.dispatchWithResult('fetchUserData', { id: '123' })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#race-execution
 * 
 * @public
 */
 async function executeRace(context, createController) {
-	/** Filter handlers that should run */
-	const runnableHandlers = context.handlers.filter((registration, _index) => {
-		/** Check condition */
-		if (registration.config.condition && !registration.config.condition()) return false;
-		/** Check validation */
-		if (registration.config.validation && !registration.config.validation(context.payload)) return false;
-		return true;
-	});
+	/** All handlers are runnable */
+	const runnableHandlers = context.handlers;
 	if (runnableHandlers.length === 0) return;
 	/** Create promises for all handlers */
 	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
@@ -303,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
 			};
 		}
@@ -324,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
 * 
@@ -392,33 +242,9 @@ var import_defineProperty$2 = /* @__PURE__ */ __toESM(require_defineProperty(),
 * debouncing and throttling mechanisms. Debouncing waits for a pause in calls
 * before executing, while throttling limits execution frequency.
 * 
-* @example Debouncing Search Input
-* ```typescript
-* const guard = new ActionGuard()
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 * 
-* // Wait 300ms after user stops typing before searching
-* register.register('searchUsers', async (payload, controller) => {
-*   const query = payload.query
-*   if (query.length < 2) return
-*   
-*   const results = await userService.search(query)
-*   controller.setResult(results)
-* }, {
-*   debounce: 300,  // Built into ActionRegister via ActionGuard
-*   tags: ['search', 'user-input']
-* })
-* ```
-* 
-* @example Throttling High-Frequency Events
-* ```typescript
-* // Limit scroll position updates to once per 100ms
-* register.register('updateScrollPosition', (payload, controller) => {
-*   scrollState.setValue(payload.position)
-* }, {
-*   throttle: 100,  // Built into ActionRegister via ActionGuard
-*   tags: ['scroll', 'performance']
-* })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 * 
 * @example Manual Usage (Advanced)
 * ```typescript
@@ -438,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
@@ -569,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);
 		}
@@ -588,7 +444,7 @@ var ActionGuard = class {
 	clearAll() {
 		/** Iterate through all guard states and clear their timers */
 		/** This prevents memory leaks when clearing the entire guard system */
-		for (const [, state] of this.guards) {
+		this.guards.forEach((state) => {
 			/** Clear any active debounce timers */
 			if (state.debounceTimer) {
 				clearTimeout(state.debounceTimer);
@@ -596,7 +452,7 @@ var ActionGuard = class {
 			}
 			/** Clear any active throttle timers */
 			if (state.throttleTimer) clearTimeout(state.throttleTimer);
-		}
+		});
 		/** Remove all guard states from memory */
 		this.guards.clear();
 	}
@@ -627,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);
 /**
 * 작업 큐 관리자
 * 
@@ -640,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);
 	}
 	/**
 	* 작업을 큐에 추가하고 실행 결과를 반환
@@ -675,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,
@@ -712,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() {
@@ -719,7 +643,7 @@ var OperationQueue = class {
 			operation.reject(/* @__PURE__ */ new Error("Queue cleared"));
 		});
 		this.queue = [];
-		this.isProcessing = false;
+		this.processingPromise = null;
 	}
 	/**
 	* 큐 크기 조회
@@ -731,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
 * 
@@ -747,100 +670,31 @@ var import_defineProperty = /* @__PURE__ */ __toESM(require_defineProperty(), 1)
 * 
 * @template TActionMap - Action payload mapping interface extending ActionPayloadMap
 * 
-* @example Basic Usage
-* ```typescript
-* interface AppActions extends ActionPayloadMap {
-*   updateUser: { id: string; name: string; email: string }
-*   deleteUser: { id: string }
-*   resetUser: void
-* }
-* 
-* const register = new ActionRegister<AppActions>({
-*   name: 'AppRegister',
-*   registry: { debug: true, maxHandlers: 10 }
-* })
-* 
-* // Register handler with priority
-* register.register('updateUser', async (payload, controller) => {
-*   await userService.update(payload.id, payload)
-*   controller.setResult({ success: true, userId: payload.id })
-* }, { priority: 10, tags: ['user', 'crud'] })
-* 
-* // Dispatch action
-* await register.dispatch('updateUser', { 
-*   id: '123', 
-*   name: 'John Doe', 
-*   email: 'john@example.com' 
-* })
-* ```
-* 
-* @example With Multiple Handlers
-* ```typescript
-* // High priority validation handler
-* register.register('updateUser', async (payload, controller) => {
-*   if (!payload.email.includes('@')) {
-*     controller.abort('Invalid email format')
-*     return
-*   }
-* }, { priority: 100, category: 'validation' })
-* 
-* // Lower priority update handler
-* register.register('updateUser', async (payload, controller) => {
-*   const user = await userService.update(payload.id, payload)
-*   controller.setResult(user)
-* }, { priority: 50, category: 'business-logic' })
-* ```
-* 
-* @example Advanced Configuration
-* ```typescript
-* const register = new ActionRegister<AppActions>({
-*   name: 'AdvancedRegister',
-*   registry: {
-*     debug: true,
-*     maxHandlers: 20,
-*     defaultExecutionMode: 'parallel',
-*     autoCleanup: true
-*   }
-* })
-* 
-* // Handler with debouncing and tags
-* register.register('searchUsers', async (payload, controller) => {
-*   const results = await userService.search(payload.query)
-*   controller.setResult(results)
-* }, {
-*   priority: 10,
-*   debounce: 300,
-*   tags: ['search', 'user'],
-*   category: 'query',
-*   once: false
-* })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/register-delegation
 * 
 * @public
 */
 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
 		});
 	}
 	/**
@@ -854,105 +708,89 @@ var ActionRegister = class {
 	* 
 	* @throws {Error} When maximum handlers limit is reached
 	* 
-	* @example Basic Registration
-	* ```typescript
-	* const unregister = register.register('updateUser', async (payload, controller) => {
-	*   await userService.update(payload.id, payload)
-	* })
-	* 
-	* // Later remove the handler
-	* unregister()
-	* ```
-	* 
-	* @example With Priority and Configuration
-	* ```typescript
-	* register.register('validateUser', async (payload, controller) => {
-	*   if (!payload.email) {
-	*     controller.abort('Email is required')
-	*   }
-	* }, {
-	*   priority: 100,
-	*   tags: ['validation'],
-	*   category: 'security',
-	*   once: false
-	* })
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @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
 	*/
-	_performRegistrationSync(action, handler, config, handlerId) {
-		const registration = {
-			handler,
-			config: {
-				priority: config.priority ?? 0,
-				id: handlerId,
-				blocking: config.blocking ?? false,
-				once: config.once ?? false,
-				condition: config.condition || (() => true),
-				debounce: config.debounce ?? void 0,
-				throttle: config.throttle ?? void 0,
-				validation: config.validation ?? void 0,
-				middleware: config.middleware ?? false,
-				tags: config.tags ?? [],
-				category: config.category ?? void 0,
-				description: config.description ?? void 0,
-				version: config.version ?? void 0,
-				returnType: config.returnType ?? "value",
-				timeout: config.timeout ?? void 0,
-				retries: config.retries ?? 0,
-				dependencies: config.dependencies ?? [],
-				conflicts: config.conflicts ?? [],
-				environment: config.environment ?? void 0,
-				feature: config.feature ?? void 0,
-				metrics: config.metrics ?? {
-					collectTiming: false,
-					collectErrors: false,
-					customMetrics: {}
-				},
-				metadata: config.metadata ?? {}
-			},
-			id: handlerId
-		};
-		if (!this.pipelines.has(action)) this.pipelines.set(action, []);
-		const pipeline = this.pipelines.get(action);
-		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}'`);
-		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)}`, {
-			handlerId,
-			priority: config.priority,
-			tags: config.tags,
-			category: config.category,
-			totalHandlers: pipeline.length,
-			registry: this.name
-		});
-		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)}`, {
-					handlerId,
-					remainingHandlers: pipeline.length,
-					registry: this.name
-				});
-			}
+	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
+		];
 	}
 	/**
-	* 🆕 실제 등록 작업 수행 (큐에서 호출됨)
-	* @deprecated Currently unused - reserved for future queue-based registration
+	* 🆕 Perform synchronous handler registration
 	*/
-	_performRegistration(action, handler, config, handlerId) {
+	_performRegistrationSync(action, handler, config, handlerId) {
 		const registration = {
 			handler,
 			config: {
@@ -960,54 +798,66 @@ var ActionRegister = class {
 				id: handlerId,
 				blocking: config.blocking ?? false,
 				once: config.once ?? false,
-				condition: config.condition || (() => true),
 				debounce: config.debounce ?? void 0,
 				throttle: config.throttle ?? void 0,
-				validation: config.validation ?? void 0,
-				middleware: config.middleware ?? false,
-				tags: config.tags ?? [],
-				category: config.category ?? void 0,
-				description: config.description ?? void 0,
-				version: config.version ?? void 0,
-				returnType: config.returnType ?? "value",
-				timeout: config.timeout ?? void 0,
-				retries: config.retries ?? 0,
-				dependencies: config.dependencies ?? [],
-				conflicts: config.conflicts ?? [],
-				environment: config.environment ?? void 0,
-				feature: config.feature ?? void 0,
-				metrics: config.metrics ?? {
-					collectTiming: false,
-					collectErrors: false,
-					customMetrics: {}
-				},
-				metadata: config.metadata ?? {}
+				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,
-			tags: config.tags,
-			category: config.category,
-			totalHandlers: pipeline.length,
-			registry: this.name
+			totalHandlers: pipeline.length
 		});
 		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
 				});
 			}
 		};
@@ -1023,39 +873,13 @@ var ActionRegister = class {
 	* 
 	* @throws {Error} When action dispatching fails
 	* 
-	* @example Basic Dispatch
-	* ```typescript
-	* await register.dispatch('updateUser', {
-	*   id: '123',
-	*   name: 'John Doe',
-	*   email: 'john@example.com'
-	* })
-	* ```
-	* 
-	* @example With Options
-	* ```typescript
-	* await register.dispatch('updateUser', payload, {
-	*   executionMode: 'parallel',
-	*   timeout: 5000,
-	*   filter: {
-	*     tags: ['validation', 'business-logic'],
-	*     excludeCategory: 'analytics'
-	*   }
-	* })
-	* ```
-	* 
-	* @example With Throttling
-	* ```typescript
-	* await register.dispatch('searchUsers', { query: 'john' }, {
-	*   throttle: 300,
-	*   debounce: 100
-	* })
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @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);
 		});
 	}
@@ -1063,47 +887,13 @@ 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 });
-				}
-			}
-		}
+		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) return;
 		const pipeline = this.pipelines.get(action);
 		if (!pipeline || pipeline.length === 0) return;
-		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;
@@ -1143,8 +933,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";
@@ -1152,15 +940,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();
 		}
 	}
 	/**
@@ -1172,65 +957,30 @@ var ActionRegister = class {
 	* 
 	* @returns Promise resolving to comprehensive execution results
 	* 
-	* @example Basic Result Collection
-	* ```typescript
-	* const result = await register.dispatchWithResult('updateUser', payload)
-	* 
-	* if (result.success) {
-	*   console.log(`Executed ${result.execution.handlersExecuted} handlers`)
-	*   console.log(`Duration: ${result.execution.duration}ms`)
-	* }
-	* ```
-	* 
-	* @example Advanced Result Processing
-	* ```typescript
-	* const result = await register.dispatchWithResult('processOrder', order, {
-	*   result: {
-	*     collect: true,
-	*     strategy: 'merge',
-	*     maxResults: 5,
-	*     merger: (results) => results.reduce((acc, curr) => ({ ...acc, ...curr }), {})
-	*   }
-	* })
-	* 
-	* if (result.terminated) {
-	*   console.log('Handler returned early:', result.result)
-	* }
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @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: []
@@ -1241,19 +991,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;
@@ -1279,13 +1031,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: [],
@@ -1300,13 +1054,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: [],
@@ -1345,59 +1101,92 @@ var ActionRegister = class {
 				timestamp: Date.now()
 			});
 		} finally {
-			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
+			cleanup();
 		}
 		const endTime = Date.now();
-		const executionSuccess = !executionError && !context.aborted;
-		this.updateExecutionStats(action, executionSuccess, endTime - startTime);
+		!executionError && context.aborted;
 		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.tags && filterOptions.tags.length > 0) {
-				const hasMatchingTag = filterOptions.tags.some((tag) => config.tags.includes(tag));
-				if (!hasMatchingTag) return false;
-			}
-			if (filterOptions.category && config.category !== filterOptions.category) return false;
-			if (filterOptions.handlerIds && filterOptions.handlerIds.length > 0) {
-				if (!filterOptions.handlerIds.includes(config.id)) return false;
-			}
-			if (filterOptions.environment && config.environment !== filterOptions.environment) return false;
-			if (filterOptions.feature && config.feature !== filterOptions.feature) return false;
-			if (filterOptions.excludeTags && filterOptions.excludeTags.length > 0) {
-				const hasExcludedTag = filterOptions.excludeTags.some((tag) => config.tags.includes(tag));
-				if (hasExcludedTag) return false;
-			}
-			if (filterOptions.excludeCategory && config.category === filterOptions.excludeCategory) 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;
@@ -1483,39 +1272,13 @@ 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
 	* 
 	* @returns Number of registered handlers
 	* 
-	* @example
-	* ```typescript
-	* register.register('updateUser', handler1)
-	* register.register('updateUser', handler2)
-	* 
-	* console.log(register.getHandlerCount('updateUser')) // 2
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1530,12 +1293,7 @@ var ActionRegister = class {
 	* 
 	* @returns True if action has handlers, false otherwise
 	* 
-	* @example
-	* ```typescript
-	* if (register.hasHandlers('updateUser')) {
-	*   await register.dispatch('updateUser', userData)
-	* }
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1547,11 +1305,7 @@ var ActionRegister = class {
 	* 
 	* @returns Array of all registered action types
 	* 
-	* @example
-	* ```typescript
-	* const actions = register.getRegisteredActions()
-	* console.log('Registered actions:', actions) // ['updateUser', 'deleteUser', 'resetUser']
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1563,41 +1317,31 @@ var ActionRegister = class {
 	* 
 	* @param action - The action type to clear handlers for
 	* 
-	* @example
-	* ```typescript
-	* register.clearAction('updateUser')
-	* console.log(register.hasHandlers('updateUser')) // false
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
 	clearAction(action) {
 		this.pipelines.delete(action);
+		this.invalidateFilterCache();
 	}
 	/**
 	* Remove all handlers for all actions
 	* 
-	* @example
-	* ```typescript
-	* register.clearAll()
-	* console.log(register.getRegisteredActions().length) // 0
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
 	clearAll() {
 		this.pipelines.clear();
+		this.invalidateFilterCache();
 	}
 	/**
 	* Get the name of this action register
 	* 
 	* @returns The register name
 	* 
-	* @example
-	* ```typescript
-	* const register = new ActionRegister({ name: 'UserRegister' })
-	* console.log(register.getName()) // 'UserRegister'
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1636,21 +1380,9 @@ var ActionRegister = class {
 		});
 		const handlersByPriority = Array.from(priorityMap.entries()).sort(([a], [b]) => b - a).map(([priority, handlers]) => ({
 			priority,
-			handlers: handlers.map((h) => ({
-				id: h.config.id,
-				tags: h.config.tags,
-				category: h.config.category,
-				description: h.config.description,
-				version: h.config.version
-			}))
+			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,
@@ -1668,34 +1400,6 @@ var ActionRegister = class {
 		return Array.from(this.pipelines.keys()).map((action) => this.getActionStats(action)).filter((stats) => stats !== null);
 	}
 	/**
-	* Get handlers by tag across all actions
-	* 
-	* @param tag Tag to filter handlers by
-	* @returns Map of actions to handlers with the specified tag
-	*/
-	getHandlersByTag(tag) {
-		const result = /* @__PURE__ */ new Map();
-		for (const [action, pipeline] of this.pipelines.entries()) {
-			const matchingHandlers = pipeline.filter((handler) => handler.config.tags.includes(tag));
-			if (matchingHandlers.length > 0) result.set(action, matchingHandlers);
-		}
-		return result;
-	}
-	/**
-	* Get handlers by category across all actions
-	* 
-	* @param category Category to filter handlers by
-	* @returns Map of actions to handlers with the specified category
-	*/
-	getHandlersByCategory(category) {
-		const result = /* @__PURE__ */ new Map();
-		for (const [action, pipeline] of this.pipelines.entries()) {
-			const matchingHandlers = pipeline.filter((handler) => handler.config.category === category);
-			if (matchingHandlers.length > 0) result.set(action, matchingHandlers);
-		}
-		return result;
-	}
-	/**
 	* Set execution mode for a specific action
 	* 
 	* @param action Action name
@@ -1724,22 +1428,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
@@ -1753,10 +1441,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