@context-action/core 0.0.3 → 0.0.4

package/dist/index.d.cts

@@ -1,244 +1,670 @@
-//#region src/logger.d.ts
-/**
- * Log levels in order of severity (lowest to highest)
- */
-declare enum LogLevel {
-  TRACE = 0,
-  DEBUG = 1,
-  INFO = 2,
-  WARN = 3,
-  ERROR = 4,
-  FATAL = 5,
-}
-/**
- * Logger interface for custom logger implementations
- */
-interface Logger {
-  trace(message: string, ...args: any[]): void;
-  debug(message: string, ...args: any[]): void;
-  info(message: string, ...args: any[]): void;
-  warn(message: string, ...args: any[]): void;
-  error(message: string, ...args: any[]): void;
-  fatal(message: string, ...args: any[]): void;
-}
-/**
- * Default console logger implementation
- */
-declare class ConsoleLogger implements Logger {
-  private level;
-  constructor(level?: LogLevel);
-  protected shouldLog(level: LogLevel): boolean;
-  private formatMessage;
-  trace(message: string, ...args: any[]): void;
-  debug(message: string, ...args: any[]): void;
-  info(message: string, ...args: any[]): void;
-  warn(message: string, ...args: any[]): void;
-  error(message: string, ...args: any[]): void;
-  fatal(message: string, ...args: any[]): void;
-  setLevel(level: LogLevel): void;
-}
-/**
- * Parse log level from string
- */
-declare function parseLogLevel(level: string): LogLevel;
-/**
- * Get log level from environment variable or default to ERROR
- */
-declare function getLogLevelFromEnv(): LogLevel;
-/**
- * Extract trace ID from payload if it exists
- */
-declare function extractTraceIdFromPayload(payload: any): string | undefined;
-/**
- * Extract session ID from payload if it exists
- */
-declare function extractSessionIdFromPayload(payload: any): string | undefined;
-/**
- * Create OTEL context from payload
- */
-declare function createOtelContextFromPayload(payload: any): OtelContext;
+import { LogLevel, Logger } from "@context-action/logger";
+
+//#region src/types.d.ts
+
 /**
- * OpenTelemetry context interface for tracing
+ * Base interface for defining action payload mappings
+ * @implements action-payload-map
+ * @implements type-safety
+ * @implements compile-time-validation
+ * @memberof core-concepts
+ * @since 1.0.0
+ *
+ * Maps action names to their corresponding payload types for type-safe dispatch
+ *
+ * @example
+ * ```typescript
+ * interface MyActions extends ActionPayloadMap {
+ *   increment: void;
+ *   setCount: number;
+ *   updateUser: { id: string; name: string };
+ *   deleteUser: { id: string };
+ * }
+ * ```
  */
