@qlover/fe-corekit 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -2466,24 +2466,33 @@ var require_pick = __commonJS({
2466
2466
  // src/executor/interface/Executor.ts
2467
2467
  var Executor = /*#__PURE__*/ function() {
2468
2468
  "use strict";
2469
- function Executor(config) {
2469
+ function Executor() {
2470
+ var config = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
2470
2471
  _class_call_check(this, Executor);
2471
2472
  this.config = config;
2472
2473
  /**
2473
- * Array of active plugins
2474
+ * Array of active plugins for this executor
2475
+ *
2476
+ * Core concept:
2477
+ * Maintains an ordered collection of plugins that participate in the execution pipeline
2474
2478
  *
2475
- * - Purpose: Stores and manages executor plugins
2476
- * - Core Concept: Ordered plugin pipeline
2477
- * - Main Features:
2478
- * - Maintains plugin execution order
2479
- * - Supports plugin lifecycle management
2480
- * - Primary Use: Plugin orchestration and execution
2479
+ * Main features:
2480
+ * - Plugin storage: Stores all registered plugins in execution order
2481
+ * - Lifecycle management: Manages plugin initialization and cleanup
2482
+ * - Execution coordination: Ensures plugins execute in the correct sequence
2483
+ * - Deduplication support: Prevents duplicate plugins when configured
2484
+ *
2485
+ * Plugin execution order:
2486
+ * 1. Plugins are executed in the order they were added
2487
+ * 2. Each plugin can modify data or control execution flow
2488
+ * 3. Plugin hooks are called based on executor configuration
2481
2489
  *
2482
2490
  * @example
2483
2491
  * ```typescript
2484
2492
  * protected plugins = [
2485
2493
  * new LoggerPlugin(),
2486
- * new RetryPlugin()
2494
+ * new RetryPlugin({ maxAttempts: 3 }),
2495
+ * new CachePlugin({ ttl: 300 })
2487
2496
  * ];
2488
2497
  * ```
2489
2498
  */ this.plugins = [];
@@ -2491,33 +2500,56 @@ var Executor = /*#__PURE__*/ function() {
2491
2500
  _create_class(Executor, [
2492
2501
  {
2493
2502
  /**
2494
- * Add a plugin to the executor
2503
+ * Add a plugin to the executor's execution pipeline
2495
2504
  *
2496
- * - Purpose: Extends executor functionality through plugins
2497
- * - Core Concept: Plugin registration and deduplication
2498
- * - Main Features:
2499
- * - Prevents duplicate plugins if onlyOne is true
2500
- * - Maintains plugin execution order
2501
- * - Primary Use: Adding new capabilities to executor
2505
+ * Core concept:
2506
+ * Registers a plugin to participate in the executor's execution pipeline,
2507
+ * extending the executor's functionality with additional capabilities
2502
2508
  *
2503
- * @param plugin - Plugin instance to add
2509
+ * Main features:
2510
+ * - Plugin registration: Adds plugins to the execution pipeline
2511
+ * - Deduplication: Prevents duplicate plugins when `onlyOne` is true
2512
+ * - Order preservation: Maintains plugin execution order
2513
+ * - Validation: Ensures plugin is a valid object
2504
2514
  *
2505
- * @example
2515
+ * Deduplication logic:
2516
+ * - Checks for exact plugin instance match
2517
+ * - Checks for plugin name match
2518
+ * - Checks for constructor match
2519
+ * - Only prevents duplicates when `plugin.onlyOne` is true
2520
+ *
2521
+ * @param plugin - Plugin instance to add to the execution pipeline
2522
+ *
2523
+ * @throws {Error} When plugin is not a valid object
2524
+ *
2525
+ * @example Add a class-based plugin
2506
2526
  * ```typescript
2507
2527
  * executor.use(new LoggerPlugin());
2508
2528
  * executor.use(new RetryPlugin({ maxAttempts: 3 }));
2509
2529
  * ```
2510
2530
  *
2511
- * @example
2512
- *
2513
- * Use a plain object as a plugin
2531
+ * @example Add a plain object plugin
2514
2532
  * ```typescript
2515
2533
  * executor.use({
2516
- * onBefore: (data) => ({ ...data, modified: true })
2534
+ * pluginName: 'CustomPlugin',
2535
+ * onBefore: (data) => ({ ...data, modified: true }),
2536
+ * onAfter: (result) => console.log('Result:', result)
2517
2537
  * });
2518
2538
  * ```
2539
+ *
2540
+ * @example Plugin with deduplication
2541
+ * ```typescript
2542
+ * const plugin = new LoggerPlugin();
2543
+ * plugin.onlyOne = true;
2544
+ *
2545
+ * executor.use(plugin); // First addition - succeeds
2546
+ * executor.use(plugin); // Second addition - skipped with warning
2547
+ * ```
2519
2548
  */ key: "use",
2520
2549
  value: function use(plugin) {
2550
+ if ((typeof plugin === "undefined" ? "undefined" : _type_of(plugin)) !== "object" || plugin === null) {
2551
+ throw new Error("Plugin must be an object");
2552
+ }
2521
2553
  if (this.plugins.find(function(p) {
2522
2554
  return p === plugin || p.pluginName === plugin.pluginName || p.constructor === plugin.constructor;
2523
2555
  }) && plugin.onlyOne) {
@@ -2548,6 +2580,267 @@ var ExecutorError = /*#__PURE__*/ function _target(Error1) {
2548
2580
  }
2549
2581
  return ExecutorError;
2550
2582
  }(_wrap_native_super(Error));
2583
+ // src/executor/impl/ContextHandler.ts
2584
+ function createContext(parameters) {
2585
+ return {
2586
+ parameters: parameters,
2587
+ returnValue: void 0,
2588
+ error: void 0,
2589
+ hooksRuntimes: {
2590
+ pluginName: "",
2591
+ hookName: "",
2592
+ returnValue: void 0,
2593
+ returnBreakChain: false,
2594
+ times: 0,
2595
+ breakChain: false,
2596
+ index: void 0
2597
+ }
2598
+ };
2599
+ }
2600
+ var ContextHandler = /*#__PURE__*/ function() {
2601
+ "use strict";
2602
+ function ContextHandler() {
2603
+ _class_call_check(this, ContextHandler);
2604
+ }
2605
+ _create_class(ContextHandler, [
2606
+ {
2607
+ /**
2608
+ * Reset hooks runtime state to initial values
2609
+ *
2610
+ * Core concept:
2611
+ * Clears all runtime tracking information for fresh execution
2612
+ *
2613
+ * Reset operations:
2614
+ * - Clears plugin name and hook name
2615
+ * - Resets return value and chain breaking flags
2616
+ * - Resets execution counter and index
2617
+ *
2618
+ * @param hooksRuntimes - The hooks runtime object to reset
2619
+ *
2620
+ * @example
2621
+ * ```typescript
2622
+ * const handler = new ContextHandler();
2623
+ * handler.resetHooksRuntimes(context.hooksRuntimes);
2624
+ * ```
2625
+ */ key: "resetHooksRuntimes",
2626
+ value: function resetHooksRuntimes(hooksRuntimes) {
2627
+ hooksRuntimes.pluginName = "";
2628
+ hooksRuntimes.hookName = "";
2629
+ hooksRuntimes.returnValue = void 0;
2630
+ hooksRuntimes.returnBreakChain = false;
2631
+ hooksRuntimes.times = 0;
2632
+ hooksRuntimes.breakChain = false;
2633
+ hooksRuntimes.index = void 0;
2634
+ }
2635
+ },
2636
+ {
2637
+ /**
2638
+ * Reset entire context to initial state
2639
+ *
2640
+ * Core concept:
2641
+ * Complete context cleanup for new execution cycle
2642
+ *
2643
+ * Reset operations:
2644
+ * - Resets hooks runtime state
2645
+ * - Clears return value
2646
+ * - Clears error state
2647
+ *
2648
+ * @template Params - Type of context parameters
2649
+ * @param context - The execution context to reset
2650
+ *
2651
+ * @example
2652
+ * ```typescript
2653
+ * const handler = new ContextHandler();
2654
+ * handler.reset(context);
2655
+ * ```
2656
+ */ key: "reset",
2657
+ value: function reset(context) {
2658
+ this.resetHooksRuntimes(context.hooksRuntimes);
2659
+ context.returnValue = void 0;
2660
+ context.error = void 0;
2661
+ }
2662
+ },
2663
+ {
2664
+ /**
2665
+ * Check if a plugin hook should be skipped
2666
+ * Returns true if the hook should be skipped (invalid or disabled)
2667
+ *
2668
+ * Core concept:
2669
+ * Plugin hook validation and enablement checking
2670
+ *
2671
+ * Validation criteria:
2672
+ * - Hook method exists and is callable
2673
+ * - Plugin is enabled for the specific hook
2674
+ * - Plugin enablement function returns true
2675
+ *
2676
+ * @template Params - Type of context parameters
2677
+ * @param plugin - The plugin to check
2678
+ * @param hookName - The name of the hook to validate
2679
+ * @param context - The execution context
2680
+ * @returns True if the hook should be skipped, false otherwise
2681
+ *
2682
+ * @example
2683
+ * ```typescript
2684
+ * const shouldSkip = handler.shouldSkipPluginHook(
2685
+ * validationPlugin,
2686
+ * 'onBefore',
2687
+ * context
2688
+ * );
2689
+ *
2690
+ * if (!shouldSkip) {
2691
+ * // Execute the hook
2692
+ * }
2693
+ * ```
2694
+ */ key: "shouldSkipPluginHook",
2695
+ value: function shouldSkipPluginHook(plugin, hookName, context) {
2696
+ return typeof plugin[hookName] !== "function" || typeof plugin.enabled == "function" && !plugin.enabled(hookName, context);
2697
+ }
2698
+ },
2699
+ {
2700
+ /**
2701
+ * Update runtime tracking information for plugin execution
2702
+ *
2703
+ * Core concept:
2704
+ * Track plugin execution metadata for debugging and flow control
2705
+ *
2706
+ * Tracking information:
2707
+ * - Current plugin name
2708
+ * - Current hook name
2709
+ * - Execution counter (times)
2710
+ * - Plugin index in execution chain
2711
+ *
2712
+ * @template Params - Type of context parameters
2713
+ * @param context - The execution context
2714
+ * @param plugin - The plugin being executed
2715
+ * @param hookName - The hook name being executed
2716
+ * @param index - The index of the plugin in the execution chain
2717
+ *
2718
+ * @example
2719
+ * ```typescript
2720
+ * handler.runtimes(context, plugin, 'onBefore', 0);
2721
+ * ```
2722
+ */ key: "runtimes",
2723
+ value: function runtimes(context, plugin, hookName, index) {
2724
+ context.hooksRuntimes.pluginName = plugin.pluginName;
2725
+ context.hooksRuntimes.hookName = hookName;
2726
+ context.hooksRuntimes.times = (context.hooksRuntimes.times || 0) + 1;
2727
+ context.hooksRuntimes.index = index;
2728
+ }
2729
+ },
2730
+ {
2731
+ /**
2732
+ * Set return value in context runtime tracking
2733
+ *
2734
+ * Core concept:
2735
+ * Store plugin hook return value for chain control and debugging
2736
+ *
2737
+ * Usage scenarios:
2738
+ * - Track plugin hook return values
2739
+ * - Enable chain breaking based on return values
2740
+ * - Debug plugin execution flow
2741
+ *
2742
+ * @template Params - Type of context parameters
2743
+ * @param context - The execution context
2744
+ * @param returnValue - The value to set as return value
2745
+ *
2746
+ * @example
2747
+ * ```typescript
2748
+ * const result = plugin.onBefore(context);
2749
+ * handler.runtimeReturnValue(context, result);
2750
+ * ```
2751
+ */ key: "runtimeReturnValue",
2752
+ value: function runtimeReturnValue(context, returnValue) {
2753
+ context.hooksRuntimes.returnValue = returnValue;
2754
+ }
2755
+ },
2756
+ {
2757
+ /**
2758
+ * Check if the execution chain should be broken
2759
+ *
2760
+ * Core concept:
2761
+ * Chain breaking control for plugin execution flow
2762
+ *
2763
+ * Chain breaking scenarios:
2764
+ * - Plugin explicitly sets breakChain flag
2765
+ * - Error conditions requiring immediate termination
2766
+ * - Business logic requiring early exit
2767
+ *
2768
+ * @template Params - Type of context parameters
2769
+ * @param context - The execution context
2770
+ * @returns True if the chain should be broken, false otherwise
2771
+ *
2772
+ * @example
2773
+ * ```typescript
2774
+ * if (handler.shouldBreakChain(context)) {
2775
+ * break; // Stop plugin execution
2776
+ * }
2777
+ * ```
2778
+ */ key: "shouldBreakChain",
2779
+ value: function shouldBreakChain(context) {
2780
+ var _context_hooksRuntimes;
2781
+ return !!((_context_hooksRuntimes = context.hooksRuntimes) === null || _context_hooksRuntimes === void 0 ? void 0 : _context_hooksRuntimes.breakChain);
2782
+ }
2783
+ },
2784
+ {
2785
+ /**
2786
+ * Check if the execution chain should be broken due to return value
2787
+ *
2788
+ * Core concept:
2789
+ * Return value-based chain breaking control
2790
+ *
2791
+ * Usage scenarios:
2792
+ * - Plugin returns a value that should terminate execution
2793
+ * - Error handling hooks return error objects
2794
+ * - Business logic requires return value-based flow control
2795
+ *
2796
+ * @template Params - Type of context parameters
2797
+ * @param context - The execution context
2798
+ * @returns True if the chain should be broken due to return value, false otherwise
2799
+ *
2800
+ * @example
2801
+ * ```typescript
2802
+ * if (handler.shouldBreakChainOnReturn(context)) {
2803
+ * return context.hooksRuntimes.returnValue;
2804
+ * }
2805
+ * ```
2806
+ */ key: "shouldBreakChainOnReturn",
2807
+ value: function shouldBreakChainOnReturn(context) {
2808
+ var _context_hooksRuntimes;
2809
+ return !!((_context_hooksRuntimes = context.hooksRuntimes) === null || _context_hooksRuntimes === void 0 ? void 0 : _context_hooksRuntimes.returnBreakChain);
2810
+ }
2811
+ },
2812
+ {
2813
+ /**
2814
+ * Set error in context
2815
+ *
2816
+ * Core concept:
2817
+ * Error state management for execution context
2818
+ *
2819
+ * Error handling:
2820
+ * - Store error for plugin error hooks
2821
+ * - Enable error-based flow control
2822
+ * - Support error propagation through plugin chain
2823
+ *
2824
+ * @template Params - Type of context parameters
2825
+ * @param context - The execution context
2826
+ * @param error - The error to set in context
2827
+ *
2828
+ * @example
2829
+ * ```typescript
2830
+ * try {
2831
+ * // Execute some operation
2832
+ * } catch (error) {
2833
+ * handler.setError(context, error as Error);
2834
+ * }
2835
+ * ```
2836
+ */ key: "setError",
2837
+ value: function setError(context, error) {
2838
+ context.error = error;
2839
+ }
2840
+ }
2841
+ ]);
2842
+ return ContextHandler;
2843
+ }();
2551
2844
  // src/executor/impl/AsyncExecutor.ts
2552
2845
  var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2553
2846
  "use strict";
@@ -2555,56 +2848,64 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2555
2848
  var _super = _create_super(AsyncExecutor);
2556
2849
  function AsyncExecutor() {
2557
2850
  _class_call_check(this, AsyncExecutor);
2558
- return _super.apply(this, arguments);
2851
+ var _this;
2852
+ _this = _super.call.apply(_super, [
2853
+ this
2854
+ ].concat(Array.prototype.slice.call(arguments)));
2855
+ _this.contextHandler = new ContextHandler();
2856
+ return _this;
2559
2857
  }
2560
2858
  _create_class(AsyncExecutor, [
2561
2859
  {
2562
- key: "runHooks",
2860
+ key: "runHook",
2563
2861
  value: /**
2564
- * Execute plugin hook functions asynchronously
2862
+ * Execute a single plugin hook function asynchronously
2565
2863
  *
2566
- * - Purpose: Orchestrates asynchronous plugin hook execution
2567
- * - Core Concept: Sequential async plugin pipeline
2568
- * - Main Features:
2569
- * - Plugin enablement checking
2570
- * - Result chaining
2571
- * - Error hook special handling
2572
- * - Primary Use: Internal plugin lifecycle management
2864
+ * Core concept:
2865
+ * Sequential async plugin execution with chain breaking and return value handling
2573
2866
  *
2574
- * Plugin execution flow:
2867
+ * Execution flow:
2575
2868
  * 1. Check if plugin is enabled for the hook
2576
2869
  * 2. Execute plugin hook if available
2577
2870
  * 3. Handle plugin results and chain breaking conditions
2871
+ * 4. Continue to next plugin or break chain
2872
+ *
2873
+ * Key features:
2874
+ * - Plugin enablement checking
2875
+ * - Chain breaking support
2876
+ * - Return value management
2877
+ * - Runtime tracking
2878
+ * - Async execution with await
2578
2879
  *
2579
2880
  * @param plugins - Array of plugins to execute
2580
2881
  * @param hookName - Name of the hook function to execute
2581
- * @param args - Arguments to pass to the hook function
2582
- * @returns Promise resolving to the hook execution result
2882
+ * @param context - Execution context containing data and runtime information
2883
+ * @param args - Additional arguments to pass to the hook function
2884
+ * @returns Promise resolving to the result of the hook function execution
2885
+ * @since 2.1.0
2583
2886
  *
2584
- * @example
2887
+ * @example Internal usage
2585
2888
  * ```typescript
2586
2889
  * const result = await this.runHook(
2587
2890
  * this.plugins,
2588
- * 'beforeExec',
2589
- * { userId: 123 }
2891
+ * 'onBefore',
2892
+ * context,
2893
+ * data
2590
2894
  * );
2591
2895
  * ```
2592
- */ function runHooks(plugins, hookName, context) {
2896
+ */ function runHook(plugins, hookName, context) {
2593
2897
  for(var _len = arguments.length, args = new Array(_len > 3 ? _len - 3 : 0), _key = 3; _key < _len; _key++){
2594
2898
  args[_key - 3] = arguments[_key];
2595
2899
  }
2900
+ var _this = this;
2596
2901
  return _async_to_generator(function() {
2597
- var _index, returnValue, _context, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, plugin, _plugin, _context_hooksRuntimes, pluginReturn, err;
2902
+ var _index, returnValue, _context, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, plugin, _plugin, pluginReturn, err;
2598
2903
  return _ts_generator(this, function(_state) {
2599
2904
  switch(_state.label){
2600
2905
  case 0:
2601
2906
  _index = -1;
2602
- _context = context || {
2603
- parameters: void 0,
2604
- hooksRuntimes: {}
2605
- };
2606
- _context.hooksRuntimes.times = 0;
2607
- _context.hooksRuntimes.index = void 0;
2907
+ _context = context || createContext({});
2908
+ _this.contextHandler.resetHooksRuntimes(_context.hooksRuntimes);
2608
2909
  _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
2609
2910
  _state.label = 1;
2610
2911
  case 1:
@@ -2623,34 +2924,31 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2623
2924
  ];
2624
2925
  plugin = _step.value;
2625
2926
  _index++;
2626
- if (typeof plugin[hookName] !== "function" || typeof plugin.enabled == "function" && !plugin.enabled(hookName, context)) {
2927
+ if (_this.contextHandler.shouldSkipPluginHook(plugin, hookName, _context)) {
2627
2928
  return [
2628
2929
  3,
2629
2930
  4
2630
2931
  ];
2631
2932
  }
2632
- if ((_context_hooksRuntimes = _context.hooksRuntimes) === null || _context_hooksRuntimes === void 0 ? void 0 : _context_hooksRuntimes.breakChain) {
2933
+ if (_this.contextHandler.shouldBreakChain(_context)) {
2633
2934
  return [
2634
2935
  3,
2635
2936
  5
2636
2937
  ];
2637
2938
  }
2638
- _context.hooksRuntimes.pluginName = plugin.pluginName;
2639
- _context.hooksRuntimes.hookName = hookName;
2640
- _context.hooksRuntimes.times++;
2641
- _context.hooksRuntimes.index = _index;
2939
+ _this.contextHandler.runtimes(_context, plugin, hookName, _index);
2642
2940
  return [
2643
2941
  4,
2644
2942
  (_plugin = plugin)[hookName].apply(_plugin, [
2645
- context
2943
+ _context
2646
2944
  ].concat(_to_consumable_array(args)))
2647
2945
  ];
2648
2946
  case 3:
2649
2947
  pluginReturn = _state.sent();
2650
2948
  if (pluginReturn !== void 0) {
2651
2949
  returnValue = pluginReturn;
2652
- _context.hooksRuntimes.returnValue = pluginReturn;
2653
- if (_context.hooksRuntimes.returnBreakChain) {
2950
+ _this.contextHandler.runtimeReturnValue(_context, pluginReturn);
2951
+ if (_this.contextHandler.shouldBreakChainOnReturn(_context)) {
2654
2952
  return [
2655
2953
  2,
2656
2954
  returnValue
@@ -2700,25 +2998,168 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2700
2998
  })();
2701
2999
  }
2702
3000
  },
3001
+ {
3002
+ key: "runHooks",
3003
+ value: /**
3004
+ * Execute multiple plugin hook functions asynchronously
3005
+ * Supports executing multiple hook names in sequence
3006
+ *
3007
+ * Core concept:
3008
+ * Sequential execution of multiple hooks with chain breaking support
3009
+ *
3010
+ * Execution flow:
3011
+ * 1. For each hook name, check if plugin is enabled
3012
+ * 2. Execute plugin hook if available
3013
+ * 3. Handle plugin results and chain breaking conditions
3014
+ * 4. Continue to next hook name if chain is not broken
3015
+ *
3016
+ * Key features:
3017
+ * - Supports multiple hook names in sequence
3018
+ * - Chain breaking support for each hook
3019
+ * - Return value management across hooks
3020
+ * - Backward compatibility with single hook execution
3021
+ * - Async execution with await
3022
+ *
3023
+ * @param plugins - Array of plugins to execute
3024
+ * @param hookNames - Single hook name or array of hook names to execute in sequence
3025
+ * @param context - Execution context containing data and runtime information
3026
+ * @param args - Additional arguments to pass to the hook functions
3027
+ * @returns Promise resolving to the result of the last executed hook function
3028
+ *
3029
+ * @example Execute multiple hooks in sequence
3030
+ * ```typescript
3031
+ * const result = await this.runHooks(
3032
+ * this.plugins,
3033
+ * ['onBefore', 'onValidate', 'onProcess'],
3034
+ * context,
3035
+ * data
3036
+ * );
3037
+ * ```
3038
+ *
3039
+ * @example Execute single hook (backward compatibility)
3040
+ * ```typescript
3041
+ * const result = await this.runHooks(
3042
+ * this.plugins,
3043
+ * 'onBefore',
3044
+ * context,
3045
+ * data
3046
+ * );
3047
+ * ```
3048
+ */ function runHooks(plugins, hookNames, context) {
3049
+ for(var _len = arguments.length, args = new Array(_len > 3 ? _len - 3 : 0), _key = 3; _key < _len; _key++){
3050
+ args[_key - 3] = arguments[_key];
3051
+ }
3052
+ var _this = this;
3053
+ return _async_to_generator(function() {
3054
+ var hookNameArray, lastReturnValue, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, hookName, result, err;
3055
+ return _ts_generator(this, function(_state) {
3056
+ switch(_state.label){
3057
+ case 0:
3058
+ hookNameArray = Array.isArray(hookNames) ? hookNames : [
3059
+ hookNames
3060
+ ];
3061
+ _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
3062
+ _state.label = 1;
3063
+ case 1:
3064
+ _state.trys.push([
3065
+ 1,
3066
+ 6,
3067
+ 7,
3068
+ 8
3069
+ ]);
3070
+ _iterator = hookNameArray[Symbol.iterator]();
3071
+ _state.label = 2;
3072
+ case 2:
3073
+ if (!!(_iteratorNormalCompletion = (_step = _iterator.next()).done)) return [
3074
+ 3,
3075
+ 5
3076
+ ];
3077
+ hookName = _step.value;
3078
+ return [
3079
+ 4,
3080
+ _this.runHook.apply(_this, [
3081
+ plugins,
3082
+ hookName,
3083
+ context
3084
+ ].concat(_to_consumable_array(args)))
3085
+ ];
3086
+ case 3:
3087
+ result = _state.sent();
3088
+ if (result !== void 0) {
3089
+ lastReturnValue = result;
3090
+ }
3091
+ if (context && _this.contextHandler.shouldBreakChain(context)) {
3092
+ return [
3093
+ 3,
3094
+ 5
3095
+ ];
3096
+ }
3097
+ _state.label = 4;
3098
+ case 4:
3099
+ _iteratorNormalCompletion = true;
3100
+ return [
3101
+ 3,
3102
+ 2
3103
+ ];
3104
+ case 5:
3105
+ return [
3106
+ 3,
3107
+ 8
3108
+ ];
3109
+ case 6:
3110
+ err = _state.sent();
3111
+ _didIteratorError = true;
3112
+ _iteratorError = err;
3113
+ return [
3114
+ 3,
3115
+ 8
3116
+ ];
3117
+ case 7:
3118
+ try {
3119
+ if (!_iteratorNormalCompletion && _iterator.return != null) {
3120
+ _iterator.return();
3121
+ }
3122
+ } finally{
3123
+ if (_didIteratorError) {
3124
+ throw _iteratorError;
3125
+ }
3126
+ }
3127
+ return [
3128
+ 7
3129
+ ];
3130
+ case 8:
3131
+ return [
3132
+ 2,
3133
+ lastReturnValue
3134
+ ];
3135
+ }
3136
+ });
3137
+ })();
3138
+ }
3139
+ },
2703
3140
  {
2704
3141
  key: "execNoError",
2705
3142
  value: /**
2706
3143
  * Execute task without throwing errors
2707
3144
  *
2708
- * - Purpose: Safe execution of async tasks
2709
- * - Core Concept: Error wrapping and handling
2710
- * - Main Features:
2711
- * - Catches all execution errors
2712
- * - Wraps errors in ExecutorError
2713
- * - Returns either result or error object
2714
- * - Primary Use: When you want to handle errors without try-catch
3145
+ * Core concept:
3146
+ * Error-safe execution pipeline that returns errors instead of throwing
2715
3147
  *
2716
- * @template T - Type of task return value
3148
+ * Advantages over try-catch:
3149
+ * - Standardized error handling
3150
+ * - No exception propagation
3151
+ * - Consistent error types
3152
+ * - Plugin error handling support
3153
+ *
3154
+ * @template Result - Type of task return value
3155
+ * @template Params - Type of task input parameters
2717
3156
  * @param dataOrTask - Task data or task function
2718
- * @param task - Task function (optional)
2719
- * @returns Promise resolving to either result or ExecutorError
3157
+ * @param task - Task function (optional when dataOrTask is a function)
3158
+ * @returns Promise resolving to task result or ExecutorError if execution fails
2720
3159
  *
2721
- * @example
3160
+ * @throws Never throws - all errors are wrapped in ExecutorError
3161
+ *
3162
+ * @example Basic usage
2722
3163
  * ```typescript
2723
3164
  * const result = await executor.execNoError(async () => {
2724
3165
  * const response = await riskyOperation();
@@ -2729,6 +3170,14 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2729
3170
  * console.error('Operation failed:', result);
2730
3171
  * }
2731
3172
  * ```
3173
+ *
3174
+ * @example With input data
3175
+ * ```typescript
3176
+ * const result = await executor.execNoError(
3177
+ * { userId: 123 },
3178
+ * async (data) => await fetchUserData(data.userId)
3179
+ * );
3180
+ * ```
2732
3181
  */ function execNoError(dataOrTask, task) {
2733
3182
  var _this = this;
2734
3183
  return _async_to_generator(function() {
@@ -2776,37 +3225,52 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2776
3225
  /**
2777
3226
  * Execute asynchronous task with full plugin pipeline
2778
3227
  *
2779
- * - Purpose: Primary method for executing async tasks
2780
- * - Core Concept: Full plugin pipeline execution
2781
- * - Main Features:
2782
- * - Plugin hook integration
2783
- * - Task validation
2784
- * - Custom execution support
2785
- * - Primary Use: Running async tasks with plugin support
3228
+ * Core concept:
3229
+ * Complete execution pipeline with plugin lifecycle management
2786
3230
  *
2787
3231
  * Execution flow:
2788
3232
  * 1. Validate and prepare task
2789
- * 2. Check for custom execution plugins
2790
- * 3. Execute task with plugin pipeline
3233
+ * 2. Execute beforeHooks (configured or default 'onBefore')
3234
+ * 3. Execute core task logic with execHook support
3235
+ * 4. Execute afterHooks (configured or default 'onSuccess')
3236
+ * 5. Handle errors with onError hooks if needed
2791
3237
  *
2792
- * @template T - Type of task return value
2793
- * @template D - Type of task data
3238
+ * Performance considerations:
3239
+ * - Async overhead for Promise handling
3240
+ * - Sequential execution path
3241
+ * - Plugin chain optimization
3242
+ *
3243
+ * @template Result - Type of task return value
3244
+ * @template Params - Type of task input parameters
2794
3245
  * @param dataOrTask - Task data or task function
2795
- * @param task - Task function (optional)
3246
+ * @param task - Task function (optional when dataOrTask is a function)
2796
3247
  * @throws {Error} When task is not an async function
2797
- * @returns Promise resolving to task result
3248
+ * @throws {ExecutorError} When task execution fails
3249
+ * @returns Promise resolving to task execution result
2798
3250
  *
2799
- * @example
3251
+ * @example Basic task execution
3252
+ * ```typescript
3253
+ * const result = await executor.exec(async (data) => {
3254
+ * const response = await fetch('https://api.example.com/data');
3255
+ * return response.json();
3256
+ * });
3257
+ * ```
3258
+ *
3259
+ * @example With input data
2800
3260
  * ```typescript
2801
- * // With separate data and task
2802
3261
  * const data = { userId: 123 };
2803
3262
  * const result = await executor.exec(data, async (input) => {
2804
3263
  * return await fetchUserData(input.userId);
2805
3264
  * });
3265
+ * ```
2806
3266
  *
2807
- * // With combined task
2808
- * const result = await executor.exec(async () => {
2809
- * return await fetchData();
3267
+ * @example With validation
3268
+ * ```typescript
3269
+ * const result = await executor.exec(async (data) => {
3270
+ * if (typeof data !== 'string') {
3271
+ * throw new Error('Data must be string');
3272
+ * }
3273
+ * return await processData(data);
2810
3274
  * });
2811
3275
  * ```
2812
3276
  */ key: "exec",
@@ -2819,105 +3283,121 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2819
3283
  return this.run(data, actualTask);
2820
3284
  }
2821
3285
  },
3286
+ {
3287
+ key: "runExec",
3288
+ value: /**
3289
+ * Execute core task logic with execHook support
3290
+ *
3291
+ * Core concept:
3292
+ * Handles the execution phase with optional plugin intervention
3293
+ *
3294
+ * Execution logic:
3295
+ * 1. Execute configured execHook (default: 'onExec')
3296
+ * 2. If no execHook was executed, run the actual task
3297
+ * 3. Otherwise, use the return value from execHook
3298
+ *
3299
+ * @template Result - Type of task return value
3300
+ * @template Params - Type of task input parameters
3301
+ * @param context - Execution context
3302
+ * @param actualTask - Task function to execute
3303
+ */ function runExec(context, actualTask) {
3304
+ var _this = this;
3305
+ return _async_to_generator(function() {
3306
+ var _this_config, execHook, _tmp;
3307
+ return _ts_generator(this, function(_state) {
3308
+ switch(_state.label){
3309
+ case 0:
3310
+ execHook = ((_this_config = _this.config) === null || _this_config === void 0 ? void 0 : _this_config.execHook) || "onExec";
3311
+ return [
3312
+ 4,
3313
+ _this.runHook(_this.plugins, execHook, context, actualTask)
3314
+ ];
3315
+ case 1:
3316
+ _state.sent();
3317
+ if (!!context.hooksRuntimes.times) return [
3318
+ 3,
3319
+ 3
3320
+ ];
3321
+ return [
3322
+ 4,
3323
+ actualTask(context)
3324
+ ];
3325
+ case 2:
3326
+ _tmp = _state.sent();
3327
+ return [
3328
+ 3,
3329
+ 4
3330
+ ];
3331
+ case 3:
3332
+ _tmp = context.hooksRuntimes.returnValue;
3333
+ _state.label = 4;
3334
+ case 4:
3335
+ context.returnValue = _tmp;
3336
+ return [
3337
+ 2
3338
+ ];
3339
+ }
3340
+ });
3341
+ })();
3342
+ }
3343
+ },
2822
3344
  {
2823
3345
  key: "run",
2824
3346
  value: /**
2825
3347
  * Core task execution method with plugin hooks
2826
3348
  *
2827
- * - Purpose: Implements the complete execution pipeline
2828
- * - Core Concept: Sequential hook execution with error handling
2829
- * - Main Features:
2830
- * - Before/After hooks
2831
- * - Error handling hooks
2832
- * - Result transformation
2833
- * - Primary Use: Internal pipeline orchestration
3349
+ * Core concept:
3350
+ * Complete execution pipeline with configurable hook lifecycle
2834
3351
  *
2835
3352
  * Pipeline stages:
2836
- * 1. onBefore hooks - Pre-process input data
2837
- * 2. Task execution - Run the actual task
2838
- * 3. onSuccess hooks - Post-process results
3353
+ * 1. beforeHooks - Pre-process input data (configurable, default: 'onBefore')
3354
+ * 2. Task execution - Run the actual task with execHook support
3355
+ * 3. afterHooks - Post-process results (configurable, default: 'onSuccess')
2839
3356
  * 4. onError hooks - Handle any errors
2840
3357
  *
2841
- * @template T - Type of task return value
2842
- * @template D - Type of task data
2843
- * @param data - Input data for the task
2844
- * @param actualTask - Task function to execute
3358
+ * Error handling strategy:
3359
+ * - Catches all errors
3360
+ * - Passes errors through plugin chain
3361
+ * - Wraps unhandled errors in ExecutorError
3362
+ * - Supports plugin error handling
3363
+ *
3364
+ * @template Result - Type of task return value
3365
+ * @template Params - Type of task input parameters
3366
+ * @param data - Data to pass to the task
3367
+ * @param actualTask - Actual task function to execute
2845
3368
  * @throws {ExecutorError} When task execution fails
2846
- * @returns Promise resolving to task result(context.returnValue)
3369
+ * @returns Promise resolving to task execution result
2847
3370
  *
2848
- * @example
3371
+ * @example Internal implementation
2849
3372
  * ```typescript
2850
- * private async run(data, task) {
3373
+ * protected async run(data, task) {
2851
3374
  * try {
2852
- * const preparedData = await this.runHook(this.plugins, 'onBefore', data);
2853
- * const result = await task(preparedData);
2854
- * return await this.runHook(this.plugins, 'onSuccess', result);
3375
+ * // Execute beforeHooks (configurable)
3376
+ * await this.runHooks(this.plugins, beforeHooks, context);
3377
+ *
3378
+ * // Execute core logic with execHook support
3379
+ * await this.runExec(context, actualTask);
3380
+ *
3381
+ * // Execute afterHooks (configurable)
3382
+ * await this.runHooks(this.plugins, afterHooks, context);
3383
+ *
3384
+ * return context.returnValue;
2855
3385
  * } catch (error) {
2856
- * const handledError = await this.runHook(
2857
- * this.plugins,
2858
- * 'onError',
2859
- * error,
2860
- * data
2861
- * );
2862
- * throw new ExecutorError('EXECUTION_FAILED', handledError);
3386
+ * // Handle errors with onError hooks
3387
+ * await this.runHook(this.plugins, 'onError', context);
2863
3388
  * }
2864
3389
  * }
2865
3390
  * ```
2866
3391
  */ function run(data, actualTask) {
2867
3392
  var _this = this;
2868
3393
  return _async_to_generator(function() {
2869
- var context, runExec, error;
3394
+ var _this_config, _this_config1, context, beforeHooks, afterHooks, error;
2870
3395
  return _ts_generator(this, function(_state) {
2871
3396
  switch(_state.label){
2872
3397
  case 0:
2873
- context = {
2874
- parameters: data,
2875
- returnValue: void 0,
2876
- error: void 0,
2877
- hooksRuntimes: {
2878
- pluginName: "",
2879
- hookName: "",
2880
- returnValue: void 0,
2881
- returnBreakChain: false,
2882
- times: 0
2883
- }
2884
- };
2885
- runExec = function() {
2886
- var _ref = _async_to_generator(function(ctx) {
2887
- return _ts_generator(this, function(_state) {
2888
- switch(_state.label){
2889
- case 0:
2890
- return [
2891
- 4,
2892
- _this.runHooks(_this.plugins, "onExec", ctx, actualTask)
2893
- ];
2894
- case 1:
2895
- _state.sent();
2896
- if (!(ctx.hooksRuntimes.times === 0)) return [
2897
- 3,
2898
- 3
2899
- ];
2900
- return [
2901
- 4,
2902
- actualTask(ctx)
2903
- ];
2904
- case 2:
2905
- ctx.returnValue = _state.sent();
2906
- return [
2907
- 2
2908
- ];
2909
- case 3:
2910
- ctx.returnValue = ctx.hooksRuntimes.returnValue;
2911
- return [
2912
- 2
2913
- ];
2914
- }
2915
- });
2916
- });
2917
- return function runExec(ctx) {
2918
- return _ref.apply(this, arguments);
2919
- };
2920
- }();
3398
+ context = createContext(data);
3399
+ beforeHooks = ((_this_config = _this.config) === null || _this_config === void 0 ? void 0 : _this_config.beforeHooks) || "onBefore";
3400
+ afterHooks = ((_this_config1 = _this.config) === null || _this_config1 === void 0 ? void 0 : _this_config1.afterHooks) || "onSuccess";
2921
3401
  _state.label = 1;
2922
3402
  case 1:
2923
3403
  _state.trys.push([
@@ -2928,19 +3408,19 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2928
3408
  ]);
2929
3409
  return [
2930
3410
  4,
2931
- _this.runHooks(_this.plugins, "onBefore", context)
3411
+ _this.runHooks(_this.plugins, beforeHooks, context)
2932
3412
  ];
2933
3413
  case 2:
2934
3414
  _state.sent();
2935
3415
  return [
2936
3416
  4,
2937
- runExec(context)
3417
+ _this.runExec(context, actualTask)
2938
3418
  ];
2939
3419
  case 3:
2940
3420
  _state.sent();
2941
3421
  return [
2942
3422
  4,
2943
- _this.runHooks(_this.plugins, "onSuccess", context)
3423
+ _this.runHooks(_this.plugins, afterHooks, context)
2944
3424
  ];
2945
3425
  case 4:
2946
3426
  _state.sent();
@@ -2950,28 +3430,22 @@ var AsyncExecutor = /*#__PURE__*/ function(Executor) {
2950
3430
  ];
2951
3431
  case 5:
2952
3432
  error = _state.sent();
2953
- context.error = error;
3433
+ _this.contextHandler.setError(context, error);
2954
3434
  return [
2955
3435
  4,
2956
- _this.runHooks(_this.plugins, "onError", context)
3436
+ _this.runHook(_this.plugins, "onError", context)
2957
3437
  ];
2958
3438
  case 6:
2959
3439
  _state.sent();
2960
3440
  if (context.hooksRuntimes.returnValue) {
2961
- context.error = context.hooksRuntimes.returnValue;
3441
+ _this.contextHandler.setError(context, context.hooksRuntimes.returnValue);
2962
3442
  }
2963
3443
  if (_instanceof(context.error, ExecutorError)) {
2964
3444
  throw context.error;
2965
3445
  }
2966
3446
  throw new ExecutorError("UNKNOWN_ASYNC_ERROR", context.error);
2967
3447
  case 7:
2968
- context.hooksRuntimes = {
2969
- pluginName: "",
2970
- hookName: "",
2971
- returnValue: void 0,
2972
- returnBreakChain: false,
2973
- times: 0
2974
- };
3448
+ _this.contextHandler.reset(context);
2975
3449
  return [
2976
3450
  7
2977
3451
  ];
@@ -2994,75 +3468,78 @@ var SyncExecutor = /*#__PURE__*/ function(Executor) {
2994
3468
  var _super = _create_super(SyncExecutor);
2995
3469
  function SyncExecutor() {
2996
3470
  _class_call_check(this, SyncExecutor);
2997
- return _super.apply(this, arguments);
3471
+ var _this;
3472
+ _this = _super.call.apply(_super, [
3473
+ this
3474
+ ].concat(Array.prototype.slice.call(arguments)));
3475
+ _this.contextHandler = new ContextHandler();
3476
+ return _this;
2998
3477
  }
2999
3478
  _create_class(SyncExecutor, [
3000
3479
  {
3001
3480
  /**
3002
- * Execute plugin hook functions synchronously
3003
- * Manages the plugin execution chain and handles results
3481
+ * Execute a single plugin hook function synchronously
3482
+ *
3483
+ * Core concept:
3484
+ * Sequential plugin execution with chain breaking and return value handling
3004
3485
  *
3005
- * Plugin execution flow:
3486
+ * Execution flow:
3006
3487
  * 1. Check if plugin is enabled for the hook
3007
3488
  * 2. Execute plugin hook if available
3008
3489
  * 3. Handle plugin results and chain breaking conditions
3490
+ * 4. Continue to next plugin or break chain
3009
3491
  *
3010
- * Key differences from AsyncExecutor:
3011
- * - All operations are synchronous
3012
- * - Results are immediately available
3013
- * - No await statements needed
3492
+ * Key features:
3493
+ * - Plugin enablement checking
3494
+ * - Chain breaking support
3495
+ * - Return value management
3496
+ * - Runtime tracking
3014
3497
  *
3015
3498
  * @param plugins - Array of plugins to execute
3016
3499
  * @param hookName - Name of the hook function to execute
3017
- * @param args - Arguments to pass to the hook function
3500
+ * @param context - Execution context containing data and runtime information
3501
+ * @param args - Additional arguments to pass to the hook function
3018
3502
  * @returns Result of the hook function execution
3503
+ * @since 2.1.0
3019
3504
  *
3020
- * @example
3505
+ * @example Internal usage
3021
3506
  * ```typescript
3022
- * // Internal usage example
3023
3507
  * const result = this.runHook(
3024
3508
  * this.plugins,
3025
3509
  * 'onBefore',
3026
- * { value: 'test' }
3510
+ * context,
3511
+ * data
3027
3512
  * );
3028
3513
  * ```
3029
- */ key: "runHooks",
3030
- value: function runHooks(plugins, hookName, context) {
3514
+ */ key: "runHook",
3515
+ value: function runHook(plugins, hookName, context) {
3031
3516
  for(var _len = arguments.length, args = new Array(_len > 3 ? _len - 3 : 0), _key = 3; _key < _len; _key++){
3032
3517
  args[_key - 3] = arguments[_key];
3033
3518
  }
3034
3519
  var _index = -1;
3035
3520
  var returnValue;
3036
- var _context = context || {
3037
- parameters: void 0,
3038
- hooksRuntimes: {}
3039
- };
3040
- _context.hooksRuntimes.times = 0;
3041
- _context.hooksRuntimes.index = void 0;
3521
+ var _context = context || createContext({});
3522
+ this.contextHandler.resetHooksRuntimes(_context.hooksRuntimes);
3042
3523
  var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
3043
3524
  try {
3044
3525
  for(var _iterator = plugins[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
3045
3526
  var plugin = _step.value;
3046
3527
  var _plugin;
3047
- var _context_hooksRuntimes;
3048
3528
  _index++;
3049
- if (typeof plugin[hookName] !== "function" || typeof plugin.enabled == "function" && !plugin.enabled(hookName, _context)) {
3529
+ if (this.contextHandler.shouldSkipPluginHook(plugin, hookName, _context)) {
3050
3530
  continue;
3051
3531
  }
3052
- if ((_context_hooksRuntimes = _context.hooksRuntimes) === null || _context_hooksRuntimes === void 0 ? void 0 : _context_hooksRuntimes.breakChain) {
3532
+ if (this.contextHandler.shouldBreakChain(_context)) {
3053
3533
  break;
3054
3534
  }
3055
- _context.hooksRuntimes.pluginName = plugin.pluginName;
3056
- _context.hooksRuntimes.hookName = hookName;
3057
- _context.hooksRuntimes.times++;
3058
- _context.hooksRuntimes.index = _index;
3535
+ this.contextHandler.runtimes(_context, plugin, hookName, _index);
3059
3536
  var pluginReturn = (_plugin = plugin)[hookName].apply(_plugin, [
3060
- context
3537
+ _context
3061
3538
  ].concat(_to_consumable_array(args)));
3062
3539
  if (pluginReturn !== void 0) {
3063
3540
  returnValue = pluginReturn;
3064
- _context.hooksRuntimes.returnValue = pluginReturn;
3065
- if (_context.hooksRuntimes.returnBreakChain) {
3541
+ this.contextHandler.runtimeReturnValue(_context, pluginReturn);
3542
+ if (this.contextHandler.shouldBreakChainOnReturn(_context)) {
3066
3543
  return returnValue;
3067
3544
  }
3068
3545
  }
@@ -3086,20 +3563,114 @@ var SyncExecutor = /*#__PURE__*/ function(Executor) {
3086
3563
  },
3087
3564
  {
3088
3565
  /**
3566
+ * Execute multiple plugin hook functions synchronously
3567
+ * Supports executing multiple hook names in sequence
3568
+ *
3569
+ * Core concept:
3570
+ * Sequential execution of multiple hooks with chain breaking support
3571
+ *
3572
+ * Execution flow:
3573
+ * 1. For each hook name, check if plugin is enabled
3574
+ * 2. Execute plugin hook if available
3575
+ * 3. Handle plugin results and chain breaking conditions
3576
+ * 4. Continue to next hook name if chain is not broken
3577
+ *
3578
+ * Key features:
3579
+ * - Supports multiple hook names in sequence
3580
+ * - Chain breaking support for each hook
3581
+ * - Return value management across hooks
3582
+ * - Backward compatibility with single hook execution
3583
+ *
3584
+ * @param plugins - Array of plugins to execute
3585
+ * @param hookNames - Single hook name or array of hook names to execute in sequence
3586
+ * @param context - Execution context containing data and runtime information
3587
+ * @param args - Additional arguments to pass to the hook functions
3588
+ * @returns Result of the last executed hook function
3589
+ *
3590
+ * @example Execute multiple hooks in sequence
3591
+ * ```typescript
3592
+ * const result = this.runHooks(
3593
+ * this.plugins,
3594
+ * ['onBefore', 'onValidate', 'onProcess'],
3595
+ * context,
3596
+ * data
3597
+ * );
3598
+ * ```
3599
+ *
3600
+ * @example Execute single hook (backward compatibility)
3601
+ * ```typescript
3602
+ * const result = this.runHooks(
3603
+ * this.plugins,
3604
+ * 'onBefore',
3605
+ * context,
3606
+ * data
3607
+ * );
3608
+ * ```
3609
+ */ key: "runHooks",
3610
+ value: function runHooks(plugins, hookNames, context) {
3611
+ for(var _len = arguments.length, args = new Array(_len > 3 ? _len - 3 : 0), _key = 3; _key < _len; _key++){
3612
+ args[_key - 3] = arguments[_key];
3613
+ }
3614
+ var hookNameArray = Array.isArray(hookNames) ? hookNames : [
3615
+ hookNames
3616
+ ];
3617
+ var lastReturnValue;
3618
+ var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
3619
+ try {
3620
+ for(var _iterator = hookNameArray[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
3621
+ var hookName = _step.value;
3622
+ var result = this.runHook.apply(this, [
3623
+ plugins,
3624
+ hookName,
3625
+ context
3626
+ ].concat(_to_consumable_array(args)));
3627
+ if (result !== void 0) {
3628
+ lastReturnValue = result;
3629
+ }
3630
+ if (context && this.contextHandler.shouldBreakChain(context)) {
3631
+ break;
3632
+ }
3633
+ }
3634
+ } catch (err) {
3635
+ _didIteratorError = true;
3636
+ _iteratorError = err;
3637
+ } finally{
3638
+ try {
3639
+ if (!_iteratorNormalCompletion && _iterator.return != null) {
3640
+ _iterator.return();
3641
+ }
3642
+ } finally{
3643
+ if (_didIteratorError) {
3644
+ throw _iteratorError;
3645
+ }
3646
+ }
3647
+ }
3648
+ return lastReturnValue;
3649
+ }
3650
+ },
3651
+ {
3652
+ /**
3089
3653
  * Execute task without throwing errors
3090
3654
  * Wraps all errors in ExecutorError for safe error handling
3091
3655
  *
3656
+ * Core concept:
3657
+ * Error-safe execution pipeline that returns errors instead of throwing
3658
+ *
3092
3659
  * Advantages over try-catch:
3093
- * 1. Standardized error handling
3094
- * 2. No exception propagation
3095
- * 3. Consistent error types
3660
+ * - Standardized error handling
3661
+ * - No exception propagation
3662
+ * - Consistent error types
3663
+ * - Plugin error handling support
3096
3664
  *
3097
- * @template T - Type of task return value
3665
+ * @template Result - Type of task return value
3666
+ * @template Params - Type of task input parameters
3098
3667
  * @param dataOrTask - Task data or task function
3099
- * @param task - Task function (optional)
3100
- * @returns Task result or ExecutorError
3668
+ * @param task - Task function (optional when dataOrTask is a function)
3669
+ * @returns Task result or ExecutorError if execution fails
3101
3670
  *
3102
- * @example
3671
+ * @throws Never throws - all errors are wrapped in ExecutorError
3672
+ *
3673
+ * @example Basic usage
3103
3674
  * ```typescript
3104
3675
  * const result = executor.execNoError((data) => {
3105
3676
  * if (!data.isValid) {
@@ -3114,6 +3685,14 @@ var SyncExecutor = /*#__PURE__*/ function(Executor) {
3114
3685
  * console.log('Task succeeded:', result);
3115
3686
  * }
3116
3687
  * ```
3688
+ *
3689
+ * @example With input data
3690
+ * ```typescript
3691
+ * const result = executor.execNoError(
3692
+ * { value: 'test' },
3693
+ * (data) => data.value.toUpperCase()
3694
+ * );
3695
+ * ```
3117
3696
  */ key: "execNoError",
3118
3697
  value: function execNoError(dataOrTask, task) {
3119
3698
  try {
@@ -3131,34 +3710,49 @@ var SyncExecutor = /*#__PURE__*/ function(Executor) {
3131
3710
  * Execute synchronous task with full plugin pipeline
3132
3711
  * Core method for task execution with plugin support
3133
3712
  *
3713
+ * Core concept:
3714
+ * Complete execution pipeline with plugin lifecycle management
3715
+ *
3134
3716
  * Execution flow:
3135
3717
  * 1. Validate and prepare task
3136
- * 2. Check for custom execution plugins
3137
- * 3. Execute task with plugin pipeline
3718
+ * 2. Execute beforeHooks (configured or default 'onBefore')
3719
+ * 3. Execute core task logic with execHook support
3720
+ * 4. Execute afterHooks (configured or default 'onSuccess')
3721
+ * 5. Handle errors with onError hooks if needed
3138
3722
  *
3139
3723
  * Performance considerations:
3140
3724
  * - No async overhead
3141
3725
  * - Direct execution path
3142
3726
  * - Immediate results
3727
+ * - Plugin chain optimization
3143
3728
  *
3144
- * @template T - Type of task return value
3145
- * @template D - Type of task data
3729
+ * @template Result - Type of task return value
3730
+ * @template Params - Type of task input parameters
3146
3731
  * @param dataOrTask - Task data or task function
3147
- * @param task - Task function (optional)
3732
+ * @param task - Task function (optional when dataOrTask is a function)
3148
3733
  * @throws {Error} When task is not a function
3734
+ * @throws {ExecutorError} When task execution fails
3149
3735
  * @returns Task execution result
3150
3736
  *
3151
- * @example
3737
+ * @example Basic task execution
3738
+ * ```typescript
3739
+ * const result = executor.exec((data) => {
3740
+ * return data.toUpperCase();
3741
+ * });
3742
+ * ```
3743
+ *
3744
+ * @example With input data
3152
3745
  * ```typescript
3153
- * // Example with data transformation
3154
3746
  * const data = { numbers: [1, 2, 3] };
3155
3747
  * const task = (input) => {
3156
3748
  * return input.numbers.map(n => n * 2);
3157
3749
  * };
3158
3750
  *
3159
3751
  * const result = executor.exec(data, task);
3752
+ * ```
3160
3753
  *
3161
- * // Example with validation
3754
+ * @example With validation
3755
+ * ```typescript
3162
3756
  * const result = executor.exec((data) => {
3163
3757
  * if (typeof data !== 'string') {
3164
3758
  * throw new Error('Data must be string');
@@ -3178,88 +3772,98 @@ var SyncExecutor = /*#__PURE__*/ function(Executor) {
3178
3772
  },
3179
3773
  {
3180
3774
  /**
3775
+ * Execute core task logic with execHook support
3776
+ *
3777
+ * Core concept:
3778
+ * Handles the execution phase with optional plugin intervention
3779
+ *
3780
+ * Execution logic:
3781
+ * 1. Execute configured execHook (default: 'onExec')
3782
+ * 2. If no execHook was executed, run the actual task
3783
+ * 3. Otherwise, use the return value from execHook
3784
+ *
3785
+ * @template Result - Type of task return value
3786
+ * @template Params - Type of task input parameters
3787
+ * @param context - Execution context
3788
+ * @param actualTask - Task function to execute
3789
+ */ key: "runExec",
3790
+ value: function runExec(context, actualTask) {
3791
+ var _this_config;
3792
+ var execHook = ((_this_config = this.config) === null || _this_config === void 0 ? void 0 : _this_config.execHook) || "onExec";
3793
+ this.runHook(this.plugins, execHook, context, actualTask);
3794
+ context.returnValue = !context.hooksRuntimes.times ? actualTask(context) : context.hooksRuntimes.returnValue;
3795
+ }
3796
+ },
3797
+ {
3798
+ /**
3181
3799
  * Core method to run synchronous task with plugin hooks
3182
3800
  * Implements the complete execution pipeline with all plugin hooks
3183
3801
  *
3802
+ * Core concept:
3803
+ * Complete execution pipeline with configurable hook lifecycle
3804
+ *
3184
3805
  * Pipeline stages:
3185
- * 1. onBefore hooks - Pre-process input data
3186
- * 2. Task execution - Run the actual task
3187
- * 3. onSuccess hooks - Post-process results
3806
+ * 1. beforeHooks - Pre-process input data (configurable, default: 'onBefore')
3807
+ * 2. Task execution - Run the actual task with execHook support
3808
+ * 3. afterHooks - Post-process results (configurable, default: 'onSuccess')
3188
3809
  * 4. onError hooks - Handle any errors
3189
3810
  *
3190
3811
  * Error handling strategy:
3191
3812
  * - Catches all errors
3192
3813
  * - Passes errors through plugin chain
3193
3814
  * - Wraps unhandled errors in ExecutorError
3815
+ * - Supports plugin error handling
3194
3816
  *
3195
- * @template T - Type of task return value
3196
- * @template D - Type of task data
3817
+ * @template Result - Type of task return value
3818
+ * @template Params - Type of task input parameters
3197
3819
  * @param data - Data to pass to the task
3198
3820
  * @param actualTask - Actual task function to execute
3199
3821
  * @throws {ExecutorError} When task execution fails
3200
3822
  * @returns Task execution result
3201
3823
  *
3202
- * @example
3824
+ * @example Internal implementation
3203
3825
  * ```typescript
3204
- * // Internal implementation example
3205
- * private run(data, task) {
3826
+ * protected run(data, task) {
3206
3827
  * try {
3207
- * const preparedData = this.runHook(this.plugins, 'onBefore', data);
3208
- * const result = task(preparedData);
3209
- * return this.runHook(this.plugins, 'onSuccess', result);
3828
+ * // Execute beforeHooks (configurable)
3829
+ * this.runHooks(this.plugins, beforeHooks, context);
3830
+ *
3831
+ * // Execute core logic with execHook support
3832
+ * this.runExec(context, actualTask);
3833
+ *
3834
+ * // Execute afterHooks (configurable)
3835
+ * this.runHooks(this.plugins, afterHooks, context);
3836
+ *
3837
+ * return context.returnValue;
3210
3838
  * } catch (error) {
3211
- * const handledError = this.runHook(
3212
- * this.plugins,
3213
- * 'onError',
3214
- * error,
3215
- * data
3216
- * );
3217
- * // Error handling logic
3839
+ * // Handle errors with onError hooks
3840
+ * this.runHook(this.plugins, 'onError', context);
3218
3841
  * }
3219
3842
  * }
3220
3843
  * ```
3221
3844
  */ key: "run",
3222
3845
  value: function run(data, actualTask) {
3223
- var _this = this;
3224
- var context = {
3225
- parameters: data,
3226
- returnValue: void 0,
3227
- error: void 0,
3228
- hooksRuntimes: {
3229
- pluginName: "",
3230
- hookName: "",
3231
- returnValue: void 0,
3232
- returnBreakChain: false,
3233
- times: 0
3234
- }
3235
- };
3236
- var runExec = function(ctx) {
3237
- _this.runHooks(_this.plugins, "onExec", ctx, actualTask);
3238
- ctx.returnValue = !ctx.hooksRuntimes.times ? actualTask(ctx) : ctx.hooksRuntimes.returnValue;
3239
- };
3846
+ var _this_config, _this_config1;
3847
+ var context = createContext(data);
3848
+ var beforeHooks = ((_this_config = this.config) === null || _this_config === void 0 ? void 0 : _this_config.beforeHooks) || "onBefore";
3849
+ var afterHooks = ((_this_config1 = this.config) === null || _this_config1 === void 0 ? void 0 : _this_config1.afterHooks) || "onSuccess";
3240
3850
  try {
3241
- this.runHooks(this.plugins, "onBefore", context);
3242
- runExec(context);
3243
- this.runHooks(this.plugins, "onSuccess", context);
3851
+ this.runHooks(this.plugins, beforeHooks, context);
3852
+ this.runExec(context, actualTask);
3853
+ this.runHooks(this.plugins, afterHooks, context);
3244
3854
  return context.returnValue;
3245
3855
  } catch (error) {
3246
- context.error = error;
3247
- this.runHooks(this.plugins, "onError", context);
3856
+ this.contextHandler.setError(context, error);
3857
+ this.runHook(this.plugins, "onError", context);
3248
3858
  if (context.hooksRuntimes.returnValue) {
3249
- context.error = context.hooksRuntimes.returnValue;
3859
+ this.contextHandler.setError(context, context.hooksRuntimes.returnValue);
3250
3860
  }
3251
3861
  if (_instanceof(context.error, ExecutorError)) {
3252
3862
  throw context.error;
3253
3863
  }
3254
3864
  throw new ExecutorError("UNKNOWN_SYNC_ERROR", context.error);
3255
3865
  } finally{
3256
- context.hooksRuntimes = {
3257
- pluginName: "",
3258
- hookName: "",
3259
- returnValue: void 0,
3260
- returnBreakChain: false,
3261
- times: 0
3262
- };
3866
+ this.contextHandler.reset(context);
3263
3867
  }
3264
3868
  }
3265
3869
  }