@context-action/core 0.0.3 → 0.0.4

package/dist/index.cjs

@@ -24,7 +24,199 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+const __context_action_logger = __toESM(require("@context-action/logger"));
 
+//#region src/execution-modes.ts
+/**
+* Execute handlers in sequential mode (one after another)
+* @implements execution-modes
+* @implements sequential-execution
+* @memberof core-concepts
+* @internal
+* @since 1.0.0
+* 
+* Executes action handlers sequentially in priority order, supporting flow control,
+* conditional execution, and priority jumping within the pipeline.
+* 
+* @template T - The type of the payload being processed
+* @param context - Pipeline execution context with handlers and state
+* @param createController - Factory function for creating pipeline controllers
+* @param logger - Logger instance for tracing execution
+* @returns Promise that resolves when all handlers complete or pipeline aborts
+* 
+* Features:
+* - Priority-based execution order (higher priority first)
+* - Support for priority jumping within execution
+* - Conditional handler execution (condition/validation checks)
+* - Blocking/non-blocking handler support
+* - Comprehensive error handling and recovery
+*/
+async function executeSequential(context, createController, logger) {
+	logger.trace("Executing in sequential mode", { handlerCount: context.handlers.length });
+	for (let i = 0; i < context.handlers.length; i++) {
+		if (context.aborted) {
+			logger.trace("Sequential execution aborted", {
+				atIndex: i,
+				reason: context.abortReason
+			});
+			break;
+		}
+		if (context.jumpToPriority !== void 0) {
+			const jumpIndex = context.handlers.findIndex((handler) => handler.config.priority === context.jumpToPriority);
+			if (jumpIndex !== -1 && jumpIndex !== i) {
+				logger.trace("Jumping to priority", {
+					fromIndex: i,
+					toIndex: jumpIndex,
+					priority: context.jumpToPriority
+				});
+				i = jumpIndex - 1;
+				context.jumpToPriority = void 0;
+				continue;
+			}
+			context.jumpToPriority = void 0;
+		}
+		const registration = context.handlers[i];
+		context.currentIndex = i;
+		if (registration.config.condition && !registration.config.condition()) {
+			logger.debug(`Skipping handler '${registration.id}' - condition not met`);
+			continue;
+		}
+		if (registration.config.validation && !registration.config.validation(context.payload)) {
+			logger.debug(`Skipping handler '${registration.id}' - validation failed`);
+			continue;
+		}
+		const controller = createController(registration, i);
+		try {
+			logger.trace(`Executing handler ${i + 1}/${context.handlers.length}`, {
+				handlerId: registration.id,
+				priority: registration.config.priority
+			});
+			const result = registration.handler(context.payload, controller);
+			if (registration.config.blocking && result instanceof Promise) {
+				logger.trace(`Waiting for blocking handler '${registration.id}'`);
+				await result;
+			}
+			logger.trace(`Handler '${registration.id}' completed`);
+		} catch (error) {
+			logger.error(`Handler '${registration.id}' threw an error`, error);
+			if (registration.config.blocking) throw error;
+		}
+	}
+}
+/**
+* Execute handlers in parallel mode (all at once)
+* @internal
+*/
+async function executeParallel(context, createController, logger) {
+	logger.trace("Executing in parallel mode", { handlerCount: context.handlers.length });
+	const runnableHandlers = context.handlers.filter((registration, _index) => {
+		if (registration.config.condition && !registration.config.condition()) {
+			logger.debug(`Skipping handler '${registration.id}' - condition not met`);
+			return false;
+		}
+		if (registration.config.validation && !registration.config.validation(context.payload)) {
+			logger.debug(`Skipping handler '${registration.id}' - validation failed`);
+			return false;
+		}
+		return true;
+	});
+	logger.trace(`Running ${runnableHandlers.length} handlers in parallel`);
+	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
+		const controller = createController(registration, _index);
+		try {
+			logger.trace(`Starting parallel handler '${registration.id}'`);
+			const result = registration.handler(context.payload, controller);
+			if (result instanceof Promise) await result;
+			logger.trace(`Parallel handler '${registration.id}' completed`);
+			return {
+				success: true,
+				handlerId: registration.id
+			};
+		} catch (error) {
+			logger.error(`Parallel handler '${registration.id}' failed`, error);
+			if (registration.config.blocking) throw error;
+			return {
+				success: false,
+				handlerId: registration.id,
+				error
+			};
+		}
+	});
+	const results = await Promise.allSettled(handlerPromises);
+	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;
+	}
+	logger.trace("Parallel execution completed", {
+		successful: results.filter((r) => r.status === "fulfilled").length,
+		failed: results.filter((r) => r.status === "rejected").length
+	});
+}
+/**
+* Execute handlers in race mode (first to complete wins)
+* @internal
+*/
+async function executeRace(context, createController, logger) {
+	logger.trace("Executing in race mode", { handlerCount: context.handlers.length });
+	const runnableHandlers = context.handlers.filter((registration, _index) => {
+		if (registration.config.condition && !registration.config.condition()) {
+			logger.debug(`Skipping handler '${registration.id}' - condition not met`);
+			return false;
+		}
+		if (registration.config.validation && !registration.config.validation(context.payload)) {
+			logger.debug(`Skipping handler '${registration.id}' - validation failed`);
+			return false;
+		}
+		return true;
+	});
+	if (runnableHandlers.length === 0) {
+		logger.trace("No runnable handlers for race mode");
+		return;
+	}
+	logger.trace(`Racing ${runnableHandlers.length} handlers`);
+	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
+		const controller = createController(registration, _index);
+		try {
+			logger.trace(`Starting race handler '${registration.id}'`);
+			const result = registration.handler(context.payload, controller);
+			if (result instanceof Promise) await result;
+			logger.trace(`Race handler '${registration.id}' completed`);
+			return {
+				success: true,
+				handlerId: registration.id,
+				registration
+			};
+		} catch (error) {
+			logger.error(`Race handler '${registration.id}' failed`, error);
+			return {
+				success: false,
+				handlerId: registration.id,
+				error,
+				registration
+			};
+		}
+	});
+	try {
+		const winner = await Promise.race(handlerPromises);
+		logger.debug("Race completed", {
+			winner: winner.handlerId,
+			success: winner.success
+		});
+		if (!winner.success && winner.registration?.config.blocking) throw winner.error;
+	} catch (error) {
+		logger.error("Race execution failed", error);
+		throw error;
+	}
+}
+
+//#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,346 +275,616 @@ 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
+* Action Guard system for managing action execution timing
+* @implements action-guard
+* @implements performance-optimization  
+* @implements user-experience-optimization
+* @memberof core-concepts
+* @internal
+* @since 1.0.0
+* 
+* Provides debouncing, throttling, and blocking mechanisms for action execution
+* to optimize performance and enhance user experience. Manages timing state
+* per action to prevent unnecessary or excessive action invocations.
+* 
+* Key Features:
+* - Debouncing: Delay execution until activity stops
+* - Throttling: Limit execution frequency to intervals
+* - Per-action state management with automatic cleanup
+* - Memory leak prevention through proper timer management
+* 
+* @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 ConsoleLogger = class {
-	constructor(level = LogLevel.ERROR) {
-		this.level = level;
-	}
-	shouldLog(level) {
-		return level >= this.level;
-	}
-	formatMessage(level, message) {
-		return `[${level.toUpperCase()}] ${message}`;
+var ActionGuard = class {
+	constructor(logger) {
+		(0, import_defineProperty$1.default)(this, "guards", /* @__PURE__ */ new Map());
+		(0, import_defineProperty$1.default)(this, "logger", void 0);
+		this.logger = logger;
 	}
-	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);
+	/**
+	* 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) {
+		this.logger.trace(`Checking debounce for '${actionKey}'`, { debounceMs });
+		let state = this.guards.get(actionKey);
+		if (!state) {
+			state = {
+				lastExecuted: 0,
+				isThrottled: false
+			};
+			this.guards.set(actionKey, state);
+		}
+		if (state.debounceTimer) {
+			clearTimeout(state.debounceTimer);
+			this.logger.trace(`Cleared existing debounce timer for '${actionKey}'`);
+		}
+		return new Promise((resolve) => {
+			state.debounceTimer = setTimeout(() => {
+				this.logger.trace(`Debounce completed for '${actionKey}'`);
+				state.debounceTimer = void 0;
+				state.lastExecuted = Date.now();
+				resolve(true);
+			}, debounceMs);
+			this.logger.trace(`Set debounce timer for '${actionKey}'`, { delay: debounceMs });
+		});
 	}
-	info(message, ...args) {
-		if (this.shouldLog(LogLevel.INFO)) console.info(this.formatMessage("info", 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) {
+		this.logger.trace(`Checking throttle for '${actionKey}'`, { throttleMs });
+		let state = this.guards.get(actionKey);
+		if (!state) {
+			state = {
+				lastExecuted: 0,
+				isThrottled: false
+			};
+			this.guards.set(actionKey, state);
+		}
+		const now = Date.now();
+		const timeSinceLastExecution = now - state.lastExecuted;
+		if (timeSinceLastExecution >= throttleMs) {
+			state.lastExecuted = now;
+			state.isThrottled = false;
+			this.logger.trace(`Throttle passed for '${actionKey}'`, {
+				timeSinceLastExecution,
+				throttleMs
+			});
+			return true;
+		}
+		if (state.isThrottled) {
+			this.logger.trace(`Action '${actionKey}' is already throttled`);
+			return false;
+		}
+		state.isThrottled = true;
+		const remainingTime = throttleMs - timeSinceLastExecution;
+		state.throttleTimer = setTimeout(() => {
+			state.isThrottled = false;
+			state.throttleTimer = void 0;
+			this.logger.trace(`Throttle period ended for '${actionKey}'`);
+		}, remainingTime);
+		this.logger.trace(`Action '${actionKey}' throttled`, {
+			timeSinceLastExecution,
+			remainingTime
+		});
+		return false;
 	}
-	warn(message, ...args) {
-		if (this.shouldLog(LogLevel.WARN)) console.warn(this.formatMessage("warn", message), ...args);
+	/**
+	* Clear all guards for an action
+	* @param actionKey - Action key to clear
+	*/
+	clearGuards(actionKey) {
+		this.logger.trace(`Clearing guards for '${actionKey}'`);
+		const state = this.guards.get(actionKey);
+		if (state) {
+			if (state.debounceTimer) clearTimeout(state.debounceTimer);
+			if (state.throttleTimer) clearTimeout(state.throttleTimer);
+			this.guards.delete(actionKey);
+			this.logger.debug(`Cleared guards for '${actionKey}'`);
+		}
 	}
-	error(message, ...args) {
-		if (this.shouldLog(LogLevel.ERROR)) console.error(this.formatMessage("error", message), ...args);
+	/**
+	* Clear all guards
+	*/
+	clearAll() {
+		this.logger.trace("Clearing all action guards");
+		for (const [, state] of this.guards) {
+			if (state.debounceTimer) clearTimeout(state.debounceTimer);
+			if (state.throttleTimer) clearTimeout(state.throttleTimer);
+		}
+		this.guards.clear();
+		this.logger.debug("Cleared all action guards");
 	}
-	fatal(message, ...args) {
-		if (this.shouldLog(LogLevel.FATAL)) console.error(this.formatMessage("fatal", message), ...args);
+	/**
+	* Get current guard state for debugging
+	* @param actionKey - Action key to inspect
+	*/
+	getGuardState(actionKey) {
+		return this.guards.get(actionKey);
 	}
-	setLevel(level) {
-		this.level = level;
+	/**
+	* Get all active guards for debugging
+	*/
+	getAllGuardStates() {
+		return new Map(this.guards);
 	}
 };
+
+//#endregion
+//#region src/ActionRegister.ts
+var import_defineProperty = __toESM(require_defineProperty(), 1);
 /**
-* 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
+* Simple event emitter implementation for ActionRegister events
+* @internal
 */
-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 SimpleEventEmitter = class {
+	constructor() {
+		(0, import_defineProperty.default)(this, "listeners", /* @__PURE__ */ new Map());
+	}
+	on(event, handler) {
+		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+		this.listeners.get(event).add(handler);
+		return () => this.off(event, handler);
+	}
+	emit(event, data) {
+		const eventListeners = this.listeners.get(event);
+		if (eventListeners) eventListeners.forEach((handler) => {
+			try {
+				handler(data);
+			} catch (error) {
+				console.error(`Error in event handler for ${String(event)}:`, error);
+			}
+		});
 	}
-	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;
+	off(event, handler) {
+		const eventListeners = this.listeners.get(event);
+		if (eventListeners) {
+			eventListeners.delete(handler);
+			if (eventListeners.size === 0) this.listeners.delete(event);
 		}
 	}
-	trace(message, ...args) {
-		this.logWithContext(LogLevel.TRACE, message, ...args);
-	}
-	debug(message, ...args) {
-		this.logWithContext(LogLevel.DEBUG, message, ...args);
-	}
-	info(message, ...args) {
-		this.logWithContext(LogLevel.INFO, message, ...args);
-	}
-	warn(message, ...args) {
-		this.logWithContext(LogLevel.WARN, message, ...args);
-	}
-	error(message, ...args) {
-		this.logWithContext(LogLevel.ERROR, message, ...args);
-	}
-	fatal(message, ...args) {
-		this.logWithContext(LogLevel.FATAL, message, ...args);
+	removeAllListeners(event) {
+		if (event) this.listeners.delete(event);
+		else this.listeners.clear();
 	}
 };
-
-//#endregion
-//#region src/ActionRegister.ts
-var import_defineProperty = __toESM(require_defineProperty(), 1);
 /**
-* Core action pipeline management system
+* Central action registration and dispatch system
+* @implements action-pipeline-system
+* @implements actionregister  
+* @memberof core-concepts
+* 
+* Core action pipeline management system with type-safe action dispatch
 * @template T - Action payload map defining available actions and their payload types
+* 
 * @example
 * ```typescript
 * interface AppActions extends ActionPayloadMap {
 *   increment: void;
 *   setCount: number;
+*   updateUser: { id: string; name: string };
 * }
-* 
+*
 * const actionRegister = new ActionRegister<AppActions>();
-* 
-* // Register handlers
-* actionRegister.register('increment', () => console.log('Incremented'));
-* actionRegister.register('setCount', (count) => console.log(`Count: ${count}`));
-* 
-* // Dispatch actions
+*
+* // Register handlers with priority and configuration
+* actionRegister.register('increment', (_, controller) => {
+*   console.log('Incremented');
+*   controller.next();
+* }, { priority: 10 });
+*
+* actionRegister.register('setCount', (count, controller) => {
+*   console.log(`Count: ${count}`);
+*   controller.next();
+* });
+*
+* // Dispatch actions with type safety
 * await actionRegister.dispatch('increment');
 * await actionRegister.dispatch('setCount', 42);
 * ```
 */
 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, "events", new SimpleEventEmitter());
+		(0, import_defineProperty.default)(this, "config", void 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,
+			/**
+			* Dispatch action through pipeline
+			* @implements action-dispatcher
+			* 
+			* Dispatch an action through the pipeline
+			* Overloaded to provide type safety for actions with and without payloads
+			*/
+			"dispatch",
+			async (action, payload) => {
+				const startTime = Date.now();
+				this.logger.trace(`Starting dispatch for action '${String(action)}'`, {
+					action,
+					payload,
+					startTime
+				});
+				this.events.emit("action:start", {
+					action,
+					payload
+				});
+				this.logger.trace(`Emitted 'action:start' event`);
+				this.logger.debug(`Dispatching action '${String(action)}'`, { payload });
+				const pipeline = this.pipelines.get(action);
+				if (!pipeline || pipeline.length === 0) {
+					this.logger.warn(`No handlers registered for action '${String(action)}'`);
+					this.logger.trace(`Dispatch completed early - no handlers`);
+					return;
+				}
+				this.logger.trace(`Found ${pipeline.length} handlers for action '${String(action)}'`, { handlerIds: pipeline.map((reg) => reg.id) });
+				const currentExecutionMode = this.actionExecutionModes.get(action) || this.executionMode;
+				const context = {
+					action: String(action),
+					payload,
+					handlers: [...pipeline],
+					aborted: false,
+					abortReason: void 0,
+					currentIndex: 0,
+					jumpToPriority: void 0,
+					executionMode: currentExecutionMode
+				};
+				try {
+					await this.executePipeline(context);
+					const metrics = {
+						action: String(action),
+						executionTime: Date.now() - startTime,
+						handlerCount: context.handlers.length,
+						success: !context.aborted,
+						timestamp: Date.now()
+					};
+					if (context.aborted) {
+						metrics.error = context.abortReason;
+						this.events.emit("action:abort", {
+							action,
+							payload,
+							reason: context.abortReason
+						});
+					} else this.events.emit("action:complete", {
+						action,
+						payload,
+						metrics
+					});
+					this.logger.debug(`Completed action '${String(action)}'`, metrics);
+				} catch (error) {
+					const metrics = {
+						action: String(action),
+						executionTime: Date.now() - startTime,
+						handlerCount: context.handlers.length,
+						success: false,
+						error: error.message || "Unknown error",
+						timestamp: Date.now()
+					};
+					this.logger.error(`Error executing action '${String(action)}'`, metrics);
+					this.events.emit("action:error", {
+						action,
+						payload,
+						error: error instanceof Error ? error : new Error(String(error))
+					});
+					throw error;
+				}
+			}
+		);
+		this.config = {
+			logger: config.logger || (0, __context_action_logger.createLogger)(config.logLevel),
+			logLevel: config.logLevel ?? 3,
+			name: config.name || (0, __context_action_logger.getLoggerNameFromEnv)(),
+			debug: config.debug ?? (0, __context_action_logger.getDebugFromEnv)(),
+			defaultExecutionMode: config.defaultExecutionMode ?? "sequential"
+		};
+		this.logger = this.config.logger;
+		this.actionGuard = new ActionGuard(this.logger);
+		this.executionMode = this.config.defaultExecutionMode;
+		this.logger.trace(`${this.config.name} constructor called`, { config });
+		if (this.config.debug) this.logger.info(`${this.config.name} initialized`, {
+			logLevel: this.config.logLevel,
+			debug: this.config.debug,
+			defaultExecutionMode: this.executionMode
 		});
+		this.logger.trace(`${this.config.name} constructor completed`);
 	}
 	/**
+	* Register action handler with pipeline
+	* @implements action-handler
+	* 
 	* 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 });
+	* const unregister = actionRegister.register('updateUser', 
+	*   async (payload, controller) => {
+	*     // Validate payload
+	*     if (!payload.id) {
+	*       controller.abort('User ID is required');
+	*       return;
+	*     }
+	*     
+	*     // Process update
+	*     await updateUserInStore(payload);
+	*     controller.next();
+	*   }, 
+	*   { priority: 10, blocking: true }
+	* );
 	* 
 	* // Later, remove the handler
 	* unregister();
 	* ```
 	*/
 	register(action, handler, config = {}) {
+		this.logger.trace(`Registering handler for action '${String(action)}'`, { config });
+		const handlerId = config.id || `handler_${++this.handlerCounter}`;
+		this.logger.trace(`Generated handler ID: ${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,
+				throttle: config.throttle,
+				validation: config.validation,
+				middleware: config.middleware ?? false
+			},
+			id: handlerId
+		};
+		this.logger.trace(`Created handler registration`, { registration: {
+			id: handlerId,
+			config: registration.config
+		} });
 		if (!this.pipelines.has(action)) {
-			this.pipelines.set(action, /* @__PURE__ */ new Map());
-			this.logger.debug(`Created new pipeline for action: ${String(action)}`);
+			this.logger.trace(`Creating new pipeline for action: ${String(action)}`);
+			this.pipelines.set(action, []);
+			this.logger.debug(`Created 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)}`);
+		this.logger.trace(`Current pipeline for '${String(action)}' has ${pipeline.length} handlers`);
+		if (pipeline.some((reg) => reg.id === handlerId)) {
+			this.logger.warn(`Handler with ID '${handlerId}' already exists for action '${String(action)}'`);
+			this.logger.trace(`Duplicate handler registration aborted`);
 			return () => {};
 		}
-		pipeline.set(handlerId, {
-			handler,
-			config
+		pipeline.push(registration);
+		this.logger.trace(`Added handler to pipeline, current length: ${pipeline.length}`);
+		pipeline.sort((a, b) => b.config.priority - a.config.priority);
+		this.logger.trace(`Pipeline sorted by priority`, { priorities: pipeline.map((reg) => ({
+			id: reg.id,
+			priority: reg.config.priority
+		})) });
+		this.logger.debug(`Registered handler for action '${String(action)}'`, {
+			handlerId,
+			priority: registration.config.priority,
+			blocking: registration.config.blocking,
+			once: registration.config.once
 		});
-		this.logger.debug(`Registered handler for action: ${String(action)}`, {
+		this.events.emit("handler:register", {
+			action,
 			handlerId,
-			priority: config.priority ?? 0,
-			blocking: config.blocking ?? false
+			config: registration.config
 		});
-		this.sortPipeline(action);
 		return () => {
-			pipeline.delete(handlerId);
-			this.logger.debug(`Unregistered handler: ${handlerId} for action: ${String(action)}`);
+			this.logger.trace(`Unregistering handler '${handlerId}' from action '${String(action)}'`);
+			const index = pipeline.findIndex((reg) => reg.id === handlerId);
+			if (index !== -1) {
+				pipeline.splice(index, 1);
+				this.logger.debug(`Unregistered handler '${handlerId}' from action '${String(action)}'`);
+				this.logger.trace(`Pipeline now has ${pipeline.length} handlers`);
+				this.events.emit("handler:unregister", {
+					action,
+					handlerId
+				});
+			} else this.logger.trace(`Handler '${handlerId}' not found in pipeline for unregistration`);
 		};
 	}
-	registerAtomSetter(name, setter) {
-		this.atomSetters.set(name, setter);
-		this.logger.debug(`Registered atom setter: ${name}`);
-	}
 	/**
-	* Internal dispatch implementation
+	* Execute the pipeline with proper flow control
 	* @internal
 	*/
-	async dispatch(action, payload) {
-		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);
-		}
-		this.logger.debug(`Dispatching action: ${String(action)}`, { payload });
-		if (!pipeline || pipeline.size === 0) {
-			this.logger.warn(`No handlers registered for action: ${String(action)}`);
-			return;
-		}
-		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;
-				},
+	async executePipeline(context) {
+		this.logger.trace(`Starting pipeline execution`, {
+			action: context.action,
+			handlerCount: context.handlers.length,
+			executionMode: context.executionMode,
+			payload: context.payload
+		});
+		const createController = (registration, _index) => {
+			return {
+				next: () => {},
 				abort: (reason) => {
-					shouldContinue = false;
-					this.logger.warn(`Pipeline aborted: ${reason}`);
+					this.logger.trace(`Handler '${registration.id}' is aborting pipeline`, { reason });
+					context.aborted = true;
+					context.abortReason = reason;
+					this.logger.warn(`Pipeline aborted by handler '${registration.id}'`, { reason });
 				},
 				modifyPayload: (modifier) => {
-					modifiedPayload = modifier(modifiedPayload);
-					this.logger.trace(`Payload modified for action: ${String(action)}`);
+					this.logger.trace(`Handler '${registration.id}' is modifying payload`);
+					const oldPayload = context.payload;
+					context.payload = modifier(context.payload);
+					this.logger.debug(`Payload modified by handler '${registration.id}'`);
+					this.logger.trace(`Payload change`, {
+						oldPayload,
+						newPayload: context.payload
+					});
+				},
+				getPayload: () => context.payload,
+				jumpToPriority: (priority) => {
+					this.logger.trace(`Handler '${registration.id}' jumping to priority ${priority}`);
+					context.jumpToPriority = priority;
 				}
 			};
-			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, this.logger);
+				break;
+			case "parallel":
+				await executeParallel(context, createController, this.logger);
+				break;
+			case "race":
+				await executeRace(context, createController, this.logger);
+				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) {
+	/**
+	* Clean up one-time handlers after pipeline execution
+	* @internal
+	*/
+	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;
+		this.logger.trace(`Cleaning up ${oneTimeHandlers.length} one-time handlers`);
+		oneTimeHandlers.forEach((registration) => {
+			const index = pipeline.findIndex((reg) => reg.id === registration.id);
+			if (index !== -1) {
+				pipeline.splice(index, 1);
+				this.logger.debug(`Removed one-time handler '${registration.id}'`);
+			}
+		});
+		this.logger.trace(`Pipeline now has ${pipeline.length} handlers`);
+	}
+	/**
+	* Get the number of handlers registered for an action
+	* @param action - The action to check
+	* @returns Number of handlers registered
+	*/
+	getHandlerCount(action) {
+		const pipeline = this.pipelines.get(action);
+		const count = pipeline ? pipeline.length : 0;
+		this.logger.trace(`Handler count for '${String(action)}': ${count}`);
+		return count;
+	}
+	/**
+	* Check if any handlers are registered for an action
+	* @param action - The action to check
+	* @returns True if handlers are registered
+	*/
+	hasHandlers(action) {
+		const hasHandlers = this.getHandlerCount(action) > 0;
+		this.logger.trace(`Has handlers for '${String(action)}': ${hasHandlers}`);
+		return hasHandlers;
+	}
+	/**
+	* Get all registered action names
+	* @returns Array of action names
+	*/
+	getRegisteredActions() {
+		const actions = Array.from(this.pipelines.keys());
+		this.logger.trace(`Registered actions`, {
+			actions,
+			count: actions.length
+		});
+		return actions;
+	}
+	/**
+	* Clear all handlers for a specific action
+	* @param action - The action to clear
+	*/
+	clearAction(action) {
+		this.logger.trace(`Clearing handlers for action '${String(action)}'`);
+		const pipeline = this.pipelines.get(action);
+		if (pipeline) {
+			const handlerCount = pipeline.length;
+			this.pipelines.delete(action);
+			this.logger.debug(`Cleared ${handlerCount} handlers for action '${String(action)}'`);
+			this.logger.trace(`Action '${String(action)}' pipeline removed`);
+		} else this.logger.trace(`No pipeline found for action '${String(action)}' to clear`);
+	}
+	/**
+	* Clear all handlers for all actions
+	*/
+	clearAll() {
+		this.logger.trace(`Clearing all handlers and pipelines`);
+		const actionCount = this.pipelines.size;
+		const totalHandlers = Array.from(this.pipelines.values()).reduce((sum, pipeline) => sum + pipeline.length, 0);
+		this.logger.trace(`Before clear`, {
+			actionCount,
+			totalHandlers
 		});
-		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)
+		this.pipelines.clear();
+		this.events.removeAllListeners();
+		this.logger.info(`Cleared all handlers`, {
+			actionCount,
+			totalHandlers
 		});
+		this.logger.trace(`All pipelines and event listeners cleared`);
+	}
+	/**
+	* Add event listener for ActionRegister events
+	* @param event - Event name to listen for
+	* @param handler - Event handler function
+	* @returns Unregister function to remove the listener
+	*/
+	on(event, handler) {
+		return this.events.on(event, handler);
+	}
+	/**
+	* Remove event listener
+	* @param event - Event name
+	* @param handler - Event handler to remove
+	*/
+	off(event, handler) {
+		this.events.off(event, handler);
+	}
+	/**
+	* Get current configuration
+	* @returns Current ActionRegister configuration
+	*/
+	getConfig() {
+		return { ...this.config };
+	}
+	/**
+	* Get logger instance
+	* @returns Current logger instance
+	*/
+	getLogger() {
+		return this.logger;
 	}
 };
 
 //#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;