@qlover/fe-corekit 3.1.1 → 3.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/common.d.ts +193 -0
- package/dist/common.js +0 -0
- package/dist/index.cjs +153 -280
- package/dist/index.d.ts +328 -695
- package/dist/index.iife.js +8348 -0
- package/dist/index.iife.min.js +2 -8442
- package/dist/index.js +147 -279
- package/package.json +31 -3
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
|
-
*
|
|
8640
|
+
* Asynchronous key-value storage interface.
|
|
8640
8641
|
*
|
|
8641
|
-
*
|
|
8642
|
-
*
|
|
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
|
-
*
|
|
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:
|
|
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
|
|
8654
|
-
/**
|
|
8655
|
-
* The number of items stored.
|
|
8656
|
-
*/
|
|
8657
|
-
readonly length: number;
|
|
8674
|
+
interface AsyncStorageInterface<Key, ValueType, Opt> {
|
|
8658
8675
|
/**
|
|
8659
|
-
*
|
|
8676
|
+
* Stores a value under the given key asynchronously.
|
|
8660
8677
|
*
|
|
8661
|
-
*
|
|
8662
|
-
*
|
|
8663
|
-
*
|
|
8664
|
-
* @
|
|
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
|
|
8686
|
+
setItem(key: Key, value: ValueType, options?: Opt): Promise<void>;
|
|
8667
8687
|
/**
|
|
8668
|
-
*
|
|
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 -
|
|
8671
|
-
* @param
|
|
8672
|
-
* @
|
|
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
|
|
8696
|
+
getItem(key: Key, options?: Opt): Promise<ValueType | null>;
|
|
8676
8697
|
/**
|
|
8677
|
-
*
|
|
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 -
|
|
8680
|
-
* @param
|
|
8681
|
-
* @
|
|
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
|
-
|
|
8707
|
+
getItem(key: Key, defaultValue: ValueType, options?: Opt): Promise<ValueType>;
|
|
8684
8708
|
/**
|
|
8685
|
-
*
|
|
8709
|
+
* Removes the entry for the given key asynchronously.
|
|
8686
8710
|
*
|
|
8687
|
-
*
|
|
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
|
-
|
|
8690
|
-
}
|
|
8691
|
-
|
|
8692
|
-
interface ExpireOptions {
|
|
8717
|
+
removeItem(key: Key, options?: Opt): Promise<void>;
|
|
8693
8718
|
/**
|
|
8694
|
-
*
|
|
8719
|
+
* Removes all entries in this storage asynchronously.
|
|
8695
8720
|
*
|
|
8696
|
-
*
|
|
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
|
-
*
|
|
8723
|
+
* @returns Promise that resolves when all values are cleared.
|
|
8703
8724
|
*/
|
|
8704
|
-
|
|
8725
|
+
clear(): Promise<void>;
|
|
8705
8726
|
}
|
|
8706
8727
|
|
|
8707
8728
|
/**
|
|
8708
|
-
*
|
|
8729
|
+
* Synchronous key-value storage interface.
|
|
8709
8730
|
*
|
|
8710
8731
|
* Core concept:
|
|
8711
|
-
*
|
|
8712
|
-
*
|
|
8713
|
-
*
|
|
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
|
-
* -
|
|
8719
|
-
* -
|
|
8720
|
-
* -
|
|
8721
|
-
* -
|
|
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
|
-
*
|
|
8754
|
-
*
|
|
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
|
-
*
|
|
8757
|
-
*
|
|
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
|
|
8749
|
+
* @example Basic usage
|
|
8761
8750
|
* ```typescript
|
|
8762
|
-
*
|
|
8763
|
-
*
|
|
8764
|
-
*
|
|
8765
|
-
*
|
|
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
|
|
8758
|
+
* @example With options (e.g. expiry)
|
|
8783
8759
|
* ```typescript
|
|
8784
|
-
*
|
|
8785
|
-
*
|
|
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
|
|
8764
|
+
interface StorageInterface<K, V, Opt = unknown> {
|
|
8799
8765
|
/**
|
|
8800
|
-
*
|
|
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
|
-
*
|
|
8768
|
+
* Overwrites any existing value for `key`. Implementations may use `options` for
|
|
8769
|
+
* behaviour such as TTL or storage scope.
|
|
8807
8770
|
*
|
|
8808
|
-
* @
|
|
8809
|
-
*
|
|
8810
|
-
*
|
|
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
|
-
|
|
8775
|
+
setItem(key: K, value: V, options?: Opt): void;
|
|
8815
8776
|
/**
|
|
8816
|
-
*
|
|
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
|
-
*
|
|
8779
|
+
* Returns `null` when the key is not found, so the signature stays compatible with the
|
|
8780
|
+
* browser {@link Storage} API.
|
|
8828
8781
|
*
|
|
8829
|
-
* @
|
|
8830
|
-
*
|
|
8831
|
-
*
|
|
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
|
-
|
|
8786
|
+
getItem(key: K, options?: Opt): V | null;
|
|
8846
8787
|
/**
|
|
8847
|
-
*
|
|
8788
|
+
* Retrieves the value for the given key, or the default when missing.
|
|
8848
8789
|
*
|
|
8849
|
-
*
|
|
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
|
-
*
|
|
8856
|
-
*
|
|
8857
|
-
*
|
|
8858
|
-
* @
|
|
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
|
-
|
|
8797
|
+
getItem(key: K, defaultValue: V, options?: Opt): V | null;
|
|
8895
8798
|
/**
|
|
8896
|
-
*
|
|
8799
|
+
* Removes the entry for the given key.
|
|
8897
8800
|
*
|
|
8898
|
-
*
|
|
8899
|
-
*
|
|
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
|
-
*
|
|
8905
|
-
*
|
|
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
|
-
|
|
8807
|
+
removeItem(key: K, options?: Opt): void;
|
|
8951
8808
|
/**
|
|
8952
|
-
*
|
|
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
|
-
*
|
|
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
|
-
|
|
8813
|
+
clear(): void;
|
|
8995
8814
|
}
|
|
8996
8815
|
|
|
8997
8816
|
/**
|
|
8998
|
-
*
|
|
8817
|
+
* Storage interface bound to a single fixed key.
|
|
8999
8818
|
*
|
|
9000
|
-
*
|
|
9001
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
9006
|
-
*
|
|
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
|
|
9011
|
-
/**
|
|
9012
|
-
* The number of items stored.
|
|
9013
|
-
*/
|
|
9014
|
-
readonly length: number;
|
|
8851
|
+
interface KeyStorageInterface<Key, Value, Opt = unknown> {
|
|
9015
8852
|
/**
|
|
9016
|
-
*
|
|
8853
|
+
* The single key this storage instance is bound to.
|
|
9017
8854
|
*
|
|
9018
|
-
*
|
|
9019
|
-
*
|
|
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
|
-
|
|
8858
|
+
readonly key: Key;
|
|
9023
8859
|
/**
|
|
9024
|
-
*
|
|
8860
|
+
* Reads the value for the bound key.
|
|
9025
8861
|
*
|
|
9026
|
-
* @param
|
|
9027
|
-
* @
|
|
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
|
-
|
|
8865
|
+
get(options?: Opt): Value | null;
|
|
9032
8866
|
/**
|
|
9033
|
-
*
|
|
8867
|
+
* Writes the value for the bound key.
|
|
9034
8868
|
*
|
|
9035
|
-
*
|
|
9036
|
-
*
|
|
9037
|
-
|
|
9038
|
-
|
|
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
|
-
|
|
8875
|
+
set(value: Value, options?: Opt): void;
|
|
9043
8876
|
/**
|
|
9044
|
-
*
|
|
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
|
|
9049
|
-
* @returns The raw value.
|
|
8882
|
+
* @param options - Optional parameters for removal. Type is `Opt`.
|
|
9050
8883
|
*/
|
|
9051
|
-
|
|
8884
|
+
remove(options?: Opt): void;
|
|
9052
8885
|
}
|
|
9053
8886
|
|
|
9054
|
-
|
|
9055
|
-
|
|
9056
|
-
|
|
9057
|
-
|
|
9058
|
-
storage?:
|
|
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
|
-
|
|
8895
|
+
get(options?: Opt): V | null;
|
|
9107
8896
|
/**
|
|
9108
8897
|
* @override
|
|
9109
8898
|
*/
|
|
9110
|
-
|
|
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
|
|
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
|
|
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<
|
|
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<
|
|
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):
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
9385
|
-
*
|
|
9386
|
-
*
|
|
9387
|
-
*
|
|
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
|
-
* @
|
|
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
|
|
9394
|
-
*
|
|
9395
|
-
*
|
|
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
|
-
|
|
9210
|
+
type?: 'storage' | string;
|
|
9400
9211
|
}
|
|
9401
|
-
|
|
9402
9212
|
/**
|
|
9403
|
-
*
|
|
9213
|
+
* Executes a pipeline of storage plugins, implementing `StorageInterface`.
|
|
9404
9214
|
*
|
|
9405
|
-
*
|
|
9406
|
-
*
|
|
9407
|
-
*
|
|
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
|
-
* -
|
|
9448
|
-
*
|
|
9449
|
-
*
|
|
9450
|
-
*
|
|
9451
|
-
*
|
|
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
|
-
*
|
|
9493
|
-
*
|
|
9494
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
9508
|
-
*
|
|
9509
|
-
*
|
|
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
|
|
9238
|
+
* @example Pipeline: serializer + encryptor + storage
|
|
9525
9239
|
* ```typescript
|
|
9526
|
-
*
|
|
9527
|
-
*
|
|
9528
|
-
* //
|
|
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
|
|
9245
|
+
* @example Multiple storages: getItem uses only the last storage
|
|
9554
9246
|
* ```typescript
|
|
9555
|
-
*
|
|
9556
|
-
*
|
|
9557
|
-
*
|
|
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
|
|
9575
|
-
protected
|
|
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
|
-
*
|
|
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
|
|
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(
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
|
|
9279
|
+
removeItem(key: K, options?: Opt | undefined): void;
|
|
9698
9280
|
/**
|
|
9699
|
-
*
|
|
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
|
|
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 };
|