@context-action/core 0.0.2 → 0.0.4

package/dist/index.d.cts

@@ -1,42 +1,670 @@
-//#region src/ActionRegister.d.ts
-type PipelineController<T = any> = {
-  next: () => void;
-  abort: (reason?: string) => void;
-  modifyPayload: (modifier: (payload: T) => T) => void;
-};
+import { LogLevel, Logger } from "@context-action/logger";
+
+//#region src/types.d.ts
+
+/**
+ * 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 ActionPayloadMap {
+  [actionName: string]: unknown;
+}
+/**
+ * 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
+ */
+interface PipelineController<T = any> {
+  /** Continue to the next handler in the pipeline */
+  next(): void;
+  /** Abort the pipeline execution with an optional reason */
+  abort(reason?: string): void;
+  /** Modify the payload that will be passed to subsequent handlers */
+  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 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 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>;
-type HandlerConfig = {
+/**
+ * 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
+ * };
+ * ```
+ */
+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;
-};
-interface ActionPayloadMap {}
+  /** 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;
+}
+/**
+ * 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
+ * const register = new ActionRegister({
+ *   defaultExecutionMode: 'parallel'
+ * });
+ *
+ * // Or set per action
+ * register.setExecutionMode('validateUser', 'sequential');
+ * register.setExecutionMode('fetchData', 'race');
+ * ```
+ */
+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 filtering output. Defaults to ERROR */
+  logLevel?: LogLevel;
+  /** 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;
+}
+/**
+ * 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 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);
+ * ```
+ */
 declare class ActionRegister<T extends ActionPayloadMap = ActionPayloadMap> {
   private pipelines;
-  private atomSetters;
-  register<K extends keyof T>(action: K, handler: ActionHandler<T[K]>, config?: HandlerConfig): () => void;
-  registerAtomSetter(name: string, setter: Function): void;
-  dispatch<K extends keyof T>(action: T[K] extends void ? K : never): Promise<void>;
-  dispatch<K extends keyof T>(action: K, payload: T[K]): Promise<void>;
-  private sortPipeline;
+  private handlerCounter;
+  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('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): 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;
+  /**
+   * Check if any handlers are registered for an action
+   * @param action - The action to check
+   * @returns True if handlers are registered
+   */
+  hasHandlers<K extends keyof T>(action: K): boolean;
+  /**
+   * Get all registered action names
+   * @returns Array of action names
+   */
+  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, ActionType, BaseActionPayloadMap, HandlerConfig, PipelineController, createAction, isAction };
+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