@qlover/fe-corekit 3.1.1 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -6957,6 +6957,7 @@ declare class RequestPlugin implements LifecyclePluginInterface<RequestAdapterCo
6957
6957
  * @override
6958
6958
  */
6959
6959
  onBefore(ctx: RequestAdapterContext): void;
6960
+ protected startsWith(url: string, baseUrl: string): boolean;
6960
6961
  /**
6961
6962
  * Main request handler
6962
6963
  *
@@ -8636,493 +8637,274 @@ declare class Base64Serializer implements SerializerIneterface<string, string> {
8636
8637
  }
8637
8638
 
8638
8639
  /**
8639
- * Interface representing an asynchronous storage mechanism.
8640
+ * Asynchronous key-value storage interface.
8640
8641
  *
8641
- * @template Key - The type of keys used to identify stored values.
8642
- * @template ValueType - The type of values stored, defaults to unknown.
8642
+ * Core concept:
8643
+ * Contract for a storage that performs I/O asynchronously. All methods return `Promise`s;
8644
+ * use this when the backend is async (e.g. IndexedDB, remote storage, encrypted async APIs).
8643
8645
  *
8644
- * @example
8646
+ * Main features:
8647
+ * - Key-value access: `setItem` / `getItem` / `removeItem` by key, all async
8648
+ * - Optional default on read: overload with `defaultValue` returns a fallback when key is missing
8649
+ * - Bulk clear: `clear()` removes all entries and resolves when done
8650
+ * - Optional parameters: generic `Opt` allows implementations to support expiry, scope, etc.
8651
+ *
8652
+ * When to use: Prefer this over sync `StorageInterface` when the underlying store is async
8653
+ * or when you want to avoid blocking the main thread.
8654
+ *
8655
+ * @template Key - Type of keys used to identify stored values.
8656
+ * @template ValueType - Type of values stored and retrieved.
8657
+ * @template Opt - Type of optional storage/retrieval options (e.g. expiry, scope).
8645
8658
  *
8659
+ * @example Basic usage
8646
8660
  * ```typescript
8647
- * const storage: AsyncStorage<string, number> = ...;
8661
+ * const storage: AsyncStorageInterface<string, number, void> = ...;
8648
8662
  * await storage.setItem('key', 123);
8649
8663
  * const value = await storage.getItem('key', 0);
8664
+ * await storage.removeItem('key');
8665
+ * await storage.clear();
8650
8666
  * ```
8651
8667
  *
8668
+ * @example Without default (returns null when missing)
8669
+ * ```typescript
8670
+ * const value = await storage.getItem('key');
8671
+ * if (value !== null) { ... }
8672
+ * ```
8652
8673
  */
