@qlover/fe-corekit 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -82,92 +82,370 @@ declare class ExecutorError extends Error {
 }
 
 /**
- * Represents the context in which a task is executed.
+ * Execution context interface for task execution state management
  *
- * This interface is designed to encapsulate the necessary information
- * for executing a task, including parameters, potential errors, and
- * the return value. It allows for additional properties to be added
- * dynamically, making it flexible for various use cases.
+ * Core concept:
+ * Encapsulates the complete execution state of a task, including input parameters,
+ * execution results, error information, and runtime metadata. Provides a centralized
+ * way to manage and track task execution throughout the plugin pipeline.
  *
- * @template Params - The type of parameters that the task accepts.
+ * Main features:
+ * - State management: Centralized storage for task execution state
+ * - Error tracking: Captures and preserves error information during execution
+ * - Parameter passing: Maintains input parameters throughout the execution pipeline
+ * - Result storage: Stores task execution results and return values
+ * - Runtime monitoring: Tracks execution time and hook performance metrics
+ * - Extensibility: Supports dynamic property addition for custom use cases
  *
- * @since 1.0.14
+ * Design considerations:
+ * - Immutable runtime data: Hook runtime information is read-only and frozen
+ * - Type safety: Full TypeScript support with generic parameter types
+ * - Pipeline integration: Seamlessly integrates with executor plugin pipeline
+ * - Memory management: Runtime data is automatically cleared after execution
  *
- * @example
+ * @template Params - Type of parameters that the task accepts
+ *
+ * @since `1.0.14`
+ *
+ * @example Basic context creation
+ * ```typescript
+ * const context: ExecutorContext<MyParams> = {
+ *   parameters: { id: 1, name: 'test' },
+ *   error: undefined,
+ *   returnValue: undefined,
+ *   hooksRuntimes: {}
+ * };
+ * ```
+ *
+ * @example Context with error state
  * ```typescript
- * const context: ExecutorContextInterface<MyParams> = {
+ * const context: ExecutorContext<MyParams> = {
  *   parameters: { id: 1 },
- *   error: null,
- *   returnValue: 'Success'
+ *   error: new Error('Task failed'),
+ *   returnValue: undefined,
+ *   hooksRuntimes: {}
+ * };
+ * ```
+ *
+ * @example Context with successful result
+ * ```typescript
+ * const context: ExecutorContext<MyParams> = {
+ *   parameters: { id: 1 },
+ *   error: undefined,
+ *   returnValue: { success: true, data: 'processed' },
+ *   hooksRuntimes: {}
  * };
  * ```
  */
 interface ExecutorContext<Params = unknown> {
     /**
-     * The error that occurred during the execution of the task.
+     * Error that occurred during task execution
+     *
+     * Core concept:
+     * Captures and preserves error information when task execution fails,
+     * enabling comprehensive error handling and debugging capabilities
      *
-     * This property is optional and will be populated if an error
-     * occurs during task execution.
+     * Main features:
+     * - Error preservation: Maintains original error objects with stack traces
+     * - Pipeline integration: Errors are propagated through the execution pipeline
+     * - Debugging support: Provides detailed error information for troubleshooting
+     * - Optional presence: Only populated when errors occur during execution
      *
-     * @type {Error | undefined}
+     * Error handling flow:
+     * 1. Error occurs during task execution or plugin hook execution
+     * 2. Error is captured and assigned to this property
+     * 3. Error information is preserved for downstream processing
+     * 4. Error can be handled by error-specific plugins or hooks
+     *
+     * @optional
+     * @example `new Error('Database connection failed')`
+     * @example `new ValidationError('Invalid input parameters')`
      */
     error?: Error;
     /**
-     * The parameters passed to the task.
+     * Input parameters passed to the task for execution
+     *
+     * Core concept:
+     * Contains all input data required for task execution, providing
+     * the necessary context and parameters for the task to perform its operations
      *
-     * These parameters are used to execute the task and are of a generic
-     * type, allowing for flexibility in the types of parameters that can
-     * be passed.
+     * Main features:
+     * - Type safety: Generic type parameter ensures type safety for different parameter types
+     * - Pipeline persistence: Parameters are maintained throughout the execution pipeline
+     * - Plugin access: All plugins can access and potentially modify parameters
+     * - Validation support: Parameters can be validated by validation plugins
      *
-     * @type {Params}
+     * Parameter lifecycle:
+     * 1. Initial parameters are set when context is created
+     * 2. Parameters can be modified by before hooks (validation, transformation)
+     * 3. Modified parameters are passed to the main task function
+     * 4. Parameters remain available for after hooks (logging, cleanup)
+     *
+     * @example Simple parameters
+     * ```typescript
+     * parameters: { id: 1, name: 'test' }
+     * ```
+     *
+     * @example Complex parameters
+     * ```typescript
+     * parameters: {
+     *   user: { id: 1, name: 'John' },
+     *   options: { timeout: 5000, retries: 3 },
+     *   metadata: { source: 'api', version: 'v2' }
+     * }
+     * ```
      */
     parameters: Params;
     /**
-     * The return value of the task.
+     * Return value from successful task execution
+     *
+     * Core concept:
+     * Stores the result of successful task execution, providing a centralized
+     * location for accessing task output and results
      *
-     * This property is optional and will contain the result of the task
-     * execution if it completes successfully.
+     * Main features:
+     * - Result storage: Captures task execution results for downstream processing
+     * - Pipeline integration: Results are available to after hooks and plugins
+     * - Type flexibility: Supports any return type from task execution
+     * - Optional presence: Only populated when task execution succeeds
      *
-     * @type {unknown | undefined}
+     * Result lifecycle:
+     * 1. Task function executes and produces a result
+     * 2. Result is stored in this property
+     * 3. Result is available to after hooks for processing
+     * 4. Result can be transformed or enhanced by plugins
+     *
+     * @optional
+     * @example `{ success: true, data: 'processed result' }`
+     * @example `'simple string result'`
+     * @example `{ items: [], total: 0, page: 1 }`
      */
     returnValue?: unknown;
     /**
-     * The runtime information of the task.
+     * Runtime information and metadata for hook execution
      *
-     * The current runtime of each hook.
+     * Core concept:
+     * Provides detailed runtime information about hook execution, including
+     * performance metrics, execution state, and control flow information
      *
-     * This property is optional and will contain the runtime information
-     * of the task if it is executed.
+     * Main features:
+     * - Performance tracking: Monitors hook execution time and performance
+     * - State management: Tracks current hook name and execution state
+     * - Flow control: Provides mechanisms to control execution flow
+     * - Read-only access: Runtime data is frozen and cannot be modified
+     * - Auto-cleanup: Data is automatically cleared after execution completes
      *
-     * property is read-only
+     * Runtime data structure:
+     * - hookName: Current hook being executed
+     * - returnValue: Return value from current hook execution
+     * - times: Number of times hook has been executed
+     * - breakChain: Flag to break the execution chain
+     * - returnBreakChain: Flag to break chain when return value exists
      *
-     * will return a frozen object that will be cleared after the chain execution is complete.
+     * Security and performance:
+     * - Data is frozen to prevent modification during execution
+     * - Memory is automatically managed and cleared after execution
+     * - Provides audit trail for debugging and monitoring
      *
+     * @readonly
+     * @example
+     * ```typescript
+     * hooksRuntimes: {
+     *   hookName: 'onBefore',
+     *   returnValue: { validated: true },
+     *   times: 1,
+     *   breakChain: false,
+     *   returnBreakChain: false
+     * }
+     * ```
      */
     hooksRuntimes: HookRuntimes;
 }
