@qlover/fe-corekit 2.0.1 → 2.2.0

package/dist/index.js

@@ -3870,6 +3870,609 @@ var SyncExecutor = /*#__PURE__*/ function(Executor) {
     ]);
     return SyncExecutor;
 }(Executor);
+// src/executor/plugins/AbortPlugin.ts
+var ABORT_ERROR_ID = "ABORT_ERROR";
+var AbortError = /*#__PURE__*/ function(ExecutorError) {
+    "use strict";
+    _inherits(AbortError, ExecutorError);
+    var _super = _create_super(AbortError);
+    function AbortError(message, abortId, timeout) {
+        _class_call_check(this, AbortError);
+        var _this;
+        _this = _super.call(this, ABORT_ERROR_ID, message);
+        _this.abortId = abortId;
+        _this.timeout = timeout;
+        return _this;
+    }
+    _create_class(AbortError, [
+        {
+            /**
+   * Checks if the abort was triggered by a timeout
+   *
+   * Useful for distinguishing between manual cancellations and timeout-based aborts,
+   * enabling different error handling strategies
+   *
+   * @returns `true` if abort was caused by timeout, `false` otherwise
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await fetchData();
+   * } catch (error) {
+   *   if (error instanceof AbortError && error.isTimeout()) {
+   *     console.log('Request timed out, please try again');
+   *   } else {
+   *     console.log('Request was cancelled');
+   *   }
+   * }
+   * ```
+   */ key: "isTimeout",
+            value: function isTimeout() {
+                return this.timeout !== void 0 && this.timeout > 0;
+            }
+        },
+        {
+            /**
+   * Generates a user-friendly error description with context
+   *
+   * Combines the error message with additional context like request ID and timeout duration
+   * Provides more informative error messages for debugging and user feedback
+   *
+   * @returns Formatted error description string
+   *
+   * @example Without context
+   * ```typescript
+   * const error = new AbortError('Operation aborted');
+   * error.getDescription(); // "Operation aborted"
+   * ```
+   *
+   * @example With request ID
+   * ```typescript
+   * const error = new AbortError('Operation aborted', 'req-123');
+   * error.getDescription(); // "Operation aborted (Request: req-123)"
+   * ```
+   *
+   * @example With timeout context
+   * ```typescript
+   * const error = new AbortError('Timeout', 'req-456', 5000);
+   * error.getDescription(); // "Timeout (Request: req-456, Timeout: 5000ms)"
+   * ```
+   */ key: "getDescription",
+            value: function getDescription() {
+                var parts = [];
+                if (this.abortId) {
+                    parts.push("Request: ".concat(this.abortId));
+                }
+                if (this.isTimeout()) {
+                    parts.push("Timeout: ".concat(this.timeout, "ms"));
+                }
+                return parts.length > 0 ? "".concat(this.message, " (").concat(parts.join(", "), ")") : this.message;
+            }
+        }
+    ]);
+    return AbortError;
+}(ExecutorError);
+var AbortPlugin = /*#__PURE__*/ function() {
+    "use strict";
+    function _AbortPlugin(options) {
+        _class_call_check(this, _AbortPlugin);
+        /**
+     * Plugin identifier name
+     *
+     * Used by the executor system to identify this plugin
+     */ this.pluginName = "AbortPlugin";
+        /**
+     * Ensures only one instance of this plugin can be registered
+     *
+     * Prevents conflicts from multiple abort plugin instances
+     */ this.onlyOne = true;
+        /**
+     * Counter for auto-generating request identifiers
+     *
+     * Incremented each time a new request without ID is processed
+     *
+     * @private
+     */ this.requestCounter = 0;
+        /**
+     * Map of active abort controllers indexed by request key
+     *
+     * Stores `AbortController` instances for ongoing operations
+     * Enables abort operations by request identifier
+     *
+     * @protected
+     */ this.controllers = /* @__PURE__ */ new Map();
+        /**
+     * Map of active timeout timers indexed by request key
+     *
+     * Stores timeout IDs for cleanup when operations complete
+     * Prevents memory leaks from abandoned timers
+     *
+     * @protected
+     */ this.timeouts = /* @__PURE__ */ new Map();
+        this.getConfig = (options === null || options === void 0 ? void 0 : options.getConfig) || function(parameters) {
+            return parameters;
+        };
+        this.logger = options === null || options === void 0 ? void 0 : options.logger;
+    }
+    _create_class(_AbortPlugin, [
+        {
+            /**
+   * Generates unique request identifier from configuration
+   *
+   * Priority order:
+   * 1. `requestId` from config
+   * 2. `id` from config
+   * 3. Auto-generated identifier: `{pluginName}-{counter}`
+   *
+   * @param config - Abort plugin configuration
+   * @returns Unique request identifier string
+   *
+   * @protected
+   * @example
+   * ```typescript
+   * // With requestId
+   * generateRequestKey({ requestId: 'fetch-user' }) // "fetch-user"
+   *
+   * // With id
+   * generateRequestKey({ id: 'upload-file' }) // "upload-file"
+   *
+   * // Auto-generated
+   * generateRequestKey({}) // "AbortPlugin-1"
+   * ```
+   */ key: "generateRequestKey",
+            value: function generateRequestKey(config) {
+                var requestId = config.requestId, id = config.id;
+                return requestId || id || "".concat(this.pluginName, "-").concat(++this.requestCounter);
+            }
+        },
+        {
+            /**
+   * Cleans up resources associated with a request
+   *
+   * Removes abort controller and clears timeout timer for the specified request
+   * Prevents memory leaks by releasing references and stopping timers
+   * Only logs when resources actually exist to avoid noise
+   *
+   * @param config - Configuration object or request identifier string
+   *
+   * @example With config object
+   * ```typescript
+   * cleanup({ id: 'fetch-users' });
+   * ```
+   *
+   * @example With identifier string
+   * ```typescript
+   * cleanup('fetch-users');
+   * ```
+   */ key: "cleanup",
+            value: function cleanup(config) {
+                var key = typeof config === "string" ? config : this.generateRequestKey(config);
+                var hasController = this.controllers.has(key);
+                var hasTimeout = this.timeouts.has(key);
+                if (hasController || hasTimeout) {
+                    var _this_logger;
+                    this.controllers.delete(key);
+                    var timeoutId = this.timeouts.get(key);
+                    if (timeoutId) {
+                        clearTimeout(timeoutId);
+                        this.timeouts.delete(key);
+                    }
+                    (_this_logger = this.logger) === null || _this_logger === void 0 ? void 0 : _this_logger.debug("[".concat(this.pluginName, "] cleanup: ").concat(key));
+                }
+            }
+        },
+        {
+            /**
+   * Executor lifecycle hook: called before operation execution
+   *
+   * Performs the following setup operations:
+   * 1. Extracts abort configuration from context parameters
+   * 2. Generates unique request key
+   * 3. Aborts any existing request with same key (prevents duplicates)
+   * 4. Creates new `AbortController` if signal not provided
+   * 5. Sets up timeout timer if `abortTimeout` configured
+   * 6. Injects abort signal into configuration
+   *
+   * @param context - Executor context containing parameters and metadata
+   *
+   * @example Configuration in context
+   * ```typescript
+   * executor.execute({
+   *   id: 'fetch-data',
+   *   abortTimeout: 5000,
+   *   onAborted: (config) => console.log('Aborted:', config.id)
+   * });
+   * ```
+   */ key: "onBefore",
+            value: function onBefore(context) {
+                var _this = this;
+                var config = this.getConfig(context.parameters);
+                var key = this.generateRequestKey(config);
+                var abortTimeout = config.abortTimeout;
+                if (this.controllers.has(key)) {
+                    var _this_logger;
+                    (_this_logger = this.logger) === null || _this_logger === void 0 ? void 0 : _this_logger.debug("[".concat(this.pluginName, "] aborting previous request: ").concat(key));
+                    this.abort(key);
+                }
+                if (!config.signal) {
+                    var controller = new AbortController();
+                    this.controllers.set(key, controller);
+                    config.signal = controller.signal;
+                    if (abortTimeout && abortTimeout > 0) {
+                        var timeoutId = setTimeout(function() {
+                            var ctrl = _this.controllers.get(key);
+                            if (ctrl) {
+                                var _this_logger;
+                                ctrl.abort(new AbortError("The operation was aborted due to timeout", key, abortTimeout));
+                                (_this_logger = _this.logger) === null || _this_logger === void 0 ? void 0 : _this_logger.info("[".concat(_this.pluginName, "] timeout abort: ").concat(key, " (").concat(abortTimeout, "ms)"));
+                                _this.cleanup(key);
+                                if (typeof config.onAborted === "function") {
+                                    config.onAborted(_object_spread_props(_object_spread({}, config), {
+                                        onAborted: void 0
+                                    }));
+                                }
+                            }
+                        }, abortTimeout);
+                        this.timeouts.set(key, timeoutId);
+                    }
+                }
+            }
+        },
+        {
+            /**
+   * Executor lifecycle hook: called after successful execution
+   *
+   * Cleans up resources (controller and timeout) for completed operation
+   * Ensures no memory leaks from successful operations
+   *
+   * @param context - Executor context containing parameters and metadata
+   *
+   * @example
+   * ```typescript
+   * // After successful execution, resources are automatically cleaned
+   * await executor.execute({ id: 'task-1' });
+   * // AbortController and timeout for 'task-1' are now removed
+   * ```
+   */ key: "onSuccess",
+            value: function onSuccess(param) {
+                var parameters = param.parameters;
+                if (parameters) {
+                    var config = this.getConfig(parameters);
+                    var key = this.generateRequestKey(config);
+                    this.cleanup(key);
+                }
+            }
+        },
+        {
+            /**
+   * Executor lifecycle hook: called when execution fails
+   *
+   * Handles abort-related errors and cleans up resources
+   *
+   * Error handling logic:
+   * 1. Check if error is abort-related using `isAbortError()`
+   * 2. If abort error: Extract reason from signal, cleanup resources, return `AbortError`
+   * 3. If other error: Still cleanup resources to prevent leaks
+   *
+   * @param context - Executor context containing error, parameters, and metadata
+   * @returns `AbortError` if error is abort-related, `void` otherwise
+   *
+   * @example Abort error handling
+   * ```typescript
+   * try {
+   *   await executor.execute({ id: 'task-1', abortTimeout: 100 });
+   * } catch (error) {
+   *   if (error instanceof AbortError) {
+   *     console.log(error.getDescription());
+   *     // "The operation was aborted due to timeout (Request: task-1, Timeout: 100ms)"
+   *   }
+   * }
+   * ```
+   */ key: "onError",
+            value: function onError(param) {
+                var error = param.error, parameters = param.parameters;
+                if (!parameters) return;
+                var config = this.getConfig(parameters);
+                var key = this.generateRequestKey(config);
+                if (_AbortPlugin.isAbortError(error)) {
+                    var controller = this.controllers.get(key);
+                    var reason = controller === null || controller === void 0 ? void 0 : controller.signal.reason;
+                    this.cleanup(key);
+                    if (_instanceof(reason, AbortError)) {
+                        return reason;
+                    }
+                    return new AbortError((reason === null || reason === void 0 ? void 0 : reason.message) || (error === null || error === void 0 ? void 0 : error.message) || "The operation was aborted", key);
+                } else {
+                    this.cleanup(key);
+                }
+            }
+        },
+        {
+            /**
+   * Manually aborts a specific operation
+   *
+   * Triggers abort for the specified request, calls `onAborted` callback if provided,
+   * and cleans up all associated resources
+   *
+   * @param config - Configuration object with request identifier or identifier string
+   * @returns `true` if operation was aborted, `false` if no matching operation found
+   *
+   * @example Abort by ID
+   * ```typescript
+   * abortPlugin.abort('fetch-users');
+   * ```
+   *
+   * @example Abort with config
+   * ```typescript
+   * abortPlugin.abort({ id: 'upload-file' });
+   * ```
+   *
+   * @example Conditional abort
+   * ```typescript
+   * if (userClickedCancel) {
+   *   const aborted = abortPlugin.abort('long-task');
+   *   if (aborted) {
+   *     console.log('Task cancelled successfully');
+   *   }
+   * }
+   * ```
+   */ key: "abort",
+            value: function abort(config) {
+                var key = typeof config === "string" ? config : this.generateRequestKey(config);
+                var controller = this.controllers.get(key);
+                if (controller) {
+                    var _this_logger;
+                    controller.abort(new AbortError("The operation was aborted", key));
+                    (_this_logger = this.logger) === null || _this_logger === void 0 ? void 0 : _this_logger.info("[".concat(this.pluginName, "] manual abort: ").concat(key));
+                    this.cleanup(key);
+                    if (typeof config !== "string" && typeof config.onAborted === "function") {
+                        config.onAborted(_object_spread_props(_object_spread({}, config), {
+                            onAborted: void 0
+                        }));
+                    }
+                    return true;
+                }
+                return false;
+            }
+        },
+        {
+            /**
+   * Aborts all pending operations
+   *
+   * Iterates through all active controllers, aborts each operation,
+   * and clears all controllers and timeout timers
+   *
+   * Use cases:
+   * - User logs out
+   * - Component unmounts
+   * - Application shutdown
+   * - Navigation away from page
+   *
+   * @example Component cleanup
+   * ```typescript
+   * class MyComponent {
+   *   private abortPlugin = new AbortPlugin();
+   *
+   *   onDestroy() {
+   *     // Cancel all pending requests
+   *     this.abortPlugin.abortAll();
+   *   }
+   * }
+   * ```
+   *
+   * @example User logout
+   * ```typescript
+   * function logout() {
+   *   abortPlugin.abortAll(); // Cancel all API calls
+   *   clearUserData();
+   *   redirectToLogin();
+   * }
+   * ```
+   */ key: "abortAll",
+            value: function abortAll() {
+                var count = this.controllers.size;
+                if (count > 0) {
+                    var _this_logger;
+                    (_this_logger = this.logger) === null || _this_logger === void 0 ? void 0 : _this_logger.debug("[".concat(this.pluginName, "] aborting all ").concat(count, " requests"));
+                }
+                this.controllers.forEach(function(controller, key) {
+                    controller.abort(new AbortError("All operations were aborted", key));
+                });
+                this.controllers.clear();
+                this.timeouts.forEach(function(timeoutId) {
+                    clearTimeout(timeoutId);
+                });
+                this.timeouts.clear();
+            }
+        },
+        {
+            /**
+   * Creates a Promise that rejects when signal is aborted
+   *
+   * Returns both the promise and a cleanup function to remove event listener
+   * Prevents memory leaks by allowing proper cleanup of abort event handlers
+   *
+   * Implementation details:
+   * 1. Immediately rejects if signal is already aborted
+   * 2. Attaches event listener for future abort events
+   * 3. Returns cleanup function to remove listener
+   * 4. Uses signal reason if available, otherwise creates new `AbortError`
+   *
+   * @param signal - AbortSignal to monitor
+   * @returns Object containing promise and cleanup function
+   * @returns promise - Promise that rejects on abort
+   * @returns cleanup - Function to remove event listener
+   *
+   * @private Internal use only
+   *
+   * @example Internal usage
+   * ```typescript
+   * const { promise, cleanup } = this.createAbortPromise(signal);
+   * try {
+   *   await Promise.race([someOperation(), promise]);
+   * } finally {
+   *   cleanup(); // Always cleanup to prevent memory leak
+   * }
+   * ```
+   */ key: "createAbortPromise",
+            value: function createAbortPromise(signal) {
+                var cleanup = function() {};
+                var promise = new Promise(function(_, reject) {
+                    if (signal.aborted) {
+                        reject(signal.reason || new AbortError("The operation was aborted"));
+                        return;
+                    }
+                    var onAbort = function() {
+                        reject(signal.reason || new AbortError("The operation was aborted"));
+                    };
+                    signal.addEventListener("abort", onAbort);
+                    cleanup = function() {
+                        signal.removeEventListener("abort", onAbort);
+                    };
+                });
+                return {
+                    promise: promise,
+                    cleanup: cleanup
+                };
+            }
+        },
+        {
+            /**
+   * Wraps an async operation with `Promise.race` to ensure abort signal responsiveness
+   *
+   * Defensive mechanism for operations that don't natively check abort signals
+   * Uses promise racing to interrupt operations when signal is aborted,
+   * even if the underlying operation ignores the signal
+   *
+   * Use cases:
+   * - Third-party APIs that don't support `AbortSignal`
+   * - Legacy code without abort handling
+   * - Gateway operations that don't check signal
+   * - Any async operation needing guaranteed cancellation
+   *
+   * @template T - Type of the promise result
+   * @param promise - Promise to wrap with abort capability
+   * @param signal - AbortSignal to monitor, if not provided returns original promise
+   * @returns Wrapped promise that rejects immediately when signal is aborted
+   *
+   * @example Basic usage
+   * ```typescript
+   * const controller = new AbortController();
+   * const result = await abortPlugin.raceWithAbort(
+   *   fetch('/api/data'), // Even if fetch doesn't check signal
+   *   controller.signal
+   * );
+   * ```
+   *
+   * @example With third-party library
+   * ```typescript
+   * const result = await abortPlugin.raceWithAbort(
+   *   legacyApiCall(), // Library doesn't support abort
+   *   signal
+   * );
+   * ```
+   *
+   * @example Without signal (pass-through)
+   * ```typescript
+   * // When signal is not provided, returns original promise
+   * const result = await abortPlugin.raceWithAbort(somePromise());
+   * ```
+   *
+   * @example Timeout with abort
+   * ```typescript
+   * const controller = new AbortController();
+   * setTimeout(() => controller.abort(), 5000);
+   *
+   * try {
+   *   const result = await abortPlugin.raceWithAbort(
+   *     longRunningOperation(),
+   *     controller.signal
+   *   );
+   * } catch (error) {
+   *   if (AbortPlugin.isAbortError(error)) {
+   *     console.log('Operation timed out');
+   *   }
+   * }
+   * ```
+   */ key: "raceWithAbort",
+            value: function raceWithAbort(promise, signal) {
+                if (!signal) {
+                    return promise;
+                }
+                var _this_createAbortPromise = this.createAbortPromise(signal), abortPromise = _this_createAbortPromise.promise, cleanup = _this_createAbortPromise.cleanup;
+                return Promise.race([
+                    promise,
+                    abortPromise
+                ]).finally(function() {
+                    cleanup();
+                });
+            }
+        }
+    ], [
+        {
+            key: "isAbortError",
+            value: /**
+   * Checks if an error is abort-related (static utility method)
+   *
+   * Comprehensive check for various abort error types including custom `AbortError`,
+   * native browser `AbortError`, `ExecutorError` with abort ID, `DOMException`,
+   * and abort events. Can be used independently without plugin instance.
+   *
+   * Detection logic:
+   * 1. Custom `AbortError` instance
+   * 2. Native `Error` with name 'AbortError'
+   * 3. `ExecutorError` with `ABORT_ERROR_ID`
+   * 4. `DOMException` with name 'AbortError'
+   * 5. `Event` with type 'abort'
+   *
+   * @param error - Error object to check
+   * @returns `true` if error is abort-related, `false` otherwise
+   *
+   * @example Basic usage
+   * ```typescript
+   * try {
+   *   await fetch(url, { signal });
+   * } catch (error) {
+   *   if (AbortPlugin.isAbortError(error)) {
+   *     console.log('Request was cancelled');
+   *   } else {
+   *     console.error('Request failed:', error);
+   *   }
+   * }
+   * ```
+   *
+   * @example In error handler
+   * ```typescript
+   * function handleError(error: unknown) {
+   *   if (AbortPlugin.isAbortError(error)) {
+   *     // User cancelled - don't show error message
+   *     return;
+   *   }
+   *   showErrorNotification(error);
+   * }
+   * ```
+   */ function isAbortError(error) {
+                if (_instanceof(error, AbortError)) {
+                    return true;
+                }
+                if (_instanceof(error, Error) && error.name === "AbortError") {
+                    return true;
+                }
+                if (_instanceof(error, ExecutorError) && (error === null || error === void 0 ? void 0 : error.id) === ABORT_ERROR_ID) {
+                    return true;
+                }
+                if (_instanceof(error, DOMException) && error.name === "AbortError") {
+                    return true;
+                }
+                if (_instanceof(error, Event) && error.type === "abort") {
+                    return true;
+                }
+                return false;
+            }
+        }
+    ]);
+    return _AbortPlugin;
+}();
 // src/executor/plugins/RetryPlugin.ts
 var SAFE_MAX_RETRIES = 16;
 var DEFAULT_MAX_RETRIES = 3;
