@context-action/core 0.0.3 → 0.0.5

package/dist/index.cjs

@@ -25,6 +25,171 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 
+//#region src/execution-modes.ts
+/**
+* Execute handlers in sequential mode (one after another)
+*/
+async function executeSequential(context, createController) {
+	let i = 0;
+	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 (handlerResult !== void 0 && !context.terminated) context.results.push(handlerResult);
+			} else if (result !== void 0 && !context.terminated)
+ /** Collect synchronous result */
+			if (result instanceof Promise) result.then((asyncResult) => {
+				if (asyncResult !== void 0 && !context.terminated) context.results.push(asyncResult);
+			}).catch(() => {});
+			else context.results.push(result);
+			/** Check if pipeline was terminated by controller.return() */
+			if (context.terminated) break;
+			/** Handle jump to priority AFTER handler execution */
+			if (context.jumpToPriority !== void 0) {
+				const jumpIndex = context.handlers.findIndex((handler) => handler.config.priority === context.jumpToPriority);
+				if (jumpIndex !== -1) {
+					i = jumpIndex;
+					context.jumpToPriority = void 0;
+					continue;
+				} else {
+					context.jumpToPriority = void 0;
+					i++;
+				}
+			} else i++;
+		} catch (error) {
+			if (registration.config.blocking) throw error;
+			i++;
+		}
+	}
+}
+/**
+* Execute handlers in parallel mode (all at once)
+*/
+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;
+	});
+	/** Create promises for all handlers */
+	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
+		const controller = createController(registration, _index);
+		try {
+			const result = registration.handler(context.payload, controller);
+			let handlerResult;
+			if (result instanceof Promise) handlerResult = await result;
+			else handlerResult = result;
+			/** Collect result if handler returned something and pipeline wasn't terminated */
+			if (handlerResult !== void 0 && !context.terminated) context.results.push(handlerResult);
+			return {
+				success: true,
+				handlerId: registration.id,
+				result: handlerResult,
+				terminated: context.terminated
+			};
+		} catch (error) {
+			if (registration.config.blocking) throw error;
+			return {
+				success: false,
+				handlerId: registration.id,
+				error
+			};
+		}
+	});
+	/** Wait for all handlers to complete */
+	const results = await Promise.allSettled(handlerPromises);
+	/** Check for any rejected blocking handlers */
+	const failures = results.filter((result, index) => {
+		if (result.status === "rejected") {
+			const registration = runnableHandlers[index];
+			return registration.config.blocking;
+		}
+		return false;
+	});
+	if (failures.length > 0) {
+		const firstFailure = failures[0];
+		throw firstFailure.reason;
+	}
+	/** Check if any handler terminated the pipeline */
+	const terminatedResults = results.filter((result) => result.status === "fulfilled" && result.value.terminated);
+	if (terminatedResults.length > 0) {
+		context.terminated = true;
+		const firstTerminated = terminatedResults[0];
+		context.terminationResult = firstTerminated.value.result;
+	}
+}
+/**
+* Execute handlers in race mode (first to complete wins)
+*/
+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;
+	});
+	if (runnableHandlers.length === 0) return;
+	/** Create promises for all handlers */
+	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
+		const controller = createController(registration, _index);
+		try {
+			const result = registration.handler(context.payload, controller);
+			let handlerResult;
+			if (result instanceof Promise) handlerResult = await result;
+			else handlerResult = result;
+			return {
+				success: true,
+				handlerId: registration.id,
+				registration,
+				result: handlerResult,
+				terminated: context.terminated
+			};
+		} catch (error) {
+			return {
+				success: false,
+				handlerId: registration.id,
+				error,
+				registration
+			};
+		}
+	});
+	/** Race all handlers */
+	const winner = await Promise.race(handlerPromises);
+	/** If the winner failed and was blocking, throw the error */
+	if (!winner.success && winner.registration?.config.blocking) throw winner.error;
+	/** Collect result from the winning handler */
+	if (winner.success && winner.result !== void 0) context.results.push(winner.result);
+	/** Check if the winning handler terminated the pipeline */
+	if (winner.success && winner.terminated) {
+		context.terminated = true;
+		context.terminationResult = winner.result;
+	}
+}
+
+//#endregion
 //#region ../../node_modules/.pnpm/@oxc-project+runtime@0.77.3/node_modules/@oxc-project/runtime/src/helpers/typeof.js
 var require_typeof = __commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.77.3/node_modules/@oxc-project/runtime/src/helpers/typeof.js"(exports, module) {
 	function _typeof$2(o) {
@@ -83,173 +248,156 @@ var require_defineProperty = __commonJS({ "../../node_modules/.pnpm/@oxc-project
 } });
 
 //#endregion