+/**
+ * Runtime information interface for hook execution tracking
+ *
+ * Core concept:
+ * Provides detailed runtime metadata for individual hook execution,
+ * enabling performance monitoring, flow control, and execution state tracking
+ *
+ * Main features:
+ * - Execution tracking: Monitors hook execution state and performance
+ * - Flow control: Provides mechanisms to control execution pipeline flow
+ * - Performance metrics: Tracks execution times and performance data
+ * - State preservation: Maintains execution state throughout the pipeline
+ * - Extensibility: Supports additional custom properties for specific use cases
+ *
+ * Flow control mechanisms:
+ * - breakChain: Immediately stops execution pipeline
+ * - returnBreakChain: Stops pipeline when return value is present
+ * - times: Tracks execution frequency for optimization
+ *
+ * @example Basic runtime information
+ * ```typescript
+ * const runtime: HookRuntimes = {
+ *   hookName: 'onBefore',
+ *   returnValue: { validated: true },
+ *   times: 1,
+ *   breakChain: false,
+ *   returnBreakChain: false
+ * };
+ * ```
+ *
+ * @example Runtime with custom properties
+ * ```typescript
+ * const runtime: HookRuntimes = {
+ *   hookName: 'customHook',
+ *   returnValue: { processed: true },
+ *   times: 3,
+ *   breakChain: false,
+ *   returnBreakChain: true,
+ *   customMetric: 'performance_data',
+ *   executionTime: 150
+ * };
+ * ```
+ */
 interface HookRuntimes {
+    /**
+     * Name of the current hook being executed
+     *
+     * Core concept:
+     * Identifies the specific hook that is currently being executed,
+     * enabling targeted debugging and monitoring of hook performance
+     *
+     * Main features:
+     * - Hook identification: Clearly identifies which hook is executing
+     * - Debugging support: Enables targeted debugging of specific hooks
+     * - Performance monitoring: Allows tracking of individual hook performance
+     * - Pipeline visibility: Provides visibility into execution pipeline state
+     *
+     * @optional
+     * @example `'onBefore'`
+     * @example `'onExec'`
+     * @example `'onAfter'`
+     * @example `'customValidationHook'`
+     */
     hookName?: string;
     /**
-     * The return value of the task.
+     * Return value from the current hook execution
      *
-     * Readonly
+     * Core concept:
+     * Captures the return value from the current hook execution,
+     * enabling result tracking and flow control based on hook output
+     *
+     * Main features:
+     * - Result tracking: Monitors what each hook returns
+     * - Flow control: Enables conditional execution based on return values
+     * - Debugging support: Provides visibility into hook output
+     * - Pipeline integration: Results can influence downstream execution
+     *
+     * @readonly
+     * @optional
+     * @example `{ validated: true, data: 'processed' }`
+     * @example `'hook_result'`
+     * @example `{ error: 'validation_failed' }`
      */
     returnValue?: unknown;
     /**
-     * 执行次数
+     * Number of times the hook has been executed
+     *
+     * Core concept:
+     * Tracks the execution frequency of hooks, enabling performance
+     * optimization and debugging of repeated executions
+     *
+     * Main features:
+     * - Execution counting: Monitors how many times hooks are called
+     * - Performance analysis: Identifies frequently executed hooks
+     * - Loop detection: Helps identify potential infinite loops
+     * - Optimization insights: Provides data for performance optimization
+     *
+     * Usage scenarios:
+     * - Performance monitoring: Track hook execution frequency
+     * - Debugging: Identify hooks that execute more than expected
+     * - Optimization: Focus optimization efforts on frequently called hooks
+     *
+     * @optional
+     * @example `1` // First execution
+     * @example `5` // Hook executed 5 times
+     * @example `0` // Hook not yet executed
      */
     times?: number;
     /**
-     * 是否中断链
+     * Flag to immediately break the execution chain
+     *
+     * Core concept:
+     * Provides a mechanism to immediately stop the execution pipeline,
+     * enabling early termination when certain conditions are met
+     *
+     * Main features:
+     * - Immediate termination: Stops execution pipeline immediately
+     * - Conditional control: Enables conditional execution flow
+     * - Error handling: Allows early termination on critical errors
+     * - Performance optimization: Avoids unnecessary processing
+     *
+     * Use cases:
+     * - Error conditions: Stop execution when critical errors occur
+     * - Validation failures: Terminate when validation fails
+     * - Early success: Stop when desired result is achieved early
+     * - Resource constraints: Terminate when resources are exhausted
+     *
+     * @optional
+     * @example `true` // Break execution chain immediately
+     * @example `false` // Continue normal execution
      */
     breakChain?: boolean;
     /**
-     * 如果有返回值，是否中断链
+     * Flag to break chain when return value exists
+     *
+     * Core concept:
+     * Enables conditional chain breaking based on the presence of a return value,
+     * commonly used in error handling and early termination scenarios
+     *
+     * Main features:
+     * - Conditional termination: Breaks chain only when return value exists
+     * - Error handling: Commonly used in `onError` lifecycle hooks
+     * - Result-based control: Enables flow control based on hook results
+     * - Flexible termination: Provides more nuanced control than `breakChain`
+     *
+     * Common usage:
+     * - Error handlers: Break chain when error is handled and result is returned
+     * - Validation: Stop processing when validation result is returned
+     * - Caching: Terminate when cached result is found
+     * - Early success: Stop when desired result is achieved
      *
-     * 一般常用于需要返回一个值时中断链,比如 onError 声明周期
+     * @optional
+     * @example `true` // Break chain if returnValue exists
+     * @example `false` // Continue regardless of returnValue
      */
     returnBreakChain?: boolean;
+    /**
+     * Additional custom properties for extensibility
+     *
+     * Core concept:
+     * Provides a flexible mechanism to add custom properties to runtime
+     * information, enabling plugin-specific metadata and custom tracking
+     *
+     * Main features:
+     * - Extensibility: Allows plugins to add custom runtime data
+     * - Custom metrics: Enables plugin-specific performance tracking
+     * - Metadata storage: Provides space for custom execution metadata
+     * - Plugin integration: Enables rich plugin-to-plugin communication
+     *
+     * Common custom properties:
+     * - executionTime: Hook execution time in milliseconds
+     * - memoryUsage: Memory consumption during hook execution
+     * - customMetrics: Plugin-specific performance metrics
+     * - debugInfo: Additional debugging information
+     *
+     * @example
+     * ```typescript
+     * {
+     *   executionTime: 150,
+     *   memoryUsage: '2.5MB',
+     *   customMetric: 'validation_score',
+     *   debugInfo: { step: 'validation', level: 'info' }
+     * }
+     * ```
+     */
     [key: string]: unknown;
 }
 
@@ -333,24 +611,102 @@ interface ExecutorPlugin<T = unknown> {
     onExec?(context: ExecutorContext<unknown>, task: Task<unknown, unknown>): Promise<unknown> | unknown;
 }
 
+type HookType = string;
 /**
- * Base executor class providing plugin management and execution pipeline
+ * Configuration interface for executor behavior customization
+ *
+ * Core concept:
+ * Provides flexible configuration options to customize executor behavior,
+ * including hook execution order, lifecycle management, and execution flow control
+ *
+ * Main features:
+ * - Hook customization: Define custom hook names for different execution phases
+ * - Execution flow control: Configure before/after execution hooks
+ * - Plugin integration: Support for custom execution logic hooks
  *
- * The Executor pattern implements a pluggable execution pipeline that allows:
- * 1. Pre-processing of input data
- * 2. Post-processing of results
- * 3. Error handling
- * 4. Custom execution logic
+ * @since 2.1.0
+ *
+ * @example Basic configuration
+ * ```typescript
+ * const config: ExecutorConfigInterface = {
+ *   beforeHooks: ['validate', 'transform'],
+ *   afterHooks: ['log', 'cleanup'],
+ *   execHook: 'process'
+ * };
+ * ```
+ */
+interface ExecutorConfigInterface {
+    /**
+     * Hook names to execute before task execution
+     *
+     * These hooks are executed in the order they appear in the array.
+     * Each hook can modify the input data or perform validation.
+     *
+     * @default `'onBefore'`
+     * @example `['validate', 'transform']`
+     * @example `'preProcess'`
+     */
+    beforeHooks?: HookType | HookType[];
+    /**
+     * Hook names to execute after successful task execution
+     *
+     * These hooks are executed in the order they appear in the array.
+     * Each hook can process the result or perform cleanup operations.
+     *
+     * @default `'onSuccess'`
+     * @example `['log', 'cleanup']`
+     * @example `'postProcess'`
+     */
+    afterHooks?: HookType | HookType[];
+    /**
+     * Hook name for the main execution logic
+     *
+     * This hook contains the core business logic for task execution.
+     * If not specified, the default `'onExec'` hook is used.
+     *
+     * @default `'onExec'`
+     * @example `'process'`
+     * @example `'execute'`
+     */
+    execHook?: HookType;
+}
+/**
+ * Base executor class providing plugin management and execution pipeline
  *
- * execNoError returns all errors as they are., and if there is a plugin onerror handler chain in which an error occurs, it will also return the error instead of throwing it.
+ * Core concept:
+ * Implements a pluggable execution pipeline that enables modular task processing
+ * with pre-processing, execution, and post-processing capabilities
+ *
+ * Main features:
+ * - Plugin management: Add, remove, and manage execution plugins
+ * - Hook system: Configurable lifecycle hooks for different execution phases
+ * - Error handling: Comprehensive error management with optional error wrapping
+ * - Task execution: Support for both synchronous and asynchronous task execution
+ * - Pipeline orchestration: Coordinate multiple plugins in a defined execution order
+ *
+ * Execution flow:
+ * 1. Before hooks: Validate and transform input data
+ * 2. Execution hook: Perform the main business logic
+ * 3. After hooks: Process results and perform cleanup
+ * 4. Error handling: Manage errors at any stage of execution
+ *
+ * Design considerations:
+ * - Plugin deduplication: Prevents duplicate plugins when `onlyOne` is true
+ * - Error propagation: `execNoError` methods return errors instead of throwing
+ * - Type safety: Full TypeScript support with generic type parameters
+ * - Extensibility: Easy to extend with custom plugins and hooks
  *
  * @abstract
  * @class Executor
  * @category Executor
- * @example
+ *
+ * @example Basic usage
  * ```typescript
  * // Create an executor instance
- * const executor = new AsyncExecutor();
+ * const executor = new AsyncExecutor({
+ *   beforeHooks: ['validate'],
+ *   afterHooks: ['log']
+ * });
  *
  * // Add plugins
  * executor.use(new LoggerPlugin());
@@ -361,157 +717,296 @@ interface ExecutorPlugin<T = unknown> {
  *   return await someAsyncOperation(data);
  * });
  * ```
+ *
+ * @example With input data
+ * ```typescript
+ * const result = await executor.exec(inputData, async (data) => {
+ *   return await processData(data);
+ * });
+ * ```
+ *
+ * @example Error-safe execution
+ * ```typescript
+ * const result = await executor.execNoError(async (data) => {
+ *   return await riskyOperation(data);
+ * });
+ *
+ * if (result instanceof ExecutorError) {
+ *   console.error('Task failed:', result.message);
+ * } else {
+ *   console.log('Task succeeded:', result);
+ * }
+ * ```
  */
