@context-action/core 0.0.2 → 0.0.4

package/dist/index.js

@@ -1,3 +1,5 @@
+import { createLogger, getDebugFromEnv, getLoggerNameFromEnv } from "@context-action/logger";
+
 //#region rolldown:runtime
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -23,6 +25,197 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 
+//#endregion
+//#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) {
@@ -70,7 +263,7 @@ var require_toPropertyKey = __commonJS({ "../../node_modules/.pnpm/@oxc-project+
 //#region ../../node_modules/.pnpm/@oxc-project+runtime@0.77.3/node_modules/@oxc-project/runtime/src/helpers/defineProperty.js
 var require_defineProperty = __commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.77.3/node_modules/@oxc-project/runtime/src/helpers/defineProperty.js"(exports, module) {
 	var toPropertyKey = require_toPropertyKey();
-	function _defineProperty$1(e, r, t) {
+	function _defineProperty$2(e, r, t) {
 		return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 			value: t,
 			enumerable: !0,
@@ -78,94 +271,617 @@ var require_defineProperty = __commonJS({ "../../node_modules/.pnpm/@oxc-project
 			writable: !0
 		}) : e[r] = t, e;
 	}
-	module.exports = _defineProperty$1, module.exports.__esModule = true, module.exports["default"] = module.exports;
+	module.exports = _defineProperty$2, module.exports.__esModule = true, module.exports["default"] = module.exports;
 } });
 
+//#endregion
+//#region src/action-guard.ts
+var import_defineProperty$1 = __toESM(require_defineProperty(), 1);
+/**
+* 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 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;
+	}
+	/**
+	* 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 });
+		});
+	}
+	/**
+	* 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;
+	}
+	/**
+	* 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}'`);
+		}
+	}
+	/**
+	* 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");
+	}
+	/**
+	* Get current guard state for debugging
+	* @param actionKey - Action key to inspect
+	*/
+	getGuardState(actionKey) {
+		return this.guards.get(actionKey);
+	}
+	/**
+	* Get all active guards for debugging
+	*/
+	getAllGuardStates() {
+		return new Map(this.guards);
+	}
+};
+
 //#endregion
 //#region src/ActionRegister.ts
 var import_defineProperty = __toESM(require_defineProperty(), 1);
-var ActionRegister = class {
+/**
+* Simple event emitter implementation for ActionRegister events
+* @internal
+*/
+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);
+			}
+		});
+	}
+	off(event, handler) {
+		const eventListeners = this.listeners.get(event);
+		if (eventListeners) {
+			eventListeners.delete(handler);
+			if (eventListeners.size === 0) this.listeners.delete(event);
+		}
+	}
+	removeAllListeners(event) {
+		if (event) this.listeners.delete(event);
+		else this.listeners.clear();
+	}
+};
+/**
+* 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 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 = {}) {
 		(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);
+		(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 || createLogger(config.logLevel),
+			logLevel: config.logLevel ?? 3,
+			name: config.name || getLoggerNameFromEnv(),
+			debug: config.debug ?? 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('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 = {}) {
-		if (!this.pipelines.has(action)) this.pipelines.set(action, /* @__PURE__ */ new Map());
+		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.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_${Date.now()}_${Math.random()}`;
-		if (pipeline.has(handlerId)) {
-			console.warn(`Handler with id ${handlerId} already exists`);
+		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.events.emit("handler:register", {
+			action,
+			handlerId,
+			config: registration.config
 		});
-		this.sortPipeline(action);
 		return () => {
-			pipeline.delete(handlerId);
+			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);
-	}
-	async dispatch(action, payload) {
-		const pipeline = this.pipelines.get(action);
-		if (!pipeline || pipeline.size === 0) {
-			console.warn(`No handlers registered for action: ${String(action)}`);
-			return;
-		}
-		let modifiedPayload = payload;
-		const handlers = Array.from(pipeline.values());
-		for (const { handler, config } of handlers) {
-			let shouldContinue = true;
-			const controller = {
-				next: () => {
-					shouldContinue = true;
-				},
+	/**
+	* Execute the pipeline with proper flow control
+	* @internal
+	*/
+	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;
-					console.log(`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(`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);
-				if (!shouldContinue) break;
-			} catch (error) {
-				console.error(`Error in pipeline handler:`, 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.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}'`);
+			}
 		});
-		pipeline.clear();
-		sorted.forEach(([id, data]) => pipeline.set(id, data));
+		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
+		});
+		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
-export { ActionRegister, createAction, isAction };
+export { ActionGuard, ActionRegister, executeParallel, executeRace, executeSequential };
 //# sourceMappingURL=index.js.map