-//#region src/logger.ts
+//#region src/action-guard.ts
 var import_defineProperty$1 = __toESM(require_defineProperty(), 1);
 /**
-* Log levels in order of severity (lowest to highest)
-*/
-let LogLevel = /* @__PURE__ */ function(LogLevel$1) {
-	LogLevel$1[LogLevel$1["TRACE"] = 0] = "TRACE";
-	LogLevel$1[LogLevel$1["DEBUG"] = 1] = "DEBUG";
-	LogLevel$1[LogLevel$1["INFO"] = 2] = "INFO";
-	LogLevel$1[LogLevel$1["WARN"] = 3] = "WARN";
-	LogLevel$1[LogLevel$1["ERROR"] = 4] = "ERROR";
-	LogLevel$1[LogLevel$1["FATAL"] = 5] = "FATAL";
-	return LogLevel$1;
-}({});
-/**
-* Default console logger implementation
-*/
-var ConsoleLogger = class {
-	constructor(level = LogLevel.ERROR) {
-		this.level = level;
-	}
-	shouldLog(level) {
-		return level >= this.level;
-	}
-	formatMessage(level, message) {
-		return `[${level.toUpperCase()}] ${message}`;
-	}
-	trace(message, ...args) {
-		if (this.shouldLog(LogLevel.TRACE)) console.trace(this.formatMessage("trace", message), ...args);
-	}
-	debug(message, ...args) {
-		if (this.shouldLog(LogLevel.DEBUG)) console.debug(this.formatMessage("debug", message), ...args);
-	}
-	info(message, ...args) {
-		if (this.shouldLog(LogLevel.INFO)) console.info(this.formatMessage("info", message), ...args);
-	}
-	warn(message, ...args) {
-		if (this.shouldLog(LogLevel.WARN)) console.warn(this.formatMessage("warn", message), ...args);
-	}
-	error(message, ...args) {
-		if (this.shouldLog(LogLevel.ERROR)) console.error(this.formatMessage("error", message), ...args);
-	}
-	fatal(message, ...args) {
-		if (this.shouldLog(LogLevel.FATAL)) console.error(this.formatMessage("fatal", message), ...args);
-	}
-	setLevel(level) {
-		this.level = level;
-	}
-};
-/**
-* Parse log level from string
-*/
-function parseLogLevel(level) {
-	const upperLevel = level.toUpperCase();
-	switch (upperLevel) {
-		case "TRACE": return LogLevel.TRACE;
-		case "DEBUG": return LogLevel.DEBUG;
-		case "INFO": return LogLevel.INFO;
-		case "WARN": return LogLevel.WARN;
-		case "ERROR": return LogLevel.ERROR;
-		case "FATAL": return LogLevel.FATAL;
-		default: return LogLevel.ERROR;
-	}
-}
-/**
-* Get log level from environment variable or default to ERROR
-*/
-function getLogLevelFromEnv() {
-	if (typeof process !== "undefined" && process.env) {
-		const envLevel = process.env.LOG_LEVEL || process.env.ACTION_LOG_LEVEL;
-		if (envLevel) return parseLogLevel(envLevel);
-	}
-	return LogLevel.TRACE;
-}
-/**
-* Extract trace ID from payload if it exists
-*/
-function extractTraceIdFromPayload(payload) {
-	if (payload && typeof payload === "object") return payload._traceId || payload.traceId || payload.trace_id;
-	return void 0;
-}
-/**
-* Extract session ID from payload if it exists
-*/
-function extractSessionIdFromPayload(payload) {
-	if (payload && typeof payload === "object") return payload._sessionId || payload.sessionId || payload.session_id;
-	return void 0;
-}
-/**
-* Create OTEL context from payload
-*/
-function createOtelContextFromPayload(payload) {
-	return {
-		traceId: extractTraceIdFromPayload(payload),
-		sessionId: extractSessionIdFromPayload(payload),
-		metadata: payload
-	};
-}
-/**
-* OpenTelemetry-aware console logger implementation
+* Action Guard system for managing action execution timing
+* @implements action-guard
+* @implements performance-optimization  
+* @implements user-experience-optimization
+* @implements class-naming
+* @memberof core-concepts
+* @internal
+* @since 1.0.0
+* 
+* Manages action execution timing through debouncing and throttling
+* @implements performance-optimization
+* 
+* @example
+* ```typescript
+* const guard = new ActionGuard(logger);
+* 
+* // Debounce search input (wait 300ms after typing stops)
+* if (await guard.debounce('search', 300)) {
+*   executeSearch();  
+* }
+* 
+* // Throttle scroll handler (max once per 100ms)
+* if (guard.throttle('scroll', 100)) {
+*   updateScrollPosition();
+* }
+* ```
 */