-declare abstract class Executor<ExecutorConfig = unknown> {
-    protected config?: ExecutorConfig | undefined;
+declare abstract class Executor<ExecutorConfig extends ExecutorConfigInterface> {
+    protected config: ExecutorConfig;
     /**
-     * Array of active plugins
+     * Array of active plugins for this executor
+     *
+     * Core concept:
+     * Maintains an ordered collection of plugins that participate in the execution pipeline
+     *
+     * Main features:
+     * - Plugin storage: Stores all registered plugins in execution order
+     * - Lifecycle management: Manages plugin initialization and cleanup
+     * - Execution coordination: Ensures plugins execute in the correct sequence
+     * - Deduplication support: Prevents duplicate plugins when configured
      *
-     * - Purpose: Stores and manages executor plugins
-     * - Core Concept: Ordered plugin pipeline
-     * - Main Features:
-     *  - Maintains plugin execution order
-     *  - Supports plugin lifecycle management
-     * - Primary Use: Plugin orchestration and execution
+     * Plugin execution order:
+     * 1. Plugins are executed in the order they were added
+     * 2. Each plugin can modify data or control execution flow
+     * 3. Plugin hooks are called based on executor configuration
      *
      * @example
      * ```typescript
      * protected plugins = [
      *   new LoggerPlugin(),
-     *   new RetryPlugin()
+     *   new RetryPlugin({ maxAttempts: 3 }),
+     *   new CachePlugin({ ttl: 300 })
      * ];
      * ```
      */
     protected plugins: ExecutorPlugin[];
     /**
-     * Creates a new Executor instance
+     * Creates a new Executor instance with optional configuration
      *
-     * - Purpose: Initialize executor with optional configuration
-     * - Core Concept: Configurable executor setup
-     * - Main Features: Configuration injection
-     * - Primary Use: Executor instantiation
+     * Core concept:
+     * Initializes the executor with configuration that controls its behavior
+     * and execution pipeline setup
      *
-     * @param {ExecutorConfig} config - Optional configuration object
+     * Main features:
+     * - Configuration injection: Accepts custom configuration for hook names and behavior
+     * - Default setup: Provides sensible defaults when no configuration is provided
+     * - Plugin preparation: Sets up the environment for plugin registration
      *
-     * @example
+     * @param config - Optional configuration object to customize executor behavior
+     *
+     * @example Basic instantiation
+     * ```typescript
+     * const executor = new AsyncExecutor();
+     * ```
+     *
+     * @example With custom configuration
      * ```typescript
-     * const executor = new Executor({
-     *   // config options
+     * const executor = new AsyncExecutor({
+     *   beforeHooks: ['validate', 'transform'],
+     *   afterHooks: ['log', 'cleanup'],
+     *   execHook: 'process'
      * });
      * ```
      */
-    constructor(config?: ExecutorConfig | undefined);
+    constructor(config?: ExecutorConfig);
     /**
-     * Add a plugin to the executor
+     * Add a plugin to the executor's execution pipeline
      *
-     * - Purpose: Extends executor functionality through plugins
-     * - Core Concept: Plugin registration and deduplication
-     * - Main Features:
-     *  - Prevents duplicate plugins if onlyOne is true
-     *  - Maintains plugin execution order
-     * - Primary Use: Adding new capabilities to executor
+     * Core concept:
+     * Registers a plugin to participate in the executor's execution pipeline,
+     * extending the executor's functionality with additional capabilities
      *
-     * @param plugin - Plugin instance to add
+     * Main features:
+     * - Plugin registration: Adds plugins to the execution pipeline
+     * - Deduplication: Prevents duplicate plugins when `onlyOne` is true
+     * - Order preservation: Maintains plugin execution order
+     * - Validation: Ensures plugin is a valid object
      *
-     * @example
+     * Deduplication logic:
+     * - Checks for exact plugin instance match
+     * - Checks for plugin name match
+     * - Checks for constructor match
+     * - Only prevents duplicates when `plugin.onlyOne` is true
+     *
+     * @param plugin - Plugin instance to add to the execution pipeline
+     *
+     * @throws {Error} When plugin is not a valid object
+     *
+     * @example Add a class-based plugin
      * ```typescript
      * executor.use(new LoggerPlugin());
      * executor.use(new RetryPlugin({ maxAttempts: 3 }));
      * ```
      *
-     * @example
-     *
-     * Use a plain object as a plugin
+     * @example Add a plain object plugin
      * ```typescript
      * executor.use({
-     *   onBefore: (data) => ({ ...data, modified: true })
+     *   pluginName: 'CustomPlugin',
+     *   onBefore: (data) => ({ ...data, modified: true }),
+     *   onAfter: (result) => console.log('Result:', result)
      * });
      * ```
+     *
+     * @example Plugin with deduplication
+     * ```typescript
+     * const plugin = new LoggerPlugin();
+     * plugin.onlyOne = true;
+     *
+     * executor.use(plugin); // First addition - succeeds
+     * executor.use(plugin); // Second addition - skipped with warning
+     * ```
      */
     use(plugin: ExecutorPlugin): void;
     /**
-     * Execute a plugin hook
+     * Execute a specific hook across all plugins
      *
-     * - Purpose: Provides plugin hook execution mechanism
-     * - Core Concept: Plugin lifecycle management
-     * - Main Features:
-     *  - Dynamic hook execution
-     *  - Support for async and sync hooks
-     * - Primary Use: Running plugin lifecycle methods
+     * Core concept:
+     * Provides the mechanism to execute plugin lifecycle hooks across all
+     * registered plugins in the correct order
      *
-     * @param plugins - Plugins to execute
-     * @param name - Hook name to execute
-     * @param args - Arguments for the hook
+     * Main features:
+     * - Hook execution: Runs specified hook on all plugins
+     * - Order preservation: Executes plugins in registration order
+     * - Async support: Handles both synchronous and asynchronous hooks
+     * - Error propagation: Manages errors from hook execution
      *
-     * @example
+     * Hook execution flow:
+     * 1. Iterate through plugins in registration order
+     * 2. Check if plugin has the specified hook method
+     * 3. Execute hook with provided arguments
+     * 4. Handle return values and errors appropriately
+     *
+     * @param plugins - Array of plugins to execute the hook on
+     * @param name - Name of the hook to execute (e.g., 'onBefore', 'onExec', 'onAfter')
+     * @param args - Arguments to pass to the hook method
+     *
+     * @returns Hook execution result or void
+     *
+     * @example Execute before hook
+     * ```typescript
+     * await executor.runHooks(plugins, 'onBefore', inputData);
+     * ```
+     *
+     * @example Execute custom hook
      * ```typescript
-     * await executor.runHook(plugins, 'beforeExec', data);
+     * const result = await executor.runHooks(plugins, 'customHook', data, options);
      * ```
      */
-    abstract runHooks(plugins: ExecutorPlugin[], name: keyof ExecutorPlugin, ...args: unknown[]): void | unknown | Promise<void | unknown>;
+    abstract runHooks(plugins: ExecutorPlugin[], name: unknown, ...args: unknown[]): void | unknown | Promise<void | unknown>;
     /**
-     * Execute a task with plugin pipeline
+     * Execute a task through the plugin pipeline
      *
-     * - Purpose: Core task execution with plugin support
-     * - Core Concept: Task execution pipeline
-     * - Main Features:
-     *  - Plugin hook integration
-     *  - Error handling
-     * - Primary Use: Running tasks through the executor pipeline
+     * Core concept:
+     * Executes a task function through the complete plugin pipeline,
+     * including before hooks, execution, and after hooks
      *
-     * @param task - Task to execute
-     * @param data - Optional input data for task
-     * @throws {ExecutorError} If task execution fails
+     * Main features:
+     * - Pipeline execution: Runs task through configured plugin pipeline
+     * - Hook integration: Executes before/after hooks as configured
+     * - Error handling: Comprehensive error management and propagation
+     * - Type safety: Full TypeScript support with generic types
      *
-     * @example
+     * Execution pipeline:
+     * 1. Execute before hooks (if configured)
+     * 2. Execute main task function
+     * 3. Execute after hooks (if configured)
+     * 4. Return result or throw error
+     *
+     * @param task - Task function to execute through the pipeline
+     * @returns Task execution result
+     *
+     * @throws {ExecutorError} When task execution fails or plugin errors occur
+     *
+     * @example Basic task execution
      * ```typescript
      * const result = await executor.exec(async (data) => {
      *   return await processData(data);
      * });
      * ```
+     *
+     * @example Synchronous task execution
+     * ```typescript
+     * const result = executor.exec((data) => {
+     *   return transformData(data);
+     * });
+     * ```
      */
     abstract exec<Result, Params = unknown>(task: Task<Result, Params>): Promise<Result> | Result;
     /**
-     * Execute a task with plugin pipeline and input data
+     * Execute a task with input data through the plugin pipeline
      *
-     * - Purpose: Core task execution with plugin support and input data
-     * - Core Concept: Task execution pipeline with data
-     * - Main Features:
-     *  - Plugin hook integration
-     *  - Error handling
-     * - Primary Use: Running tasks with input data through the executor pipeline
+     * Core concept:
+     * Executes a task function with provided input data through the complete
+     * plugin pipeline, enabling data transformation and processing
      *
-     * @param data - Input data for task
-     * @param task - Task to execute
-     * @throws {ExecutorError} If task execution fails
+     * Main features:
+     * - Data processing: Passes input data through the execution pipeline
+     * - Pipeline execution: Runs task through configured plugin pipeline
+     * - Hook integration: Executes before/after hooks with input data
+     * - Error handling: Comprehensive error management and propagation
      *
-     * @example
+     * Data flow:
+     * 1. Input data is passed to before hooks for validation/transformation
+     * 2. Transformed data is passed to the main task function
+     * 3. Task result is passed to after hooks for processing
+     * 4. Final result is returned or error is thrown
+     *
+     * @param data - Input data to pass through the execution pipeline
+     * @param task - Task function to execute with the input data
+     * @returns Task execution result
+     *
+     * @throws {ExecutorError} When task execution fails or plugin errors occur
+     *
+     * @example Execute task with input data
      * ```typescript
-     * const result = await executor.exec(data, async (data) => {
+     * const result = await executor.exec(inputData, async (data) => {
      *   return await processData(data);
      * });
      * ```
+     *
+     * @example Data transformation pipeline
+     * ```typescript
+     * const result = await executor.exec(rawData, (data) => {
+     *   return transformAndValidate(data);
+     * });
+     * ```
      */
     abstract exec<Result, Params = unknown>(data: unknown, task: Task<Result, Params>): Promise<Result> | Result;
     /**
-     * Execute a task without throwing errors
+     * Execute a task without throwing errors, returning errors as values
      *
-     * - Purpose: Safe task execution with error wrapping
-     * - Core Concept: Error-safe execution pipeline
-     * - Main Features:
-     *  - Error wrapping in ExecutorError
-     *  - Non-throwing execution
-     * - Primary Use: When error handling is preferred over exceptions
+     * Core concept:
+     * Provides error-safe task execution by wrapping errors in `ExecutorError`
+     * instances instead of throwing them, enabling explicit error handling
      *
-     * @param task - Task to execute
+     * Main features:
+     * - Error wrapping: All errors are wrapped in `ExecutorError` instances
+     * - Non-throwing: Never throws errors, always returns a value
+     * - Pipeline execution: Runs through complete plugin pipeline
+     * - Type safety: Returns union type of result or error
      *
-     * @example
+     * Error handling:
+     * - Task execution errors are wrapped in `ExecutorError`
+     * - Plugin hook errors are wrapped in `ExecutorError`
+     * - Network/async errors are wrapped in `ExecutorError`
+     * - All errors include original error information and context
+     *
+     * @param task - Task function to execute safely
+     * @returns Task result or `ExecutorError` instance
+     *
+     * @example Safe task execution
      * ```typescript
      * const result = await executor.execNoError(async (data) => {
      *   return await riskyOperation(data);
      * });
+     *
      * if (result instanceof ExecutorError) {
-     *   console.error('Task failed:', result);
+     *   console.error('Task failed:', result.message);
+     *   console.error('Original error:', result.cause);
+     * } else {
+     *   console.log('Task succeeded:', result);
+     * }
+     * ```
+     *
+     * @example Error handling with type guards
+     * ```typescript
+     * const result = await executor.execNoError(async (data) => {
+     *   return await apiCall(data);
+     * });
+     *
+     * if (result instanceof ExecutorError) {
+     *   // Handle error case
+     *   return { success: false, error: result.message };
+     * } else {
+     *   // Handle success case
+     *   return { success: true, data: result };
      * }
      * ```
      */
@@ -519,41 +1014,304 @@ declare abstract class Executor<ExecutorConfig = unknown> {
     /**
      * Execute a task with input data without throwing errors
      *
-     * - Purpose: Safe task execution with error wrapping and input data
-     * - Core Concept: Error-safe execution pipeline with data
-     * - Main Features:
-     *  - Error wrapping in ExecutorError
-     *  - Non-throwing execution
-     * - Primary Use: When error handling is preferred over exceptions with input data
+     * Core concept:
+     * Provides error-safe task execution with input data by wrapping errors
+     * in `ExecutorError` instances, enabling explicit error handling with data processing
      *
-     * @param data - Input data for task
-     * @param task - Task to execute
+     * Main features:
+     * - Error wrapping: All errors are wrapped in `ExecutorError` instances
+     * - Non-throwing: Never throws errors, always returns a value
+     * - Data processing: Passes input data through the execution pipeline
+     * - Pipeline execution: Runs through complete plugin pipeline
      *
-     * @example
+     * Data and error flow:
+     * 1. Input data is processed through before hooks
+     * 2. Task function executes with processed data
+     * 3. Result is processed through after hooks
+     * 4. Final result or error is returned (never thrown)
+     *
+     * @param data - Input data to pass through the execution pipeline
+     * @param task - Task function to execute with the input data
+     * @returns Task result or `ExecutorError` instance
+     *
+     * @example Safe execution with input data
      * ```typescript
-     * const result = await executor.execNoError(data, async (data) => {
-     *   return await riskyOperation(data);
+     * const result = await executor.execNoError(inputData, async (data) => {
+     *   return await processData(data);
      * });
+     *
      * if (result instanceof ExecutorError) {
-     *   console.error('Task failed:', result);
+     *   console.error('Processing failed:', result.message);
+     * } else {
+     *   console.log('Processing succeeded:', result);
      * }
      * ```
+     *
+     * @example Batch processing with error handling
+     * ```typescript
+     * const results = await Promise.all(
+     *   dataItems.map(item =>
+     *     executor.execNoError(item, async (data) => {
+     *       return await processItem(data);
+     *     })
+     *   )
+     * );
+     *
+     * const successes = results.filter(r => !(r instanceof ExecutorError));
+     * const errors = results.filter(r => r instanceof ExecutorError);
+     * ```
      */
     abstract execNoError<Result, Params = unknown>(data: unknown, task: Task<Result, Params>): Promise<Result | ExecutorError> | Result | ExecutorError;
 }
 
+/**
+ * Manages execution context state and plugin runtime tracking
+ *
+ * Core concept:
+ * Centralized context management for executor plugin lifecycle tracking
+ *
+ * Main features:
+ * - Context state management: Reset and initialize context state
+ * - Plugin runtime tracking: Monitor plugin execution times and metadata
+ * - Chain control: Manage execution chain breaking conditions
+ * - Error handling: Context error state management
+ * - Hook validation: Check plugin hook availability and enablement
+ *
+ * Key responsibilities:
+ * - Maintain execution context consistency
+ * - Track plugin execution metadata
+ * - Control execution flow through chain breaking
+ * - Manage error state propagation
+ *
+ * @example Basic usage
+ * ```typescript
+ * const handler = new ContextHandler();
+ * const context = createContext(data);
+ *
+ * // Reset context for new execution
+ * handler.reset(context);
+ *
+ * // Check if plugin should be skipped
+ * const shouldSkip = handler.shouldSkipPluginHook(plugin, 'onBefore', context);
+ * ```
+ *
+ * @category ContextHandler
+ */
+declare class ContextHandler {
+    /**
+     * Reset hooks runtime state to initial values
+     *
+     * Core concept:
+     * Clears all runtime tracking information for fresh execution
+     *
+     * Reset operations:
+     * - Clears plugin name and hook name
+     * - Resets return value and chain breaking flags
+     * - Resets execution counter and index
+     *
+     * @param hooksRuntimes - The hooks runtime object to reset
+     *
+     * @example
+     * ```typescript
+     * const handler = new ContextHandler();
+     * handler.resetHooksRuntimes(context.hooksRuntimes);
+     * ```
+     */
+    resetHooksRuntimes(hooksRuntimes: HookRuntimes): void;
+    /**
+     * Reset entire context to initial state
+     *
+     * Core concept:
+     * Complete context cleanup for new execution cycle
+     *
+     * Reset operations:
+     * - Resets hooks runtime state
+     * - Clears return value
+     * - Clears error state
+     *
+     * @template Params - Type of context parameters
+     * @param context - The execution context to reset
+     *
+     * @example
+     * ```typescript
+     * const handler = new ContextHandler();
+     * handler.reset(context);
+     * ```
+     */
+    reset<Params>(context: ExecutorContext<Params>): void;
+    /**
+     * Check if a plugin hook should be skipped
+     * Returns true if the hook should be skipped (invalid or disabled)
+     *
+     * Core concept:
+     * Plugin hook validation and enablement checking
+     *
+     * Validation criteria:
+     * - Hook method exists and is callable
+     * - Plugin is enabled for the specific hook
+     * - Plugin enablement function returns true
+     *
+     * @template Params - Type of context parameters
+     * @param plugin - The plugin to check
+     * @param hookName - The name of the hook to validate
+     * @param context - The execution context
+     * @returns True if the hook should be skipped, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const shouldSkip = handler.shouldSkipPluginHook(
+     *   validationPlugin,
+     *   'onBefore',
+     *   context
+     * );
+     *
+     * if (!shouldSkip) {
+     *   // Execute the hook
+     * }
+     * ```
+     */
+    shouldSkipPluginHook<Params>(plugin: ExecutorPlugin, hookName: string, context: ExecutorContext<Params>): boolean;
+    /**
+     * Update runtime tracking information for plugin execution
+     *
+     * Core concept:
+     * Track plugin execution metadata for debugging and flow control
+     *
+     * Tracking information:
+     * - Current plugin name
+     * - Current hook name
+     * - Execution counter (times)
+     * - Plugin index in execution chain
+     *
+     * @template Params - Type of context parameters
+     * @param context - The execution context
+     * @param plugin - The plugin being executed
+     * @param hookName - The hook name being executed
+     * @param index - The index of the plugin in the execution chain
+     *
+     * @example
+     * ```typescript
+     * handler.runtimes(context, plugin, 'onBefore', 0);
+     * ```
+     */
+    runtimes<Params>(context: ExecutorContext<Params>, plugin: ExecutorPlugin, hookName: string, index: number): void;
+    /**
+     * Set return value in context runtime tracking
+     *
+     * Core concept:
+     * Store plugin hook return value for chain control and debugging
+     *
+     * Usage scenarios:
+     * - Track plugin hook return values
+     * - Enable chain breaking based on return values
+     * - Debug plugin execution flow
+     *
+     * @template Params - Type of context parameters
+     * @param context - The execution context
+     * @param returnValue - The value to set as return value
+     *
+     * @example
+     * ```typescript
+     * const result = plugin.onBefore(context);
+     * handler.runtimeReturnValue(context, result);
+     * ```
+     */
+    runtimeReturnValue<Params>(context: ExecutorContext<Params>, returnValue: unknown): void;
+    /**
+     * Check if the execution chain should be broken
+     *
+     * Core concept:
+     * Chain breaking control for plugin execution flow
+     *
+     * Chain breaking scenarios:
+     * - Plugin explicitly sets breakChain flag
+     * - Error conditions requiring immediate termination
+     * - Business logic requiring early exit
+     *
+     * @template Params - Type of context parameters
+     * @param context - The execution context
+     * @returns True if the chain should be broken, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (handler.shouldBreakChain(context)) {
+     *   break; // Stop plugin execution
+     * }
+     * ```
+     */
+    shouldBreakChain<Params>(context: ExecutorContext<Params>): boolean;
+    /**
+     * Check if the execution chain should be broken due to return value
+     *
+     * Core concept:
+     * Return value-based chain breaking control
+     *
+     * Usage scenarios:
+     * - Plugin returns a value that should terminate execution
+     * - Error handling hooks return error objects
+     * - Business logic requires return value-based flow control
+     *
+     * @template Params - Type of context parameters
+     * @param context - The execution context
+     * @returns True if the chain should be broken due to return value, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (handler.shouldBreakChainOnReturn(context)) {
+     *   return context.hooksRuntimes.returnValue;
+     * }
+     * ```
+     */
+    shouldBreakChainOnReturn<Params>(context: ExecutorContext<Params>): boolean;
+    /**
+     * Set error in context
+     *
+     * Core concept:
+     * Error state management for execution context
+     *
+     * Error handling:
+     * - Store error for plugin error hooks
+     * - Enable error-based flow control
+     * - Support error propagation through plugin chain
+     *
+     * @template Params - Type of context parameters
+     * @param context - The execution context
+     * @param error - The error to set in context
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Execute some operation
+     * } catch (error) {
+     *   handler.setError(context, error as Error);
+     * }
+     * ```
+     */
+    setError<Params>(context: ExecutorContext<Params>, error: Error): void;
+}
+
 /**
  * Asynchronous implementation of the Executor pattern
  *
- * - Purpose: Provides asynchronous task execution with plugin support
- * - Core Concept: Async execution pipeline with plugin hooks
- * - Main Features:
- *  - Asynchronous plugin hook execution
- *  - Promise-based task handling
- *  - Error handling with plugin support
- * - Primary Use: Handling async operations with extensible middleware
+ * Core concept:
+ * Asynchronous execution pipeline with plugin lifecycle management
  *
- * @example
+ * Main features:
+ * - Asynchronous plugin hook execution: All operations are Promise-based
+ * - Plugin lifecycle management: Support for onBefore, onExec, onSuccess, onError hooks
+ * - Configurable hook execution: Customizable beforeHooks, afterHooks, and execHook
+ * - Chain breaking support: Plugins can interrupt execution chain
+ * - Error handling: Comprehensive error handling with plugin support
+ *
+ * Use this executor when:
+ * - Operations involve async operations (API calls, file I/O, etc.)
+ * - You need to handle Promise-based workflows
+ * - Performance allows for async overhead
+ * - Async operations are involved
+ *
+ * @extends Executor
+ *
+ * @example Basic usage
  * ```typescript
  * const executor = new AsyncExecutor();
  * executor.use(new LogPlugin());
@@ -564,64 +1322,137 @@ declare abstract class Executor<ExecutorConfig = unknown> {
  * });
  * ```
  *
+ * @example With custom configuration
+ * ```typescript
+ * const executor = new AsyncExecutor({
+ *   beforeHooks: ['onBefore', 'onValidate'],
+ *   afterHooks: ['onSuccess', 'onLog'],
+ *   execHook: 'onCustomExec'
+ * });
+ *
+ * const result = await executor.exec(data, async (input) => {
+ *   return await fetchUserData(input.userId);
+ * });
+ * ```
+ *
  * @category AsyncExecutor
  */
-declare class AsyncExecutor<ExecutorConfig = unknown> extends Executor<ExecutorConfig> {
+declare class AsyncExecutor<ExecutorConfig extends ExecutorConfigInterface = ExecutorConfigInterface> extends Executor<ExecutorConfig> {
+    protected contextHandler: ContextHandler;
     /**
-     * Execute plugin hook functions asynchronously
+     * Execute a single plugin hook function asynchronously
      *
-     * - Purpose: Orchestrates asynchronous plugin hook execution
-     * - Core Concept: Sequential async plugin pipeline
-     * - Main Features:
-     *  - Plugin enablement checking
-     *  - Result chaining
-     *  - Error hook special handling
-     * - Primary Use: Internal plugin lifecycle management
+     * Core concept:
+     * Sequential async plugin execution with chain breaking and return value handling
      *
-     * Plugin execution flow:
+     * Execution flow:
      * 1. Check if plugin is enabled for the hook
      * 2. Execute plugin hook if available
      * 3. Handle plugin results and chain breaking conditions
+     * 4. Continue to next plugin or break chain
+     *
+     * Key features:
+     * - Plugin enablement checking
+     * - Chain breaking support
+     * - Return value management
+     * - Runtime tracking
+     * - Async execution with await
      *
      * @param plugins - Array of plugins to execute
      * @param hookName - Name of the hook function to execute
-     * @param args - Arguments to pass to the hook function
-     * @returns Promise resolving to the hook execution result
+     * @param context - Execution context containing data and runtime information
+     * @param args - Additional arguments to pass to the hook function
+     * @returns Promise resolving to the result of the hook function execution
+     * @since 2.1.0
      *
-     * @example
+     * @example Internal usage
      * ```typescript
      * const result = await this.runHook(
      *   this.plugins,
-     *   'beforeExec',
-     *   { userId: 123 }
+     *   'onBefore',
+     *   context,
+     *   data
      * );
      * ```
      */
-    runHooks<Params>(plugins: ExecutorPlugin[], 
+    protected runHook<Params>(plugins: ExecutorPlugin[], 
     /**
-     * allow any string as hook name.
-     * if the hook name is not a function, it will be skipped
+     * Hook name to execute
+     *
+     * Allows any string as hook name. If the hook name is not a function,
+     * the plugin will be skipped for this hook execution.
      *
      * @since 1.1.3
      */
-    hookName: string, context?: ExecutorContext<Params>, ...args: unknown[]): Promise<unknown>;
+    hookName: HookType, context?: ExecutorContext<Params>, ...args: unknown[]): Promise<Params>;
+    /**
+     * Execute multiple plugin hook functions asynchronously
+     * Supports executing multiple hook names in sequence
+     *
+     * Core concept:
+     * Sequential execution of multiple hooks with chain breaking support
+     *
+     * Execution flow:
+     * 1. For each hook name, check if plugin is enabled
+     * 2. Execute plugin hook if available
+     * 3. Handle plugin results and chain breaking conditions
+     * 4. Continue to next hook name if chain is not broken
+     *
+     * Key features:
+     * - Supports multiple hook names in sequence
+     * - Chain breaking support for each hook
+     * - Return value management across hooks
+     * - Backward compatibility with single hook execution
+     * - Async execution with await
+     *
+     * @param plugins - Array of plugins to execute
+     * @param hookNames - Single hook name or array of hook names to execute in sequence
+     * @param context - Execution context containing data and runtime information
+     * @param args - Additional arguments to pass to the hook functions
+     * @returns Promise resolving to the result of the last executed hook function
+     *
+     * @example Execute multiple hooks in sequence
+     * ```typescript
+     * const result = await this.runHooks(
+     *   this.plugins,
+     *   ['onBefore', 'onValidate', 'onProcess'],
+     *   context,
+     *   data
+     * );
+     * ```
+     *
+     * @example Execute single hook (backward compatibility)
+     * ```typescript
+     * const result = await this.runHooks(
+     *   this.plugins,
+     *   'onBefore',
+     *   context,
+     *   data
+     * );
+     * ```
+     */
+    runHooks<Params>(plugins: ExecutorPlugin[], hookNames: HookType | HookType[], context?: ExecutorContext<Params>, ...args: unknown[]): Promise<Params>;
     /**
      * Execute task without throwing errors
      *
-     * - Purpose: Safe execution of async tasks
-     * - Core Concept: Error wrapping and handling
-     * - Main Features:
-     *  - Catches all execution errors
-     *  - Wraps errors in ExecutorError
-     *  - Returns either result or error object
-     * - Primary Use: When you want to handle errors without try-catch
+     * Core concept:
+     * Error-safe execution pipeline that returns errors instead of throwing
      *
-     * @template T - Type of task return value
+     * Advantages over try-catch:
+     * - Standardized error handling
+     * - No exception propagation
+     * - Consistent error types
+     * - Plugin error handling support
+     *
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
      * @param dataOrTask - Task data or task function
-     * @param task - Task function (optional)
-     * @returns Promise resolving to either result or ExecutorError
+     * @param task - Task function (optional when dataOrTask is a function)
+     * @returns Promise resolving to task result or ExecutorError if execution fails
      *
-     * @example
+     * @throws Never throws - all errors are wrapped in ExecutorError
+     *
+     * @example Basic usage
      * ```typescript
      * const result = await executor.execNoError(async () => {
      *   const response = await riskyOperation();
@@ -632,190 +1463,305 @@ declare class AsyncExecutor<ExecutorConfig = unknown> extends Executor<ExecutorC
      *   console.error('Operation failed:', result);
      * }
      * ```
+     *
+     * @example With input data
+     * ```typescript
+     * const result = await executor.execNoError(
+     *   { userId: 123 },
+     *   async (data) => await fetchUserData(data.userId)
+     * );
+     * ```
      */
-    execNoError<Result, Params = unknown>(dataOrTask: unknown | PromiseTask<Result, Params>, task?: PromiseTask<Result, Params>): Promise<Result | ExecutorError>;
+    execNoError<Result, Params = unknown>(dataOrTask: Params | PromiseTask<Result, Params>, task?: PromiseTask<Result, Params>): Promise<Result | ExecutorError>;
     /**
      * Execute asynchronous task with full plugin pipeline
      *
-     * - Purpose: Primary method for executing async tasks
-     * - Core Concept: Full plugin pipeline execution
-     * - Main Features:
-     *  - Plugin hook integration
-     *  - Task validation
-     *  - Custom execution support
-     * - Primary Use: Running async tasks with plugin support
+     * Core concept:
+     * Complete execution pipeline with plugin lifecycle management
      *
      * Execution flow:
      * 1. Validate and prepare task
-     * 2. Check for custom execution plugins
-     * 3. Execute task with plugin pipeline
+     * 2. Execute beforeHooks (configured or default 'onBefore')
+     * 3. Execute core task logic with execHook support
+     * 4. Execute afterHooks (configured or default 'onSuccess')
+     * 5. Handle errors with onError hooks if needed
      *
-     * @template T - Type of task return value
-     * @template D - Type of task data
+     * Performance considerations:
+     * - Async overhead for Promise handling
+     * - Sequential execution path
+     * - Plugin chain optimization
+     *
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
      * @param dataOrTask - Task data or task function
-     * @param task - Task function (optional)
+     * @param task - Task function (optional when dataOrTask is a function)
      * @throws {Error} When task is not an async function
-     * @returns Promise resolving to task result
+     * @throws {ExecutorError} When task execution fails
+     * @returns Promise resolving to task execution result
      *
-     * @example
+     * @example Basic task execution
+     * ```typescript
+     * const result = await executor.exec(async (data) => {
+     *   const response = await fetch('https://api.example.com/data');
+     *   return response.json();
+     * });
+     * ```
+     *
+     * @example With input data
      * ```typescript
-     * // With separate data and task
      * const data = { userId: 123 };
      * const result = await executor.exec(data, async (input) => {
      *   return await fetchUserData(input.userId);
      * });
+     * ```
      *
-     * // With combined task
-     * const result = await executor.exec(async () => {
-     *   return await fetchData();
+     * @example With validation
+     * ```typescript
+     * const result = await executor.exec(async (data) => {
+     *   if (typeof data !== 'string') {
+     *     throw new Error('Data must be string');
+     *   }
+     *   return await processData(data);
      * });
      * ```
      */
     exec<Result, Params = unknown>(dataOrTask: Params | PromiseTask<Result, Params>, task?: PromiseTask<Result, Params>): Promise<Result>;
+    /**
+     * Execute core task logic with execHook support
+     *
+     * Core concept:
+     * Handles the execution phase with optional plugin intervention
+     *
+     * Execution logic:
+     * 1. Execute configured execHook (default: 'onExec')
+     * 2. If no execHook was executed, run the actual task
+     * 3. Otherwise, use the return value from execHook
+     *
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
+     * @param context - Execution context
+     * @param actualTask - Task function to execute
+     */
+    protected runExec<Result, Params = unknown>(context: ExecutorContext<Params>, actualTask: PromiseTask<Result, Params>): Promise<void>;
     /**
      * Core task execution method with plugin hooks
      *
-     * - Purpose: Implements the complete execution pipeline
-     * - Core Concept: Sequential hook execution with error handling
-     * - Main Features:
-     *  - Before/After hooks
-     *  - Error handling hooks
-     *  - Result transformation
-     * - Primary Use: Internal pipeline orchestration
+     * Core concept:
+     * Complete execution pipeline with configurable hook lifecycle
      *
      * Pipeline stages:
-     * 1. onBefore hooks - Pre-process input data
-     * 2. Task execution - Run the actual task
-     * 3. onSuccess hooks - Post-process results
+     * 1. beforeHooks - Pre-process input data (configurable, default: 'onBefore')
+     * 2. Task execution - Run the actual task with execHook support
+     * 3. afterHooks - Post-process results (configurable, default: 'onSuccess')
      * 4. onError hooks - Handle any errors
      *
-     * @template T - Type of task return value
-     * @template D - Type of task data
-     * @param data - Input data for the task
-     * @param actualTask - Task function to execute
+     * Error handling strategy:
+     * - Catches all errors
+     * - Passes errors through plugin chain
+     * - Wraps unhandled errors in ExecutorError
+     * - Supports plugin error handling
+     *
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
+     * @param data - Data to pass to the task
+     * @param actualTask - Actual task function to execute
      * @throws {ExecutorError} When task execution fails
-     * @returns Promise resolving to task result(context.returnValue)
+     * @returns Promise resolving to task execution result
      *
-     * @example
+     * @example Internal implementation
      * ```typescript
-     * private async run(data, task) {
+     * protected async run(data, task) {
      *   try {
-     *     const preparedData = await this.runHook(this.plugins, 'onBefore', data);
-     *     const result = await task(preparedData);
-     *     return await this.runHook(this.plugins, 'onSuccess', result);
+     *     // Execute beforeHooks (configurable)
+     *     await this.runHooks(this.plugins, beforeHooks, context);
+     *
+     *     // Execute core logic with execHook support
+     *     await this.runExec(context, actualTask);
+     *
+     *     // Execute afterHooks (configurable)
+     *     await this.runHooks(this.plugins, afterHooks, context);
+     *
+     *     return context.returnValue;
      *   } catch (error) {
-     *     const handledError = await this.runHook(
-     *       this.plugins,
-     *       'onError',
-     *       error,
-     *       data
-     *     );
-     *     throw new ExecutorError('EXECUTION_FAILED', handledError);
+     *     // Handle errors with onError hooks
+     *     await this.runHook(this.plugins, 'onError', context);
      *   }
      * }
      * ```
      */
-    run<Result, Params = unknown>(data: Params, actualTask: PromiseTask<Result, Params>): Promise<Result>;
+    protected run<Result, Params = unknown>(data: Params, actualTask: PromiseTask<Result, Params>): Promise<Result>;
 }
 
 /**
  * Synchronous executor class that extends the base Executor
  * Provides synchronous task execution with plugin support
  *
- * Key features:
- * 1. Synchronous plugin hook execution
- * 2. No Promise-based operations
- * 3. Immediate error handling
- * 4. Direct execution flow
+ * Core concept:
+ * Synchronous execution pipeline with plugin lifecycle management
+ *
+ * Main features:
+ * - Synchronous plugin hook execution: All operations are immediate without Promise overhead
+ * - Plugin lifecycle management: Support for onBefore, onExec, onSuccess, onError hooks
+ * - Configurable hook execution: Customizable beforeHooks, afterHooks, and execHook
+ * - Chain breaking support: Plugins can interrupt execution chain
+ * - Error handling: Comprehensive error handling with plugin support
  *
  * Use this executor when:
- * 1. All operations are synchronous
- * 2. You need immediate results
- * 3. Performance is critical
- * 4. No async operations are involved
+ * - All operations are synchronous
+ * - You need immediate results
+ * - Performance is critical
+ * - No async operations are involved
  *
  * @extends Executor
  *
- * @example
+ * @example Basic usage
  * ```typescript
- * // Create a sync executor
  * const executor = new SyncExecutor();
- *
- * // Add plugins for different purposes
  * executor.use(new ValidationPlugin());
  * executor.use(new LoggerPlugin());
  *
- * // Example 1: Basic sync task execution
  * const result = executor.exec((data) => {
  *   return data.toUpperCase();
  * });
+ * ```
+ *
+ * @example With custom configuration
+ * ```typescript
+ * const executor = new SyncExecutor({
+ *   beforeHooks: ['onBefore', 'onValidate'],
+ *   afterHooks: ['onSuccess', 'onLog'],
+ *   execHook: 'onCustomExec'
+ * });
  *
- * // Example 2: Execution with input data
- * const data = { value: 'hello' };
  * const result = executor.exec(data, (input) => {
  *   return input.value.toUpperCase();
  * });
+ * ```
  *
- * // Example 3: Error handling with execNoError
+ * @example Error handling
+ * ```typescript
  * const result = executor.execNoError(() => {
  *   throw new Error('Validation Error');
  * }); // Returns ExecutorError instead of throwing
  * ```
+ *
  * @category SyncExecutor
  */
-declare class SyncExecutor<ExecutorConfig = unknown> extends Executor<ExecutorConfig> {
+declare class SyncExecutor<ExecutorConfig extends ExecutorConfigInterface = ExecutorConfigInterface> extends Executor<ExecutorConfig> {
+    protected contextHandler: ContextHandler;
     /**
-     * Execute plugin hook functions synchronously
-     * Manages the plugin execution chain and handles results
+     * Execute a single plugin hook function synchronously
+     *
+     * Core concept:
+     * Sequential plugin execution with chain breaking and return value handling
      *
-     * Plugin execution flow:
+     * Execution flow:
      * 1. Check if plugin is enabled for the hook
      * 2. Execute plugin hook if available
      * 3. Handle plugin results and chain breaking conditions
+     * 4. Continue to next plugin or break chain
      *
-     * Key differences from AsyncExecutor:
-     * - All operations are synchronous
-     * - Results are immediately available
-     * - No await statements needed
+     * Key features:
+     * - Plugin enablement checking
+     * - Chain breaking support
+     * - Return value management
+     * - Runtime tracking
      *
      * @param plugins - Array of plugins to execute
      * @param hookName - Name of the hook function to execute
-     * @param args - Arguments to pass to the hook function
+     * @param context - Execution context containing data and runtime information
+     * @param args - Additional arguments to pass to the hook function
      * @returns Result of the hook function execution
+     * @since 2.1.0
      *
-     * @example
+     * @example Internal usage
      * ```typescript
-     * // Internal usage example
      * const result = this.runHook(
      *   this.plugins,
      *   'onBefore',
-     *   { value: 'test' }
+     *   context,
+     *   data
      * );
      * ```
      */
-    runHooks<Params>(plugins: ExecutorPlugin[], 
+    protected runHook<Params>(plugins: ExecutorPlugin[], 
     /**
-     * allow any string as hook name.
-     * if the hook name is not a function, it will be skipped
+     * Hook name to execute
+     *
+     * Allows any string as hook name. If the hook name is not a function,
+     * the plugin will be skipped for this hook execution.
      *
      * @since 1.1.3
      */
-    hookName: string, context?: ExecutorContext<Params>, ...args: unknown[]): Params;
+    hookName: HookType, context?: ExecutorContext<Params>, ...args: unknown[]): Params;
+    /**
+     * Execute multiple plugin hook functions synchronously
+     * Supports executing multiple hook names in sequence
+     *
+     * Core concept:
+     * Sequential execution of multiple hooks with chain breaking support
+     *
+     * Execution flow:
+     * 1. For each hook name, check if plugin is enabled
+     * 2. Execute plugin hook if available
+     * 3. Handle plugin results and chain breaking conditions
+     * 4. Continue to next hook name if chain is not broken
+     *
+     * Key features:
+     * - Supports multiple hook names in sequence
+     * - Chain breaking support for each hook
+     * - Return value management across hooks
+     * - Backward compatibility with single hook execution
+     *
+     * @param plugins - Array of plugins to execute
+     * @param hookNames - Single hook name or array of hook names to execute in sequence
+     * @param context - Execution context containing data and runtime information
+     * @param args - Additional arguments to pass to the hook functions
+     * @returns Result of the last executed hook function
+     *
+     * @example Execute multiple hooks in sequence
+     * ```typescript
+     * const result = this.runHooks(
+     *   this.plugins,
+     *   ['onBefore', 'onValidate', 'onProcess'],
+     *   context,
+     *   data
+     * );
+     * ```
+     *
+     * @example Execute single hook (backward compatibility)
+     * ```typescript
+     * const result = this.runHooks(
+     *   this.plugins,
+     *   'onBefore',
+     *   context,
+     *   data
+     * );
+     * ```
+     */
+    runHooks<Params>(plugins: ExecutorPlugin[], hookNames: HookType | HookType[], context?: ExecutorContext<Params>, ...args: unknown[]): Params;
     /**
      * Execute task without throwing errors
      * Wraps all errors in ExecutorError for safe error handling
      *
+     * Core concept:
+     * Error-safe execution pipeline that returns errors instead of throwing
+     *
      * Advantages over try-catch:
-     * 1. Standardized error handling
-     * 2. No exception propagation
-     * 3. Consistent error types
+     * - Standardized error handling
+     * - No exception propagation
+     * - Consistent error types
+     * - Plugin error handling support
      *
-     * @template T - Type of task return value
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
      * @param dataOrTask - Task data or task function
-     * @param task - Task function (optional)
-     * @returns Task result or ExecutorError
+     * @param task - Task function (optional when dataOrTask is a function)
+     * @returns Task result or ExecutorError if execution fails
      *
-     * @example
+     * @throws Never throws - all errors are wrapped in ExecutorError
+     *
+     * @example Basic usage
      * ```typescript
      * const result = executor.execNoError((data) => {
      *   if (!data.isValid) {
@@ -830,40 +1776,63 @@ declare class SyncExecutor<ExecutorConfig = unknown> extends Executor<ExecutorCo
      *   console.log('Task succeeded:', result);
      * }
      * ```
+     *
+     * @example With input data
+     * ```typescript
+     * const result = executor.execNoError(
+     *   { value: 'test' },
+     *   (data) => data.value.toUpperCase()
+     * );
+     * ```
      */
     execNoError<Result, Params = unknown>(dataOrTask: Params | SyncTask<Result, Params>, task?: SyncTask<Result, Params>): Result | ExecutorError;
     /**
      * Execute synchronous task with full plugin pipeline
      * Core method for task execution with plugin support
      *
+     * Core concept:
+     * Complete execution pipeline with plugin lifecycle management
+     *
      * Execution flow:
      * 1. Validate and prepare task
-     * 2. Check for custom execution plugins
-     * 3. Execute task with plugin pipeline
+     * 2. Execute beforeHooks (configured or default 'onBefore')
+     * 3. Execute core task logic with execHook support
+     * 4. Execute afterHooks (configured or default 'onSuccess')
+     * 5. Handle errors with onError hooks if needed
      *
      * Performance considerations:
      * - No async overhead
      * - Direct execution path
      * - Immediate results
+     * - Plugin chain optimization
      *
-     * @template T - Type of task return value
-     * @template D - Type of task data
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
      * @param dataOrTask - Task data or task function
-     * @param task - Task function (optional)
+     * @param task - Task function (optional when dataOrTask is a function)
      * @throws {Error} When task is not a function
+     * @throws {ExecutorError} When task execution fails
      * @returns Task execution result
      *
-     * @example
+     * @example Basic task execution
+     * ```typescript
+     * const result = executor.exec((data) => {
+     *   return data.toUpperCase();
+     * });
+     * ```
+     *
+     * @example With input data
      * ```typescript
-     * // Example with data transformation
      * const data = { numbers: [1, 2, 3] };
      * const task = (input) => {
      *   return input.numbers.map(n => n * 2);
      * };
      *
      * const result = executor.exec(data, task);
+     * ```
      *
-     * // Example with validation
+     * @example With validation
+     * ```typescript
      * const result = executor.exec((data) => {
      *   if (typeof data !== 'string') {
      *     throw new Error('Data must be string');
@@ -873,49 +1842,71 @@ declare class SyncExecutor<ExecutorConfig = unknown> extends Executor<ExecutorCo
      * ```
      */
     exec<Result, Params = unknown>(dataOrTask: Params | SyncTask<Result, Params>, task?: SyncTask<Result, Params>): Result;
+    /**
+     * Execute core task logic with execHook support
+     *
+     * Core concept:
+     * Handles the execution phase with optional plugin intervention
+     *
+     * Execution logic:
+     * 1. Execute configured execHook (default: 'onExec')
+     * 2. If no execHook was executed, run the actual task
+     * 3. Otherwise, use the return value from execHook
+     *
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
+     * @param context - Execution context
+     * @param actualTask - Task function to execute
+     */
+    protected runExec<Result, Params = unknown>(context: ExecutorContext<Params>, actualTask: SyncTask<Result, Params>): void;
     /**
      * Core method to run synchronous task with plugin hooks
      * Implements the complete execution pipeline with all plugin hooks
      *
+     * Core concept:
+     * Complete execution pipeline with configurable hook lifecycle
+     *
      * Pipeline stages:
-     * 1. onBefore hooks - Pre-process input data
-     * 2. Task execution - Run the actual task
-     * 3. onSuccess hooks - Post-process results
+     * 1. beforeHooks - Pre-process input data (configurable, default: 'onBefore')
+     * 2. Task execution - Run the actual task with execHook support
+     * 3. afterHooks - Post-process results (configurable, default: 'onSuccess')
      * 4. onError hooks - Handle any errors
      *
      * Error handling strategy:
      * - Catches all errors
      * - Passes errors through plugin chain
      * - Wraps unhandled errors in ExecutorError
+     * - Supports plugin error handling
      *
-     * @template T - Type of task return value
-     * @template D - Type of task data
+     * @template Result - Type of task return value
+     * @template Params - Type of task input parameters
      * @param data - Data to pass to the task
      * @param actualTask - Actual task function to execute
      * @throws {ExecutorError} When task execution fails
      * @returns Task execution result
      *
-     * @example
+     * @example Internal implementation
      * ```typescript
-     * // Internal implementation example
-     * private run(data, task) {
+     * protected run(data, task) {
      *   try {
-     *     const preparedData = this.runHook(this.plugins, 'onBefore', data);
-     *     const result = task(preparedData);
-     *     return this.runHook(this.plugins, 'onSuccess', result);
+     *     // Execute beforeHooks (configurable)
+     *     this.runHooks(this.plugins, beforeHooks, context);
+     *
+     *     // Execute core logic with execHook support
+     *     this.runExec(context, actualTask);
+     *
+     *     // Execute afterHooks (configurable)
+     *     this.runHooks(this.plugins, afterHooks, context);
+     *
+     *     return context.returnValue;
      *   } catch (error) {
-     *     const handledError = this.runHook(
-     *       this.plugins,
-     *       'onError',
-     *       error,
-     *       data
-     *     );
-     *     // Error handling logic
+     *     // Handle errors with onError hooks
+     *     this.runHook(this.plugins, 'onError', context);
      *   }
      * }
      * ```
      */
-    run<Result, Params = unknown>(data: Params, actualTask: SyncTask<Result, Params>): Result;
+    protected run<Result, Params = unknown>(data: Params, actualTask: SyncTask<Result, Params>): Result;
 }
 
 /**
@@ -2956,4 +3947,4 @@ type Intersection<T1, T2> = {
     [P in keyof T1 & keyof T2]: T1[P] | T2[P];
 };
 
-export { AsyncExecutor, type AsyncStorageInterface, Base64Serializer, type Encryptor, Executor, type ExecutorContext, ExecutorError, type ExecutorPlugin, type ExpireOptions, FetchAbortPlugin, FetchURLPlugin, type HookRuntimes, type Intersection, JSONSerializer, type JSONSerializerOptions, KeyStorage, KeyStorageInterface, type KeyStorageOptions, ObjectStorage, type ObjectStorageOptions, type PipeArg, type PromiseTask, RequestAdapterAxios, type RequestAdapterConfig, RequestAdapterFetch, type RequestAdapterFetchConfig, type RequestAdapterInterface, type RequestAdapterResponse, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, type RequestTransactionInterface, type RetryOptions, RetryPlugin, type SerializerIneterface, type StorageValue, SyncExecutor, SyncStorage, type SyncStorageInterface, type SyncTask, type Task, type ValueOf };
+export { AsyncExecutor, type AsyncStorageInterface, Base64Serializer, type Encryptor, Executor, type ExecutorConfigInterface, type ExecutorContext, ExecutorError, type ExecutorPlugin, type ExpireOptions, FetchAbortPlugin, FetchURLPlugin, type HookRuntimes, type HookType, type Intersection, JSONSerializer, type JSONSerializerOptions, KeyStorage, KeyStorageInterface, type KeyStorageOptions, ObjectStorage, type ObjectStorageOptions, type PipeArg, type PromiseTask, RequestAdapterAxios, type RequestAdapterConfig, RequestAdapterFetch, type RequestAdapterFetchConfig, type RequestAdapterInterface, type RequestAdapterResponse, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, type RequestTransactionInterface, type RetryOptions, RetryPlugin, type SerializerIneterface, type StorageValue, SyncExecutor, SyncStorage, type SyncStorageInterface, type SyncTask, type Task, type ValueOf };