-interface OtelContext {
-  /** Session ID for tracking user sessions */
-  sessionId?: string;
-  /** Trace ID for distributed tracing */
-  traceId?: string;
-  /** Span ID for current operation */
-  spanId?: string;
-  /** Parent span ID for operation hierarchy */
-  parentSpanId?: string;
-  /** Additional context metadata */
-  metadata?: Record<string, any>;
-}
-/**
- * Extended logger interface with OpenTelemetry support
- */
-interface OtelLogger extends Logger {
-  /** Set OpenTelemetry context */
-  setContext(context: OtelContext): void;
-  /** Get current OpenTelemetry context */
-  getContext(): OtelContext;
-  /** Clear OpenTelemetry context */
-  clearContext(): void;
-  /** Log with OpenTelemetry context */
-  logWithContext(level: LogLevel, message: string, ...args: any[]): void;
+interface ActionPayloadMap {
+  [actionName: string]: unknown;
 }
-/**
- * OpenTelemetry-aware console logger implementation
- */
-declare class OtelConsoleLogger extends ConsoleLogger implements OtelLogger {
-  private context;
-  constructor(level?: LogLevel);
-  setContext(context: OtelContext): void;
-  getContext(): OtelContext;
-  clearContext(): void;
-  private formatWithContext;
-  logWithContext(level: LogLevel, message: string, ...args: any[]): void;
-  trace(message: string, ...args: any[]): void;
-  debug(message: string, ...args: any[]): void;
-  info(message: string, ...args: any[]): void;
-  warn(message: string, ...args: any[]): void;
-  error(message: string, ...args: any[]): void;
-  fatal(message: string, ...args: any[]): void;
-}
-//# sourceMappingURL=logger.d.ts.map
-//#endregion
-//#region src/ActionRegister.d.ts
 /**
  * Controller object provided to action handlers for pipeline management
+ * @implements pipeline-controller
+ * @memberof core-concepts
+ * @since 1.0.0
+ *
+ * Provides methods for controlling pipeline flow and payload modification
+ *
  * @template T - The type of the payload being processed
  */
-type PipelineController<T = any> = {
+interface PipelineController<T = any> {
   /** Continue to the next handler in the pipeline */
-  next: () => void;
+  next(): void;
   /** Abort the pipeline execution with an optional reason */
-  abort: (reason?: string) => void;
+  abort(reason?: string): void;
   /** Modify the payload that will be passed to subsequent handlers */
-  modifyPayload: (modifier: (payload: T) => T) => void;
-};
+  modifyPayload(modifier: (payload: T) => T): void;
+  /** Get the current payload */
+  getPayload(): T;
+  /** Jump to a specific priority level in the pipeline */
+  jumpToPriority(priority: number): void;
+}
 /**
- * Action handler function that processes actions in the pipeline
- * @template T - The type of the payload
- * @param payload - The data passed to the handler
+ * Action handler function type for processing actions in the pipeline
+ * @implements action-handler
+ * @memberof core-concepts
+ * @since 1.0.0
+ *
+ * Function signature for handlers that process specific actions within the pipeline.
+ * Handlers receive the action payload and a controller for managing pipeline flow.
+ *
+ * @template T - The type of the payload this handler processes
+ * @param payload - The action payload data
  * @param controller - Pipeline controller for flow management
- * @returns void or Promise<void> for async handlers
+ * @returns void or Promise<void> for async operations
+ *
+ * @example
+ * ```typescript
+ * const userUpdateHandler: ActionHandler<{id: string, name: string}> =
+ *   async (payload, controller) => {
+ *     // Validate payload
+ *     if (!payload.id) {
+ *       controller.abort('User ID is required');
+ *       return;
+ *     }
+ *
+ *     // Update user store
+ *     const user = userStore.getValue();
+ *     userStore.setValue({ ...user, ...payload });
+ *   };
+ * ```
  */
 type ActionHandler<T = any> = (payload: T, controller: PipelineController<T>) => void | Promise<void>;
 /**
  * Configuration options for action handlers
+ * @implements handler-configuration
+ * @memberof core-concepts
+ * @since 1.0.0
+ *
+ * Defines behavior and execution characteristics for action handlers in the pipeline.
+ * Supports priority-based execution, conditional execution, and performance optimizations.
+ *
+ * @example
+ * ```typescript
+ * const config: HandlerConfig = {
+ *   priority: 10,        // Higher priority runs first
+ *   id: 'userValidator', // Unique identifier
+ *   blocking: true,      // Wait for async completion
+ *   once: false,         // Run multiple times
+ *   condition: () => isLoggedIn(), // Conditional execution
+ *   debounce: 500,       // Debounce delay in ms
+ *   throttle: 1000,      // Throttle interval in ms
+ *   validation: (payload) => payload?.id != null
+ * };
+ * ```
  */
-type HandlerConfig = {
+interface HandlerConfig {
   /** Priority level (higher numbers execute first). Default: 0 */
   priority?: number;
   /** Unique identifier for the handler. Auto-generated if not provided */
   id?: string;
   /** Whether to wait for async handlers to complete. Default: false */
   blocking?: boolean;
-};
+  /** Whether this handler should run once and then be removed. Default: false */
+  once?: boolean;
+  /** Condition function to determine if handler should run */
+  condition?: () => boolean;
+  /** Debounce delay in milliseconds */
+  debounce?: number;
+  /** Throttle delay in milliseconds */
+  throttle?: number;
+  /** Validation function that must return true for handler to execute */
+  validation?: (payload: any) => boolean;
+  /** Mark this handler as middleware */
+  middleware?: boolean;
+}
 /**
- * Base interface for defining action payload mappings
+ * Internal handler registration data
+ * @internal
+ */
+interface HandlerRegistration<T = any> {
+  handler: ActionHandler<T>;
+  config: Required<HandlerConfig>;
+  id: string;
+}
+/**
+ * Execution modes for action pipeline
+ * @implements execution-mode
+ * @memberof core-concepts
+ * @since 1.0.0
+ *
+ * Defines how handlers are executed within the action pipeline.
+ * Each mode provides different execution strategies for various use cases.
+ *
+ * - `sequential`: Execute handlers one after another (default)
+ * - `parallel`: Execute all handlers simultaneously
+ * - `race`: Execute handlers simultaneously, use first completed result
+ *
  * @example
  * ```typescript
- * interface MyActions extends ActionPayloadMap {
- *   increment: void;
- *   setCount: number;
- *   updateUser: { id: string; name: string };
- * }
+ * const register = new ActionRegister({
+ *   defaultExecutionMode: 'parallel'
+ * });
+ *
+ * // Or set per action
+ * register.setExecutionMode('validateUser', 'sequential');
+ * register.setExecutionMode('fetchData', 'race');
  * ```
  */
-interface ActionPayloadMap {}
+type ExecutionMode = 'sequential' | 'parallel' | 'race';
+/**
+ * Internal execution context for action pipeline processing
+ * @implements pipeline-context
+ * @memberof api-terms
+ * @internal
+ * @since 1.0.0
+ *
+ * Maintains state during action pipeline execution including current payload,
+ * handler queue, execution status, and flow control information.
+ *
+ * @template T - The type of the payload being processed
+ *
+ * @example
+ * ```typescript
+ * // Internal usage in ActionRegister
+ * const context: PipelineContext<UserPayload> = {
+ *   action: 'updateUser',
+ *   payload: { id: '123', name: 'John' },
+ *   handlers: registeredHandlers,
+ *   aborted: false,
+ *   currentIndex: 0,
+ *   executionMode: 'sequential'
+ * };
+ * ```
+ */
+interface PipelineContext<T = any> {
+  action: string;
+  payload: T;
+  handlers: HandlerRegistration<T>[];
+  aborted: boolean;
+  abortReason?: string;
+  currentIndex: number;
+  jumpToPriority?: number;
+  executionMode: ExecutionMode;
+}
 /**
  * Configuration options for ActionRegister
+ * @implements actionregister-configuration
+ * @memberof api-terms
+ * @since 1.0.0
+ *
+ * Defines configuration options for ActionRegister instances, including
+ * logging setup, debugging options, and default execution behavior.
+ *
+ * @example
+ * ```typescript
+ * const config: ActionRegisterConfig = {
+ *   logger: createLogger(LogLevel.DEBUG),
+ *   logLevel: LogLevel.INFO,
+ *   name: 'UserActions',
+ *   debug: true,
+ *   defaultExecutionMode: 'sequential'
+ * };
+ *
+ * const actionRegister = new ActionRegister(config);
+ * ```
  */
 interface ActionRegisterConfig {
   /** Custom logger implementation. Defaults to ConsoleLogger */
   logger?: Logger;
-  /** Log level for the logger. Defaults to ERROR if not provided */
+  /** Log level for filtering output. Defaults to ERROR */
   logLevel?: LogLevel;
-  /** OpenTelemetry context for tracing */
-  otelContext?: OtelContext;
-  /** Whether to use OTEL-aware logger. Defaults to false */
-  useOtel?: boolean;
+  /** Name identifier for this ActionRegister instance */
+  name?: string;
+  /** Whether to enable debug mode with additional logging */
+  debug?: boolean;
+  /** Default execution mode for actions. Defaults to 'sequential' */
+  defaultExecutionMode?: ExecutionMode;
+}
+/**
+ * Unregister function returned by register method
+ * @implements cleanup-function
+ * @memberof api-terms
+ * @since 1.0.0
+ *
+ * Function type for unregistering action handlers from the pipeline.
+ * Returned by the register method to provide cleanup capability.
+ *
+ * @example
+ * ```typescript
+ * const unregister = actionRegister.register('updateUser', handler);
+ *
+ * // Later, remove the handler
+ * unregister();
+ * ```
+ */
+type UnregisterFunction = () => void;
+/**
+ * Type-safe action dispatcher interface
+ * @implements action-dispatcher
+ * @memberof api-terms
+ * @since 1.0.0
+ *
+ * Provides overloaded function signatures for dispatching actions with proper
+ * type checking. Supports both actions with payloads and void actions.
+ *
+ * @template T - Action payload map defining available actions
+ *
+ * @example
+ * ```typescript
+ * interface AppActions extends ActionPayloadMap {
+ *   increment: void;
+ *   setCount: number;
+ *   updateUser: { id: string; name: string };
+ * }
+ *
+ * const dispatch: ActionDispatcher<AppActions> = actionRegister.dispatch;
+ *
+ * // Type-safe dispatching
+ * await dispatch('increment');              // No payload required
+ * await dispatch('setCount', 42);          // Number payload required
+ * await dispatch('updateUser', { id: '1', name: 'John' }); // Object payload
+ * ```
+ */
+interface ActionDispatcher<T extends ActionPayloadMap> {
+  /** Dispatch an action without payload */
+  <K extends keyof T>(action: T[K] extends void ? K : never): Promise<void>;
+  /** Dispatch an action with payload */
+  <K extends keyof T>(action: K, payload: T[K]): Promise<void>;
+}
+/**
+ * Performance metrics for action execution
+ * @implements action-metrics
+ * @implements performance-monitoring
+ * @memberof api-terms
+ * @since 1.0.0
+ *
+ * Provides detailed metrics for action execution performance and status.
+ * Used for monitoring, debugging, and performance optimization.
+ *
+ * @example
+ * ```typescript
+ * actionRegister.on('action:complete', ({ metrics }) => {
+ *   console.log(`Action ${metrics.action} took ${metrics.executionTime}ms`);
+ *   console.log(`Success: ${metrics.success}, Handlers: ${metrics.handlerCount}`);
+ * });
+ * ```
+ */
+interface ActionMetrics {
+  action: string;
+  executionTime: number;
+  handlerCount: number;
+  success: boolean;
+  error?: string;
+  timestamp: number;
 }
 /**
- * Core action pipeline management system
+ * Event types emitted by ActionRegister
+ * @implements action-events
+ * @implements event-driven-architecture
+ * @memberof api-terms
+ * @since 1.0.0
+ *
+ * Defines all event types that can be emitted by ActionRegister instances.
+ * Enables reactive programming and monitoring of action lifecycle events.
+ *
+ * @template T - Action payload map defining available actions
+ *
+ * @example
+ * ```typescript
+ * interface AppActions extends ActionPayloadMap {
+ *   updateUser: { id: string; name: string };
+ * }
+ *
+ * const actionRegister = new ActionRegister<AppActions>();
+ *
+ * actionRegister.on('action:start', ({ action, payload }) => {
+ *   console.log(`Starting action: ${action}`, payload);
+ * });
+ *
+ * actionRegister.on('action:complete', ({ action, metrics }) => {
+ *   console.log(`Completed: ${action} in ${metrics.executionTime}ms`);
+ * });
+ * ```
+ */
+interface ActionRegisterEvents<T extends ActionPayloadMap = ActionPayloadMap> {
+  /** Emitted before action dispatch */
+  'action:start': {
+    action: keyof T;
+    payload: any;
+  };
+  /** Emitted after successful action completion */
+  'action:complete': {
+    action: keyof T;
+    payload: any;
+    metrics: ActionMetrics;
+  };
+  /** Emitted when action is aborted */
+  'action:abort': {
+    action: keyof T;
+    payload: any;
+    reason?: string;
+  };
+  /** Emitted when action encounters an error */
+  'action:error': {
+    action: keyof T;
+    payload: any;
+    error: Error;
+  };
+  /** Emitted when handler is registered */
+  'handler:register': {
+    action: keyof T;
+    handlerId: string;
+    config: HandlerConfig;
+  };
+  /** Emitted when handler is unregistered */
+  'handler:unregister': {
+    action: keyof T;
+    handlerId: string;
+  };
+}
+/**
+ * Event handler type for ActionRegister events
+ * @implements event-handler
+ * @memberof api-terms
+ * @since 1.0.0
+ *
+ * Function type for handling events emitted by ActionRegister.
+ *
+ * @template T - The type of event data
+ */
+type EventHandler<T = any> = (data: T) => void;
+/**
+ * Simple event emitter interface
+ * @implements event-emitter
+ * @memberof api-terms
+ * @since 1.0.0
+ *
+ * Basic event emitter interface for ActionRegister event system.
+ * Provides methods for subscribing, emitting, and unsubscribing from events.
+ *
+ * @template T - Record type defining available events and their data types
+ */
+interface EventEmitter<T extends Record<string, any> = Record<string, any>> {
+  on<K extends keyof T>(event: K, handler: EventHandler<T[K]>): UnregisterFunction;
+  emit<K extends keyof T>(event: K, data: T[K]): void;
+  off<K extends keyof T>(event: K, handler: EventHandler<T[K]>): void;
+  removeAllListeners(event?: keyof T): void;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/ActionRegister.d.ts
+/**
+ * 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}`));
+ * // Register handlers with priority and configuration
+ * actionRegister.register('increment', (_, controller) => {
+ *   console.log('Incremented');
+ *   controller.next();
+ * }, { priority: 10 });
  *
- * // Dispatch actions
+ * 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);
  * ```
  */
 declare class ActionRegister<T extends ActionPayloadMap = ActionPayloadMap> {
   private pipelines;
-  private atomSetters;
   private handlerCounter;
-  readonly logger: Logger;
+  private readonly logger;
+  private readonly events;
+  private readonly config;
+  private readonly actionGuard;
+  private executionMode;
+  private actionExecutionModes;
   constructor(config?: ActionRegisterConfig);
   /**
+   * 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<K extends keyof T>(action: K, handler: ActionHandler<T[K]>, config?: HandlerConfig): () => void;
-  registerAtomSetter(name: string, setter: Function): void;
+  register<K extends keyof T>(action: K, handler: ActionHandler<T[K]>, config?: HandlerConfig): UnregisterFunction;
+  /**
+   * 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: ActionDispatcher<T>;
+  /**
+   * Execute the pipeline with proper flow control
+   * @internal
+   */
+  private executePipeline;
+  /**
+   * Clean up one-time handlers after pipeline execution
+   * @internal
+   */
+  private cleanupOneTimeHandlers;
+  /**
+   * Get the number of handlers registered for an action
+   * @param action - The action to check
+   * @returns Number of handlers registered
+   */
+  getHandlerCount<K extends keyof T>(action: K): number;
   /**
-   * Dispatch an action through the pipeline (for actions without payload)
-   * @param action - The action to dispatch
-   * @returns Promise that resolves when all handlers complete
+   * Check if any handlers are registered for an action
+   * @param action - The action to check
+   * @returns True if handlers are registered
    */
-  dispatch<K extends keyof T>(action: T[K] extends void ? K : never): Promise<void>;
+  hasHandlers<K extends keyof T>(action: K): boolean;
   /**
-   * Dispatch an action through the pipeline (for actions with payload)
-   * @param action - The action to dispatch
-   * @param payload - The payload data to pass to handlers
-   * @returns Promise that resolves when all handlers complete
+   * Get all registered action names
+   * @returns Array of action names
    */
-  dispatch<K extends keyof T>(action: K, payload: T[K]): Promise<void>;
-  private sortPipeline;
+  getRegisteredActions(): (keyof T)[];
+  /**
+   * Clear all handlers for a specific action
+   * @param action - The action to clear
+   */
+  clearAction<K extends keyof T>(action: K): void;
+  /**
+   * Clear all handlers for all actions
+   */
+  clearAll(): void;
+  /**
+   * 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<K extends keyof ActionRegisterEvents<T>>(event: K, handler: EventHandler<ActionRegisterEvents<T>[K]>): UnregisterFunction;
+  /**
+   * Remove event listener
+   * @param event - Event name
+   * @param handler - Event handler to remove
+   */
+  off<K extends keyof ActionRegisterEvents<T>>(event: K, handler: EventHandler<ActionRegisterEvents<T>[K]>): void;
+  /**
+   * Get current configuration
+   * @returns Current ActionRegister configuration
+   */
+  getConfig(): Readonly<Required<ActionRegisterConfig>>;
+  /**
+   * Get logger instance
+   * @returns Current logger instance
+   */
+  getLogger(): Logger;
 }
 //# sourceMappingURL=ActionRegister.d.ts.map
 //#endregion
-//#region src/types.d.ts
-interface BaseActionPayloadMap {}
-type ActionType<T extends Record<string, any>> = keyof T;
-type ActionPayload<T extends Record<string, any>, K extends keyof T> = T[K];
-type ActionHandlerMap<T extends Record<string, any>> = { [K in keyof T]?: (payload: T[K]) => void | Promise<void> };
-declare function createAction<T extends Record<string, any>, K extends keyof T>(type: K, payload: T[K]): {
-  type: K;
-  payload: T[K];
-};
-declare function isAction<T extends Record<string, any>, K extends keyof T>(action: any, type: K): action is {
-  type: K;
-  payload: T[K];
-};
-//# sourceMappingURL=types.d.ts.map
+//#region src/action-guard.d.ts
+/**
+ * Action guard state tracking
+ * @internal
+ */
+interface GuardState {
+  lastExecuted: number;
+  debounceTimer?: NodeJS.Timeout;
+  throttleTimer?: NodeJS.Timeout;
+  isThrottled: boolean;
+}
+/**
+ * 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();
+ * }
+ * ```
+ */
+declare class ActionGuard {
+  private guards;
+  private logger;
+  constructor(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
+   */
+  debounce(actionKey: string, debounceMs: number): Promise<boolean>;
+  /**
+   * 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: string, throttleMs: number): boolean;
+  /**
+   * Clear all guards for an action
+   * @param actionKey - Action key to clear
+   */
+  clearGuards(actionKey: string): void;
+  /**
+   * Clear all guards
+   */
+  clearAll(): void;
+  /**
+   * Get current guard state for debugging
+   * @param actionKey - Action key to inspect
+   */
+  getGuardState(actionKey: string): GuardState | undefined;
+  /**
+   * Get all active guards for debugging
+   */
+  getAllGuardStates(): Map<string, GuardState>;
+}
+//#endregion
+//#region src/execution-modes.d.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
+ */
+declare function executeSequential<T>(context: PipelineContext<T>, createController: (registration: HandlerRegistration<T>, index: number) => PipelineController<T>, logger: Logger): Promise<void>;
+/**
+ * Execute handlers in parallel mode (all at once)
+ * @internal
+ */
+declare function executeParallel<T>(context: PipelineContext<T>, createController: (registration: HandlerRegistration<T>, index: number) => PipelineController<T>, logger: Logger): Promise<void>;
+/**
+ * Execute handlers in race mode (first to complete wins)
+ * @internal
+ */
+declare function executeRace<T>(context: PipelineContext<T>, createController: (registration: HandlerRegistration<T>, index: number) => PipelineController<T>, logger: Logger): Promise<void>;
+//# sourceMappingURL=execution-modes.d.ts.map
 
 //#endregion
-export { ActionHandler, ActionHandlerMap, ActionPayload, ActionPayloadMap, ActionRegister, ActionRegisterConfig, ActionType, BaseActionPayloadMap, ConsoleLogger, HandlerConfig, LogLevel, Logger, OtelConsoleLogger, OtelContext, OtelLogger, PipelineController, createAction, createOtelContextFromPayload, extractSessionIdFromPayload, extractTraceIdFromPayload, getLogLevelFromEnv, isAction, parseLogLevel };
+export { type ActionDispatcher, ActionGuard, type ActionHandler, type ActionMetrics, type ActionPayloadMap, ActionRegister, type ActionRegisterConfig, type ActionRegisterEvents, type EventEmitter, type EventHandler, type ExecutionMode, type HandlerConfig, type HandlerRegistration, type PipelineContext, type PipelineController, type UnregisterFunction, executeParallel, executeRace, executeSequential };
 //# sourceMappingURL=index.d.cts.map