@qlover/fe-corekit 1.2.1

package/dist/index.d.ts

@@ -0,0 +1,2574 @@
+import { AxiosRequestConfig, AxiosStatic } from 'axios';
+
+/**
+ * Generic interface for encryption/decryption operations
+ * Provides a standard contract for implementing encryption strategies
+ *
+ * @template ValueType - Type of value to encrypt/decrypt
+ * @template EncryptResult - Type of encrypted result
+ *
+ * @example
+ * ```typescript
+ * // String encryption implementation
+ * class StringEncryptor implements Encryptor<string, string> {
+ *   encrypt(value: string): string {
+ *     // Encryption logic
+ *   }
+ *
+ *   decrypt(encryptedData: string): string {
+ *     // Decryption logic
+ *   }
+ * }
+ * ```
+ */
+interface Encryptor<ValueType, EncryptResult> {
+    /**
+     * Encrypts the provided value
+     * @param value - Value to encrypt
+     * @returns Encrypted result
+     */
+    encrypt(value: ValueType): EncryptResult;
+    /**
+     * Decrypts the encrypted data
+     * @param encryptedData - Data to decrypt
+     * @returns Original value
+     */
+    decrypt(encryptedData: EncryptResult): ValueType;
+}
+
+/**
+ * Custom error class for executor operations.
+ *
+ * This class provides a structured way to handle errors that occur during executor operations.
+ * It extends the standard Error class to include an error identification string, which can be used
+ * to categorize and manage errors more effectively.
+ *
+ * @category Executor
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // some executor operation
+ * } catch (error) {
+ *   throw new ExecutorError('EXECUTOR_ERROR', error);
+ * }
+ * ```
+ *
+ * @example
+ *
+ * create an error with a message from a string
+ *
+ * ```typescript
+ * const error = new ExecutorError('ERROR_ID', 'This is an error message');
+ *
+ * // => error.message is 'This is an error message'
+ * // => error.id is 'ERROR_ID'
+ * ```
+ */
+declare class ExecutorError extends Error {
+    id: string;
+    /**
+     * Constructs a new ExecutorError.
+     *
+     * if originalError is a string, it will be used as the error message.
+     * if originalError is an Error object, its message will be used as the error message.
+     * if originalError is not provided, the error message will be the id.
+     *
+     * @param id - A unique identifier for the error, used for categorization and tracking.
+     * @param originalError - The original error message or Error object that triggered this error.
+     *                        This parameter is optional.
+     */
+    constructor(id: string, originalError?: string | Error);
+}
+
+/**
+ * Represents the context in which a task is executed.
+ *
+ * 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.
+ *
+ * @template Params - The type of parameters that the task accepts.
+ *
+ * @since 1.0.14
+ *
+ * @example
+ * ```typescript
+ * const context: ExecutorContextInterface<MyParams> = {
+ *   parameters: { id: 1 },
+ *   error: null,
+ *   returnValue: 'Success'
+ * };
+ * ```
+ */
+interface ExecutorContext<Params = unknown> {
+    /**
+     * The error that occurred during the execution of the task.
+     *
+     * This property is optional and will be populated if an error
+     * occurs during task execution.
+     *
+     * @type {Error | undefined}
+     */
+    error?: Error;
+    /**
+     * The parameters passed to the task.
+     *
+     * 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.
+     *
+     * @type {Params}
+     */
+    parameters: Params;
+    /**
+     * The return value of the task.
+     *
+     * This property is optional and will contain the result of the task
+     * execution if it completes successfully.
+     *
+     * @type {unknown | undefined}
+     */
+    returnValue?: unknown;
+    /**
+     * The runtime information of the task.
+     *
+     * The current runtime of each hook.
+     *
+     * This property is optional and will contain the runtime information
+     * of the task if it is executed.
+     *
+     * property is read-only
+     *
+     * will return a frozen object that will be cleared after the chain execution is complete.
+     *
+     */
+    hooksRuntimes: HookRuntimes;
+}
+interface HookRuntimes {
+    hookName?: string;
+    /**
+     * The return value of the task.
+     *
+     * Readonly
+     */
+    returnValue?: unknown;
+    /**
+     * 执行次数
+     */
+    times?: number;
+    /**
+     * 是否中断链
+     */
+    breakChain?: boolean;
+    /**
+     * 如果有返回值，是否中断链
+     *
+     * 一般常用于需要返回一个值时中断链,比如 onError 声明周期
+     */
+    returnBreakChain?: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Type definition for promise-based task
+ * @template T - Return type of the task
+ * @template D - Input data type for the task
+ * @example
+ * ```typescript
+ * const promiseTask: PromiseTask<string, number> = async (data: number) => {
+ *   return `Result: ${data}`;
+ * };
+ * ```
+ * @category ExecutorPlugin
+ */
+type PromiseTask<Result, Params> = (context: ExecutorContext<Params>) => Promise<Result>;
+/**
+ * Type definition for synchronous task
+ * @template Result - Return type of the task
+ * @template D - Input data type for the task
+ * @example
+ * ```typescript
+ * const syncTask: SyncTask<string, number> = (data: number) => {
+ *   return `Result: ${data}`;
+ * };
+ * ```
+ * @category ExecutorPlugin
+ */
+type SyncTask<Result, Params> = (context: ExecutorContext<Params>) => Result;
+/**
+ * Union type for both promise and sync tasks
+ * @template T - Return type of the task
+ * @template D - Input data type for the task
+ * @category ExecutorPlugin
+ */
+type Task<Result, Params> = PromiseTask<Result, Params> | SyncTask<Result, Params>;
+/**
+ * Base plugin class for extending executor functionality.
+ *
+ * Plugins provide a way to intercept and modify the execution flow at different stages:
+ * - Before execution (onBefore)
+ * - After successful execution (onSuccess)
+ * - On error (onError)
+ * - Custom execution logic (onExec)
+ *
+ * LifeCycle:
+ *
+ * **onBefore**
+ *   - onBefore can modify the input data before it reaches the task, before exec is called.
+ *   - The parameter of the first plugin's onBefore is the input data of exec.
+ *   - The parameter of other plugins' onBefore is the return value of previous plugin's onBefore.
+ *   - Also, not return value, will use first plugin's onBefore return value or exec's input data.
+ *   - The parameter of the first plugin's onBefore is the input data of exec.
+ *   - If any plugin's onBefore throws an error, it immediately stops the onBefore chain and enters the onError chain.
+ *
+ * **onExec**
+ *   - onExec can modify the task before it is executed.
+ *   - Use first plugin's onExec return value or exec's task.
+ *   - The exec execution is only allowed to be modified once, so only the first onExec lifecycle method registered in the plugins list will be used.
+ *
+ * **onSuccess**
+ *   - When call exec, onSuccess will be executed after onExec.
+ *   - onSuccess accept the result of previous plugin's onSuccess, and can return a new result to the next plugin's onSuccess.
+ *   - That means, if any plugin's onSuccess returns a new value, the next plugin's onSuccess will accept the value of previous plugin's onSuccess as parameter,
+ *   - and can continue to return a new value, until the last plugin's onSuccess. The entire chain will not stop.
+ *   - The parameter of the first plugin's onSuccess is the result of exec.
+ *   - If any plugin's onSuccess throws an error, it immediately stops the onSuccess chain and enters the onError chain.
+ *
+ * **onError**
+ *   - When an error occurs during call exec, all plugins' onError will be ordered executed.
+ *   - After exec, all errors will be wrapped with ExecutorError.
+ *   - If onError of any of the plugins returns an error, the error is thrown and the entire chain is stopped, but execNoError only return the error.
+ *   - If any plugin's onError throws an error, it immediately stops the entire chain and throws the error, since errors in the error chain cannot be caught. Whether exec or execNoError.
+ *   - If all plugins' onError neither return nor throw an error, wrapping raw Errors with ExecutorError and throw.
+ *   - If execNoError is called, the first error encountered is returned, and the entire lifecycle is terminated.
+ *
+ *
+ * **execNoError returns all errors as they are.**
+ *
+ * @template T - Type of data being processed
+ * @template R - Type of result after processing
+ *
+ * @example
+ * ```typescript
+ * class LoggerPlugin extends ExecutorPlugin {
+ *   onBefore(data: unknown) {
+ *     console.log('Before execution:', data);
+ *     return data;
+ *   }
+ *
+ *   onSuccess(result: unknown) {
+ *     console.log('Execution succeeded:', result);
+ *     return result;
+ *   }
+ *
+ *   onError(error: Error) {
+ *     console.error('Execution failed:', error);
+ *     throw error;
+ *   }
+ * }
+ * ```
+ * @category ExecutorPlugin
+ */
+interface ExecutorPlugin<T = unknown> {
+    /**
+     * The pluginName of the plugin.
+     *
+     * Plugins with the same pluginName will be merged.
+     */
+    readonly pluginName: string;
+    /**
+     * Indicates if only one instance of this plugin should exist in the executor
+     * When true, attempting to add duplicate plugins will result in a warning
+     */
+    readonly onlyOne?: boolean;
+    /**
+     * Controls whether the plugin is active for specific hook executions
+     * @param name - Name of the hook being executed
+     * @param args - Arguments passed to the hook
+     * @returns Boolean indicating if the plugin should be executed
+     *
+     * @example
+     * ```typescript
+     * enabled(name: keyof ExecutorPlugin, context: ExecutorContextInterface<T>) {
+     *   // Only enable for error handling
+     *   return name === 'onError';
+     * }
+     * ```
+     */
+    enabled?(name: keyof ExecutorPlugin, context?: ExecutorContext<T>): boolean;
+    /**
+     * Hook executed before the main task
+     * Can modify the input data before it reaches the task
+     * @param data - Input data
+     * @returns Modified data or Promise of modified data
+     */
+    onBefore?(context: ExecutorContext<T>): void | Promise<void>;
+    /**
+     * Error handling hook
+     * - For `exec`: returning a value or throwing will break the chain
+     * - For `execNoError`: returning a value or throwing will return the error
+     *
+     * Because `onError` can break the chain, best practice is each plugin only handle plugin related error
+     *
+     * @param error - Error that occurred
+     * @param data - Original input data
+     * @returns ExecutorError, void, or Promise of either
+     */
+    onError?(context: ExecutorContext<T>): Promise<ExecutorError | Error | void> | ExecutorError | Error | void;
+    /**
+     * Hook executed after successful task completion
+     * Can transform the task result
+     * @param result - Task execution result
+     * @returns Modified result or Promise of modified result
+     */
+    onSuccess?(context: ExecutorContext<T>): void | Promise<void>;
+    /**
+     * Custom execution logic hook
+     * Only the first plugin with onExec will be used
+     * @param task - Task to be executed
+     * @returns Task result or Promise of result
+     */
+    onExec?(context: ExecutorContext<unknown>, task: Task<unknown, unknown>): Promise<unknown> | unknown;
+}
+
+/**
+ * Base executor class providing plugin management and execution pipeline
+ *
+ * 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
+ *
+ * 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.
+ *
+ * @abstract
+ * @class Executor
+ * @category Executor
+ * @example
+ * ```typescript
+ * // Create an executor instance
+ * const executor = new AsyncExecutor();
+ *
+ * // Add plugins
+ * executor.use(new LoggerPlugin());
+ * executor.use(new RetryPlugin({ maxAttempts: 3 }));
+ *
+ * // Execute a task
+ * const result = await executor.exec(async (data) => {
+ *   return await someAsyncOperation(data);
+ * });
+ * ```
+ */
+declare abstract class Executor<ExecutorConfig = unknown> {
+    protected config?: ExecutorConfig | undefined;
+    /**
+     * Array of active plugins
+     *
+     * - 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
+     *
+     * @example
+     * ```typescript
+     * protected plugins = [
+     *   new LoggerPlugin(),
+     *   new RetryPlugin()
+     * ];
+     * ```
+     */
+    protected plugins: ExecutorPlugin[];
+    /**
+     * Creates a new Executor instance
+     *
+     * - Purpose: Initialize executor with optional configuration
+     * - Core Concept: Configurable executor setup
+     * - Main Features: Configuration injection
+     * - Primary Use: Executor instantiation
+     *
+     * @param {ExecutorConfig} config - Optional configuration object
+     *
+     * @example
+     * ```typescript
+     * const executor = new Executor({
+     *   // config options
+     * });
+     * ```
+     */
+    constructor(config?: ExecutorConfig | undefined);
+    /**
+     * Add a plugin to the executor
+     *
+     * - 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
+     *
+     * @param plugin - Plugin instance to add
+     *
+     * @example
+     * ```typescript
+     * executor.use(new LoggerPlugin());
+     * executor.use(new RetryPlugin({ maxAttempts: 3 }));
+     * ```
+     *
+     * @example
+     *
+     * Use a plain object as a plugin
+     * ```typescript
+     * executor.use({
+     *   onBefore: (data) => ({ ...data, modified: true })
+     * });
+     * ```
+     */
+    use(plugin: ExecutorPlugin): void;
+    /**
+     * Execute a plugin hook
+     *
+     * - 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
+     *
+     * @param plugins - Plugins to execute
+     * @param name - Hook name to execute
+     * @param args - Arguments for the hook
+     *
+     * @example
+     * ```typescript
+     * await executor.runHook(plugins, 'beforeExec', data);
+     * ```
+     */
+    abstract runHooks(plugins: ExecutorPlugin[], name: keyof ExecutorPlugin, ...args: unknown[]): void | unknown | Promise<void | unknown>;
+    /**
+     * Execute a task with 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
+     *
+     * @param task - Task to execute
+     * @param data - Optional input data for task
+     * @throws {ExecutorError} If task execution fails
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.exec(async (data) => {
+     *   return await processData(data);
+     * });
+     * ```
+     */
+    abstract exec<Result, Params = unknown>(task: Task<Result, Params>): Promise<Result> | Result;
+    /**
+     * Execute a task with plugin pipeline and input data
+     *
+     * - 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
+     *
+     * @param data - Input data for task
+     * @param task - Task to execute
+     * @throws {ExecutorError} If task execution fails
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.exec(data, async (data) => {
+     *   return await processData(data);
+     * });
+     * ```
+     */
+    abstract exec<Result, Params = unknown>(data: unknown, task: Task<Result, Params>): Promise<Result> | Result;
+    /**
+     * Execute a task without throwing errors
+     *
+     * - 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
+     *
+     * @param task - Task to execute
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.execNoError(async (data) => {
+     *   return await riskyOperation(data);
+     * });
+     * if (result instanceof ExecutorError) {
+     *   console.error('Task failed:', result);
+     * }
+     * ```
+     */
+    abstract execNoError<Result, Params = unknown>(task: Task<Result, Params>): Promise<Result | ExecutorError> | Result | ExecutorError;
+    /**
+     * 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
+     *
+     * @param data - Input data for task
+     * @param task - Task to execute
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.execNoError(data, async (data) => {
+     *   return await riskyOperation(data);
+     * });
+     * if (result instanceof ExecutorError) {
+     *   console.error('Task failed:', result);
+     * }
+     * ```
+     */
+    abstract execNoError<Result, Params = unknown>(data: unknown, task: Task<Result, Params>): Promise<Result | ExecutorError> | Result | ExecutorError;
+}
+
+/**
+ * Request adapter configuration
+ *
+ * This type defines the configuration options for a request adapter.
+ * It includes properties for URL, method, headers, and other request details.
+ * The main purpose is to provide a flexible structure for configuring HTTP requests.
+ *
+ * @since 1.0.14
+ */
+type RequestAdapterConfig<RequestData = unknown> = {
+    /**
+     * Request URL path
+     * Will be combined with baseURL if provided
+     *
+     * Processed by FetchURLPlugin during request
+     *
+     * @todo Change to URL | Request, add attribute `input`
+     * @example
+     * ```typescript
+     * url: '/users/1'
+     * ```
+     */
+    url?: string;
+    /**
+     * HTTP request methods supported by the executor
+     * Follows standard HTTP method definitions
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+     * @example
+     * ```typescript
+     * method: 'GET'
+     * ```
+     */
+    method?: string;
+    /**
+     * Base URL for all requests
+     * Will be prepended to the request URL
+     *
+     * @example
+     * ```typescript
+     * baseURL: 'https://api.example.com'
+     * // url = /users/1 => https://api.example.com/users/1
+     * // url = users/1 => https://api.example.com/users/1
+     * ```
+     */
+    baseURL?: string;
+    /**
+     * Request body data
+     *
+     * Mapping fetch `body`
+     *
+     * @typeParam RequestData - The type of the request body data.
+     * @example
+     * ```typescript
+     * data: { name: 'John Doe' }
+     * ```
+     */
+    data?: RequestData;
+    /**
+     * URL query parameters
+     * Will be serialized and appended to the URL
+     *
+     * @example
+     * ```typescript
+     * params: { search: 'query' }
+     * ```
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Request headers
+     *
+     * @example
+     * ```typescript
+     * headers: { 'Content-Type': 'application/json' }
+     * ```
+     */
+    headers?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Response type
+     *
+     * Specifies the type of data that the server will respond with.
+     *
+     * @example
+     * ```typescript
+     * responseType: 'json'
+     * ```
+     */
+    responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream' | 'formdata';
+    /**
+     * Request ID, used to identify the request in the abort plugin.
+     */
+    requestId?: string;
+    [key: string]: any;
+};
+/**
+ * Request adapter response
+ *
+ * This type defines the structure of a response from a request adapter.
+ * It includes the response data, status, headers, and the original request configuration.
+ *
+ * @typeParam Req - The type of the request data.
+ * @typeParam Res - The type of the response data.
+ */
+type RequestAdapterResponse<Req = unknown, Res = unknown> = {
+    data: Res;
+    status: number;
+    statusText: string;
+    headers: {
+        [key: string]: unknown;
+    };
+    config: RequestAdapterConfig<Req>;
+    response: Response;
+    [key: string]: unknown;
+};
+/**
+ * Request adapter interface
+ *
+ * This interface defines the contract for request adapters.
+ * Adapters are responsible for handling the specific details of a request,
+ * such as URL construction, headers, and response handling.
+ *
+ */
+interface RequestAdapterInterface<Config extends RequestAdapterConfig> {
+    /**
+     * The configuration for the request adapter.
+     *
+     * @type {Config}
+     */
+    readonly config: Config;
+    /**
+     * Sends a request using the specified options and returns a promise with the response.
+     *
+     * @typeParam Request - The type of the request data.
+     * @typeParam Response - The type of the response data.
+     * @param options - The configuration options for the request.
+     * @returns A promise that resolves to the response of the request.
+     * @example
+     * ```typescript
+     * adapter.request({ url: '/users', method: 'GET' }).then(response => console.log(response));
+     * ```
+     */
+    request<Request, Response>(options: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Request, Response>>;
+    /**
+     * Retrieves the current configuration of the request adapter.
+     *
+     * @returns The current configuration.
+     * @example
+     * ```typescript
+     * const config = adapter.getConfig();
+     * ```
+     */
+    getConfig: () => Config;
+}
+
+/**
+ * Represents a custom error class for handling request-related errors in the application
+ *
+ * RequestError extends the base ExecutorError class to provide specific error handling
+ * for HTTP requests and fetch operations. It works in conjunction with RequestErrorID
+ * to categorize different types of request failures.
+ *
+ * @since 1.0.14
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetchData(url);
+ * } catch (error) {
+ *   if (error instanceof RequestError) {
+ *     // Handle request specific error
+ *     console.error('Request failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class RequestError extends ExecutorError {
+}
+/**
+ * Error IDs for different fetch request failure scenarios
+ * Used to identify specific error types in error handling
+ *
+ * @description
+ * This enum provides a standardized set of error identifiers that can be used
+ * to categorize and handle different types of request failures in a consistent manner.
+ * Each error ID represents a specific failure scenario that might occur during HTTP requests.
+ *
+ * @example
+ * ```typescript
+ * if (error.id === RequestErrorID.RESPONSE_NOT_OK) {
+ *   // Handle non-200 response
+ * } else if (error.id === RequestErrorID.ABORT_ERROR) {
+ *   // Handle aborted request
+ * }
+ * ```
+ */
+declare enum RequestErrorID {
+    /** Generic fetch request error */
+    REQUEST_ERROR = "REQUEST_ERROR",
+    /** Environment doesn't support fetch API */
+    ENV_FETCH_NOT_SUPPORT = "ENV_FETCH_NOT_SUPPORT",
+    /** No fetcher function provided */
+    FETCHER_NONE = "FETCHER_NONE",
+    /** Response status is not OK (not in 200-299 range) */
+    RESPONSE_NOT_OK = "RESPONSE_NOT_OK",
+    /** Request was aborted */
+    ABORT_ERROR = "ABORT_ERROR",
+    /** URL is not provided */
+    URL_NONE = "URL_NONE"
+}
+
+/**
+ * Generic interface for data serialization/deserialization operations
+ * Provides a standard contract for implementing serialization strategies
+ *
+ * This is a generic interface, you can implement it with different serialization strategies
+ *
+ * @template T - Type of data to serialize/deserialize, defaults to any
+ * @template R - Type of serialized result, defaults to string
+ *
+ * @since 1.0.10
+ *
+ * @example
+ * ```typescript
+ * // JSON serialization implementation
+ * class JSONSerializer implements Serializer {
+ *   serialize(data: any): string {
+ *     return JSON.stringify(data);
+ *   }
+ *
+ *   deserialize(data: string): any {
+ *     return JSON.parse(data);
+ *   }
+ * }
+ * ```
+ */
+interface Serializer<T = unknown, R = string> {
+    /**
+     * Serializes data into a target format
+     * @since 1.0.10
+     * @param data - Data to serialize
+     * @returns Serialized representation
+     */
+    serialize(data: T): R;
+    /**
+     * Deserializes data from target format back to original form
+     * @since 1.0.10
+     * @param data - Data to deserialize
+     * @param defaultValue - Optional default value to return if deserialization fails
+     * @returns Original data structure
+     */
+    deserialize(data: R, defaultValue?: T): T;
+}
+
+/**
+ * Interface representing a synchronous storage mechanism.
+ *
+ * @template Key - The type of keys used to identify stored values.
+ * @template ValueType - The type of values stored, defaults to unknown.
+ *
+ * @example
+ * ```typescript
+ * const storage: SyncStorage<string, number> = ...;
+ * storage.setItem('key', 123);
+ * const value = storage.getItem('key', 0);
+ * ```
+ */
+interface SyncStorage<Key, ValueType = unknown> {
+    /**
+     * The number of items stored.
+     */
+    readonly length: number;
+    /**
+     * Stores a value with the specified key.
+     *
+     * @param key - The key to identify the stored value.
+     * @param value - The value to store.
+     * @param options - Optional parameters for storage.
+     */
+    setItem<T>(key: Key, value: T, options?: unknown): void;
+    /**
+     * Retrieves a value by key.
+     *
+     * @param key - The key of the value to retrieve.
+     * @param defaultValue - The default value to return if the key is not found.
+     * @param options - Optional parameters for retrieval.
+     * @returns The value associated with the key, or the default value if not found.
+     */
+    getItem<T extends ValueType>(key: Key, defaultValue?: T, options?: unknown): T | null;
+    /**
+     * Removes a value by key.
+     *
+     * @param key - The key of the value to remove.
+     * @param options - Optional parameters for removal.
+     */
+    removeItem(key: Key, options?: unknown): void;
+    /**
+     * Clears all stored values.
+     */
+    clear(): void;
+}
+/**
+ * Interface representing an asynchronous storage mechanism.
+ *
+ * @template Key - The type of keys used to identify stored values.
+ * @template ValueType - The type of values stored, defaults to unknown.
+ *
+ * @example
+ *
+ * ```typescript
+ * const storage: AsyncStorage<string, number> = ...;
+ * await storage.setItem('key', 123);
+ * const value = await storage.getItem('key', 0);
+ * ```
+ *
+ */
+interface AsyncStorage<Key, ValueType = unknown> {
+    /**
+     * The number of items stored.
+     */
+    readonly length: number;
+    /**
+     * Asynchronously stores a value with the specified key.
+     *
+     * @param key - The key to identify the stored value.
+     * @param value - The value to store.
+     * @param options - Optional parameters for storage.
+     * @returns A promise that resolves when the value is stored.
+     */
+    setItem<T>(key: Key, value: T, options?: unknown): Promise<void>;
+    /**
+     * Asynchronously retrieves a value by key.
+     *
+     * @param key - The key of the value to retrieve.
+     * @param defaultValue - The default value to return if the key is not found.
+     * @param options - Optional parameters for retrieval.
+     * @returns A promise that resolves to the value associated with the key, or the default value if not found.
+     */
+    getItem<T extends ValueType>(key: Key, defaultValue?: T, options?: unknown): Promise<T | null>;
+    /**
+     * Asynchronously removes a value by key.
+     *
+     * @param key - The key of the value to remove.
+     * @param options - Optional parameters for removal.
+     * @returns A promise that resolves when the value is removed.
+     */
+    removeItem(key: Key, options?: unknown): Promise<void>;
+    /**
+     * Asynchronously clears all stored values.
+     *
+     * @returns A promise that resolves when all values are cleared.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Get the value type of an object
+ *
+ * @since 1.0.14
+ *
+ * @example
+ * ```ts
+ * type T = { a: number; b: string };
+ * type V = ValueOf<T>; // V is number | string
+ * ```
+ */
+type ValueOf<T> = T[keyof T];
+/**
+ * Get the intersection type of two types
+ *
+ * @since 1.0.14
+ *
+ * @example
+ * ```ts
+ * type T1 = { a: number; b: string };
+ * type T2 = { a: number; c: boolean };
+ * type I = Intersection<T1, T2>; // I is { a: number }
+ * ```
+ */
+type Intersection<T1, T2> = {
+    [P in keyof T1 & keyof T2]: T1[P] | T2[P];
+};
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * const executor = new AsyncExecutor();
+ * executor.use(new LogPlugin());
+ *
+ * const result = await executor.exec(async (data) => {
+ *   const response = await fetch('https://api.example.com/data');
+ *   return response.json();
+ * });
+ * ```
+ *
+ * @category AsyncExecutor
+ */
+declare class AsyncExecutor<ExecutorConfig = unknown> extends Executor<ExecutorConfig> {
+    /**
+     * Execute plugin hook functions 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
+     *
+     * Plugin 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
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const result = await this.runHook(
+     *   this.plugins,
+     *   'beforeExec',
+     *   { userId: 123 }
+     * );
+     * ```
+     */
+    runHooks<Params>(plugins: ExecutorPlugin[], 
+    /**
+     * allow any string as hook name.
+     * if the hook name is not a function, it will be skipped
+     *
+     * @since 1.1.3
+     */
+    hookName: string, context?: ExecutorContext<Params>, ...args: unknown[]): Promise<unknown>;
+    /**
+     * 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
+     *
+     * @template T - Type of task return value
+     * @param dataOrTask - Task data or task function
+     * @param task - Task function (optional)
+     * @returns Promise resolving to either result or ExecutorError
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.execNoError(async () => {
+     *   const response = await riskyOperation();
+     *   return response.data;
+     * });
+     *
+     * if (result instanceof ExecutorError) {
+     *   console.error('Operation failed:', result);
+     * }
+     * ```
+     */
+    execNoError<Result, Params = unknown>(dataOrTask: unknown | 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
+     *
+     * Execution flow:
+     * 1. Validate and prepare task
+     * 2. Check for custom execution plugins
+     * 3. Execute task with plugin pipeline
+     *
+     * @template T - Type of task return value
+     * @template D - Type of task data
+     * @param dataOrTask - Task data or task function
+     * @param task - Task function (optional)
+     * @throws {Error} When task is not an async function
+     * @returns Promise resolving to task result
+     *
+     * @example
+     * ```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();
+     * });
+     * ```
+     */
+    exec<Result, Params = unknown>(dataOrTask: Params | PromiseTask<Result, Params>, task?: PromiseTask<Result, Params>): Promise<Result>;
+    /**
+     * 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
+     *
+     * Pipeline stages:
+     * 1. onBefore hooks - Pre-process input data
+     * 2. Task execution - Run the actual task
+     * 3. onSuccess hooks - Post-process results
+     * 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
+     * @throws {ExecutorError} When task execution fails
+     * @returns Promise resolving to task result(context.returnValue)
+     *
+     * @example
+     * ```typescript
+     * private 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);
+     *   } catch (error) {
+     *     const handledError = await this.runHook(
+     *       this.plugins,
+     *       'onError',
+     *       error,
+     *       data
+     *     );
+     *     throw new ExecutorError('EXECUTION_FAILED', handledError);
+     *   }
+     * }
+     * ```
+     */
+    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
+ *
+ * Use this executor when:
+ * 1. All operations are synchronous
+ * 2. You need immediate results
+ * 3. Performance is critical
+ * 4. No async operations are involved
+ *
+ * @extends Executor
+ *
+ * @example
+ * ```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 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
+ * const result = executor.execNoError(() => {
+ *   throw new Error('Validation Error');
+ * }); // Returns ExecutorError instead of throwing
+ * ```
+ * @category SyncExecutor
+ */
+declare class SyncExecutor<ExecutorConfig = unknown> extends Executor<ExecutorConfig> {
+    /**
+     * Execute plugin hook functions synchronously
+     * Manages the plugin execution chain and handles results
+     *
+     * Plugin 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
+     *
+     * Key differences from AsyncExecutor:
+     * - All operations are synchronous
+     * - Results are immediately available
+     * - No await statements needed
+     *
+     * @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 Result of the hook function execution
+     *
+     * @example
+     * ```typescript
+     * // Internal usage example
+     * const result = this.runHook(
+     *   this.plugins,
+     *   'onBefore',
+     *   { value: 'test' }
+     * );
+     * ```
+     */
+    runHooks<Params>(plugins: ExecutorPlugin[], 
+    /**
+     * allow any string as hook name.
+     * if the hook name is not a function, it will be skipped
+     *
+     * @since 1.1.3
+     */
+    hookName: string, context?: ExecutorContext<Params>, ...args: unknown[]): Params;
+    /**
+     * Execute task without throwing errors
+     * Wraps all errors in ExecutorError for safe error handling
+     *
+     * Advantages over try-catch:
+     * 1. Standardized error handling
+     * 2. No exception propagation
+     * 3. Consistent error types
+     *
+     * @template T - Type of task return value
+     * @param dataOrTask - Task data or task function
+     * @param task - Task function (optional)
+     * @returns Task result or ExecutorError
+     *
+     * @example
+     * ```typescript
+     * const result = executor.execNoError((data) => {
+     *   if (!data.isValid) {
+     *     throw new Error('Invalid data');
+     *   }
+     *   return data.value;
+     * });
+     *
+     * if (result instanceof ExecutorError) {
+     *   console.log('Task failed:', result.message);
+     * } else {
+     *   console.log('Task succeeded:', result);
+     * }
+     * ```
+     */
+    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
+     *
+     * Execution flow:
+     * 1. Validate and prepare task
+     * 2. Check for custom execution plugins
+     * 3. Execute task with plugin pipeline
+     *
+     * Performance considerations:
+     * - No async overhead
+     * - Direct execution path
+     * - Immediate results
+     *
+     * @template T - Type of task return value
+     * @template D - Type of task data
+     * @param dataOrTask - Task data or task function
+     * @param task - Task function (optional)
+     * @throws {Error} When task is not a function
+     * @returns Task execution result
+     *
+     * @example
+     * ```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
+     * const result = executor.exec((data) => {
+     *   if (typeof data !== 'string') {
+     *     throw new Error('Data must be string');
+     *   }
+     *   return data.trim();
+     * });
+     * ```
+     */
+    exec<Result, Params = unknown>(dataOrTask: Params | SyncTask<Result, Params>, task?: SyncTask<Result, Params>): Result;
+    /**
+     * Core method to run synchronous task with plugin hooks
+     * Implements the complete execution pipeline with all plugin hooks
+     *
+     * Pipeline stages:
+     * 1. onBefore hooks - Pre-process input data
+     * 2. Task execution - Run the actual task
+     * 3. onSuccess hooks - Post-process results
+     * 4. onError hooks - Handle any errors
+     *
+     * Error handling strategy:
+     * - Catches all errors
+     * - Passes errors through plugin chain
+     * - Wraps unhandled errors in ExecutorError
+     *
+     * @template T - Type of task return value
+     * @template D - Type of task data
+     * @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
+     * ```typescript
+     * // Internal implementation example
+     * private run(data, task) {
+     *   try {
+     *     const preparedData = this.runHook(this.plugins, 'onBefore', data);
+     *     const result = task(preparedData);
+     *     return this.runHook(this.plugins, 'onSuccess', result);
+     *   } catch (error) {
+     *     const handledError = this.runHook(
+     *       this.plugins,
+     *       'onError',
+     *       error,
+     *       data
+     *     );
+     *     // Error handling logic
+     *   }
+     * }
+     * ```
+     */
+    run<Result, Params = unknown>(data: Params, actualTask: SyncTask<Result, Params>): Result;
+}
+
+/**
+ * Configuration options for the RetryPlugin
+ *
+ * This interface defines the configuration options for the RetryPlugin,
+ * which is used to control the retry behavior of task executions.
+ *
+ * - Core Idea: Provide a flexible configuration for retry logic.
+ * - Main Function: Define retry parameters such as max retries, delay, and conditions.
+ * - Main Purpose: Allow customization of retry behavior to suit different use cases.
+ *
+ * @category RetryPlugin
+ *
+ * @example
+ * ```typescript
+ * const options: RetryOptions = {
+ *   maxRetries: 5,
+ *   retryDelay: 2000,
+ *   useExponentialBackoff: true,
+ *   shouldRetry: (error) => error.message !== 'Invalid credentials'
+ * };
+ * ```
+ */
+interface RetryOptions {
+    /**
+     * Maximum number of retry attempts (starting from 0)
+     * Will be clamped between 1 and SAFE_MAX_RETRIES (16)
+     * @default 3
+     */
+    maxRetries: number;
+    /**
+     * Base delay between retry attempts in milliseconds
+     * Used directly for fixed delay, or as base for exponential backoff
+     * @default 1000
+     */
+    retryDelay: number;
+    /**
+     * When true, implements exponential backoff delay strategy
+     * Delay formula: retryDelay * (2 ^ attemptNumber)
+     * @default false
+     */
+    useExponentialBackoff: boolean;
+    /**
+     * Custom function to determine if a retry should be attempted
+     * @param error - The error that caused the failure
+     * @returns boolean indicating if retry should be attempted
+     * @default () => true (always retry)
+     */
+    shouldRetry: (error: Error) => boolean;
+}
+/**
+ * Plugin that implements retry logic for failed task executions
+ *
+ * This class provides a mechanism to retry failed tasks with configurable
+ * options such as maximum retries, delay strategies, and custom retry conditions.
+ *
+ * - Core Idea: Enhance task execution reliability through retries.
+ * - Main Function: Retry failed tasks based on specified conditions and strategies.
+ * - Main Purpose: Improve success rates of task executions by handling transient errors.
+ *
+ * @implements {ExecutorPlugin}
+ *
+ * @example
+ * ```typescript
+ * const retryPlugin = new RetryPlugin({
+ *   maxRetries: 5,
+ *   retryDelay: 2000,
+ *   useExponentialBackoff: true,
+ *   shouldRetry: (error) => error.message !== 'Invalid credentials'
+ * });
+ * ```
+ *
+ * @category RetryPlugin
+ */
+declare class RetryPlugin implements ExecutorPlugin {
+    /**
+     * The pluginName of the plugin
+     */
+    readonly pluginName = "RetryPlugin";
+    /**
+     * Ensures only one instance of RetryPlugin is used per executor
+     */
+    readonly onlyOne = true;
+    /**
+     * Normalized options with defaults applied
+     */
+    private readonly options;
+    /**
+     * Constructs a new instance of RetryPlugin with specified options.
+     *
+     * This constructor initializes the RetryPlugin with user-defined options,
+     * applying default values where necessary and clamping the maxRetries value.
+     *
+     * @param options - Partial configuration options for retry behavior
+     *
+     * @example
+     * ```typescript
+     * const retryPlugin = new RetryPlugin({
+     *   maxRetries: 5,
+     *   retryDelay: 2000,
+     *   useExponentialBackoff: true
+     * });
+     * ```
+     */
+    constructor(options?: Partial<RetryOptions>);
+    /**
+     * Implements delay between retry attempts
+     *
+     * This method calculates and applies a delay between retry attempts,
+     * using either a fixed delay or an exponential backoff strategy.
+     *
+     * @param attempt - Current attempt number
+     * @returns Promise that resolves after the delay
+     *
+     * @example
+     * ```typescript
+     * await this.delay(2); // Applies delay for the third attempt
+     * ```
+     */
+    private delay;
+    /**
+     * Custom execution hook that implements retry logic
+     *
+     * This method intercepts task execution to add retry capability,
+     * executing the task with the configured retry logic.
+     *
+     * @template T - Type of task return value
+     * @param task - Task to be executed with retry support
+     * @returns Promise resolving to task result
+     *
+     * @example
+     * ```typescript
+     * const result = await retryPlugin.onExec(() => fetchData());
+     * ```
+     */
+    onExec(context: ExecutorContext<unknown>, task: PromiseTask<unknown, unknown>): Promise<unknown>;
+    /**
+     * Determines if another retry attempt should be made
+     *
+     * This method checks if a retry should be attempted based on the
+     * remaining retry count and a custom retry condition function.
+     *
+     * @param error - Error from failed attempt
+     * @param retryCount - Number of retries remaining
+     * @returns boolean indicating if retry should be attempted
+     *
+     * @example
+     * ```typescript
+     * if (this.shouldRetry({ error, retryCount })) {
+     *   // Proceed with retry
+     * }
+     * ```
+     */
+    private shouldRetry;
+    /**
+     * Core retry implementation
+     *
+     * This method recursively attempts to execute the task until it succeeds
+     * or the maximum number of retries is reached, applying the configured delay strategy.
+     *
+     * @template T - Type of task return value
+     * @param fn - Function to retry
+     * @param options - Retry configuration options
+     * @param retryCount - Number of retries remaining
+     * @throws {ExecutorError} When all retry attempts fail
+     * @returns Promise resolving to task result
+     *
+     * @example
+     * ```typescript
+     * const result = await this.retry(fetchData, options, 3);
+     * ```
+     */
+    retry<Result, Params = unknown>(fn: PromiseTask<Result, Params>, context: ExecutorContext<Params>, options: RetryOptions, retryCount: number): Promise<Result | undefined>;
+}
+
+/**
+ * Available log levels
+ * Used to categorize and control log output
+ */
+declare const LEVELS: {
+    readonly LOG: "LOG";
+    readonly INFO: "INFO";
+    readonly ERROR: "ERROR";
+    readonly WARN: "WARN";
+    readonly DEBUG: "DEBUG";
+};
+type LogLevel = (typeof LEVELS)[keyof typeof LEVELS];
+type LogArgument = unknown;
+/**
+ * Options for execution logging
+ * @interface ExecOptions
+ */
+type ExecOptions = {
+    /** When true, commands are only logged but not executed */
+    isDryRun?: boolean;
+    /** When true, indicates the command is from an external source */
+    isExternal?: boolean;
+};
+/**
+ * Logger class providing various logging methods
+ *
+ * The Logger class supports multiple log levels and can be configured
+ * to operate in different environments such as CI, dry run, debug, and silent modes.
+ *
+ * - Core Idea: Provide a flexible and configurable logging utility.
+ * - Main Function: Log messages at different levels with optional environment-specific behavior.
+ * - Main Purpose: Facilitate debugging and monitoring by providing structured log output.
+ *
+ * @class Logger
+ * @example
+ * ```typescript
+ * // Create a logger instance
+ * const logger = new Logger({ debug: true });
+ *
+ * // Log messages at different levels
+ * logger.info('This is an info message');
+ * logger.error('This is an error message');
+ * logger.debug('This is a debug message');
+ * ```
+ */
+declare class Logger {
+    protected isCI: boolean;
+    protected isDryRun: boolean;
+    protected isDebug: boolean;
+    protected isSilent: boolean;
+    /**
+     * Creates a new Logger instance
+     *
+     * This constructor initializes the Logger with configuration options
+     * that determine its behavior in different environments.
+     *
+     * @param options - Logger configuration options
+     * @param {boolean} options.isCI  - Whether running in CI environment
+     * @param {boolean} options.dryRun  - Whether to perform dry run only
+     * @param {boolean} options.debug  - Whether to enable debug output
+     * @param {boolean} options.silent  - Whether to suppress all output
+     *
+     * @example
+     * ```typescript
+     * const logger = new Logger({ isCI: true, debug: true });
+     * ```
+     */
+    constructor({ isCI, dryRun, debug, silent }?: {
+        isCI?: boolean | undefined;
+        dryRun?: boolean | undefined;
+        debug?: boolean | undefined;
+        silent?: boolean | undefined;
+    });
+    /**
+     * Core logging method
+     * Handles actual console output based on configuration
+     *
+     * @param level - Log level for the message
+     * @param args - Arguments to log
+     *
+     * @example
+     * ```typescript
+     * this.print(LEVELS.INFO, 'Information message');
+     * ```
+     */
+    protected print(_level: LogLevel, ...args: LogArgument[]): void;
+    /**
+     * Adds prefix to log messages
+     * Can be overridden to customize log format
+     *
+     * @param value - The prefix value
+     * @param _level - Log level (optional)
+     * @returns Formatted prefix string or array
+     *
+     * @example
+     * ```typescript
+     * const prefix = this.prefix('INFO');
+     * ```
+     */
+    prefix(value: string, _level?: LogLevel): string | string[];
+    /**
+     * Basic log output
+     *
+     * @param args - Values to log
+     *
+     * @example
+     * ```typescript
+     * logger.log('This is a log message');
+     * ```
+     */
+    log(...args: LogArgument[]): void;
+    /**
+     * Informational log output
+     *
+     * @param args - Values to log
+     *
+     * @example
+     * ```typescript
+     * logger.info('This is an info message');
+     * ```
+     */
+    info(...args: LogArgument[]): void;
+    /**
+     * Warning log output
+     *
+     * @param args - Values to log
+     *
+     * @example
+     * ```typescript
+     * logger.warn('This is a warning message');
+     * ```
+     */
+    warn(...args: LogArgument[]): void;
+    /**
+     * Error log output
+     *
+     * @param args - Values to log
+     *
+     * @example
+     * ```typescript
+     * logger.error('This is an error message');
+     * ```
+     */
+    error(...args: LogArgument[]): void;
+    /**
+     * Debug log output
+     *
+     * - Only active when debug mode is enabled
+     * - Formats objects as JSON strings
+     *
+     * @param args - Values to log
+     *
+     * @example
+     * ```typescript
+     * logger.debug('This is a debug message');
+     * ```
+     */
+    debug(...args: LogArgument[]): void;
+    /**
+     * Verbose log output
+     *
+     * - Only active when debug mode is enabled
+     * - Uses purple color for output
+     *
+     * @param args - Values to log
+     *
+     * @example
+     * ```typescript
+     * logger.verbose('This is a verbose message');
+     * ```
+     */
+    verbose(...args: LogArgument[]): void;
+    /**
+     * Command execution logging
+     * Supports dry run mode and external command indication
+     *
+     * @param args - Command arguments and options
+     *
+     * @example
+     * ```typescript
+     * logger.exec('npm', 'install', { isDryRun: true });
+     * logger.exec(['git', 'commit', '-m', 'feat: update'], { isExternal: true });
+     * ```
+     */
+    exec(...args: (LogArgument | ExecOptions)[]): void;
+    /**
+     * Obtrusive log output
+     * Adds extra line breaks in non-CI environments
+     *
+     * @param args - Values to log
+     *
+     * @example
+     * ```typescript
+     * logger.obtrusive('This is an important message');
+     * ```
+     */
+    obtrusive(...args: LogArgument[]): void;
+}
+
+/**
+ * Request adapter fetch configuration
+ *
+ * This type defines the configuration options for a request adapter.
+ * It includes properties for URL, method, headers, and other request details.
+ * The main purpose is to provide a flexible structure for configuring HTTP requests.
+ *
+ * @since 1.0.14
+ */
+type RequestAdapterFetchConfig<Request = unknown> = Omit<globalThis.RequestInit, 'headers'> & RequestAdapterConfig<Request> & {
+    fetcher?: typeof fetch;
+    onStreamProgress?: (progress: number) => void;
+    signal?: AbortSignal;
+    onAbort?(config: RequestAdapterFetchConfig): void;
+};
+declare class RequestAdapterFetch implements RequestAdapterInterface<RequestAdapterFetchConfig> {
+    readonly config: RequestAdapterFetchConfig;
+    private executor;
+    /**
+     * Creates a new FetchRequest instance
+     * Automatically detects and configures fetch implementation
+     *
+     * - Core Idea: Simplify HTTP requests with built-in fetch support.
+     * - Main Function: Initialize fetch requests with optional configuration.
+     * - Main Purpose: Provide a flexible and extensible HTTP request utility.
+     *
+     * @param config - Request configuration options
+     * @throws {FetchRequestError} When fetch is not available
+     *
+     * @example
+     * ```typescript
+     * const fetchRequest = new FetchRequest({ baseURL: 'https://api.example.com' });
+     * ```
+     */
+    constructor(config?: Partial<RequestAdapterFetchConfig>);
+    getConfig(): RequestAdapterFetchConfig;
+    usePlugin(plugin: ExecutorPlugin): void;
+    /**
+     * Core request implementation
+     * Merges configurations and executes fetch request
+     *
+     * - Core Idea: Execute HTTP requests with merged configurations.
+     * - Main Function: Perform fetch requests using provided configurations.
+     * - Main Purpose: Facilitate HTTP communication with error handling.
+     *
+     * @override
+     * @param config - Request configuration
+     * @returns Promise resolving to Response object
+     * @throws {FetchRequestError} When fetcher is not available
+     *
+     * @example
+     * ```typescript
+     * const response = await fetchRequest.request({ url: '/data' });
+     * ```
+     */
+    request<Request, Response>(config: RequestAdapterFetchConfig<Request>): Promise<RequestAdapterResponse<Request, Response>>;
+    parametersToRequest(parameters: RequestAdapterFetchConfig): Request;
+    /**
+     * Converts the raw fetch response into a standardized adapter response.
+     *
+     * @param data The data extracted from the response based on the response type.
+     * @param response The original fetch Response object.
+     * @param config The configuration used for the fetch request.
+     * @returns A RequestAdapterResponse containing the processed response data.
+     */
+    toAdapterResponse<Request>(data: unknown, response: Response, config: RequestAdapterFetchConfig<Request>): RequestAdapterResponse<Request>;
+    /**
+     * Extracts headers from the fetch Response object and returns them as a record.
+     *
+     * @param response The fetch Response object from which headers are extracted.
+     * @returns A record of headers with header names as keys and header values as values.
+     */
+    getResponseHeaders(response: Response): Record<string, string>;
+}
+
+/**
+ * Axios request adapter
+ *
+ * Only base config is supported
+ *
+ * @since 1.0.14
+ */
+declare class RequestAdapterAxios implements RequestAdapterInterface<AxiosRequestConfig> {
+    readonly config: AxiosRequestConfig;
+    private axiosInstance;
+    constructor(axios: AxiosStatic, config?: AxiosRequestConfig);
+    getConfig(): AxiosRequestConfig;
+    request<Request, Response>(config: AxiosRequestConfig<Request>): Promise<RequestAdapterResponse<Request, Response>>;
+}
+
+/**
+ * Plugin for handling request cancellation
+ * Provides abort functionality for fetch requests
+ *
+ * - Core Idea: Enhance request management with cancellation capabilities.
+ * - Main Function: Allow requests to be aborted programmatically.
+ * - Main Purpose: Improve control over network requests and resource management.
+ *
+ * Features:
+ * - Request cancellation support
+ * - Automatic cleanup of aborted requests
+ * - Multiple concurrent request handling
+ * - Custom abort callbacks
+ *
+ * **Not Support**
+ * - Abort signal from outside
+ *
+ * Request parameters serialized to be used as unique identifiers.
+ * Or you can pass in a specific requestid.
+ *
+ * You can also manually specify an onAbort callback that will be executed after termination.
+ *
+ * @implements {ExecutorPlugin}
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const abortPlugin = new AbortPlugin();
+ * const client = new FetchRequest();
+ * client.executor.use(abortPlugin);
+ *
+ * // Abort specific request
+ * const config = { url: '/api/data' };
+ * abortPlugin.abort(config);
+ *
+ * // Abort all pending requests
+ * abortPlugin.abortAll();
+ * ```
+ *
+ * @example
+ *
+ * Use RequestId to identify the request
+ *
+ * ```typescript
+ * const abortPlugin = new AbortPlugin();
+ * const client = new FetchRequest();
+ * client.executor.use(abortPlugin);
+ *
+ * // Abort specific request
+ * const config = { url: '/api/data', requestId: '123' };
+ * abortPlugin.abort(config);
+ * // or
+ * abortPlugin.abort('123');
+ * ```
+ */
+declare class FetchAbortPlugin implements ExecutorPlugin {
+    readonly pluginName = "FetchAbortPlugin";
+    readonly onlyOne = true;
+    /**
+     * Map to store active AbortControllers
+     * Keys are generated from request config
+     */
+    private controllers;
+    /**
+     * Generates unique key for request identification
+     * Combines method, URL, params, and body to create unique identifier
+     *
+     * @param config - Request configuration
+     * @returns Unique request identifier
+     *
+     * @example
+     * ```typescript
+     * const key = abortPlugin.generateRequestKey(config);
+     * ```
+     */
+    private generateRequestKey;
+    /**
+     * Pre-request hook that sets up abort handling
+     * Creates new AbortController and cancels any existing request with same key
+     *
+     * @param config - Request configuration
+     * @returns Modified configuration with abort control
+     *
+     * @example
+     * ```typescript
+     * const modifiedConfig = abortPlugin.onBefore(config);
+     * ```
+     */
+    onBefore(context: ExecutorContext<RequestAdapterConfig>): void;
+    onSuccess({ parameters }: ExecutorContext<RequestAdapterConfig>): void;
+    /**
+     * Error handling hook for abort scenarios
+     * Processes different types of abort errors and cleans up resources
+     *
+     * @param error - Original error
+     * @param config - Request configuration
+     * @returns RequestError or void
+     *
+     * @example
+     * ```typescript
+     * const error = abortPlugin.onError(new Error('AbortError'), config);
+     * ```
+     */
+    onError({ error, parameters }: ExecutorContext<RequestAdapterConfig>): RequestError | void;
+    /**
+     * Determines if the given error is an abort error.
+     *
+     * - Identify errors that are related to request abortion.
+     * - Check error properties to determine if it's an abort error.
+     * - Provide a unified method to recognize abort errors.
+     *
+     * @param error - The error to check
+     * @returns True if the error is an abort error, false otherwise
+     *
+     */
+    isSameAbortError(error?: Error): boolean;
+    /**
+     * Aborts a specific request
+     * Triggers abort callback if provided
+     *
+     * @param config - Configuration of request to abort
+     *
+     * @example
+     * ```typescript
+     * abortPlugin.abort({
+     *   url: '/api/data',
+     *   onAbort: (config) => {
+     *     console.log('Request aborted:', config.url);
+     *   }
+     * });
+     * ```
+     */
+    abort(config: RequestAdapterConfig | string): void;
+    /**
+     * Aborts all pending requests
+     * Clears all stored controllers
+     *
+     * @example
+     * ```typescript
+     * // Cancel all requests when component unmounts
+     * useEffect(() => {
+     *   return () => abortPlugin.abortAll();
+     * }, []);
+     * ```
+     */
+    abortAll(): void;
+}
+
+/**
+ * Plugin for URL manipulation and response handling
+ * Provides URL composition and response status checking
+ *
+ * - Core Idea: Simplify URL handling and response validation.
+ * - Main Function: Manage URL construction and check response status.
+ * - Main Purpose: Ensure correct URL formation and response handling.
+ *
+ * Features:
+ * - URL normalization
+ * - Base URL handling
+ * - Query parameter management
+ * - Response status validation
+ *
+ * @implements {ExecutorPlugin}
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const urlPlugin = new FetchURLPlugin();
+ * const client = new FetchRequest();
+ * client.executor.use(urlPlugin);
+ *
+ * // Request with base URL and params
+ * await client.get({
+ *   baseURL: 'https://api.example.com',
+ *   url: '/users',
+ *   params: { role: 'admin' }
+ * });
+ * ```
+ */
+declare class FetchURLPlugin implements ExecutorPlugin {
+    readonly pluginName = "FetchURLPlugin";
+    /**
+     * Checks if URL is absolute (starts with http:// or https://)
+     *
+     * @param url - URL to check
+     * @returns Boolean indicating if URL is absolute
+     *
+     * @example
+     * ```typescript
+     * const isAbsolute = urlPlugin.isFullURL('https://example.com');
+     * ```
+     */
+    isFullURL(url: string): boolean;
+    /**
+     * Appends query parameters to URL
+     * Handles existing query parameters in URL
+     *
+     * @param url - Base URL
+     * @param params - Parameters to append
+     * @returns URL with query parameters
+     *
+     * @example
+     * ```typescript
+     * const url = urlPlugin.appendQueryParams(
+     *   'https://api.example.com/users',
+     *   { role: 'admin', status: 'active' }
+     * );
+     * ```
+     */
+    appendQueryParams(url: string, params?: Record<string, unknown>): string;
+    /**
+     * Combines base URL with path.
+     *
+     * Ensures proper slash handling
+     *
+     * @param url - URL path
+     * @param baseURL - Base URL
+     * @returns Combined URL
+     *
+     * @example
+     * ```typescript
+     * const fullUrl = urlPlugin.connectBaseURL('/users', 'https://api.example.com');
+     * ```
+     */
+    connectBaseURL(url: string, baseURL: string): string;
+    /**
+     * Builds complete URL from configuration.
+     *
+     * Handles base URL, path normalization, and query parameters.
+     *
+     * @param config - Request configuration
+     * @returns Complete URL
+     *
+     * @example
+     * ```typescript
+     * const completeUrl = urlPlugin.buildUrl(config);
+     * ```
+     */
+    buildUrl(config: RequestAdapterConfig): string;
+    /**
+     * Pre-request hook that builds complete URL
+     *
+     * @param config - Request configuration
+     *
+     * @example
+     * ```typescript
+     * urlPlugin.onBefore(config);
+     * ```
+     */
+    onBefore({ parameters }: ExecutorContext<RequestAdapterConfig>): void;
+    /**
+     * Success hook that validates response status
+     * Throws error for non-OK responses
+     *
+     * @param result - Fetch response
+     * @returns Response if OK
+     * @throws {RequestError} If response is not OK
+     *
+     * @example
+     * ```typescript
+     * const response = urlPlugin.onSuccess(fetchResponse);
+     * ```
+     */
+    onSuccess({ returnValue }: ExecutorContext): void;
+    /**
+     * Error handling hook
+     * Wraps non-RequestError errors
+     *
+     * @param error - Original error
+     * @returns RequestError
+     *
+     * @example
+     * ```typescript
+     * const error = urlPlugin.onError(new Error('Network Error'));
+     * ```
+     */
+    onError({ error }: ExecutorContext): RequestError;
+}
+
+/**
+ * Represents a scheduler for managing HTTP requests.
+ *
+ * This class provides a unified API for making HTTP requests with support for plugins,
+ * streaming responses, and request cancellation. Future enhancements may include caching,
+ * upload/download progress, retries, timeouts, and mock data.
+ *
+ * @since 1.0.14
+ * @example
+ *
+ * Create a Adapter
+ *
+ * ```typescript
+ * class MockRequestAdapter implements RequestAdapterInterface<any> {
+ * config: any;
+ *
+ * constructor(config: any = {}) {
+ *   this.config = config;
+ * }
+ *
+ * getConfig(): any {
+ *   return this.config;
+ * }
+ * async request<Request, Response>(
+ *   config: any
+ * ): Promise<RequestAdapterResponse<Response, Request>> {
+ *   const sendConfig = { ...this.config, ...config };
+ *   await new Promise((resolve) => setTimeout(resolve, 1000));
+ *
+ *   return {
+ *     status: 200,
+ *     statusText: 'ok',
+ *     headers: {},
+ *     data: sendConfig.data,
+ *     config: sendConfig
+ *   };
+ * }
+ *
+ * ```
+ *
+ * @example
+ *
+ * Execute a request using the adapter
+ *
+ * ```typescript
+ * const adapter = new MockRequestAdapter();
+ * const scheduler = new RequestScheduler();
+ * const reqData = 'mock response';
+ * const response = await scheduler.request({ url: '/test', data: reqData });
+ * // => response.data is 'mock response'
+ * ```
+ *
+ * @template Config - The configuration type extending RequestAdapterConfig.
+ */
+declare class RequestScheduler<Config extends RequestAdapterConfig> {
+    readonly adapter: RequestAdapterInterface<Config>;
+    readonly executor: AsyncExecutor;
+    /**
+     * Initializes a new instance of the RequestScheduler class.
+     *
+     * @since 1.0.14
+     *
+     * @param adapter - The request adapter interface to be used for making requests.
+     */
+    constructor(adapter: RequestAdapterInterface<Config>);
+    /**
+     * Adds a plugin to the request execution process.
+     *
+     * @since 1.0.14
+     *
+     * @param plugin - The plugin to be used by the executor.
+     * @returns The current instance of RequestScheduler for chaining.
+     */
+    usePlugin(plugin: ExecutorPlugin): this;
+    /**
+     * Executes a request with the given configuration.
+     *
+     * @since 1.0.14
+     *
+     * @param config - The configuration for the request.
+     * @returns A promise that resolves to the response of the request.
+     */
+    request<Request, Response>(config: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a GET request.
+     *
+     * @param config - The configuration for the GET request.
+     * @returns A promise that resolves to the response of the GET request.
+     */
+    get<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a POST request.
+     *
+     * @param config - The configuration for the POST request.
+     * @returns A promise that resolves to the response of the POST request.
+     */
+    post<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a PUT request.
+     *
+     * @param config - The configuration for the PUT request.
+     * @returns A promise that resolves to the response of the PUT request.
+     */
+    put<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a DELETE request.
+     *
+     * @param config - The configuration for the DELETE request.
+     * @returns A promise that resolves to the response of the DELETE request.
+     */
+    delete<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a PATCH request.
+     *
+     * @param config - The configuration for the PATCH request.
+     * @returns A promise that resolves to the response of the PATCH request.
+     */
+    patch<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a HEAD request.
+     *
+     * @param config - The configuration for the HEAD request.
+     * @returns A promise that resolves to the response of the HEAD request.
+     */
+    head<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes an OPTIONS request.
+     *
+     * @param config - The configuration for the OPTIONS request.
+     * @returns A promise that resolves to the response of the OPTIONS request.
+     */
+    options<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a TRACE request.
+     *
+     * @param config - The configuration for the TRACE request.
+     * @returns A promise that resolves to the response of the TRACE request.
+     */
+    trace<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+    /**
+     * Executes a CONNECT request.
+     *
+     * @param config - The configuration for the CONNECT request.
+     * @returns A promise that resolves to the response of the CONNECT request.
+     */
+    connect<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
+}
+
+/**
+ * Enhanced JSON serialization implementation that combines standard JSON API with additional features
+ *
+ * Why implement both Serializer and JSON interfaces:
+ * 1. Serializer interface provides a consistent API across different serialization formats
+ * 2. JSON interface maintains compatibility with native JSON methods
+ * 3. Allows seamless integration with both existing JSON code and new serialization patterns
+ *
+ * Enhanced capabilities beyond standard JSON:
+ * 1. Cross-platform line ending normalization (\r\n -> \n)
+ * 2. Built-in pretty printing configuration
+ * 3. Default value support for failed deserialization
+ * 4. Circular reference detection with clear error messages
+ * 5. Type-safe interface with better TypeScript support
+ *
+ * Usage scenarios:
+ * 1. Direct replacement for JSON global object
+ * 2. Part of a pluggable serialization system
+ * 3. Configuration file parsing with error handling
+ * 4. Cross-platform data exchange
+ *
+ * @implements {Serializer<unknown, string>} - Generic serialization interface
+ * @implements {JSON} - Standard JSON interface compatibility
+ * @todo - If circular reference is detected, the error message is not very friendly, can use [flatted](https://www.npmjs.com/package/flatted) to improve it
+ * @since 1.0.10
+ *
+ * @example
+ * ```typescript
+ * const serializer = new JSONSerializer({ pretty: true });
+ *
+ * // Using Serializer interface (with enhanced features)
+ * const serialized = serializer.serialize({ name: "test" });
+ * const deserialized = serializer.deserialize('invalid json', { fallback: true });
+ *
+ * // Using standard JSON API (maintains compatibility)
+ * const json = serializer.stringify({ name: "test" });
+ * const obj = serializer.parse(json);
+ * ```
+ *
+ * @example
+ *
+ * `JSON.parse` may encounter errors, so we use `deserialize` method to handle them, set default value if needed
+ *
+ * ```typescript
+ * const serializer = new JSONSerializer();
+ * serializer.deserialize('invalid json', { fallback: true }); // returns { fallback: true }
+ * ```
+ *
+ * @example
+ * Or, use `JSONSerializer` replace native `JSON` methods
+ *
+ * ```typescript
+ * const JSON = new JSONSerializer();
+ *
+ * JSON.stringify({ name: 'test' }); // same as JSON.stringify({ name: 'test' })
+ * JSON.parse('{ "name": "test" }'); // same as JSON.parse('{ "name": "test" }')
+ * ```
+ */
+declare class JSONSerializer implements Serializer<unknown, string>, JSON {
+    private options;
+    /**
+     * Implements Symbol.toStringTag to properly identify this class
+     * Required by JSON interface
+     */
+    readonly [Symbol.toStringTag] = "JSONSerializer";
+    constructor(options?: {
+        /**
+         * Enable pretty printing of JSON output
+         * Adds automatic indentation and line breaks for better readability
+         *
+         * @since 1.0.10
+         * @default false
+         */
+        pretty?: boolean;
+        /**
+         * Number of spaces to use for indentation when pretty printing
+         * Only used when pretty is true
+         *
+         * @since 1.0.10
+         * @default 2
+         */
+        indent?: number;
+        /**
+         * Custom replacer function for JSON.stringify
+         * Allows custom transformation during serialization
+         * Note: Will be wrapped to handle line endings
+         *
+         * @since 1.0.10
+         */
+        replacer?: (this: unknown, key: string, value: unknown) => unknown;
+    });
+    /**
+     * Creates a replacer function that handles line endings normalization
+     *
+     * Why normalize line endings:
+     * 1. Ensures consistent output across different platforms (Windows, Unix)
+     * 2. Prevents issues with source control systems
+     * 3. Makes string comparisons reliable
+     *
+     * Handles three cases:
+     * 1. Array replacer - Used for property filtering
+     * 2. Function replacer - Wrapped to handle line endings
+     * 3. Null/undefined - Creates default line ending handler
+     *
+     * @private
+     * @param replacer - Custom replacer function or array of properties to include
+     * @returns Replacer function or array of properties to include
+     * @since 1.0.10
+     */
+    private createReplacer;
+    /**
+     * Enhanced JSON.stringify with additional features
+     *
+     * Enhancements:
+     * 1. Line ending normalization
+     * 2. Configurable pretty printing
+     * 3. Better error messages for circular references
+     * 4. Type-safe replacer handling
+     *
+     * **If circular reference is detected, the error message is not very friendly, can use [flatted](https://www.npmjs.com/package/flatted) to improve it**
+     *
+     * @since 1.0.10
+     * @override
+     * @returns Serialized string
+     */
+    stringify(value: unknown, replacer?: ((this: unknown, key: string, value: unknown) => unknown) | (number | string)[] | null, space?: string | number): string;
+    /**
+     * Standard JSON.parse implementation
+     * Note: Error handling is done in deserialize method
+     *
+     * @since 1.0.10
+     * @override
+     * @returns Parsed value
+     */
+    parse(text: string, reviver?: (this: unknown, key: string, value: unknown) => unknown): unknown;
+    /**
+     * Implements Serializer.serialize
+     * Provides a simplified interface with configured options
+     *
+     * Benefits:
+     * 1. Uses configured pretty printing
+     * 2. Applies custom replacer if specified
+     * 3. Maintains consistent line endings
+     *
+     * @override
+     * @since 1.0.10
+     * @returns Serialized string
+     */
+    serialize(data: unknown): string;
+    /**
+     * Implements Serializer.deserialize with enhanced error handling
+     *
+     * Benefits:
+     * 1. Safe parsing with default value fallback
+     * 2. No try-catch needed in calling code
+     * 3. Predictable error handling
+     *
+     * @override
+     * @since 1.0.10
+     * @returns Parsed value
+     */
+    deserialize(data: string, defaultValue?: unknown): unknown;
+    /**
+     * Optimized serialization for arrays of primitive values
+     * Avoids object property enumeration
+     *
+     * @param arr - Array of primitive values to serialize
+     * @returns JSON array string
+     * @since 1.0.10
+     */
+    serializeArray(arr: (string | number | boolean)[]): string;
+}
+
+/**
+ * Base64 serialization implementation
+ * Provides string-to-base64 encoding/decoding with optional compression
+ *
+ * Features:
+ * - Base64 encoding/decoding
+ * - UTF-8 support
+ * - URL-safe encoding option
+ *
+ * @implements {Serializer<string, string>}
+ *
+ * @since 1.0.10
+ *
+ * @example
+ * ```typescript
+ * const serializer = new Base64Serializer({ urlSafe: true });
+ *
+ * // Encode string to base64
+ * const encoded = serializer.stringify("Hello World!");
+ *
+ * // Decode base64 back to string
+ * const decoded = serializer.parse(encoded);
+ * ```
+ */
+declare class Base64Serializer implements Serializer<string, string> {
+    private options;
+    constructor(options?: {
+        /**
+         * Use URL-safe base64 encoding
+         * @default false
+         *
+         * @since 1.0.10
+         */
+        urlSafe?: boolean;
+    });
+    /**
+     * Serializes string to base64
+     * @override
+     * @since 1.0.10
+     * @param data - String to encode
+     * @returns Base64 encoded string
+     */
+    serialize(data: string): string;
+    /**
+     * Deserializes base64 string back to original
+     * @override
+     * @since 1.0.10
+     * @param data - Base64 string to decode
+     * @param defaultValue - Optional default value if decoding fails
+     * @returns Decoded string
+     */
+    deserialize(data: string, defaultValue?: string): string;
+    /**
+     * Converts standard base64 to URL-safe base64
+     * @since 1.0.10
+     * @param base64 - Standard base64 string
+     * @returns URL-safe base64 string
+     */
+    private makeUrlSafe;
+    /**
+     * Converts URL-safe base64 back to standard base64
+     * @private
+     * @since 1.0.10
+     * @param safe - URL-safe base64 string
+     * @returns Standard base64 string
+     */
+    private makeUrlUnsafe;
+}
+
+/**
+ * Represents a storage mechanism for JSON-serializable data.
+ *
+ * This class provides a way to store, retrieve, and manage JSON data
+ * with optional expiration times. It can operate with a provided
+ * synchronous storage backend or use an internal store.
+ *
+ * The main purpose of this class is to facilitate the storage of
+ * complex data structures in a serialized JSON format, allowing
+ * for easy retrieval and management.
+ *
+ * inner serializer is used by default, which is `JSONSerializer`.
+ *
+ * @since 1.0.17
+ *
+ * @example
+ *
+ * A simple example of how to use the JSONStorage class
+ *
+ * ```typescript
+ * const storage = new JSONStorage();
+ * storage.setItem('key', { data: 'value' }, 3600);
+ * const value = storage.getItem('key');
+ * // => { data: 'value' }
+ * ```
+ * @example
+ *
+ * If need persistent storage, you can use `localStorage` or `sessionStorage`
+ *
+ * ```typescript
+ * const storage = new JSONStorage(localStorage);
+ * storage.setItem('key', { data: 'value' }, 3600);
+ * const value = storage.getItem('key');
+ * // => { data: 'value' }
+ * ```
+ *
+ * @example
+ *
+ * Or use custom serializer and storage
+ *
+ * ```typescript
+ * // use native JSON
+ * const customSerializer = {
+ *   serialize: JSON.stringify,
+ *   deserialize: JSON.parse,
+ * };
+ *
+ * // can use localStorage or sessionStorage
+ * const customStorage = {
+ *   setItem: (key: string, value: string) => {
+ *     localStorage.setItem(key, value);
+ *   },
+ *   getItem: (key: string) => {
+ *     return localStorage.getItem(key);
+ *   },
+ *   removeItem: (key: string) => {
+ *     localStorage.removeItem(key);
+ *   },
+ *   clear: () => {
+ *     localStorage.clear();
+ *   },
+ * };
+ *
+ * const storage = new JSONStorage(customStorage, customSerializer);
+ * storage.setItem('key', { data: 'value' }, 3600);
+ * const value = storage.getItem('key');
+ * ```
+ *
+ */
+declare class JSONStorage implements SyncStorage<string> {
+    /**
+     * The storage backend to use.
+     */
+    private readonly storage?;
+    /**
+     * The serializer used to serialize and deserialize the data.
+     *
+     * **serializer and deserialize is only support sync operation**
+     */
+    private readonly serializer;
+    /**
+     * The internal store for the JSONStorage class.
+     *
+     * If `storage` is not provided, it is stored in memory by default.
+     */
+    private store;
+    /**
+     * Initializes a new instance of the JSONStorage class.
+     *
+     * @param storage - An optional synchronous storage backend to use.
+     */
+    constructor(
+    /**
+     * The storage backend to use.
+     */
+    storage?: SyncStorage<string, string> | undefined, 
+    /**
+     * The serializer used to serialize and deserialize the data.
+     *
+     * **serializer and deserialize is only support sync operation**
+     */
+    serializer?: Serializer<unknown, string>);
+    /**
+     * Gets the number of items stored in the local storage.
+     *
+     * @returns The number of stored items.
+     */
+    get length(): number;
+    /**
+     * Stores a value with an optional expiration time.
+     *
+     * @param key - The key under which the value is stored.
+     * @param value - The value to store, which must be JSON-serializable.
+     * @param expire - Optional expiration time in milliseconds.
+     */
+    setItem<T>(key: string, value: T, expire?: number): void;
+    /**
+     * Retrieves a stored value by its key.
+     *
+     * @param key - The key of the value to retrieve.
+     * @param defaultValue - An optional default value to return if the key is not found.
+     * @returns The stored value or the default value if the key is not found or expired.
+     */
+    getItem<T>(key: string, defaultValue?: T): T | null;
+    /**
+     * Removes a stored item by its key.
+     *
+     * @param key - The key of the item to remove.
+     */
+    removeItem(key: string): void;
+    /**
+     * Clears all stored items.
+     */
+    clear(): void;
+}
+
+export { AsyncExecutor, Base64Serializer, Executor, ExecutorError, FetchAbortPlugin, FetchURLPlugin, JSONSerializer, JSONStorage, LEVELS, Logger, RequestAdapterAxios, RequestAdapterFetch, RequestError, RequestErrorID, RequestScheduler, RetryPlugin, SyncExecutor };
+export type { AsyncStorage, Encryptor, ExecOptions, ExecutorContext, ExecutorPlugin, HookRuntimes, Intersection, LogArgument, LogLevel, PromiseTask, RequestAdapterConfig, RequestAdapterFetchConfig, RequestAdapterInterface, RequestAdapterResponse, RetryOptions, Serializer, SyncStorage, SyncTask, Task, ValueOf };