8653
- interface AsyncStorageInterface<Key, ValueType = unknown> {
8654
- /**
8655
- * The number of items stored.
8656
- */
8657
- readonly length: number;
8674
+ interface AsyncStorageInterface<Key, ValueType, Opt> {
8658
8675
  /**
8659
- * Asynchronously stores a value with the specified key.
8676
+ * Stores a value under the given key asynchronously.
8660
8677
  *
8661
- * @param key - The key to identify the stored value.
8662
- * @param value - The value to store.
8663
- * @param options - Optional parameters for storage.
8664
- * @returns A promise that resolves when the value is stored.
8678
+ * Overwrites any existing value for `key`. Resolves when the write has completed;
8679
+ * rejections are implementation-defined (e.g. quota, I/O errors).
8680
+ *
8681
+ * @param key - Key to identify the stored value.
8682
+ * @param value - Value to store. Serialization is implementation-defined.
8683
+ * @param options - Optional parameters for this write (e.g. `maxAge`, `scope`). Type is `Opt`.
8684
+ * @returns Promise that resolves when the value is stored, or rejects on failure.
8665
8685
  */
8666
- setItem<T>(key: Key, value: T, options?: unknown): Promise<void>;
8686
+ setItem(key: Key, value: ValueType, options?: Opt): Promise<void>;
8667
8687
  /**
8668
- * Asynchronously retrieves a value by key.
8688
+ * Retrieves the value for the given key asynchronously.
8689
+ *
8690
+ * Use this overload when the caller handles missing keys explicitly (e.g. with `null` check).
8669
8691
  *
8670
- * @param key - The key of the value to retrieve.
8671
- * @param defaultValue - The default value to return if the key is not found.
8672
- * @param options - Optional parameters for retrieval.
8673
- * @returns A promise that resolves to the value associated with the key, or the default value if not found.
8692
+ * @param key - Key of the value to retrieve.
8693
+ * @param options - Optional parameters for retrieval. Type is `Opt`.
8694
+ * @returns Promise resolving to the stored value, or `null` if the key does not exist.
8674
8695
  */
8675
- getItem<T extends ValueType>(key: Key, defaultValue?: T, options?: unknown): Promise<T | null>;
8696
+ getItem(key: Key, options?: Opt): Promise<ValueType | null>;
8676
8697
  /**
8677
- * Asynchronously removes a value by key.
8698
+ * Retrieves the value for the given key, or the default when missing.
8699
+ *
8700
+ * Use this overload when a fallback is required; the promise resolves to `ValueType` (never `null`).
8678
8701
  *
8679
- * @param key - The key of the value to remove.
8680
- * @param options - Optional parameters for removal.
8681
- * @returns A promise that resolves when the value is removed.
8702
+ * @param key - Key of the value to retrieve.
8703
+ * @param defaultValue - Value to return when the key is not found.
8704
+ * @param options - Optional parameters for retrieval. Type is `Opt`.
8705
+ * @returns Promise resolving to the stored value if present, otherwise `defaultValue`.
8682
8706
  */
8683
- removeItem(key: Key, options?: unknown): Promise<void>;
8707
+ getItem(key: Key, defaultValue: ValueType, options?: Opt): Promise<ValueType>;
8684
8708
  /**
8685
- * Asynchronously clears all stored values.
8709
+ * Removes the entry for the given key asynchronously.
8686
8710
  *
8687
- * @returns A promise that resolves when all values are cleared.
8711
+ * No-op if the key does not exist. Resolves when the removal has completed.
8712
+ *
8713
+ * @param key - Key of the value to remove.
8714
+ * @param options - Optional parameters for removal. Type is `Opt`.
8715
+ * @returns Promise that resolves when the value is removed (or when no-op completes).
8688
8716
  */
8689
- clear(): Promise<void>;
8690
- }
8691
-
8692
- interface ExpireOptions {
8717
+ removeItem(key: Key, options?: Opt): Promise<void>;
8693
8718
  /**
8694
- * Expire time
8719
+ * Removes all entries in this storage asynchronously.
8695
8720
  *
8696
- * maybe is
8697
- * - number: milliseconds
8698
- * - string: time string, like '1d', '1h', '1m', '1s'
8699
- * - object: {}
8700
- * - ...
8721
+ * Scope of "all" is implementation-defined. Resolves when the clear has completed.
8701
8722
  *
8702
- * Subclass implementation
8723
+ * @returns Promise that resolves when all values are cleared.
8703
8724
  */
8704
- expires?: unknown;
8725
+ clear(): Promise<void>;
8705
8726
  }
8706
8727
 
8707
8728
  /**
8708
- * Key-value storage interface for managing a single value with persistence support
8729
+ * Synchronous key-value storage interface.
8709
8730
  *
8710
8731
  * Core concept:
8711
- * Provides a unified interface for storing and retrieving a single value associated
8712
- * with a specific key. Supports both in-memory and persistent storage backends,
8713
- * enabling flexible storage strategies for different use cases.
8714
- *
8715
- * **v2.3.0 before this was an abstract class, now it is an interface**
8732
+ * Contract for a sync storage that maps keys to values. All operations complete immediately;
8733
+ * suitable for in-memory stores, `localStorage`/`sessionStorage` adapters, or any backend
8734
+ * that does not require async I/O.
8716
8735
  *
8717
8736
  * Main features:
8718
- * - Single value storage: Store one value per key instance
8719
- * - Key management: Retrieve the storage key associated with this instance
8720
- * - Value retrieval: Get stored value from memory or persistent storage
8721
- * - Value persistence: Save value to underlying storage backend
8722
- * - Value removal: Clear value from both memory and persistent storage
8723
- * - Options support: Flexible options parameter for storage-specific configurations
8724
- *
8725
- * Typical usage scenarios:
8726
- * - Token storage: Store authentication tokens with persistence
8727
- * - User info storage: Persist user information across sessions
8728
- * - Configuration storage: Store application settings (theme, language, etc.)
8729
- * - Session data: Manage temporary session-specific data
8730
- *
8731
- * Design decisions:
8732
- * - Returns `null` when value is not found (explicit null handling)
8733
- * - Options parameter is optional to support simple use cases
8734
- * - Generic types allow type-safe storage of any value type
8735
- * - Supports both synchronous and asynchronous storage backends through options
8736
- *
8737
- * @template Key - The type of the storage key (e.g., `string`, `number`, `symbol`)
8738
- * @template Value - The type of value to store
8739
- * @template Opt - The type of options for storage operations (defaults to `unknown`)
8740
- *
8741
- * @example Basic usage with localStorage
8742
- * ```typescript
8743
- * const tokenStorage: KeyStorageInterface<string, string> = new KeyStorage('token', {
8744
- * storage: localStorage
8745
- * });
8746
- *
8747
- * // Store token
8748
- * tokenStorage.set('abc123token');
8749
- *
8750
- * // Retrieve token
8751
- * const token = tokenStorage.get(); // Returns 'abc123token'
8737
+ * - Key-value access: `setItem` / `getItem` / `removeItem` by key
8738
+ * - Optional default on read: second `getItem` overload returns a default when key is missing
8739
+ * - Bulk clear: `clear()` removes all entries
8740
+ * - Optional parameters: generic `Opt` allows implementations to support expiry, scope, etc.
8752
8741
  *
8753
- * // Get storage key
8754
- * const key = tokenStorage.getKey(); // Returns 'token'
8742
+ * Design note: `getItem` returns `V | null` when no default is given, to align with the
8743
+ * browser {@link Storage} API (e.g. `localStorage.getItem` returns `string | null`).
8755
8744
  *
8756
- * // Remove token
8757
- * tokenStorage.remove();
8758
- * ```
8745
+ * @template K - Type of keys used to identify stored values.
8746
+ * @template V - Type of values stored and retrieved.
8747
+ * @template Opt - Type of optional storage/retrieval options (e.g. expiry, scope). Defaults to `unknown`.
8759
8748
  *
8760
- * @example User information storage
8749
+ * @example Basic usage
8761
8750
  * ```typescript
8762
- * interface User {
8763
- * id: string;
8764
- * name: string;
8765
- * email: string;
8766
- * }
8767
- *
8768
- * const userStorage: KeyStorageInterface<string, User> = new KeyStorage('user', {
8769
- * storage: localStorage
8770
- * });
8771
- *
8772
- * const user: User = {
8773
- * id: '123',
8774
- * name: 'John Doe',
8775
- * email: 'john@example.com'
8776
- * };
8777
- *
8778
- * userStorage.set(user);
8779
- * const storedUser = userStorage.get(); // Returns User object
8751
+ * const storage: StorageInterface<string, number> = ...;
8752
+ * storage.setItem('count', 42);
8753
+ * const value = storage.getItem('count', 0) ?? 0;
8754
+ * storage.removeItem('count');
8755
+ * storage.clear();
8780
8756
  * ```
8781
8757
  *
8782
- * @example With custom options
8758
+ * @example With options (e.g. expiry)
8783
8759
  * ```typescript
8784
- * interface StorageOptions {
8785
- * encrypt?: boolean;
8786
- * expires?: number;
8787
- * }
8788
- *
8789
- * const secureStorage: KeyStorageInterface<string, string, StorageOptions> =
8790
- * new KeyStorage('secret', {
8791
- * storage: localStorage,
8792
- * encrypt: true
8793
- * });
8794
- *
8795
- * secureStorage.set('sensitive-data', { encrypt: true, expires: 3600 });
8760
+ * storage.setItem('token', 'abc', { maxAge: 3600 });
8761
+ * const token = storage.getItem('token', { scope: 'session' });
8796
8762
  * ```
8797
8763
  */
8798
- interface KeyStorageInterface<Key, Value, Opt = unknown> {
8764
+ interface StorageInterface<K, V, Opt = unknown> {
8799
8765
  /**
8800
- * Get the storage key associated with this instance
8801
- *
8802
- * Returns the key that was used to initialize this storage instance.
8803
- * This key is used to identify the storage location in the underlying
8804
- * storage backend.
8766
+ * Stores a value under the given key.
8805
8767
  *
8806
- * @returns The storage key of type `Key`
8768
+ * Overwrites any existing value for `key`. Implementations may use `options` for
8769
+ * behaviour such as TTL or storage scope.
8807
8770
  *
8808
- * @example
8809
- * ```typescript
8810
- * const storage = new KeyStorage('my-key', { storage: localStorage });
8811
- * const key = storage.getKey(); // Returns 'my-key'
8812
- * ```
8771
+ * @param key - Key to identify the stored value. Must be valid for the underlying store.
8772
+ * @param value - Value to store. Serialization is implementation-defined (e.g. JSON, string-only).
8773
+ * @param options - Optional parameters for this write (e.g. `maxAge`, `scope`). Type is `Opt`.
8813
8774
  */
8814
- getKey(): Key;
8775
+ setItem(key: K, value: V, options?: Opt): void;
8815
8776
  /**
8816
- * Get the current in-memory value without accessing persistent storage
8817
- *
8818
- * Returns the value currently stored in memory. This method does not
8819
- * attempt to load from persistent storage. Use `get()` if you want
8820
- * to retrieve from persistent storage when memory value is null.
8821
- *
8822
- * Returns `null` if:
8823
- * - No value has been set yet
8824
- * - Value was removed via `remove()`
8825
- * - Value was never loaded from storage
8777
+ * Retrieves the value for the given key.
8826
8778
  *
8827
- * @returns The current in-memory value, or `null` if not available
8779
+ * Returns `null` when the key is not found, so the signature stays compatible with the
8780
+ * browser {@link Storage} API.
8828
8781
  *
8829
- * @example
8830
- * ```typescript
8831
- * const storage = new KeyStorage('token', { storage: localStorage });
8832
- *
8833
- * // Initially null (not loaded from storage yet)
8834
- * const memValue = storage.getValue(); // Returns null
8835
- *
8836
- * // After setting
8837
- * storage.set('abc123');
8838
- * const memValue2 = storage.getValue(); // Returns 'abc123'
8839
- *
8840
- * // After removal
8841
- * storage.remove();
8842
- * const memValue3 = storage.getValue(); // Returns null
8843
- * ```
8782
+ * @param key - Key of the value to retrieve.
8783
+ * @param options - Optional parameters for retrieval (e.g. scope). Type is `Opt`.
8784
+ * @returns The stored value, or `null` if the key does not exist.
8844
8785
  */
8845
- getValue(): Value | null;
8786
+ getItem(key: K, options?: Opt): V | null;
8846
8787
  /**
8847
- * Retrieve value from storage with optional configuration
8788
+ * Retrieves the value for the given key, or the default when missing.
8848
8789
  *
8849
- * Retrieval strategy:
8850
- * 1. First checks in-memory value (fast path)
8851
- * 2. If memory value is null and persistent storage is available,
8852
- * loads from persistent storage and updates memory cache
8853
- * 3. Returns null if value doesn't exist in either location
8790
+ * Use this overload when a fallback is required so callers avoid explicit `null` checks.
8854
8791
  *
8855
- * The `options` parameter allows passing storage-specific configuration
8856
- * that may override default behavior (e.g., encryption settings, expiration checks).
8857
- *
8858
- * @param options - Optional storage operation configuration
8859
- * @returns The stored value, or `null` if not found
8860
- *
8861
- * @example Basic retrieval
8862
- * ```typescript
8863
- * const storage = new KeyStorage('token', { storage: localStorage });
8864
- * storage.set('abc123');
8865
- * const token = storage.get(); // Returns 'abc123'
8866
- * ```
8867
- *
8868
- * @example With options
8869
- * ```typescript
8870
- * interface Options {
8871
- * decrypt?: boolean;
8872
- * }
8873
- *
8874
- * const storage = new KeyStorage<string, string, Options>('secret', {
8875
- * storage: localStorage
8876
- * });
8877
- *
8878
- * // Retrieve with decryption
8879
- * const value = storage.get({ decrypt: true });
8880
- * ```
8881
- *
8882
- * @example Handling null values
8883
- * ```typescript
8884
- * const storage = new KeyStorage('data', { storage: localStorage });
8885
- * const value = storage.get();
8886
- *
8887
- * if (value === null) {
8888
- * console.log('No value stored');
8889
- * } else {
8890
- * console.log('Value:', value);
8891
- * }
8892
- * ```
8792
+ * @param key - Key of the value to retrieve.
8793
+ * @param defaultValue - Value to return when the key is not found.
8794
+ * @param options - Optional parameters for retrieval. Type is `Opt`.
8795
+ * @returns The stored value if present, otherwise `defaultValue`.
8893
8796
  */
8894
- get(options?: Opt): Value | null;
8797
+ getItem(key: K, defaultValue: V, options?: Opt): V | null;
8895
8798
  /**
8896
- * Store a value with optional configuration
8799
+ * Removes the entry for the given key.
8897
8800
  *
8898
- * Storage behavior:
8899
- * - Updates in-memory value immediately
8900
- * - Persists to underlying storage backend if available
8901
- * - Merges provided options with default options
8902
- * - Overwrites any existing value for this key
8801
+ * No-op if the key does not exist. Implementations may use `options` (e.g. scope) to
8802
+ * target a specific storage area.
8903
8803
  *
8904
- * The `options` parameter can be used to pass storage-specific settings
8905
- * such as encryption, expiration, or other backend-specific configurations.
8906
- *
8907
- * @param value - The value to store (can be any type matching `Value`)
8908
- * @param options - Optional storage operation configuration
8909
- *
8910
- * @example Basic storage
8911
- * ```typescript
8912
- * const storage = new KeyStorage('token', { storage: localStorage });
8913
- * storage.set('abc123token');
8914
- * ```
8915
- *
8916
- * @example Storing complex objects
8917
- * ```typescript
8918
- * interface User {
8919
- * id: string;
8920
- * name: string;
8921
- * }
8922
- *
8923
- * const storage = new KeyStorage<string, User>('user', {
8924
- * storage: localStorage
8925
- * });
8926
- *
8927
- * storage.set({
8928
- * id: '123',
8929
- * name: 'John Doe'
8930
- * });
8931
- * ```
8932
- *
8933
- * @example With encryption options
8934
- * ```typescript
8935
- * interface Options {
8936
- * encrypt?: boolean;
8937
- * expires?: number;
8938
- * }
8939
- *
8940
- * const storage = new KeyStorage<string, string, Options>('secret', {
8941
- * storage: localStorage
8942
- * });
8943
- *
8944
- * storage.set('sensitive-data', {
8945
- * encrypt: true,
8946
- * expires: Date.now() + 3600000 // 1 hour
8947
- * });
8948
- * ```
8804
+ * @param key - Key of the value to remove.
8805
+ * @param options - Optional parameters for removal. Type is `Opt`.
8949
8806
  */
8950
- set(value: Value, options?: Opt): void;
8807
+ removeItem(key: K, options?: Opt): void;
8951
8808
  /**
8952
- * Remove the stored value from both memory and persistent storage
8953
- *
8954
- * Removal behavior:
8955
- * - Clears in-memory value (sets to `null`)
8956
- * - Removes value from persistent storage backend if available
8957
- * - Applies any options-specific removal behavior
8958
- *
8959
- * After calling `remove()`, subsequent calls to `get()` will return `null`
8960
- * until a new value is set via `set()`.
8809
+ * Removes all entries in this storage.
8961
8810
  *
8962
- * @param options - Optional storage operation configuration
8963
- *
8964
- * @example Basic removal
8965
- * ```typescript
8966
- * const storage = new KeyStorage('token', { storage: localStorage });
8967
- * storage.set('abc123');
8968
- * storage.remove(); // Removes from both memory and localStorage
8969
- * const token = storage.get(); // Returns null
8970
- * ```
8971
- *
8972
- * @example With options
8973
- * ```typescript
8974
- * interface Options {
8975
- * softDelete?: boolean;
8976
- * }
8977
- *
8978
- * const storage = new KeyStorage<string, string, Options>('data', {
8979
- * storage: localStorage
8980
- * });
8981
- *
8982
- * // Remove with soft delete option
8983
- * storage.remove({ softDelete: true });
8984
- * ```
8985
- *
8986
- * @example Clearing user session
8987
- * ```typescript
8988
- * const userStorage = new KeyStorage('user', { storage: localStorage });
8989
- *
8990
- * // User logs out
8991
- * userStorage.remove();
8992
- * ```
8811
+ * Scope of "all" is implementation-defined (e.g. may be limited to a prefix or namespace).
8993
8812
  */
8994
- remove(options?: Opt): void;
8813
+ clear(): void;
8995
8814
  }
8996
8815
 
8997
8816
  /**
8998
- * Interface representing a synchronous storage mechanism.
8817
+ * Storage interface bound to a single fixed key.
8999
8818
  *
9000
- * @template Key - The type of keys used to identify stored values.
9001
- * @template ValueType - The type of values stored, defaults to unknown.
8819
+ * Core concept:
8820
+ * A storage abstraction that only ever reads/writes one key, exposed as `key`. Callers use
8821
+ * `get`/`set`/`remove` without passing a key; useful for token storage, single preference,
8822
+ * or any "one value per instance" scenario.
9002
8823
  *
9003
- * @example
8824
+ * Main features:
8825
+ * - Fixed key: `readonly key` identifies the sole key this instance operates on
8826
+ * - Simple API: `get()` / `set(value)` / `remove()` with no key argument
8827
+ * - Optional parameters: generic `Opt` allows implementations to support expiry, scope, etc.
8828
+ *
8829
+ * When to use: Prefer this over a generic key-value interface when the semantic is "one
8830
+ * named slot" (e.g. auth token, theme, locale) and you want to avoid key typos and keep
8831
+ * API minimal.
8832
+ *
8833
+ * @template Key - Type of the fixed key (e.g. string literal `'token'` or union of known keys).
8834
+ * @template Value - Type of the value stored and retrieved.
8835
+ * @template Opt - Type of optional storage/retrieval options. Defaults to `unknown`.
8836
+ *
8837
+ * @example Basic usage (token)
8838
+ * ```typescript
8839
+ * const tokenStorage: KeyStorageInterface<'token', string> = ...;
8840
+ * tokenStorage.set('jwt-abc');
8841
+ * const token = tokenStorage.get();
8842
+ * tokenStorage.remove();
8843
+ * ```
8844
+ *
8845
+ * @example With options
9004
8846
  * ```typescript
9005
- * const storage: SyncStorage<string, number> = ...;
9006
- * storage.setItem('key', 123);
9007
- * const value = storage.getItem('key', 0);
8847
+ * tokenStorage.set('jwt-abc', { maxAge: 3600 });
8848
+ * const token = tokenStorage.get({ scope: 'session' });
9008
8849
  * ```
9009
8850
  */
9010
- interface SyncStorageInterface<Key, Opt = unknown> {
9011
- /**
9012
- * The number of items stored.
9013
- */
9014
- readonly length: number;
8851
+ interface KeyStorageInterface<Key, Value, Opt = unknown> {
9015
8852
  /**
9016
- * Stores a value with the specified key.
8853
+ * The single key this storage instance is bound to.
9017
8854
  *
9018
- * @param key - The key to identify the stored value.
9019
- * @param value - The value to store.
9020
- * @param options - Optional parameters for storage.
8855
+ * All `get`/`set`/`remove` operations act on this key. Read-only so that the binding
8856
+ * cannot change after creation.
9021
8857
  */
9022
- setItem<T>(key: Key, value: T, options?: Opt): void | unknown;
8858
+ readonly key: Key;
9023
8859
  /**
9024
- * Retrieves a value by key.
8860
+ * Reads the value for the bound key.
9025
8861
  *
9026
- * @param key - The key of the value to retrieve.
9027
- * @param defaultValue - The default value to return if the key is not found.
9028
- * @param options - Optional parameters for retrieval.
9029
- * @returns The value associated with the key, or the default value if not found.
8862
+ * @param options - Optional parameters for retrieval (e.g. scope). Type is `Opt`.
8863
+ * @returns The stored value, or `null` if no value has been set or it was removed.
9030
8864
  */
9031
- getItem<T>(key: Key, defaultValue?: T, options?: Opt): T | null;
8865
+ get(options?: Opt): Value | null;
9032
8866
  /**
9033
- * Removes a value by key.
8867
+ * Writes the value for the bound key.
9034
8868
  *
9035
- * @param key - The key of the value to remove.
9036
- * @param options - Optional parameters for removal.
9037
- */
9038
- removeItem(key: Key, options?: Opt): void;
9039
- /**
9040
- * Clears all stored values.
8869
+ * Overwrites any existing value. Implementations may use `options` for behaviour such
8870
+ * as TTL or storage scope.
8871
+ *
8872
+ * @param value - Value to store. Serialization is implementation-defined.
8873
+ * @param options - Optional parameters for this write (e.g. `maxAge`, `scope`). Type is `Opt`.
9041
8874
  */
9042
- clear(): void;
8875
+ set(value: Value, options?: Opt): void;
9043
8876
  /**
9044
- * Get the raw value from the storage.
8877
+ * Removes the value for the bound key.
9045
8878
  *
9046
- * 通过这个方法可以获取到内部原始的值
8879
+ * No-op if the key is already absent. Implementations may use `options` (e.g. scope)
8880
+ * to target a specific storage area.
9047
8881
  *
9048
- * @param value - The value to get the raw value from.
9049
- * @returns The raw value.
8882
+ * @param options - Optional parameters for removal. Type is `Opt`.
9050
8883
  */
9051
- getRawValue?<T>(value: unknown, defaultValue?: T, options?: Opt): T | null;
8884
+ remove(options?: Opt): void;
9052
8885
  }
9053
8886
 
9054
- interface KeyStorageOptions<Key, Sopt = unknown> extends ExpireOptions {
9055
- /**
9056
- * Persistent storage
9057
- */
9058
- storage?: SyncStorageInterface<Key, Sopt>;
9059
- }
9060
- /**
9061
- * KeyStorage is a storage that can be used to store a single value.
9062
- *
9063
- * Typical usage scenario: need to store a value and need to persist it:
9064
- *
9065
- * - token storage
9066
- * - user info storage
9067
- * - page theme, language
9068
- * - ...
9069
- *
9070
- * And support for data encryption, there are times when reporting errors in the local data can easily be tampered with, this time you can use encryption to protect the data!
9071
- *
9072
- * @since 1.5.0
9073
- *
9074
- * @example basic usage
9075
- *
9076
- * use localStorage as storage, persist the value
9077
- *
9078
- * ```typescript
9079
- * const tokenStorage = new KeyStorage('token', localStorage);
9080
- *
9081
- * tokenStorage.get(); // get from localStorage
9082
- * tokenStorage.set('token-123123123'); // set to localStorage
9083
- * tokenStorage.remove(); // remove from localStorage
9084
- * ```
9085
- *
9086
- * @example with encrypt
9087
- * ```typescript
9088
- * const tokenStorage = new KeyStorage('token', localStorage, {
9089
- * encrypt: new Encryptor(new AESCipher('1234567890'))
9090
- * });
9091
- *
9092
- * tokenStorage.get(); // get from localStorage
9093
- * tokenStorage.set('token-123123123'); // set to localStorage
9094
- * tokenStorage.remove(); // remove from localStorage
9095
- * ```
9096
- */
9097
- declare class KeyStorage<Key, Value, Opt extends KeyStorageOptions<Key> = KeyStorageOptions<Key>> implements KeyStorageInterface<Key, Value, Opt> {
9098
- readonly key: Key;
9099
- protected options: Opt;
9100
- protected value: Value | null;
9101
- constructor(key: Key, options?: Opt);
9102
- protected mergeOptions(options?: Opt): Opt;
8887
+ declare class KeyStorage<K, V, Opt = unknown> implements KeyStorageInterface<K, V, Opt> {
8888
+ readonly key: K;
8889
+ protected readonly storage?: StorageInterface<K, V, Opt> | undefined;
8890
+ protected value: V | undefined | null;
8891
+ constructor(key: K, storage?: StorageInterface<K, V, Opt> | undefined);
9103
8892
  /**
9104
8893
  * @override
9105
8894
  */
9106
- getKey(): Key;
8895
+ get(options?: Opt): V | null;
9107
8896
  /**
9108
8897
  * @override
9109
8898
  */
9110
- getValue(): Value | null;
9111
- /**
9112
- * @override
9113
- */
9114
- get(options?: Opt): Value | null;
9115
- /**
9116
- * @override
9117
- */
9118
- set(token: Value, options?: Opt): void;
8899
+ set(value: V, options?: Opt): void;
9119
8900
  /**
9120
8901
  * @override
9121
8902
  */
9122
8903
  remove(options?: Opt): void;
9123
8904
  }
9124
8905
 
9125
- interface ObjectStorageOptions extends ExpireOptions {
8906
+ interface ObjectStorageOptions {
8907
+ expires?: number;
9126
8908
  }
9127
8909
  /**
9128
8910
  * Storage value wrapper with expiration support
@@ -9190,7 +8972,7 @@ type StorageValue<Key, ValueType> = {
9190
8972
  *
9191
8973
  * @since 1.5.0
9192
8974
  */
9193
- declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOptions = ObjectStorageOptions> implements SyncStorageInterface<Key, Opt> {
8975
+ declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOptions = ObjectStorageOptions> implements StorageInterface<Key, ValueType, Opt> {
9194
8976
  /**
9195
8977
  * Serializer for data transformation
9196
8978
  *
@@ -9199,7 +8981,7 @@ declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOp
9199
8981
  * Main function: Serialize/deserialize storage values
9200
8982
  * Main purpose: Support type-safe storage operations
9201
8983
  */
9202
- protected readonly serializer?: SerializerIneterface<unknown, ValueType> | undefined;
8984
+ protected readonly serializer?: SerializerIneterface<ValueType, string> | undefined;
9203
8985
  /**
9204
8986
  * In-memory storage map for fast data access
9205
8987
  *
@@ -9232,11 +9014,10 @@ declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOp
9232
9014
  * Main function: Serialize/deserialize storage values
9233
9015
  * Main purpose: Support type-safe storage operations
9234
9016
  */
9235
- serializer?: SerializerIneterface<unknown, ValueType> | undefined);
9017
+ serializer?: SerializerIneterface<ValueType, string> | undefined);
9236
9018
  /**
9237
9019
  * Gets the number of items stored in the memory cache
9238
9020
  *
9239
- * @override
9240
9021
  * @returns The number of stored items in memory
9241
9022
  *
9242
9023
  * @example
@@ -9268,7 +9049,7 @@ declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOp
9268
9049
  * storage.setItem('session', sessionData, Date.now() + 3600000);
9269
9050
  * ```
9270
9051
  */
9271
- setItem<T>(key: Key, value: T, options?: ObjectStorageOptions): unknown;
9052
+ setItem<T>(key: Key, value: T, options?: ObjectStorageOptions): ValueType;
9272
9053
  /**
9273
9054
  * Retrieves a stored value by key with fallback strategy
9274
9055
  *
@@ -9298,11 +9079,8 @@ declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOp
9298
9079
  * const config = storage.getItem<AppConfig>('app-config');
9299
9080
  * ```
9300
9081
  */
9301
- getItem<T>(key: Key, defaultValue?: T): T | null;
9302
- /**
9303
- * @override
9304
- */
9305
- getRawValue<T>(value: unknown, defaultValue?: T): T | null;
9082
+ getItem(key: Key, defaultValue?: unknown): ValueType | null;
9083
+ protected getRawValue<T>(value: unknown, defaultValue?: T): T | null;
9306
9084
  /**
9307
9085
  * Removes a stored item by its key from both memory and persistent storage
9308
9086
  *
@@ -9378,339 +9156,194 @@ declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOp
9378
9156
  * ```
9379
9157
  */
9380
9158
  protected isStorageValue(value: unknown): value is StorageValue<Key, ValueType>;
9159
+ }
9160
+
9161
+ /**
9162
+ * Plugin contract for the storage pipeline.
9163
+ *
9164
+ * Each plugin participates in a chain: on `set`, value flows forward (e.g. serialize → encrypt → persist);
9165
+ * on `get`, value flows backward (e.g. read → decrypt → deserialize). The second argument to `get` is
9166
+ * the value produced by the previous plugin in the chain so each step can transform it.
9167
+ *
9168
+ * @template K - Key type
9169
+ * @template V - Value type
9170
+ * @template Opt - Options type passed through the chain
9171
+ */
9172
+ interface StorageExecutorPlugin<K, V, Opt> {
9381
9173
  /**
9382
- * Gets the serializer instance
9174
+ * Transform or read value in the get pipeline. Receives `valueFromPrevious` from the next plugin
9175
+ * in the chain (e.g. raw string from storage, then decrypted, then deserialized).
9383
9176
  *
9384
- * Significance: Provides access to the serialization logic
9385
- * Core idea: Expose serializer for advanced use cases
9386
- * Main function: Return the serializer instance
9387
- * Main purpose: Enable direct access to serialization when needed
9177
+ * @param key - Storage key
9178
+ * @param valueFromPrevious - Value from the previous step in the reverse chain; first call gets `defaultValue`
9179
+ * @param options - Optional options forwarded to the chain
9180
+ * @returns Transformed value, or `undefined` to keep current pipeline value
9181
+ */
9182
+ get(key: K, valueFromPrevious: unknown, options?: Opt): V | undefined | null;
9183
+ /**
9184
+ * Transform or persist value in the set pipeline. May return the transformed value for the next plugin.
9388
9185
  *
9389
- * @returns The serializer instance
9186
+ * @param key - Storage key
9187
+ * @param value - Value from the previous step (or initial value)
9188
+ * @param options - Optional options forwarded to the chain
9189
+ * @returns Transformed value for the next plugin, or `undefined` if this step does not change the value
9190
+ */
9191
+ set(key: K, value: V, options?: Opt): unknown;
9192
+ /** Optional: remove item for this key. Only storage plugins typically implement this. */
9193
+ remove?(key?: K, options?: Opt): void;
9194
+ /** Optional: clear all data. Only storage plugins typically implement this. */
9195
+ clear?(): void;
9196
+ /**
9197
+ * When `'storage'`, this plugin reads from a backing store. On `getItem`, once the first
9198
+ * storage (from tail) returns a value, no further storage plugins are used for get; only
9199
+ * `'pipe'` plugins keep transforming the value. When `'pipe'` or omitted, the plugin only
9200
+ * transforms (e.g. serialize, encrypt).
9201
+ *
9202
+ * @example type=storage use first storage
9390
9203
  *
9391
- * @example
9392
9204
  * ```typescript
9393
- * const serializer = storage.getSerializer();
9394
- * if (serializer) {
9395
- * // Direct access to serializer
9396
- * }
9205
+ * const executor = new StorageExecutor([jsonSerializer, aesEncryptor, sessionStorage, localStorage]);
9206
+ * executor.setItem('key', { a: 1 }); // { a: 1 } → serialize → encrypt → sessionStorage → localStorage
9207
+ * executor.getItem('key'); // localStorage decrypt → deserialize → { a: 1 }
9397
9208
  * ```
9398
9209
  */
9399
- getSerializer(): SerializerIneterface<unknown, ValueType> | undefined;
9210
+ type?: 'storage' | string;
9400
9211
  }
9401
-
9402
9212
  /**
9403
- * Pipe processor type definition
9213
+ * Executes a pipeline of storage plugins, implementing `StorageInterface`.
9404
9214
  *
9405
- * Significance: Define the type of components that can be used for data processing pipelines
9406
- * Core idea: Unify the type definition of different processors, supporting data transformation and intermediate storage
9407
- * Main function: Provide type-safe pipeline components
9408
- * Main purpose: Support serialization, encryption, intermediate storage, and other data processing operations
9409
- */
9410
- type PipeType<Key> = SerializerIneterface<unknown, unknown> | EncryptorInterface<unknown, unknown> | SyncStorageInterface<Key, unknown>;
9411
- /**
9412
- * Pipe value definition, containing the pipe processor and its type identifier
9413
- *
9414
- * Significance: Pre-determine the pipe type to avoid runtime type checks
9415
- * Core idea: Bind the pipe processor with its type to improve execution efficiency
9416
- * Main function: Store the pipe processor and its type information
9417
- * Main purpose: Optimize pipe execution performance, simplify type judgment logic
9418
- */
9419
- type PipeValue<Key> = {
9420
- type: 'serialize';
9421
- pipe: SerializerIneterface<unknown, unknown>;
9422
- } | {
9423
- type: 'encrypt';
9424
- pipe: EncryptorInterface<unknown, unknown>;
9425
- } | {
9426
- type: 'storage';
9427
- pipe: SyncStorageInterface<Key, unknown>;
9428
- };
9429
-
9430
- /**
9431
- * Pipe argument type for storage initialization
9432
- *
9433
- * Accepts either a typed pipe or a pipe value wrapper.
9434
- *
9435
- * @template Key - Type of storage keys
9436
- */
9437
- type PipeArg<Key> = PipeType<Key> | PipeValue<Key>;
9438
- /**
9439
- * Synchronous storage implementation with pipeline support
9440
- *
9441
- * Core concept:
9442
- * Provides a flexible storage abstraction with a pipeline architecture that
9443
- * allows chaining multiple transformations (serialization, encryption, intermediate
9444
- * storage) before data reaches the final storage backend.
9215
+ * Core concept: values flow through plugins in order on `set` (e.g. serialize encrypt → storage),
9216
+ * and in reverse order on `get` (storage decrypt deserialize). Each plugin receives the value
9217
+ * from the previous step and may return a transformed value for the next.
9445
9218
  *
9446
9219
  * Main features:
9447
- * - Pipeline architecture: Chain multiple data transformations
9448
- * - Serialization: Convert objects to strings (JSON, Base64, etc.)
9449
- * - Encryption: Secure data before storage
9450
- * - Intermediate storage: Multi-layer storage support
9451
- * - Custom transformations: Extensible pipe system
9452
- *
9453
- * - Automatic pipe detection: Identifies pipe types by interface
9454
- * - Serializer: Has `serialize()` and `deserialize()` methods
9455
- * - Encryptor: Has `encrypt()` and `decrypt()` methods
9456
- * - Storage: Has `setItem()`, `getItem()`, `removeItem()`, `clear()` methods
9457
- * - No manual type specification needed
9458
- *
9459
- * - Bidirectional processing: Handles both storage and retrieval
9460
- * - setItem: Forward pipeline (value → serialize → encrypt → store)
9461
- * - getItem: Reverse pipeline (retrieve → decrypt → deserialize → value)
9462
- * - Maintains data integrity through the pipeline
9463
- *
9464
- * - Multi-layer storage: Support for intermediate storage layers
9465
- * - Primary storage: Final storage backend
9466
- * - Intermediate storage: Additional storage layers in pipeline
9467
- * - Fallback mechanism: Try intermediate storage if primary fails
9468
- *
9469
- * Pipeline execution order:
9470
- *
9471
- * **setItem (forward):**
9472
- * 1. Original value
9473
- * 2. Serialize (if serializer in pipeline)
9474
- * 3. Encrypt (if encryptor in pipeline)
9475
- * 4. Store in intermediate storage (if storage in pipeline)
9476
- * 5. Store in primary storage
9477
- *
9478
- * **getItem (reverse):**
9479
- * 1. Retrieve from primary storage
9480
- * 2. If not found, try intermediate storage layers (reversed order)
9481
- * 3. Decrypt (if encryptor in pipeline)
9482
- * 4. Deserialize (if serializer in pipeline)
9483
- * 5. Return final value
9484
- *
9485
- * @template Key - Type of storage keys (typically `string`)
9486
- * @template Opt - Type of storage options (optional)
9487
- *
9488
- * @example Basic usage with JSON serialization
9489
- * ```typescript
9490
- * import { SyncStorage, JSONSerializer } from '@qlover/fe-corekit';
9220
+ * - **setItem**: Iterates plugins forward; each `set` may return a new value (e.g. serialized/encrypted) for the next
9221
+ * - **getItem**: Iterates plugins backward. **When there are multiple storage plugins, only the value from the
9222
+ * last storage (the one at the end of the plugin array) is used for reading; all other storage plugins are
9223
+ * skipped and their values are ignored.** Pipe plugins (serializer, encryptor, etc.) still transform the
9224
+ * value as usual.
9225
+ * - **removeItem** / **clear**: Delegated to all plugins that implement `remove` / `clear`
9491
9226
  *
9492
- * const storage = new SyncStorage(
9493
- * localStorage,
9494
- * new JSONSerializer()
9495
- * );
9496
- *
9497
- * // Store object (automatically serialized to JSON)
9498
- * storage.setItem('user', { id: 1, name: 'John' });
9227
+ * @template K - Key type
9228
+ * @template V - Value type (after serialization/encryption may differ internally)
9229
+ * @template Opt - Options type
9499
9230
  *
9500
- * // Retrieve object (automatically deserialized from JSON)
9501
- * const user = storage.getItem('user');
9502
- * console.log(user); // { id: 1, name: 'John' }
9503
- * ```
9504
- *
9505
- * @example With encryption
9231
+ * @example Single storage backend
9506
9232
  * ```typescript
9507
- * import { SyncStorage, JSONSerializer, AESEncryptor } from '@qlover/fe-corekit';
9508
- *
9509
- * const storage = new SyncStorage(
9510
- * localStorage,
9511
- * [
9512
- * new JSONSerializer(), // First: serialize to JSON
9513
- * new AESEncryptor('key') // Then: encrypt JSON string
9514
- * ]
9515
- * );
9516
- *
9517
- * // Data is serialized then encrypted before storage
9518
- * storage.setItem('sensitive', { password: 'secret' });
9519
- *
9520
- * // Data is decrypted then deserialized on retrieval
9521
- * const data = storage.getItem('sensitive');
9233
+ * const executor = new StorageExecutor(localStorage);
9234
+ * executor.setItem('key', { a: 1 });
9235
+ * executor.getItem('key');
9522
9236
  * ```
9523
9237
  *
9524
- * @example Multi-layer storage
9238
+ * @example Pipeline: serializer + encryptor + storage
9525
9239
  * ```typescript
9526
- * import { SyncStorage, JSONSerializer } from '@qlover/fe-corekit';
9527
- *
9528
- * // Create intermediate storage layer
9529
- * const memoryCache = new Map();
9530
- * const cacheStorage = {
9531
- * setItem: (k, v) => memoryCache.set(k, v),
9532
- * getItem: (k) => memoryCache.get(k) ?? null,
9533
- * removeItem: (k) => memoryCache.delete(k),
9534
- * clear: () => memoryCache.clear(),
9535
- * length: memoryCache.size
9536
- * };
9537
- *
9538
- * const storage = new SyncStorage(
9539
- * localStorage,
9540
- * [
9541
- * new JSONSerializer(),
9542
- * cacheStorage // Intermediate cache layer
9543
- * ]
9544
- * );
9545
- *
9546
- * // Data stored in both cache and localStorage
9547
- * storage.setItem('data', { value: 123 });
9548
- *
9549
- * // Retrieval tries cache first, then localStorage
9550
- * const data = storage.getItem('data');
9240
+ * const executor = new StorageExecutor([jsonSerializer, aesEncryptor, localStorage]);
9241
+ * executor.setItem('key', obj); // obj → serialize → encrypt → persist
9242
+ * executor.getItem('key'); // read decrypt → deserialize → obj
9551
9243
  * ```
9552
9244
  *
9553
- * @example Custom pipe order
9245
+ * @example Multiple storages: getItem uses only the last storage
9554
9246
  * ```typescript
9555
- * // Order matters! Pipes are applied in sequence
9556
- * const storage = new SyncStorage(
9557
- * localStorage,
9558
- * [
9559
- * new JSONSerializer(), // 1. Serialize to JSON string
9560
- * new Base64Serializer(), // 2. Encode to Base64
9561
- * new AESEncryptor('key') // 3. Encrypt the Base64 string
9562
- * ]
9563
- * );
9564
- *
9565
- * // setItem: value → JSON → Base64 → Encrypt → store
9566
- * // getItem: retrieve → Decrypt → Base64 decode → JSON parse → value
9247
+ * const executor = new StorageExecutor([sessionStorage, localStorage]);
9248
+ * executor.setItem('key', 'v'); // writes to both
9249
+ * executor.getItem('key'); // reads only from localStorage (last); sessionStorage is ignored
9567
9250
  * ```
9568
- *
9569
- * @see {@link SyncStorageInterface} for the storage interface
9570
- * @see {@link PipeType} for pipe type definitions
9571
- * @see {@link SerializerInterface} for serializer interface
9572
- * @see {@link EncryptorInterface} for encryptor interface
9573
9251
  */
9574
- declare class SyncStorage<Key, Opt = unknown> implements SyncStorageInterface<Key, Opt> {
9575
- protected readonly storage: SyncStorageInterface<Key, Opt>;
9576
- /**
9577
- * Internal pipe value list with pre-determined types
9578
- *
9579
- * Stores the processed pipeline of transformations that will be
9580
- * applied to data during storage and retrieval operations.
9581
- *
9582
- * @protected
9583
- */
9584
- protected readonly pipes: PipeValue<Key>[];
9252
+ declare class StorageExecutor<K, V, Opt = unknown> implements StorageInterface<K, V, Opt> {
9253
+ protected plugins: StorageExecutorPlugin<K, V, Opt>[];
9585
9254
  /**
9586
- * Creates a new SyncStorage instance with pipeline support
9255
+ * Builds the plugin list from either a single `StorageInterface` or an array whose last element
9256
+ * is the backing storage and preceding elements are transformers (e.g. serializer, encryptor).
9587
9257
  *
9588
- * @param storage - Primary storage backend (e.g., localStorage, sessionStorage)
9589
- * @param pipes - Optional pipe or array of pipes for data transformation
9590
- *
9591
- * @example Single pipe
9592
- * ```typescript
9593
- * const storage = new SyncStorage(
9594
- * localStorage,
9595
- * new JSONSerializer()
9596
- * );
9597
- * ```
9598
- *
9599
- * @example Multiple pipes
9600
- * ```typescript
9601
- * const storage = new SyncStorage(
9602
- * localStorage,
9603
- * [
9604
- * new JSONSerializer(),
9605
- * new AESEncryptor('secret-key')
9606
- * ]
9607
- * );
9608
- * ```
9609
- *
9610
- * @example No pipes (direct storage)
9611
- * ```typescript
9612
- * const storage = new SyncStorage(localStorage);
9613
- * // Data stored as-is without transformation
9614
- * ```
9258
+ * @param plugins - Single storage instance or tuple of `[ ...transformers, storage ]`
9615
9259
  */
9616
- constructor(storage: SyncStorageInterface<Key, Opt>, pipes?: PipeArg<Key>[] | PipeArg<Key>);
9260
+ constructor(plugins: StorageInterface<K, V, Opt> | [
9261
+ ...(SerializerIneterface<V> | StorageInterface<K, V, Opt> | EncryptorInterface<V, unknown> | StorageExecutorPlugin<K, V, Opt>)[],
9262
+ StorageInterface<K, V, Opt>
9263
+ ]);
9617
9264
  /**
9618
- * Get the number of items in the primary storage
9619
- *
9620
- * Returns the count of items in the primary storage backend only.
9621
- * Does not include items in intermediate storage layers.
9622
- *
9623
- * @override
9624
- * @returns Number of items in primary storage
9625
- *
9626
- * @example
9627
- * ```typescript
9628
- * console.log(storage.length); // 5
9629
- * storage.setItem('newKey', 'value');
9630
- * console.log(storage.length); // 6
9631
- * ```
9632
- */
9633
- get length(): number;
9634
- /**
9635
- * Store a value with pipeline processing
9636
- *
9637
- * Processes the value through the configured pipeline (serialization,
9638
- * encryption, intermediate storage) before storing in the primary storage.
9639
- *
9640
- * Pipeline execution:
9641
- * 1. Apply serialization (if configured)
9642
- * 2. Apply encryption (if configured)
9643
- * 3. Store in intermediate storage layers (if configured)
9644
- * 4. Store in primary storage
9265
+ * Writes value through the plugin chain (forward). Each plugin may return a transformed value for the next.
9645
9266
  *
9646
9267
  * @override
9647
- * @template T - Type of value to store
9648
- * @param key - Storage key
9649
- * @param value - Value to store
9650
- * @param options - Optional storage options (e.g., expiration)
9651
- *
9652
- * @example Basic storage
9653
- * ```typescript
9654
- * storage.setItem('user', { id: 1, name: 'John' });
9655
- * ```
9656
- *
9657
- * @example With options
9658
- * ```typescript
9659
- * storage.setItem('session', { token: 'abc' }, { expire: 3600 });
9660
- * ```
9661
9268
  */
9662
- setItem<T>(key: Key, value: T, options?: Opt): void;
9269
+ setItem(key: K, value: V, options?: Opt | undefined): void;
9270
+ /** @override */
9271
+ getItem(key: K, options?: Opt | undefined): V | null;
9272
+ /** @override */
9273
+ getItem(key: K, defaultValue: V, options?: Opt | undefined): V;
9663
9274
  /**
9664
- * Retrieve a value with pipeline processing
9665
- *
9666
- * Retrieves the value from storage and processes it through the pipeline
9667
- * in reverse order (decryption, deserialization) to restore the original value.
9668
- *
9669
- * Retrieval strategy:
9670
- * 1. Try to retrieve from primary storage
9671
- * 2. If not found, try intermediate storage layers (in reverse order)
9672
- * 3. Apply decryption (if configured)
9673
- * 4. Apply deserialization (if configured)
9674
- * 5. Return processed value or default
9275
+ * Removes item for the given key from all plugins that implement `remove`.
9675
9276
  *
9676
9277
  * @override
9677
- * @template T - Type of value to retrieve
9678
- * @param key - Storage key
9679
- * @param defaultValue - Default value if key not found
9680
- * @param options - Optional retrieval options
9681
- * @returns Retrieved value or default, `null` if not found and no default
9682
- *
9683
- * @example Basic retrieval
9684
- * ```typescript
9685
- * const user = storage.getItem('user');
9686
- * if (user) {
9687
- * console.log(user.name);
9688
- * }
9689
- * ```
9690
- *
9691
- * @example With default value
9692
- * ```typescript
9693
- * const config = storage.getItem('config', { theme: 'light' });
9694
- * console.log(config.theme); // 'light' if not found
9695
- * ```
9696
9278
  */
9697
- getItem<T>(key: Key, defaultValue?: T, options?: Opt): T | null;
9279
+ removeItem(key: K, options?: Opt | undefined): void;
9698
9280
  /**
9699
- * Delete data items, delete from all storage layers
9281
+ * Clears data in all plugins that implement `clear`.
9700
9282
  *
9701
9283
  * @override
9702
- * @param key - Storage key
9703
- * @param options - Delete options
9704
9284
  */
9705
- removeItem(key: Key, options?: Opt): void;
9706
- /**
9707
- * Clear all data, including storage in the pipeline
9708
-
9709
- * @override
9710
- */
9711
9285
  clear(): void;
9712
9286
  }
9713
9287
 
9288
+ /**
9289
+ * Wraps a `StorageInterface` as a `StorageExecutorPlugin` so it can participate in the pipeline.
9290
+ * Forwards `get`/`set`/`remove`/`clear` to the underlying storage.
9291
+ *
9292
+ * @template K - Key type
9293
+ * @template V - Value type
9294
+ * @template Opt - Options type
9295
+ * @param storage - The backing storage implementation
9296
+ * @returns A plugin that delegates to `storage`
9297
+ */
9298
+ declare function createStoragePluginWithStorage<K, V, Opt = unknown>(storage: StorageInterface<K, V, Opt>): StorageExecutorPlugin<K, V, Opt>;
9299
+ /**
9300
+ * Type guard: checks if the value is a serializer (has `serialize` and `deserialize` methods).
9301
+ *
9302
+ * @template V - Value type the serializer handles
9303
+ * @param plugin - Value to check
9304
+ * @returns `true` if `plugin` implements `SerializerIneterface<V>`
9305
+ */
9306
+ declare function isSerializer<V>(plugin: unknown): plugin is SerializerIneterface<V>;
9307
+ /**
9308
+ * Type guard: checks if the value is an encryptor (has `encrypt` and `decrypt` methods).
9309
+ *
9310
+ * @template V - Value type the encryptor handles
9311
+ * @template E - Encrypted result type
9312
+ * @param plugin - Value to check
9313
+ * @returns `true` if `plugin` implements `EncryptorInterface<V, E>`
9314
+ */
9315
+ declare function isEncryptor<V, E>(plugin: unknown): plugin is EncryptorInterface<V, E>;
9316
+ /**
9317
+ * Normalizes plugin input into an array of `StorageExecutorPlugin`.
9318
+ *
9319
+ * - If a single `StorageInterface` is passed, returns one plugin that wraps it.
9320
+ * - If an array is passed, maps each element: serializers and encryptors are adapted so that
9321
+ * only the pipeline value is passed to `serialize`/`deserialize`/`encrypt`/`decrypt`; storage
9322
+ * instances are wrapped; other values are treated as already-implemented plugins. Array order
9323
+ * is preserved (first plugin = first in set chain, last = storage in typical usage).
9324
+ *
9325
+ * @template K - Key type
9326
+ * @template V - Value type
9327
+ * @template Opt - Options type
9328
+ * @param plugins - Single storage or tuple `[ ...transformers, storage ]`
9329
+ * @returns Array of plugins in pipeline order
9330
+ *
9331
+ * @example
9332
+ * ```typescript
9333
+ * createStoragePlugin(localStorage);
9334
+ * // => [ wrap(localStorage) ]
9335
+ *
9336
+ * createStoragePlugin([jsonSerializer, encryptor, localStorage]);
9337
+ * // => [ adapter(serialize/deserialize), adapter(encrypt/decrypt), wrap(localStorage) ]
9338
+ * ```
9339
+ */
9340
+ declare function createStoragePlugin<K, V, Opt = unknown>(plugins: StorageInterface<K, V, Opt> | [
9341
+ ...(SerializerIneterface<V> | StorageInterface<K, V, Opt> | EncryptorInterface<V, unknown> | StorageExecutorPlugin<K, V, Opt>)[],
9342
+ StorageInterface<K, V, Opt>
9343
+ ]): StorageExecutorPlugin<K, V, Opt>[];
9344
+
9345
+ declare function isStorage<Key, Value, Opt = unknown>(storage: unknown): storage is StorageInterface<Key, Value, Opt>;
9346
+
9714
9347
  /**
9715
9348
  * Extract all possible value types from an object type
9716
9349
  *
@@ -9903,4 +9536,4 @@ type PartialDeep<T> = {
9903
9536
  [K in keyof T]?: T[K] extends object ? PartialDeep<T[K]> : T[K];
9904
9537
  };
9905
9538
 
9906
- export { ABORT_ERROR_ID, AbortError, Aborter, type AborterConfig, type AborterConfigExtractor, type AborterId, type AborterInterface, AborterPlugin, type AborterPluginOptions, type AsyncStorageInterface, Base64Serializer, BasePluginExecutor, DEFAULT_HOOK_ON_BEFORE, DEFAULT_HOOK_ON_ERROR, DEFAULT_HOOK_ON_EXEC, DEFAULT_HOOK_ON_FINALLY, DEFAULT_HOOK_ON_SUCCESS, EXECUTOR_ASYNC_ERROR, EXECUTOR_ERROR_NAME, EXECUTOR_SYNC_ERROR, type EncryptorInterface, type ExecutorAsyncTask, ExecutorContextImpl, type ExecutorContextInterface, ExecutorError, type ExecutorErrorType, type ExecutorHookRuntimesInterface, type ExecutorInterface, type ExecutorPluginInterface, type ExecutorPluginNameType, type ExecutorSyncTask, type ExecutorTask, type ExpireOptions, type HeaderInjectorConfig, type HeaderInjectorInterface, type HookRuntimes, type HttpMethodType, HttpMethods, type Intersection, JSONSerializer, type JSONSerializerOptions, KeyStorage, type KeyStorageInterface, type KeyStorageOptions, type LifecycleErrorResult, type LifecycleExecResult, LifecycleExecutor, type LifecyclePluginInterface, LifecycleSyncExecutor, type LifecycleSyncPluginInterface, ObjectStorage, type ObjectStorageOptions, type PartialDeep, type PipeArg, type PluginExecutorConfig, RETRY_ERROR_ID, RequestAdapterAxios, type RequestAdapterConfig, type RequestAdapterContext, RequestAdapterFetch, type RequestAdapterFetchConfig, type RequestAdapterInterface, type RequestAdapterResponse, RequestExecutor, type RequestExecutorInterface, RequestHeaderInjector, RequestPlugin, type RequestPluginConfig, type RequestPluginInnerConfig, type ResponseParser, type ResponseParsers, ResponsePlugin, type ResponsePluginConfig, type ResponsePluginContext, RetryPlugin, type SerializerIneterface, SimpleUrlBuilder, type StorageValue, SyncStorage, type SyncStorageInterface, type UrlBuilderInterface, type ValueOf, appendHeaders, createAbortPromise, hasObjectKey, hasObjectKeyWithValue, isAbortError, isAbsoluteUrl, isAsString, isRequestAdapterResponse, normalizeHookNames, raceWithAbort, runPluginHook, runPluginsHookAsync, runPluginsHookSync, runPluginsHooksAsync, runPluginsHooksSync };
9539
+ export { ABORT_ERROR_ID, AbortError, Aborter, type AborterConfig, type AborterConfigExtractor, type AborterId, type AborterInterface, AborterPlugin, type AborterPluginOptions, type AsyncStorageInterface, Base64Serializer, BasePluginExecutor, DEFAULT_HOOK_ON_BEFORE, DEFAULT_HOOK_ON_ERROR, DEFAULT_HOOK_ON_EXEC, DEFAULT_HOOK_ON_FINALLY, DEFAULT_HOOK_ON_SUCCESS, EXECUTOR_ASYNC_ERROR, EXECUTOR_ERROR_NAME, EXECUTOR_SYNC_ERROR, type EncryptorInterface, type ExecutorAsyncTask, ExecutorContextImpl, type ExecutorContextInterface, ExecutorError, type ExecutorErrorType, type ExecutorHookRuntimesInterface, type ExecutorInterface, type ExecutorPluginInterface, type ExecutorPluginNameType, type ExecutorSyncTask, type ExecutorTask, type HeaderInjectorConfig, type HeaderInjectorInterface, type HookRuntimes, type HttpMethodType, HttpMethods, type Intersection, JSONSerializer, type JSONSerializerOptions, KeyStorage, type KeyStorageInterface, type LifecycleErrorResult, type LifecycleExecResult, LifecycleExecutor, type LifecyclePluginInterface, LifecycleSyncExecutor, type LifecycleSyncPluginInterface, ObjectStorage, type ObjectStorageOptions, type PartialDeep, type PluginExecutorConfig, RETRY_ERROR_ID, RequestAdapterAxios, type RequestAdapterConfig, type RequestAdapterContext, RequestAdapterFetch, type RequestAdapterFetchConfig, type RequestAdapterInterface, type RequestAdapterResponse, RequestExecutor, type RequestExecutorInterface, RequestHeaderInjector, RequestPlugin, type RequestPluginConfig, type RequestPluginInnerConfig, type ResponseParser, type ResponseParsers, ResponsePlugin, type ResponsePluginConfig, type ResponsePluginContext, RetryPlugin, type SerializerIneterface, SimpleUrlBuilder, StorageExecutor, type StorageExecutorPlugin, type StorageInterface, type StorageValue, type UrlBuilderInterface, type ValueOf, appendHeaders, createAbortPromise, createStoragePlugin, createStoragePluginWithStorage, hasObjectKey, hasObjectKeyWithValue, isAbortError, isAbsoluteUrl, isAsString, isEncryptor, isRequestAdapterResponse, isSerializer, isStorage, normalizeHookNames, raceWithAbort, runPluginHook, runPluginsHookAsync, runPluginsHookSync, runPluginsHooksAsync, runPluginsHooksSync };