-var OtelConsoleLogger = class extends ConsoleLogger {
-	constructor(level = LogLevel.ERROR) {
-		super(level);
-		(0, import_defineProperty$1.default)(this, "context", {});
-	}
-	setContext(context) {
-		this.context = {
-			...this.context,
-			...context
-		};
+var ActionGuard = class {
+	constructor() {
+		(0, import_defineProperty$1.default)(this, "guards", /* @__PURE__ */ new Map());
 	}
-	getContext() {
-		return { ...this.context };
-	}
-	clearContext() {
-		this.context = {};
-	}
-	formatWithContext(level, message) {
-		const contextParts = [];
-		if (this.context.sessionId) contextParts.push(`session=${this.context.sessionId}`);
-		if (this.context.traceId) contextParts.push(`trace=${this.context.traceId}`);
-		if (this.context.spanId) contextParts.push(`span=${this.context.spanId}`);
-		const contextStr = contextParts.length > 0 ? ` [${contextParts.join(", ")}]` : "";
-		return `[${level.toUpperCase()}]${contextStr} ${message}`;
-	}
-	logWithContext(level, message, ...args) {
-		const levelName = LogLevel[level].toLowerCase();
-		const formattedMessage = this.formatWithContext(levelName, message);
-		switch (level) {
-			case LogLevel.TRACE:
-				if (this.shouldLog(LogLevel.TRACE)) console.trace(formattedMessage, ...args);
-				break;
-			case LogLevel.DEBUG:
-				if (this.shouldLog(LogLevel.DEBUG)) console.debug(formattedMessage, ...args);
-				break;
-			case LogLevel.INFO:
-				if (this.shouldLog(LogLevel.INFO)) console.info(formattedMessage, ...args);
-				break;
-			case LogLevel.WARN:
-				if (this.shouldLog(LogLevel.WARN)) console.warn(formattedMessage, ...args);
-				break;
-			case LogLevel.ERROR:
-				if (this.shouldLog(LogLevel.ERROR)) console.error(formattedMessage, ...args);
-				break;
-			case LogLevel.FATAL:
-				if (this.shouldLog(LogLevel.FATAL)) console.error(formattedMessage, ...args);
-				break;
+	/**
+	* Check if action should be debounced
+	* @param actionKey - Unique key for the action
+	* @param debounceMs - Debounce delay in milliseconds
+	* @returns Promise that resolves when debounce period is complete
+	*/
+	async debounce(actionKey, debounceMs) {
+		/** Get or create guard state for this action */
+		let state = this.guards.get(actionKey);
+		if (!state) {
+			/** Initialize new guard state with default values */
+			state = {
+				lastExecuted: 0,
+				isThrottled: false
+			};
+			this.guards.set(actionKey, state);
 		}
+		/** Clear any existing debounce timer to restart the delay period */
+		/** This implements the "debounce" behavior where rapid calls reset the timer */
+		if (state.debounceTimer) clearTimeout(state.debounceTimer);
+		/** Create new debounce promise that resolves after the delay period */
+		/** The promise will only resolve if no new debounce requests arrive */
+		return new Promise((resolve) => {
+			state.debounceTimer = setTimeout(() => {
+				/** Clean up timer reference to prevent memory leaks */
+				state.debounceTimer = void 0;
+				/** Update last execution timestamp for throttling calculations */
+				state.lastExecuted = Date.now();
+				resolve(true);
+			}, debounceMs);
+		});
 	}
-	trace(message, ...args) {
-		this.logWithContext(LogLevel.TRACE, message, ...args);
-	}
-	debug(message, ...args) {
-		this.logWithContext(LogLevel.DEBUG, message, ...args);
+	/**
+	* Check if action should be throttled
+	* @param actionKey - Unique key for the action
+	* @param throttleMs - Throttle delay in milliseconds
+	* @returns True if action should proceed, false if throttled
+	*/
+	throttle(actionKey, throttleMs) {
+		/** Get or create guard state for this action */
+		let state = this.guards.get(actionKey);
+		if (!state) {
+			/** Initialize new guard state with default values */
+			state = {
+				lastExecuted: 0,
+				isThrottled: false
+			};
+			this.guards.set(actionKey, state);
+		}
+		const now = Date.now();
+		const timeSinceLastExecution = now - state.lastExecuted;
+		/** Check if enough time has passed since last execution */
+		/** If throttle period has elapsed, allow immediate execution */
+		if (timeSinceLastExecution >= throttleMs) {
+			/** Update execution timestamp and clear throttled state */
+			state.lastExecuted = now;
+			state.isThrottled = false;
+			return true;
+		}
+		/** If already in throttled state, don't create duplicate timers */
+		/** This prevents timer accumulation and unnecessary processing */
+		if (state.isThrottled) return false;
+		/** Set throttle timer to automatically clear the throttled state */
+		/** Calculate remaining time until throttle period expires */
+		state.isThrottled = true;
+		const remainingTime = throttleMs - timeSinceLastExecution;
+		/** Create timer to reset throttled state when period expires */
+		state.throttleTimer = setTimeout(() => {
+			/** Clear throttled state and timer reference */
+			state.isThrottled = false;
+			state.throttleTimer = void 0;
+		}, remainingTime);
+		return false;
 	}
-	info(message, ...args) {
-		this.logWithContext(LogLevel.INFO, message, ...args);
+	/**
+	* Clear all guards for an action
+	* @param actionKey - Action key to clear
+	*/
+	clearGuards(actionKey) {
+		const state = this.guards.get(actionKey);
+		if (state) {
+			/** Clear debounce timer if active to prevent memory leaks */
+			if (state.debounceTimer) clearTimeout(state.debounceTimer);
+			/** Clear throttle timer if active to prevent memory leaks */
+			if (state.throttleTimer) clearTimeout(state.throttleTimer);
+			/** Remove guard state from memory */
+			this.guards.delete(actionKey);
+		}
 	}
-	warn(message, ...args) {
-		this.logWithContext(LogLevel.WARN, message, ...args);
+	/**
+	* Clear all guards
+	*/
+	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) {
+			/** Clear any active debounce timers */
+			if (state.debounceTimer) clearTimeout(state.debounceTimer);
+			/** Clear any active throttle timers */
+			if (state.throttleTimer) clearTimeout(state.throttleTimer);
+		}
+		/** Remove all guard states from memory */
+		this.guards.clear();
 	}
-	error(message, ...args) {
-		this.logWithContext(LogLevel.ERROR, message, ...args);
+	/**
+	* Get current guard state for debugging
+	* @param actionKey - Action key to inspect
+	*/
+	getGuardState(actionKey) {
+		return this.guards.get(actionKey);
 	}
-	fatal(message, ...args) {
-		this.logWithContext(LogLevel.FATAL, message, ...args);
+	/**
+	* Get all active guards for debugging
+	*/
+	getAllGuardStates() {
+		return new Map(this.guards);
 	}
 };
 
@@ -257,172 +405,669 @@ var OtelConsoleLogger = class extends ConsoleLogger {
 //#region src/ActionRegister.ts
 var import_defineProperty = __toESM(require_defineProperty(), 1);
 /**
-* Core action pipeline management system
-* @template T - Action payload map defining available actions and their payload types
+* 중앙화된 액션 등록 및 디스패치 시스템으로, 타입 안전한 액션 파이프라인 관리를 제공하는 핵심 클래스입니다.
+* 
+* @implements {ActionRegister}
+* @implements {Action Pipeline System}
+* @memberof core-concepts
+* 
 * @example
 * ```typescript
 * interface AppActions extends ActionPayloadMap {
-*   increment: void;
-*   setCount: number;
+*   updateUser: { id: string; name: string };
+*   calculateTotal: void;
 * }
 * 
-* const actionRegister = new ActionRegister<AppActions>();
+* const register = new ActionRegister<AppActions>({
+*   name: 'AppRegister',
+*   logLevel: LogLevel.DEBUG
+* });
 * 
-* // Register handlers
-* actionRegister.register('increment', () => console.log('Incremented'));
-* actionRegister.register('setCount', (count) => console.log(`Count: ${count}`));
+* // 핸들러 등록
+* register.register('updateUser', ({ id, name }, controller) => {
+*   userStore.setValue({ id, name });
+*   controller.next();
+* }, { priority: 10 });
 * 
-* // Dispatch actions
-* await actionRegister.dispatch('increment');
-* await actionRegister.dispatch('setCount', 42);
+* // 액션 디스패치
+* await register.dispatch('updateUser', { id: '1', name: 'John' });
 * ```
 */
 var ActionRegister = class {
-	constructor(config) {
+	constructor(config = {}) {
 		(0, import_defineProperty.default)(this, "pipelines", /* @__PURE__ */ new Map());
-		(0, import_defineProperty.default)(this, "atomSetters", /* @__PURE__ */ new Map());
 		(0, import_defineProperty.default)(this, "handlerCounter", 0);
-		(0, import_defineProperty.default)(this, "logger", void 0);
-		const envLogLevel = getLogLevelFromEnv();
-		const configLogLevel = config?.logLevel ?? envLogLevel;
-		if (config?.logger) this.logger = config.logger;
-		else if (config?.useOtel) this.logger = new OtelConsoleLogger(configLogLevel);
-		else this.logger = new ConsoleLogger(configLogLevel);
-		if (config?.otelContext && this.logger instanceof OtelConsoleLogger) this.logger.setContext(config.otelContext);
-		this.logger.debug("ActionRegister initialized", {
-			logLevel: configLogLevel,
-			useOtel: config?.useOtel ?? false,
-			hasOtelContext: !!config?.otelContext
+		(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());
+		this.name = config.name || "ActionRegister";
+		this.registryConfig = config.registry;
+		this.actionGuard = new ActionGuard();
+		if (this.registryConfig?.defaultExecutionMode) this.executionMode = this.registryConfig.defaultExecutionMode;
+		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 ActionRegister created: ${this.name}`, {
+			defaultExecutionMode: this.executionMode,
+			maxHandlers: this.registryConfig.maxHandlers,
+			autoCleanup: this.registryConfig.autoCleanup ?? true
 		});
 	}
-	/**
-	* Register a handler for an action in the pipeline
-	* @param action - The action name to handle
-	* @param handler - The handler function to execute
-	* @param config - Optional configuration for the handler
-	* @returns Unregister function to remove the handler
-	* @example
-	* ```typescript
-	* const unregister = actionRegister.register('increment', () => {
-	*   console.log('Incremented!');
-	* }, { priority: 10 });
-	* 
-	* // Later, remove the handler
-	* unregister();
-	* ```
-	*/
 	register(action, handler, config = {}) {
-		if (!this.pipelines.has(action)) {
-			this.pipelines.set(action, /* @__PURE__ */ new Map());
-			this.logger.debug(`Created new pipeline for action: ${String(action)}`);
-		}
-		const pipeline = this.pipelines.get(action);
-		const handlerId = config.id || `handler_${++this.handlerCounter}`;
-		if (pipeline.has(handlerId)) {
-			this.logger.warn(`Handler with id ${handlerId} already exists for action: ${String(action)}`);
-			return () => {};
-		}
-		pipeline.set(handlerId, {
+		const handlerId = config.id || `handler_${++this.handlerCounter}_${Math.random().toString(36).substr(2, 5)}`;
+		const registration = {
 			handler,
-			config
-		});
-		this.logger.debug(`Registered handler for action: ${String(action)}`, {
+			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 ?? 0,
-			blocking: config.blocking ?? false
+			priority: config.priority,
+			tags: config.tags,
+			category: config.category,
+			totalHandlers: pipeline.length,
+			registry: this.name
 		});
-		this.sortPipeline(action);
 		return () => {
-			pipeline.delete(handlerId);
-			this.logger.debug(`Unregistered handler: ${handlerId} for action: ${String(action)}`);
+			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
+				});
+			}
 		};
 	}
-	registerAtomSetter(name, setter) {
-		this.atomSetters.set(name, setter);
-		this.logger.debug(`Registered atom setter: ${name}`);
+	async dispatch(action, payload, options) {
+		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 (effectiveSignal?.aborted) return;
+		const pipeline = this.pipelines.get(action);
+		if (!pipeline || pipeline.length === 0) return;
+		const filteredHandlers = this.filterHandlers([...pipeline], options?.filter);
+		const actionKey = String(action);
+		let throttleMs;
+		let debounceMs;
+		if (options?.throttle !== void 0) throttleMs = options.throttle;
+		else if (filteredHandlers.length > 0) {
+			for (const handler of filteredHandlers) if (handler.config.throttle !== void 0) {
+				throttleMs = handler.config.throttle;
+				break;
+			}
+		}
+		if (options?.debounce !== void 0) debounceMs = options.debounce;
+		else if (filteredHandlers.length > 0) {
+			for (const handler of filteredHandlers) if (handler.config.debounce !== void 0) {
+				debounceMs = handler.config.debounce;
+				break;
+			}
+		}
+		if (debounceMs !== void 0) {
+			const shouldProceed = await this.actionGuard.debounce(actionKey, debounceMs);
+			if (!shouldProceed) return;
+		}
+		if (throttleMs !== void 0) {
+			const shouldProceed = this.actionGuard.throttle(actionKey, throttleMs);
+			if (!shouldProceed) return;
+		}
+		const currentExecutionMode = options?.executionMode || this.actionExecutionModes.get(action) || this.executionMode;
+		const context = {
+			action: String(action),
+			payload,
+			handlers: filteredHandlers,
+			aborted: false,
+			abortReason: void 0,
+			currentIndex: 0,
+			jumpToPriority: void 0,
+			executionMode: currentExecutionMode,
+			results: [],
+			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";
+		} : void 0;
+		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler);
+		try {
+			await this.executePipeline(context, autoAbortController, options?.autoAbort);
+		} catch (error) {
+			executionSuccess = false;
+			throw error;
+		} finally {
+			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
+			const duration = Date.now() - startTime;
+			this.updateExecutionStats(action, executionSuccess, duration);
+		}
 	}
-	/**
-	* Internal dispatch implementation
-	* @internal
-	*/
-	async dispatch(action, payload) {
+	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 });
+				}
+			}
+		}
+		if (effectiveSignal?.aborted) return {
+			success: false,
+			aborted: true,
+			abortReason: "Action dispatch aborted by signal",
+			terminated: false,
+			result: void 0,
+			results: [],
+			execution: {
+				duration: 0,
+				handlersExecuted: 0,
+				handlersSkipped: 0,
+				handlersFailed: 0,
+				startTime,
+				endTime: startTime
+			},
+			handlers: [],
+			errors: []
+		};
 		const pipeline = this.pipelines.get(action);
-		if (this.logger instanceof OtelConsoleLogger && payload) {
-			const otelContext = createOtelContextFromPayload(payload);
-			if (otelContext.traceId || otelContext.sessionId) this.logger.setContext(otelContext);
+		if (!pipeline || pipeline.length === 0) return {
+			success: true,
+			aborted: false,
+			terminated: false,
+			result: void 0,
+			results: [],
+			execution: {
+				duration: 0,
+				handlersExecuted: 0,
+				handlersSkipped: 0,
+				handlersFailed: 0,
+				startTime,
+				endTime: startTime
+			},
+			handlers: [],
+			errors: []
+		};
+		const filteredHandlers = this.filterHandlers([...pipeline], options?.filter);
+		const actionKey = String(action);
+		let throttleMs;
+		let debounceMs;
+		if (options?.throttle !== void 0) throttleMs = options.throttle;
+		else if (filteredHandlers.length > 0) {
+			for (const handler of filteredHandlers) if (handler.config.throttle !== void 0) {
+				throttleMs = handler.config.throttle;
+				break;
+			}
 		}
-		this.logger.debug(`Dispatching action: ${String(action)}`, { payload });
-		if (!pipeline || pipeline.size === 0) {
-			this.logger.warn(`No handlers registered for action: ${String(action)}`);
-			return;
+		if (options?.debounce !== void 0) debounceMs = options.debounce;
+		else if (filteredHandlers.length > 0) {
+			for (const handler of filteredHandlers) if (handler.config.debounce !== void 0) {
+				debounceMs = handler.config.debounce;
+				break;
+			}
 		}
-		let modifiedPayload = payload;
-		const handlers = Array.from(pipeline.values());
-		let shouldContinue = true;
-		this.logger.trace(`Executing pipeline for action: ${String(action)}`, { handlerCount: handlers.length });
-		for (const { handler, config } of handlers) {
-			if (!shouldContinue) break;
-			const controller = {
-				next: () => {
-					shouldContinue = true;
+		if (debounceMs !== void 0) {
+			const shouldProceed = await this.actionGuard.debounce(actionKey, debounceMs);
+			if (!shouldProceed) return {
+				success: false,
+				aborted: true,
+				abortReason: "Debounced execution",
+				terminated: false,
+				result: void 0,
+				results: [],
+				execution: {
+					duration: Date.now() - startTime,
+					handlersExecuted: 0,
+					handlersSkipped: pipeline.length,
+					handlersFailed: 0,
+					startTime,
+					endTime: Date.now()
 				},
+				handlers: [],
+				errors: []
+			};
+		}
+		if (throttleMs !== void 0) {
+			const shouldProceed = this.actionGuard.throttle(actionKey, throttleMs);
+			if (!shouldProceed) return {
+				success: false,
+				aborted: true,
+				abortReason: "Throttled execution",
+				terminated: false,
+				result: void 0,
+				results: [],
+				execution: {
+					duration: Date.now() - startTime,
+					handlersExecuted: 0,
+					handlersSkipped: pipeline.length,
+					handlersFailed: 0,
+					startTime,
+					endTime: Date.now()
+				},
+				handlers: [],
+				errors: []
+			};
+		}
+		const currentExecutionMode = options?.executionMode || this.actionExecutionModes.get(action) || this.executionMode;
+		const context = {
+			action: String(action),
+			payload,
+			handlers: filteredHandlers,
+			aborted: false,
+			abortReason: void 0,
+			currentIndex: 0,
+			jumpToPriority: void 0,
+			executionMode: currentExecutionMode,
+			results: [],
+			terminated: false,
+			terminationResult: void 0
+		};
+		let executionError;
+		const handlerResults = [];
+		const errors = [];
+		const abortHandler = effectiveSignal ? () => {
+			context.aborted = true;
+			context.abortReason = "Action dispatch aborted by signal";
+		} : void 0;
+		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler);
+		try {
+			await this.executePipeline(context, autoAbortController, options?.autoAbort);
+		} catch (error) {
+			executionError = error instanceof Error ? error : new Error(String(error));
+			errors.push({
+				handlerId: "pipeline",
+				error: executionError,
+				timestamp: Date.now()
+			});
+		} finally {
+			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
+		}
+		const endTime = Date.now();
+		const executionSuccess = !executionError && !context.aborted;
+		this.updateExecutionStats(action, executionSuccess, endTime - startTime);
+		const processedResult = this.processResults(context, options?.result);
+		const executionResult = {
+			success: !executionError && !context.aborted,
+			aborted: context.aborted,
+			abortReason: context.abortReason,
+			terminated: context.terminated,
+			result: processedResult,
+			results: context.results,
+			execution: {
+				duration: endTime - startTime,
+				handlersExecuted: context.currentIndex + (context.aborted ? 0 : 1),
+				handlersSkipped: Math.max(0, filteredHandlers.length - (context.currentIndex + 1)),
+				handlersFailed: errors.length,
+				startTime,
+				endTime
+			},
+			handlers: handlerResults,
+			errors
+		};
+		/** Clean up one-time handlers after execution */
+		this.cleanupOneTimeHandlers(action, context.handlers);
+		return executionResult;
+	}
+	filterHandlers(handlers, filterOptions) {
+		if (!filterOptions) return handlers;
+		return 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.custom && !filterOptions.custom(config)) return false;
+			return true;
+		});
+	}
+	processResults(context, resultOptions) {
+		if (!resultOptions || !resultOptions.collect) return void 0;
+		const results = context.results;
+		if (context.terminated && context.terminationResult !== void 0) return context.terminationResult;
+		const limitedResults = resultOptions.maxResults ? results.slice(0, resultOptions.maxResults) : results;
+		if (limitedResults.length === 0) return void 0;
+		switch (resultOptions.strategy) {
+			case "first": return limitedResults[0];
+			case "last": return limitedResults[limitedResults.length - 1];
+			case "all": return limitedResults;
+			case "merge":
+				if (resultOptions.merger) return resultOptions.merger(limitedResults);
+				return limitedResults[limitedResults.length - 1];
+			case "custom":
+				if (resultOptions.merger) return resultOptions.merger(limitedResults);
+				throw new Error("Custom result strategy requires a merger function");
+			default: return limitedResults;
+		}
+	}
+	async executePipeline(context, autoAbortController, autoAbortOptions) {
+		const createController = (_registration, _index) => {
+			return {
+				next: () => {},
 				abort: (reason) => {
-					shouldContinue = false;
-					this.logger.warn(`Pipeline aborted: ${reason}`);
+					context.aborted = true;
+					context.abortReason = reason;
+					if (autoAbortController && autoAbortOptions?.allowHandlerAbort) autoAbortController.abort(reason);
 				},
 				modifyPayload: (modifier) => {
-					modifiedPayload = modifier(modifiedPayload);
-					this.logger.trace(`Payload modified for action: ${String(action)}`);
+					context.payload = modifier(context.payload);
+				},
+				getPayload: () => context.payload,
+				jumpToPriority: (priority) => {
+					context.jumpToPriority = priority;
+				},
+				return: (result) => {
+					context.terminated = true;
+					context.terminationResult = result;
+				},
+				setResult: (result) => {
+					context.results.push(result);
+				},
+				getResults: () => {
+					return [...context.results];
+				},
+				mergeResult: (merger) => {
+					const currentResult = context.results[context.results.length - 1];
+					const previousResults = context.results.slice(0, -1);
+					const mergedResult = merger(previousResults, currentResult);
+					context.results[context.results.length - 1] = mergedResult;
 				}
 			};
-			try {
-				if (config.blocking) await handler(modifiedPayload, controller);
-				else handler(modifiedPayload, controller);
-			} catch (error) {
-				this.logger.error(`Error in pipeline handler for action: ${String(action)}`, error);
-				if (config.blocking) throw error;
-			}
+		};
+		switch (context.executionMode) {
+			case "sequential":
+				await executeSequential(context, createController);
+				break;
+			case "parallel":
+				await executeParallel(context, createController);
+				break;
+			case "race":
+				await executeRace(context, createController);
+				break;
+			default: throw new Error(`Unknown execution mode: ${context.executionMode}`);
 		}
-		this.logger.debug(`Completed dispatching action: ${String(action)}`);
+		this.cleanupOneTimeHandlers(context.action, context.handlers);
 	}
-	sortPipeline(action) {
+	cleanupOneTimeHandlers(action, executedHandlers) {
 		const pipeline = this.pipelines.get(action);
 		if (!pipeline) return;
-		const sorted = Array.from(pipeline.entries()).sort(([, a], [, b]) => {
-			const priorityA = a.config.priority ?? 0;
-			const priorityB = b.config.priority ?? 0;
-			return priorityB - priorityA;
+		const oneTimeHandlers = executedHandlers.filter((reg) => reg.config.once);
+		if (oneTimeHandlers.length === 0) return;
+		oneTimeHandlers.forEach((registration) => {
+			const index = pipeline.findIndex((reg) => reg.id === registration.id);
+			if (index !== -1) {
+				pipeline.splice(index, 1);
+				if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 One-time handler removed: ${String(action)}`, {
+					handlerId: registration.id,
+					remainingHandlers: pipeline.length,
+					registry: this.name
+				});
+			}
+		});
+	}
+	/**
+	* 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
 		});
-		pipeline.clear();
-		sorted.forEach(([id, data]) => pipeline.set(id, data));
-		this.logger.trace(`Sorted pipeline for action: ${String(action)}`, {
-			handlerCount: sorted.length,
-			priorities: sorted.map(([, data]) => data.config.priority ?? 0)
+		const stats = this.executionStats.get(action);
+		stats.totalExecutions++;
+		stats.totalDuration += duration;
+		if (success) stats.successCount++;
+		else stats.errorCount++;
+	}
+	getHandlerCount(action) {
+		const pipeline = this.pipelines.get(action);
+		return pipeline ? pipeline.length : 0;
+	}
+	hasHandlers(action) {
+		return this.getHandlerCount(action) > 0;
+	}
+	getRegisteredActions() {
+		return Array.from(this.pipelines.keys());
+	}
+	clearAction(action) {
+		this.pipelines.delete(action);
+	}
+	clearAll() {
+		this.pipelines.clear();
+	}
+	getName() {
+		return this.name;
+	}
+	/**
+	* Get comprehensive registry information (similar to DeclarativeStoreRegistry pattern)
+	* 
+	* @returns Registry information including actions, handlers, and execution modes
+	*/
+	getRegistryInfo() {
+		const totalHandlers = Array.from(this.pipelines.values()).reduce((total, pipeline) => total + pipeline.length, 0);
+		return {
+			name: this.name,
+			totalActions: this.pipelines.size,
+			totalHandlers,
+			registeredActions: Array.from(this.pipelines.keys()),
+			actionExecutionModes: new Map(this.actionExecutionModes),
+			defaultExecutionMode: this.executionMode
+		};
+	}
+	/**
+	* Get detailed statistics for a specific action
+	* 
+	* @param action Action name to get statistics for
+	* @returns Detailed handler statistics
+	*/
+	getActionStats(action) {
+		const pipeline = this.pipelines.get(action);
+		if (!pipeline) return null;
+		const priorityMap = /* @__PURE__ */ new Map();
+		pipeline.forEach((handler) => {
+			if (!priorityMap.has(handler.config.priority)) priorityMap.set(handler.config.priority, []);
+			priorityMap.get(handler.config.priority).push(handler);
 		});
+		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
+			}))
+		}));
+		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;
+		return {
+			action,
+			handlerCount: pipeline.length,
+			handlersByPriority,
+			executionStats
+		};
+	}
+	/**
+	* Get statistics for all registered actions
+	* 
+	* @returns Array of statistics for all actions
+	*/
+	getAllActionStats() {
+		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
+	* @param mode Execution mode to set
+	*/
+	setActionExecutionMode(action, mode) {
+		this.actionExecutionModes.set(action, mode);
+		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Execution mode set for action '${String(action)}': ${mode}`);
+	}
+	/**
+	* Get execution mode for a specific action
+	* 
+	* @param action Action name
+	* @returns Execution mode for the action, or default if not set
+	*/
+	getActionExecutionMode(action) {
+		return this.actionExecutionModes.get(action) || this.executionMode;
+	}
+	/**
+	* Remove execution mode override for a specific action
+	* 
+	* @param action Action name
+	*/
+	removeActionExecutionMode(action) {
+		this.actionExecutionModes.delete(action);
+		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
+	*/
+	getRegistryConfig() {
+		return this.registryConfig;
+	}
+	/**
+	* Check if registry has debug mode enabled
+	* 
+	* @returns Whether debug mode is enabled
+	*/
+	isDebugEnabled() {
+		return Boolean(this.registryConfig?.debug && process.env.NODE_ENV === "development");
 	}
 };
 
 //#endregion
-//#region src/types.ts
-function createAction(type, payload) {
-	return {
-		type,
-		payload
-	};
-}
-function isAction(action, type) {
-	return action?.type === type;
-}
-
-//#endregion
+exports.ActionGuard = ActionGuard;
 exports.ActionRegister = ActionRegister;
-exports.ConsoleLogger = ConsoleLogger;
-exports.LogLevel = LogLevel;
-exports.OtelConsoleLogger = OtelConsoleLogger;
-exports.createAction = createAction;
-exports.createOtelContextFromPayload = createOtelContextFromPayload;
-exports.extractSessionIdFromPayload = extractSessionIdFromPayload;
-exports.extractTraceIdFromPayload = extractTraceIdFromPayload;
-exports.getLogLevelFromEnv = getLogLevelFromEnv;
-exports.isAction = isAction;
-exports.parseLogLevel = parseLogLevel;
+exports.executeParallel = executeParallel;
+exports.executeRace = executeRace;
+exports.executeSequential = executeSequential;