@qlover/fe-corekit 1.4.1 → 1.5.0

package/dist/index.d.ts

@@ -2098,7 +2098,7 @@ declare class RequestTransaction<Config extends RequestAdapterConfig<unknown>> e
  * @example
  * ```typescript
  * // JSON serialization implementation
- * class JSONSerializer implements Serializer {
+ * class JSONSerializer implements SerializerIneterface {
  *   serialize(data: any): string {
  *     return JSON.stringify(data);
  *   }
@@ -2109,7 +2109,7 @@ declare class RequestTransaction<Config extends RequestAdapterConfig<unknown>> e
  * }
  * ```
  */
-interface Serializer<T = unknown, R = string> {
+interface SerializerIneterface<T = unknown, R = string> {
     /**
      * Serializes data into a target format
      * @since 1.0.10
@@ -2127,6 +2127,32 @@ interface Serializer<T = unknown, R = string> {
     deserialize(data: R, defaultValue?: T): T;
 }
 
+interface JSONSerializerOptions {
+    /**
+     * Enable pretty printing of JSON output
+     * Adds automatic indentation and line breaks for better readability
+     *
+     * @since 1.0.10
+     * @default false
+     */
+    pretty?: boolean;
+    /**
+     * Number of spaces to use for indentation when pretty printing
+     * Only used when pretty is true
+     *
+     * @since 1.0.10
+     * @default 2
+     */
+    indent?: number;
+    /**
+     * Custom replacer function for JSON.stringify
+     * Allows custom transformation during serialization
+     * Note: Will be wrapped to handle line endings
+     *
+     * @since 1.0.10
+     */
+    replacer?: (this: unknown, key: string, value: unknown) => unknown;
+}
 /**
  * Enhanced JSON serialization implementation that combines standard JSON API with additional features
  *
@@ -2148,7 +2174,7 @@ interface Serializer<T = unknown, R = string> {
  * 3. Configuration file parsing with error handling
  * 4. Cross-platform data exchange
  *
- * @implements {Serializer<unknown, string>} - Generic serialization interface
+ * @implements {SerializerIneterface<unknown, string>} - Generic serialization interface
  * @implements {JSON} - Standard JSON interface compatibility
  * @todo - If circular reference is detected, the error message is not very friendly, can use [flatted](https://www.npmjs.com/package/flatted) to improve it
  * @since 1.0.10
@@ -2185,39 +2211,35 @@ interface Serializer<T = unknown, R = string> {
  * JSON.parse('{ "name": "test" }'); // same as JSON.parse('{ "name": "test" }')
  * ```
  */
-declare class JSONSerializer implements Serializer<unknown, string>, JSON {
-    private options;
+declare class JSONSerializer<T = unknown, Opt extends JSONSerializerOptions = JSONSerializerOptions> implements SerializerIneterface<T, string>, JSON {
+    /**
+     * Options for JSONSerializer
+     *
+     * @since 1.5.0
+     * @default `{}`
+     */
+    protected options: Opt;
     /**
      * Implements Symbol.toStringTag to properly identify this class
      * Required by JSON interface
+     *
+     * When this object calls toString, it returns this value
+     *
+     * @example
+     * ```typescript
+     * const serializer = new JSONSerializer();
+     * serializer.toString(); // returns '[object JSONSerializer]'
+     * ```
      */
     readonly [Symbol.toStringTag] = "JSONSerializer";
-    constructor(options?: {
-        /**
-         * Enable pretty printing of JSON output
-         * Adds automatic indentation and line breaks for better readability
-         *
-         * @since 1.0.10
-         * @default false
-         */
-        pretty?: boolean;
-        /**
-         * Number of spaces to use for indentation when pretty printing
-         * Only used when pretty is true
-         *
-         * @since 1.0.10
-         * @default 2
-         */
-        indent?: number;
-        /**
-         * Custom replacer function for JSON.stringify
-         * Allows custom transformation during serialization
-         * Note: Will be wrapped to handle line endings
-         *
-         * @since 1.0.10
-         */
-        replacer?: (this: unknown, key: string, value: unknown) => unknown;
-    });
+    constructor(
+    /**
+     * Options for JSONSerializer
+     *
+     * @since 1.5.0
+     * @default `{}`
+     */
+    options?: Opt);
     /**
      * Creates a replacer function that handles line endings normalization
      *
@@ -2231,12 +2253,11 @@ declare class JSONSerializer implements Serializer<unknown, string>, JSON {
      * 2. Function replacer - Wrapped to handle line endings
      * 3. Null/undefined - Creates default line ending handler
      *
-     * @private
      * @param replacer - Custom replacer function or array of properties to include
      * @returns Replacer function or array of properties to include
      * @since 1.0.10
      */
-    private createReplacer;
+    protected createReplacer(replacer?: ((this: unknown, key: string, value: unknown) => unknown) | (number | string)[] | null): ((this: unknown, key: string, value: unknown) => unknown) | (number | string)[] | null;
     /**
      * Enhanced JSON.stringify with additional features
      *
@@ -2288,7 +2309,7 @@ declare class JSONSerializer implements Serializer<unknown, string>, JSON {
      * @since 1.0.10
      * @returns Parsed value
      */
-    deserialize(data: string, defaultValue?: unknown): unknown;
+    deserialize(data: string, defaultValue?: T): T;
     /**
      * Optimized serialization for arrays of primitive values
      * Avoids object property enumeration
@@ -2302,14 +2323,21 @@ declare class JSONSerializer implements Serializer<unknown, string>, JSON {
 
 /**
  * Base64 serialization implementation
- * Provides string-to-base64 encoding/decoding with optional compression
+ * Cross-platform string-to-base64 encoding/decoding for both browser and Node.js
+ *
+ * Significance: Provides universal Base64 serialization across different JavaScript environments
+ * Core idea: Environment-aware Base64 encoding with consistent API
+ * Main function: Convert strings to/from Base64 with optional URL-safe encoding
+ * Main purpose: Enable cross-platform data serialization with Base64 encoding
  *
  * Features:
+ * - Cross-platform compatibility (Browser + Node.js)
  * - Base64 encoding/decoding
  * - UTF-8 support
  * - URL-safe encoding option
+ * - Robust error handling
  *
- * @implements {Serializer<string, string>}
+ * @implements {SerializerIneterface<string, string>}
  *
  * @since 1.0.10
  *
@@ -2318,13 +2346,13 @@ declare class JSONSerializer implements Serializer<unknown, string>, JSON {
  * const serializer = new Base64Serializer({ urlSafe: true });
  *
  * // Encode string to base64
- * const encoded = serializer.stringify("Hello World!");
+ * const encoded = serializer.serialize("Hello World!");
  *
  * // Decode base64 back to string
- * const decoded = serializer.parse(encoded);
+ * const decoded = serializer.deserialize(encoded);
  * ```
  */
-declare class Base64Serializer implements Serializer<string, string> {
+declare class Base64Serializer implements SerializerIneterface<string, string> {
     private options;
     constructor(options?: {
         /**
@@ -2336,7 +2364,20 @@ declare class Base64Serializer implements Serializer<string, string> {
         urlSafe?: boolean;
     });
     /**
-     * Serializes string to base64
+     * Detects if running in Node.js environment
+     * @private
+     * @returns True if in Node.js, false if in browser
+     */
+    private isNodeEnvironment;
+    /**
+     * Validates if a string is a valid Base64 encoded string
+     * @private
+     * @param value - The string to validate
+     * @returns True if valid Base64, false otherwise
+     */
+    private isValidBase64;
+    /**
+     * Serializes string to base64 using environment-appropriate method
      * @override
      * @since 1.0.10
      * @param data - String to encode
@@ -2344,7 +2385,7 @@ declare class Base64Serializer implements Serializer<string, string> {
      */
     serialize(data: string): string;
     /**
-     * Deserializes base64 string back to original
+     * Deserializes base64 string back to original using environment-appropriate method
      * @override
      * @since 1.0.10
      * @param data - Base64 string to decode
@@ -2370,238 +2411,519 @@ declare class Base64Serializer implements Serializer<string, string> {
 }
 
 /**
- * Interface representing a synchronous storage mechanism.
+ * Interface representing an asynchronous storage mechanism.
  *
  * @template Key - The type of keys used to identify stored values.
  * @template ValueType - The type of values stored, defaults to unknown.
  *
  * @example
+ *
  * ```typescript
- * const storage: SyncStorage<string, number> = ...;
- * storage.setItem('key', 123);
- * const value = storage.getItem('key', 0);
+ * const storage: AsyncStorage<string, number> = ...;
+ * await storage.setItem('key', 123);
+ * const value = await storage.getItem('key', 0);
  * ```
+ *
  */
-interface SyncStorage<Key, ValueType = unknown> {
+interface AsyncStorageInterface<Key, ValueType = unknown> {
     /**
      * The number of items stored.
      */
     readonly length: number;
     /**
-     * Stores a value with the specified key.
+     * Asynchronously stores a value with the specified key.
      *
      * @param key - The key to identify the stored value.
      * @param value - The value to store.
      * @param options - Optional parameters for storage.
+     * @returns A promise that resolves when the value is stored.
      */
-    setItem<T>(key: Key, value: T, options?: unknown): void;
+    setItem<T>(key: Key, value: T, options?: unknown): Promise<void>;
     /**
-     * Retrieves a value by key.
+     * Asynchronously retrieves a value by key.
      *
      * @param key - The key of the value to retrieve.
      * @param defaultValue - The default value to return if the key is not found.
      * @param options - Optional parameters for retrieval.
-     * @returns The value associated with the key, or the default value if not found.
+     * @returns A promise that resolves to the value associated with the key, or the default value if not found.
      */
-    getItem<T extends ValueType>(key: Key, defaultValue?: T, options?: unknown): T | null;
+    getItem<T extends ValueType>(key: Key, defaultValue?: T, options?: unknown): Promise<T | null>;
     /**
-     * Removes a value by key.
+     * Asynchronously removes a value by key.
      *
      * @param key - The key of the value to remove.
      * @param options - Optional parameters for removal.
+     * @returns A promise that resolves when the value is removed.
      */
-    removeItem(key: Key, options?: unknown): void;
+    removeItem(key: Key, options?: unknown): Promise<void>;
     /**
-     * Clears all stored values.
+     * Asynchronously clears all stored values.
+     *
+     * @returns A promise that resolves when all values are cleared.
      */
-    clear(): void;
+    clear(): Promise<void>;
 }
+
+interface ExpireOptions {
+    /**
+     * Expire time
+     *
+     * maybe is
+     * - number: milliseconds
+     * - string: time string, like '1d', '1h', '1m', '1s'
+     * - object: {}
+     * - ...
+     *
+     * Subclass implementation
+     */
+    expires?: unknown;
+}
+
 /**
- * Interface representing an asynchronous storage mechanism.
+ * Interface representing a synchronous storage mechanism.
  *
  * @template Key - The type of keys used to identify stored values.
  * @template ValueType - The type of values stored, defaults to unknown.
  *
  * @example
- *
  * ```typescript
- * const storage: AsyncStorage<string, number> = ...;
- * await storage.setItem('key', 123);
- * const value = await storage.getItem('key', 0);
+ * const storage: SyncStorage<string, number> = ...;
+ * storage.setItem('key', 123);
+ * const value = storage.getItem('key', 0);
  * ```
- *
  */
-interface AsyncStorage<Key, ValueType = unknown> {
+interface SyncStorageInterface<Key, Opt = unknown> {
     /**
      * The number of items stored.
      */
     readonly length: number;
     /**
-     * Asynchronously stores a value with the specified key.
+     * Stores a value with the specified key.
      *
      * @param key - The key to identify the stored value.
      * @param value - The value to store.
      * @param options - Optional parameters for storage.
-     * @returns A promise that resolves when the value is stored.
      */
-    setItem<T>(key: Key, value: T, options?: unknown): Promise<void>;
+    setItem<T>(key: Key, value: T, options?: Opt): void | unknown;
     /**
-     * Asynchronously retrieves a value by key.
+     * Retrieves a value by key.
      *
      * @param key - The key of the value to retrieve.
      * @param defaultValue - The default value to return if the key is not found.
      * @param options - Optional parameters for retrieval.
-     * @returns A promise that resolves to the value associated with the key, or the default value if not found.
+     * @returns The value associated with the key, or the default value if not found.
      */
-    getItem<T extends ValueType>(key: Key, defaultValue?: T, options?: unknown): Promise<T | null>;
+    getItem<T>(key: Key, defaultValue?: T, options?: Opt): T | null;
     /**
-     * Asynchronously removes a value by key.
+     * Removes a value by key.
      *
      * @param key - The key of the value to remove.
      * @param options - Optional parameters for removal.
-     * @returns A promise that resolves when the value is removed.
      */
-    removeItem(key: Key, options?: unknown): Promise<void>;
+    removeItem(key: Key, options?: Opt): void;
     /**
-     * Asynchronously clears all stored values.
+     * Clears all stored values.
+     */
+    clear(): void;
+    /**
+     * Get the raw value from the storage.
      *
-     * @returns A promise that resolves when all values are cleared.
+     * 通过这个方法可以获取到内部原始的值
+     *
+     * @param value - The value to get the raw value from.
+     * @returns The raw value.
      */
-    clear(): Promise<void>;
+    getRawValue?<T>(value: unknown, defaultValue?: T, options?: Opt): T | null;
+}
+
+interface KeyStorageOptions<Key, Sopt = unknown> extends ExpireOptions {
+    /**
+     * Persistent storage
+     */
+    storage?: SyncStorageInterface<Key, Sopt>;
+}
+declare abstract class KeyStorageInterface<Key, Value, Opt extends KeyStorageOptions<Key> = KeyStorageOptions<Key>> {
+    readonly key: Key;
+    protected options: Opt;
+    protected value: Value | null;
+    constructor(key: Key, options?: Opt);
+    getKey(): Key;
+    getValue(): Value | null;
+    abstract get(options?: Opt): Value | null;
+    abstract set(value: Value, options?: Opt): void;
+    abstract remove(options?: Opt): void;
 }
 
 /**
- * Represents a storage mechanism for JSON-serializable data.
+ * KeyStorage is a storage that can be used to store a single value.
  *
- * This class provides a way to store, retrieve, and manage JSON data
- * with optional expiration times. It can operate with a provided
- * synchronous storage backend or use an internal store.
+ * Typical usage scenario: need to store a value and need to persist it:
  *
- * The main purpose of this class is to facilitate the storage of
- * complex data structures in a serialized JSON format, allowing
- * for easy retrieval and management.
+ * - token storage
+ * - user info storage
+ * - page theme, language
+ * - ...
  *
- * inner serializer is used by default, which is `JSONSerializer`.
+ * 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!
  *
- * @since 1.0.17
+ * @since 1.5.0
  *
- * @example
+ * @example basic usage
  *
- * A simple example of how to use the JSONStorage class
+ * use localStorage as storage, persist the value
  *
  * ```typescript
- * const storage = new JSONStorage();
- * storage.setItem('key', { data: 'value' }, 3600);
- * const value = storage.getItem('key');
- * // => { data: 'value' }
- * ```
- * @example
+ * const tokenStorage = new KeyStorage('token', localStorage);
  *
- * If need persistent storage, you can use `localStorage` or `sessionStorage`
+ * tokenStorage.get(); // get from localStorage
+ * tokenStorage.set('token-123123123'); // set to localStorage
+ * tokenStorage.remove(); // remove from localStorage
+ * ```
  *
+ * @example with encrypt
  * ```typescript
- * const storage = new JSONStorage(localStorage);
- * storage.setItem('key', { data: 'value' }, 3600);
- * const value = storage.getItem('key');
- * // => { data: 'value' }
+ * const tokenStorage = new KeyStorage('token', localStorage, {
+ *   encrypt: new Encryptor(new AESCipher('1234567890'))
+ * });
+ *
+ * tokenStorage.get(); // get from localStorage
+ * tokenStorage.set('token-123123123'); // set to localStorage
+ * tokenStorage.remove(); // remove from localStorage
  * ```
+ */
+declare class KeyStorage<Key, Value, Opt extends KeyStorageOptions<Key> = KeyStorageOptions<Key>> extends KeyStorageInterface<Key, Value, Opt> {
+    protected value: Value | null;
+    protected mergeOptions(options?: Opt): Opt;
+    get(options?: Opt): Value | null;
+    set(token: Value, options?: Opt): void;
+    remove(options?: Opt): void;
+}
+
+interface ObjectStorageOptions extends ExpireOptions {
+}
+/**
+ * Storage value wrapper with expiration support
  *
- * @example
+ * Significance: Provides a standardized structure for stored values with metadata
+ * Core idea: Encapsulate stored data with key, value, and optional expiration time
+ * Main function: Wrap user data with storage metadata
+ * Main purpose: Enable expiration-aware storage operations
  *
- * Or use custom serializer and storage
+ * @template Key - The type of the storage key
+ * @template ValueType - The type of the stored value
  *
+ * @example
  * ```typescript
- * // use native JSON
- * const customSerializer = {
- *   serialize: JSON.stringify,
- *   deserialize: JSON.parse,
+ * const storageValue: StorageValue<string, number> = {
+ *   key: 'user-id',
+ *   value: 12345,
+ *   expires: Date.now() + 3600000 // 1 hour from now
  * };
+ * ```
+ */
+type StorageValue<Key, ValueType> = {
+    /** The storage key */
+    key: Key;
+    /** The actual stored value */
+    value: ValueType;
+    /** Optional expiration timestamp in milliseconds */
+    expires?: number;
+};
+/**
+ * Object-based storage implementation with memory caching and optional persistence
  *
- * // can use localStorage or sessionStorage
- * const customStorage = {
- *   setItem: (key: string, value: string) => {
- *     localStorage.setItem(key, value);
- *   },
- *   getItem: (key: string) => {
- *     return localStorage.getItem(key);
- *   },
- *   removeItem: (key: string) => {
- *     localStorage.removeItem(key);
- *   },
- *   clear: () => {
- *     localStorage.clear();
- *   },
- * };
+ * Significance: Provides a high-performance storage solution with dual-layer architecture
+ * Core idea: Combine in-memory caching with optional persistent storage for optimal performance
+ * Main function: Store and retrieve data with expiration support and automatic cache management
+ * Main purpose: Enable fast data access with persistence and expiration capabilities
+ *
+ * Features:
+ * - In-memory caching for fast access
+ * - Optional persistent storage backend
+ * - Automatic expiration handling
+ * - Type-safe operations with generics
+ * - Serialization support for complex data types
+ *
+ * @template Key - The type of storage keys
+ * @template ValueType - The type of stored values (defaults to string)
+ *
+ * @example
+ * ```typescript
+ * import { ObjectStorage } from './ObjectStorage';
+ * import { JsonSerializer } from '../serializer';
+ *
+ * // Create storage with JSON serializer
+ * const storage = new ObjectStorage(
+ *   new JsonSerializer(),
+ *   localStorage // optional persistent storage
+ * );
+ *
+ * // Store data with expiration
+ * storage.setItem('user-session', { userId: 123 }, Date.now() + 3600000);
  *
- * const storage = new JSONStorage(customStorage, customSerializer);
- * storage.setItem('key', { data: 'value' }, 3600);
- * const value = storage.getItem('key');
+ * // Retrieve data
+ * const session = storage.getItem('user-session');
  * ```
  *
+ * @since 1.5.0
  */
-declare class JSONStorage implements SyncStorage<string> {
+declare class ObjectStorage<Key, ValueType = string, Opt extends ObjectStorageOptions = ObjectStorageOptions> implements SyncStorageInterface<Key, Opt> {
     /**
-     * The storage backend to use.
+     * Serializer for data transformation
+     *
+     * Significance: Enables storage of complex data types
+     * Core idea: Convert between runtime objects and storage format
+     * Main function: Serialize/deserialize storage values
+     * Main purpose: Support type-safe storage operations
      */
-    private readonly storage?;
+    protected readonly serializer?: SerializerIneterface<unknown, ValueType> | undefined;
     /**
-     * The serializer used to serialize and deserialize the data.
+     * In-memory storage map for fast data access
      *
-     * **serializer and deserialize is only support sync operation**
+     * Significance: Primary storage layer for performance optimization
+     * Core idea: Keep frequently accessed data in memory
+     * Main function: Provide instant data access without I/O operations
+     * Main purpose: Minimize latency for storage operations
      */
-    private readonly serializer;
+    protected store: Map<Key, ValueType>;
     /**
-     * The internal store for the JSONStorage class.
+     * Creates a new ObjectStorage instance
+     *
+     * @param serializer - Serializer for converting between storage values and stored format
+     * @param persistent - Optional persistent storage backend for data durability
      *
-     * If `storage` is not provided, it is stored in memory by default.
+     * @example
+     * ```typescript
+     * const storage = new ObjectStorage(
+     *   new JsonSerializer(),
+     *   localStorage
+     * );
+     * ```
      */
-    private store;
+    constructor(
     /**
-     * Initializes a new instance of the JSONStorage class.
+     * Serializer for data transformation
      *
-     * @param storage - An optional synchronous storage backend to use.
+     * Significance: Enables storage of complex data types
+     * Core idea: Convert between runtime objects and storage format
+     * Main function: Serialize/deserialize storage values
+     * Main purpose: Support type-safe storage operations
      */
-    constructor(
+    serializer?: SerializerIneterface<unknown, ValueType> | undefined);
     /**
-     * The storage backend to use.
+     * Gets the number of items stored in the memory cache
+     *
+     * @override
+     * @returns The number of stored items in memory
+     *
+     * @example
+     * ```typescript
+     * console.log(`Storage contains ${storage.length} items`);
+     * ```
      */
-    storage?: SyncStorage<string, string> | undefined, 
+    get length(): number;
     /**
-     * The serializer used to serialize and deserialize the data.
+     * Stores a value with optional expiration time
      *
-     * **serializer and deserialize is only support sync operation**
+     * Significance: Primary method for data storage operations
+     * Core idea: Store data with metadata and optional expiration
+     * Main function: Persist data to both memory and persistent storage
+     * Main purpose: Enable reliable data storage with expiration support
+     *
+     * @override
+     * @template T - The type of the value to store
+     * @param key - The key under which the value is stored
+     * @param value - The value to store (must be serializable)
+     * @param expire - Optional expiration time in milliseconds from epoch
+     *
+     * @example
+     * ```typescript
+     * // Store without expiration
+     * storage.setItem('username', 'john_doe');
+     *
+     * // Store with expiration (1 hour)
+     * storage.setItem('session', sessionData, Date.now() + 3600000);
+     * ```
      */
-    serializer?: Serializer<unknown, string>);
+    setItem<T>(key: Key, value: T, options?: ObjectStorageOptions): unknown;
     /**
-     * Gets the number of items stored in the local storage.
+     * Retrieves a stored value by key with fallback strategy
+     *
+     * Significance: Primary method for data retrieval operations
+     * Core idea: Multi-layer retrieval with expiration checking
+     * Main function: Get data from memory first, then persistent storage
+     * Main purpose: Provide fast, reliable data access with automatic cleanup
+     *
+     * Retrieval strategy:
+     * 1. Check memory cache first
+     * 2. Fallback to persistent storage if not in memory
+     * 3. Validate expiration and cleanup if expired
+     * 4. Return default value if not found or expired
+     *
+     * @override
+     * @template T - The expected type of the retrieved value
+     * @param key - The key of the item to retrieve
+     * @param defaultValue - Default value to return if item not found or expired
+     * @returns The stored value or default value if not found/expired
+     *
+     * @example
+     * ```typescript
+     * // Get value with default
+     * const username = storage.getItem('username', 'anonymous');
      *
-     * @returns The number of stored items.
+     * // Get complex object
+     * const config = storage.getItem<AppConfig>('app-config');
+     * ```
      */
-    get length(): number;
+    getItem<T>(key: Key, defaultValue?: T): T | null;
+    getRawValue<T>(value: unknown, defaultValue?: T): T | null;
     /**
-     * Stores a value with an optional expiration time.
+     * Removes a stored item by its key from both memory and persistent storage
+     *
+     * Significance: Essential cleanup method for storage management
+     * Core idea: Synchronize removal across all storage layers
+     * Main function: Delete data from memory and persistent storage
+     * Main purpose: Maintain data consistency and free up storage space
+     *
+     * @override
+     * @param key - The key of the item to remove
      *
-     * @param key - The key under which the value is stored.
-     * @param value - The value to store, which must be JSON-serializable.
-     * @param expire - Optional expiration time in milliseconds.
+     * @example
+     * ```typescript
+     * storage.removeItem('expired-session');
+     * ```
      */
-    setItem<T>(key: string, value: T, expire?: number): void;
+    removeItem(key: Key): void;
     /**
-     * Retrieves a stored value by its key.
+     * Clears all stored items from both memory and persistent storage
      *
-     * @param key - The key of the value to retrieve.
-     * @param defaultValue - An optional default value to return if the key is not found.
-     * @returns The stored value or the default value if the key is not found or expired.
+     * Significance: Bulk cleanup method for complete storage reset
+     * Core idea: Synchronize clearing across all storage layers
+     * Main function: Remove all data from memory and persistent storage
+     * Main purpose: Provide complete storage reset capability
+     *
+     * @override
+     *
+     * @example
+     * ```typescript
+     * storage.clear(); // Removes all stored data
+     * ```
+     */
+    clear(): void;
+    /**
+     * Checks if a storage value has expired
+     *
+     * Significance: Core expiration validation logic
+     * Core idea: Compare expiration timestamp with current time
+     * Main function: Determine if stored data is still valid
+     * Main purpose: Enable automatic cleanup of expired data
+     *
+     * @param value - The storage value to check for expiration
+     * @returns True if the value has expired, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isExpired = this.isExpired(storageValue);
+     * if (isExpired) {
+     *   this.removeItem(key);
+     * }
+     * ```
+     */
+    protected isExpired(value: StorageValue<Key, ValueType>): boolean;
+    /**
+     * Type guard to check if a value is a valid StorageValue
+     *
+     * Significance: Type safety validation for deserialized data
+     * Core idea: Verify object structure matches expected StorageValue format
+     * Main function: Validate deserialized data structure
+     * Main purpose: Ensure type safety and prevent runtime errors
+     *
+     * @template Key - The type of the storage key
+     * @template ValueType - The type of the stored value
+     * @param value - The value to check
+     * @returns True if the value is a valid StorageValue, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (this.isStorageValue(deserializedValue)) {
+     *   // Safe to access .key, .value, .expire properties
+     *   return deserializedValue.value;
+     * }
+     * ```
      */
-    getItem<T>(key: string, defaultValue?: T): T | null;
+    protected isStorageValue(value: unknown): value is StorageValue<Key, ValueType>;
+    /**
+     * Gets the serializer instance
+     *
+     * Significance: Provides access to the serialization logic
+     * Core idea: Expose serializer for advanced use cases
+     * Main function: Return the serializer instance
+     * Main purpose: Enable direct access to serialization when needed
+     *
+     * @returns The serializer instance
+     *
+     * @example
+     * ```typescript
+     * const serializer = storage.getSerializer();
+     * if (serializer) {
+     *   // Direct access to serializer
+     * }
+     * ```
+     */
+    getSerializer(): SerializerIneterface<unknown, ValueType> | undefined;
+}
+
+/**
+ * Pipe processor type definition
+ *
+ * Significance: Define the type of components that can be used for data processing pipelines
+ * Core idea: Unify the type definition of different processors, supporting data transformation and intermediate storage
+ * Main function: Provide type-safe pipeline components
+ * Main purpose: Support serialization, encryption, intermediate storage, and other data processing operations
+ */
+type PipeType<Key> = SerializerIneterface<unknown, unknown> | Encryptor<unknown, unknown> | SyncStorageInterface<Key, unknown>;
+/**
+ * Pipe value definition, containing the pipe processor and its type identifier
+ *
+ * Significance: Pre-determine the pipe type to avoid runtime type checks
+ * Core idea: Bind the pipe processor with its type to improve execution efficiency
+ * Main function: Store the pipe processor and its type information
+ * Main purpose: Optimize pipe execution performance, simplify type judgment logic
+ */
+type PipeValue<Key> = {
+    type: 'serialize';
+    pipe: SerializerIneterface<unknown, unknown>;
+} | {
+    type: 'encrypt';
+    pipe: Encryptor<unknown, unknown>;
+} | {
+    type: 'storage';
+    pipe: SyncStorageInterface<Key, unknown>;
+};
+
+type PipeArg<Key> = PipeType<Key> | PipeValue<Key>;
+declare class SyncStorage<Key, Opt = unknown> implements SyncStorageInterface<Key, Opt> {
+    protected readonly storage: SyncStorageInterface<Key, Opt>;
+    /**
+     * Internal pipe value list, pre-determined type
+     */
+    protected readonly pipes: PipeValue<Key>[];
+    constructor(storage: SyncStorageInterface<Key, Opt>, pipes?: PipeArg<Key>[] | PipeArg<Key>);
+    /**
+     * Get the number of storage items
+     */
+    get length(): number;
+    setItem<T>(key: Key, value: T, options?: Opt): void;
+    getItem<T>(key: Key, defaultValue?: T, options?: Opt): T | null;
     /**
-     * Removes a stored item by its key.
+     * Delete data items, delete from all storage layers
      *
-     * @param key - The key of the item to remove.
+     * @param key - Storage key
+     * @param options - Delete options
      */
-    removeItem(key: string): void;
+    removeItem(key: Key, options?: Opt): void;
     /**
-     * Clears all stored items.
+     * Clear all data, including storage in the pipeline
      */
     clear(): void;
 }
@@ -2634,5 +2956,4 @@ type Intersection<T1, T2> = {
     [P in keyof T1 & keyof T2]: T1[P] | T2[P];
 };
 
-export { AsyncExecutor, Base64Serializer, Executor, ExecutorError, FetchAbortPlugin, FetchURLPlugin, JSONSerializer, JSONStorage, RequestAdapterAxios, RequestAdapterFetch, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, RetryPlugin, SyncExecutor };
-export type { AsyncStorage, Encryptor, ExecutorContext, ExecutorPlugin, HookRuntimes, Intersection, PromiseTask, RequestAdapterConfig, RequestAdapterFetchConfig, RequestAdapterInterface, RequestAdapterResponse, RequestTransactionInterface, RetryOptions, Serializer, SyncStorage, SyncTask, Task, ValueOf };
+export { AsyncExecutor, type AsyncStorageInterface, Base64Serializer, type Encryptor, Executor, type ExecutorContext, ExecutorError, type ExecutorPlugin, type ExpireOptions, FetchAbortPlugin, FetchURLPlugin, type HookRuntimes, type Intersection, JSONSerializer, type JSONSerializerOptions, KeyStorage, KeyStorageInterface, type KeyStorageOptions, ObjectStorage, type ObjectStorageOptions, type PipeArg, type PromiseTask, RequestAdapterAxios, type RequestAdapterConfig, RequestAdapterFetch, type RequestAdapterFetchConfig, type RequestAdapterInterface, type RequestAdapterResponse, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, type RequestTransactionInterface, type RetryOptions, RetryPlugin, type SerializerIneterface, type StorageValue, SyncExecutor, SyncStorage, type SyncStorageInterface, type SyncTask, type Task, type ValueOf };