@@ -5865,4 +6468,4 @@ var SyncStorage = /*#__PURE__*/ function() {
     ]);
     return SyncStorage;
 }();
-export { AsyncExecutor, Base64Serializer, Executor, ExecutorError, FetchAbortPlugin, FetchURLPlugin, JSONSerializer, KeyStorage, KeyStorageInterface, ObjectStorage, RequestAdapterAxios, RequestAdapterFetch, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, RetryPlugin, SyncExecutor, SyncStorage };
+export { ABORT_ERROR_ID, AbortError, AbortPlugin, AsyncExecutor, Base64Serializer, Executor, ExecutorError, FetchAbortPlugin, FetchURLPlugin, JSONSerializer, KeyStorage, KeyStorageInterface, ObjectStorage, RequestAdapterAxios, RequestAdapterFetch, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, RetryPlugin, SyncExecutor, SyncStorage };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qlover/fe-corekit",
   "description": "A corekit for frontwork",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "private": false,
   "type": "module",
   "files": [
@@ -41,14 +41,16 @@
     "access": "public"
   },
   "dependencies": {
+    "@types/lodash": "^4.17.12",
     "axios": "^1.7.9",
-    "@types/lodash": "^4.17.12"
+    "@qlover/logger": "0.2.0"
   },
   "devDependencies": {
     "lodash": "^4.17.21"
   },
   "scripts": {
+    "lint": "eslint src --fix",
     "build": "tsup",
-    "build:docs": "fe-code2md --removePrefix -p ./src/index.ts -g ./docs -o ./docs/.output/fe-corekit.json -t ./docs/.output/fe-corekit.tpl.json --formatOutput prettier && rimraf ./docs/**/index.md -g"
+    "build:docs": "fe-code2md --removePrefix -p ./src/index.ts -g ./docs -o ./docs/.output/fe-corekit.json -t ./docs/.output/fe-corekit.tpl.json --formatOutput prettier && rimraf './doc/**/index.md' -g"
   }
 }