@qlover/fe-corekit 2.2.0 → 2.3.1

package/dist/index.d.ts

@@ -2476,6 +2476,7 @@ declare class AbortPlugin<TParameters> implements ExecutorPlugin {
      * 5. Sets up timeout timer if `abortTimeout` configured
      * 6. Injects abort signal into configuration
      *
+     * @override
      * @param context - Executor context containing parameters and metadata
      *
      * @example Configuration in context
@@ -2494,6 +2495,7 @@ declare class AbortPlugin<TParameters> implements ExecutorPlugin {
      * Cleans up resources (controller and timeout) for completed operation
      * Ensures no memory leaks from successful operations
      *
+     * @override
      * @param context - Executor context containing parameters and metadata
      *
      * @example
@@ -2514,6 +2516,7 @@ declare class AbortPlugin<TParameters> implements ExecutorPlugin {
      * 2. If abort error: Extract reason from signal, cleanup resources, return `AbortError`
      * 3. If other error: Still cleanup resources to prevent leaks
      *
+     * @override
      * @param context - Executor context containing error, parameters, and metadata
      * @returns `AbortError` if error is abort-related, `void` otherwise
      *
@@ -2810,6 +2813,7 @@ declare class RetryPlugin implements ExecutorPlugin {
      * This method intercepts task execution to add retry capability,
      * executing the task with the configured retry logic.
      *
+     * @override
      * @template T - Type of task return value
      * @param task - Task to be executed with retry support
      * @returns Promise resolving to task result
@@ -3140,6 +3144,9 @@ declare class RequestAdapterFetch implements RequestAdapterInterface<RequestAdap
      * ```
      */
     constructor(config?: Partial<RequestAdapterFetchConfig>);
+    /**
+     * @override
+     */
     getConfig(): RequestAdapterFetchConfig;
     usePlugin(plugin: ExecutorPlugin): void;
     /**
@@ -3191,7 +3198,13 @@ declare class RequestAdapterAxios implements RequestAdapterInterface<AxiosReques
     readonly config: AxiosRequestConfig;
     private axiosInstance;
     constructor(axios: AxiosStatic, config?: AxiosRequestConfig);
+    /**
+     * @override
+     */
     getConfig(): AxiosRequestConfig;
+    /**
+     * @override
+     */
     request<Request, Response>(config: AxiosRequestConfig<Request>): Promise<RequestAdapterResponse<Request, Response>>;
 }
 
@@ -3275,6 +3288,7 @@ declare class FetchAbortPlugin implements ExecutorPlugin {
      * Pre-request hook that sets up abort handling
      * Creates new AbortController and cancels any existing request with same key
      *
+     * @override
      * @param config - Request configuration
      * @returns Modified configuration with abort control
      *
@@ -3284,11 +3298,15 @@ declare class FetchAbortPlugin implements ExecutorPlugin {
      * ```
      */
     onBefore(context: ExecutorContext<RequestAdapterConfig>): void;
+    /**
+     * @override
+     */
     onSuccess({ parameters }: ExecutorContext<RequestAdapterConfig>): void;
     /**
      * Error handling hook for abort scenarios
      * Processes different types of abort errors and cleans up resources
      *
+     * @override
      * @param error - Original error
      * @param config - Request configuration
      * @returns RequestError or void
@@ -3437,6 +3455,7 @@ declare class FetchURLPlugin implements ExecutorPlugin {
     /**
      * Pre-request hook that builds complete URL
      *
+     * @override
      * @param config - Request configuration
      *
      * @example
@@ -3449,6 +3468,7 @@ declare class FetchURLPlugin implements ExecutorPlugin {
      * Success hook that validates response status
      * Throws error for non-OK responses
      *
+     * @override
      * @param result - Fetch response
      * @returns Response if OK
      * @throws {RequestError} If response is not OK
@@ -3463,6 +3483,7 @@ declare class FetchURLPlugin implements ExecutorPlugin {
      * Error handling hook
      * Wraps non-RequestError errors
      *
+     * @override
      * @param error - Original error
      * @returns RequestError
      *
@@ -3806,6 +3827,7 @@ declare class RequestScheduler<Config extends RequestAdapterConfig> extends Requ
 declare class RequestTransaction<Config extends RequestAdapterConfig<unknown>> extends RequestManager<Config> {
     /**
      * Makes an HTTP request with flexible type definitions
+     * @override
      * @template Transaction - Can be either the direct response data type or a RequestTransactionInterface
      * @param config - Request configuration object
      * @returns Promise of response data
@@ -4246,6 +4268,296 @@ interface ExpireOptions {
     expires?: unknown;
 }
 
+/**
+ * Key-value storage interface for managing a single value with persistence support
+ *
+ * Core concept:
+ * Provides a unified interface for storing and retrieving a single value associated
+ * with a specific key. Supports both in-memory and persistent storage backends,
+ * enabling flexible storage strategies for different use cases.
+ *
+ * **v2.3.0 before this was an abstract class, now it is an interface**
+ *
+ * Main features:
+ * - Single value storage: Store one value per key instance
+ * - Key management: Retrieve the storage key associated with this instance
+ * - Value retrieval: Get stored value from memory or persistent storage
+ * - Value persistence: Save value to underlying storage backend
+ * - Value removal: Clear value from both memory and persistent storage
+ * - Options support: Flexible options parameter for storage-specific configurations
+ *
+ * Typical usage scenarios:
+ * - Token storage: Store authentication tokens with persistence
+ * - User info storage: Persist user information across sessions
+ * - Configuration storage: Store application settings (theme, language, etc.)
+ * - Session data: Manage temporary session-specific data
+ *
+ * Design decisions:
+ * - Returns `null` when value is not found (explicit null handling)
+ * - Options parameter is optional to support simple use cases
+ * - Generic types allow type-safe storage of any value type
+ * - Supports both synchronous and asynchronous storage backends through options
+ *
+ * @template Key - The type of the storage key (e.g., `string`, `number`, `symbol`)
+ * @template Value - The type of value to store
+ * @template Opt - The type of options for storage operations (defaults to `unknown`)
+ *
+ * @example Basic usage with localStorage
+ * ```typescript
+ * const tokenStorage: KeyStorageInterface<string, string> = new KeyStorage('token', {
+ *   storage: localStorage
+ * });
+ *
+ * // Store token
+ * tokenStorage.set('abc123token');
+ *
+ * // Retrieve token
+ * const token = tokenStorage.get(); // Returns 'abc123token'
+ *
+ * // Get storage key
+ * const key = tokenStorage.getKey(); // Returns 'token'
+ *
+ * // Remove token
+ * tokenStorage.remove();
+ * ```
+ *
+ * @example User information storage
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const userStorage: KeyStorageInterface<string, User> = new KeyStorage('user', {
+ *   storage: localStorage
+ * });
+ *
+ * const user: User = {
+ *   id: '123',
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * };
+ *
+ * userStorage.set(user);
+ * const storedUser = userStorage.get(); // Returns User object
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * interface StorageOptions {
+ *   encrypt?: boolean;
+ *   expires?: number;
+ * }
+ *
+ * const secureStorage: KeyStorageInterface<string, string, StorageOptions> =
+ *   new KeyStorage('secret', {
+ *     storage: localStorage,
+ *     encrypt: true
+ *   });
+ *
+ * secureStorage.set('sensitive-data', { encrypt: true, expires: 3600 });
+ * ```
+ */
+interface KeyStorageInterface<Key, Value, Opt = unknown> {
+    /**
+     * Get the storage key associated with this instance
+     *
+     * Returns the key that was used to initialize this storage instance.
+     * This key is used to identify the storage location in the underlying
+     * storage backend.
+     *
+     * @returns The storage key of type `Key`
+     *
+     * @example
+     * ```typescript
+     * const storage = new KeyStorage('my-key', { storage: localStorage });
+     * const key = storage.getKey(); // Returns 'my-key'
+     * ```
+     */
+    getKey(): Key;
+    /**
+     * Get the current in-memory value without accessing persistent storage
+     *
+     * Returns the value currently stored in memory. This method does not
+     * attempt to load from persistent storage. Use `get()` if you want
+     * to retrieve from persistent storage when memory value is null.
+     *
+     * Returns `null` if:
+     * - No value has been set yet
+     * - Value was removed via `remove()`
+     * - Value was never loaded from storage
+     *
+     * @returns The current in-memory value, or `null` if not available
+     *
+     * @example
+     * ```typescript
+     * const storage = new KeyStorage('token', { storage: localStorage });
+     *
+     * // Initially null (not loaded from storage yet)
+     * const memValue = storage.getValue(); // Returns null
+     *
+     * // After setting
+     * storage.set('abc123');
+     * const memValue2 = storage.getValue(); // Returns 'abc123'
+     *
+     * // After removal
+     * storage.remove();
+     * const memValue3 = storage.getValue(); // Returns null
+     * ```
+     */
+    getValue(): Value | null;
+    /**
+     * Retrieve value from storage with optional configuration
+     *
+     * Retrieval strategy:
+     * 1. First checks in-memory value (fast path)
+     * 2. If memory value is null and persistent storage is available,
+     *    loads from persistent storage and updates memory cache
+     * 3. Returns null if value doesn't exist in either location
+     *
+     * The `options` parameter allows passing storage-specific configuration
+     * that may override default behavior (e.g., encryption settings, expiration checks).
+     *
+     * @param options - Optional storage operation configuration
+     * @returns The stored value, or `null` if not found
+     *
+     * @example Basic retrieval
+     * ```typescript
+     * const storage = new KeyStorage('token', { storage: localStorage });
+     * storage.set('abc123');
+     * const token = storage.get(); // Returns 'abc123'
+     * ```
+     *
+     * @example With options
+     * ```typescript
+     * interface Options {
+     *   decrypt?: boolean;
+     * }
+     *
+     * const storage = new KeyStorage<string, string, Options>('secret', {
+     *   storage: localStorage
+     * });
+     *
+     * // Retrieve with decryption
+     * const value = storage.get({ decrypt: true });
+     * ```
+     *
+     * @example Handling null values
+     * ```typescript
+     * const storage = new KeyStorage('data', { storage: localStorage });
+     * const value = storage.get();
+     *
+     * if (value === null) {
+     *   console.log('No value stored');
+     * } else {
+     *   console.log('Value:', value);
+     * }
+     * ```
+     */
+    get(options?: Opt): Value | null;
+    /**
+     * Store a value with optional configuration
+     *
+     * Storage behavior:
+     * - Updates in-memory value immediately
+     * - Persists to underlying storage backend if available
+     * - Merges provided options with default options
+     * - Overwrites any existing value for this key
+     *
+     * The `options` parameter can be used to pass storage-specific settings
+     * such as encryption, expiration, or other backend-specific configurations.
+     *
+     * @param value - The value to store (can be any type matching `Value`)
+     * @param options - Optional storage operation configuration
+     *
+     * @example Basic storage
+     * ```typescript
+     * const storage = new KeyStorage('token', { storage: localStorage });
+     * storage.set('abc123token');
+     * ```
+     *
+     * @example Storing complex objects
+     * ```typescript
+     * interface User {
+     *   id: string;
+     *   name: string;
+     * }
+     *
+     * const storage = new KeyStorage<string, User>('user', {
+     *   storage: localStorage
+     * });
+     *
+     * storage.set({
+     *   id: '123',
+     *   name: 'John Doe'
+     * });
+     * ```
+     *
+     * @example With encryption options
+     * ```typescript
+     * interface Options {
+     *   encrypt?: boolean;
+     *   expires?: number;
+     * }
+     *
+     * const storage = new KeyStorage<string, string, Options>('secret', {
+     *   storage: localStorage
+     * });
+     *
+     * storage.set('sensitive-data', {
+     *   encrypt: true,
+     *   expires: Date.now() + 3600000 // 1 hour
+     * });
+     * ```
+     */
+    set(value: Value, options?: Opt): void;
+    /**
+     * Remove the stored value from both memory and persistent storage
+     *
+     * Removal behavior:
+     * - Clears in-memory value (sets to `null`)
+     * - Removes value from persistent storage backend if available
+     * - Applies any options-specific removal behavior
+     *
+     * After calling `remove()`, subsequent calls to `get()` will return `null`
+     * until a new value is set via `set()`.
+     *
+     * @param options - Optional storage operation configuration
+     *
+     * @example Basic removal
+     * ```typescript
+     * const storage = new KeyStorage('token', { storage: localStorage });
+     * storage.set('abc123');
+     * storage.remove(); // Removes from both memory and localStorage
+     * const token = storage.get(); // Returns null
+     * ```
+     *
+     * @example With options
+     * ```typescript
+     * interface Options {
+     *   softDelete?: boolean;
+     * }
+     *
+     * const storage = new KeyStorage<string, string, Options>('data', {
+     *   storage: localStorage
+     * });
+     *
+     * // Remove with soft delete option
+     * storage.remove({ softDelete: true });
+     * ```
+     *
+     * @example Clearing user session
+     * ```typescript
+     * const userStorage = new KeyStorage('user', { storage: localStorage });
+     *
+     * // User logs out
+     * userStorage.remove();
+     * ```
+     */
+    remove(options?: Opt): void;
+}
+
 /**
  * Interface representing a synchronous storage mechanism.
  *
@@ -4309,18 +4621,6 @@ interface KeyStorageOptions<Key, Sopt = unknown> extends ExpireOptions {
      */
     storage?: SyncStorageInterface<Key, Sopt>;
 }
-declare abstract class KeyStorageInterface<Key, Value, Opt extends KeyStorageOptions<Key> = KeyStorageOptions<Key>> {
-    readonly key: Key;
-    protected options: Opt;
-    protected value: Value | null;
-    constructor(key: Key, options?: Opt);
-    getKey(): Key;
-    getValue(): Value | null;
-    abstract get(options?: Opt): Value | null;
-    abstract set(value: Value, options?: Opt): void;
-    abstract remove(options?: Opt): void;
-}
-
 /**
  * KeyStorage is a storage that can be used to store a single value.
  *
@@ -4358,11 +4658,31 @@ declare abstract class KeyStorageInterface<Key, Value, Opt extends KeyStorageOpt
  * tokenStorage.remove(); // remove from localStorage
  * ```
  */
-declare class KeyStorage<Key, Value, Opt extends KeyStorageOptions<Key> = KeyStorageOptions<Key>> extends KeyStorageInterface<Key, Value, Opt> {
+declare class KeyStorage<Key, Value, Opt extends KeyStorageOptions<Key> = KeyStorageOptions<Key>> implements KeyStorageInterface<Key, Value, Opt> {
+    readonly key: Key;
+    protected options: Opt;
     protected value: Value | null;
+    constructor(key: Key, options?: Opt);
     protected mergeOptions(options?: Opt): Opt;
+    /**
+     * @override
+     */
+    getKey(): Key;
+    /**
+     * @override
+     */
+    getValue(): Value | null;
+    /**
+     * @override
+     */
     get(options?: Opt): Value | null;
+    /**
+     * @override
+     */
     set(token: Value, options?: Opt): void;
+    /**
+     * @override
+     */
     remove(options?: Opt): void;
 }
 
@@ -4543,6 +4863,9 @@ declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOp
      * ```
      */
     getItem<T>(key: Key, defaultValue?: T): T | null;
+    /**
+     * @override
+     */
     getRawValue<T>(value: unknown, defaultValue?: T): T | null;
     /**
      * Removes a stored item by its key from both memory and persistent storage
@@ -4678,20 +5001,31 @@ declare class SyncStorage<Key, Opt = unknown> implements SyncStorageInterface<Ke
     constructor(storage: SyncStorageInterface<Key, Opt>, pipes?: PipeArg<Key>[] | PipeArg<Key>);
     /**
      * Get the number of storage items
-     */
+  
+     * @override
+        */
     get length(): number;
+    /**
+     * @override
+     */
     setItem<T>(key: Key, value: T, options?: Opt): void;
+    /**
+     * @override
+     */
     getItem<T>(key: Key, defaultValue?: T, options?: Opt): T | null;
     /**
      * Delete data items, delete from all storage layers
      *
+     * @override
      * @param key - Storage key
      * @param options - Delete options
      */
     removeItem(key: Key, options?: Opt): void;
     /**
      * Clear all data, including storage in the pipeline
-     */
+  
+     * @override
+        */
     clear(): void;
 }
 
@@ -4723,4 +5057,4 @@ type Intersection<T1, T2> = {
     [P in keyof T1 & keyof T2]: T1[P] | T2[P];
 };
 
-export { ABORT_ERROR_ID, type AbortConfigExtractor, AbortError, AbortPlugin, type AbortPluginConfig, type AbortPluginOptions, AsyncExecutor, type AsyncStorageInterface, Base64Serializer, type Encryptor, Executor, type ExecutorConfigInterface, type ExecutorContext, ExecutorError, type ExecutorPlugin, type ExpireOptions, FetchAbortPlugin, FetchURLPlugin, type HookRuntimes, type HookType, type Intersection, JSONSerializer, type JSONSerializerOptions, KeyStorage, KeyStorageInterface, type KeyStorageOptions, ObjectStorage, type ObjectStorageOptions, type PipeArg, type PromiseTask, RequestAdapterAxios, type RequestAdapterConfig, RequestAdapterFetch, type RequestAdapterFetchConfig, type RequestAdapterInterface, type RequestAdapterResponse, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, type RequestTransactionInterface, type RetryOptions, RetryPlugin, type SerializerIneterface, type StorageValue, SyncExecutor, SyncStorage, type SyncStorageInterface, type SyncTask, type Task, type ValueOf };
+export { ABORT_ERROR_ID, type AbortConfigExtractor, AbortError, AbortPlugin, type AbortPluginConfig, type AbortPluginOptions, AsyncExecutor, type AsyncStorageInterface, Base64Serializer, type Encryptor, Executor, type ExecutorConfigInterface, type ExecutorContext, ExecutorError, type ExecutorPlugin, type ExpireOptions, FetchAbortPlugin, FetchURLPlugin, type HookRuntimes, type HookType, type Intersection, JSONSerializer, type JSONSerializerOptions, KeyStorage, type KeyStorageInterface, type KeyStorageOptions, ObjectStorage, type ObjectStorageOptions, type PipeArg, type PromiseTask, RequestAdapterAxios, type RequestAdapterConfig, RequestAdapterFetch, type RequestAdapterFetchConfig, type RequestAdapterInterface, type RequestAdapterResponse, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, type RequestTransactionInterface, type RetryOptions, RetryPlugin, type SerializerIneterface, type StorageValue, SyncExecutor, SyncStorage, type SyncStorageInterface, type SyncTask, type Task, type ValueOf };