@ahoo-wang/fetcher-storage 2.8.8 → 2.9.0

package/README.md

@@ -8,18 +8,18 @@
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ahoo-wang%2Ffetcher-storage)](https://www.npmjs.com/package/@ahoo-wang/fetcher-storage)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
 
-A lightweight, cross-environment storage library with change event listening capabilities. Provides consistent API for
-browser localStorage/sessionStorage and in-memory storage with change notifications.
+A lightweight, cross-environment storage library with key-based storage and automatic environment detection. Provides
+consistent API for browser localStorage and in-memory storage with change notifications.
 
 ## Features
 
 - 🌐 Cross-environment support (Browser & Node.js)
 - 📦 Ultra-lightweight (~1KB gzip)
 - 🔔 Storage change event listening
-- 🔄 Automatic environment detection
-- 🛠️ Key-based storage with caching
+- 🔄 Automatic environment detection with fallback
+- 🛠️ Key-based storage with caching and serialization
 - 🔧 Custom serialization support
-- 📝 TypeScript support
+- 📝 Full TypeScript support
 
 ## Installation
 
@@ -29,25 +29,20 @@ npm install @ahoo-wang/fetcher-storage
 
 ## Usage
 
-### Basic Usage
+### Environment Detection and Storage Selection
 
 ```typescript
-import { createListenableStorage } from '@ahoo-wang/fetcher-storage';
+import { getStorage, isBrowser } from '@ahoo-wang/fetcher-storage';
 
-// Automatically selects the appropriate storage implementation
-const storage = createListenableStorage();
+// Check if running in browser
+console.log('Is browser:', isBrowser());
 
-// Use like regular Storage API
+// Get appropriate storage for current environment
+const storage = getStorage(); // localStorage in browser, InMemoryStorage in Node.js
+
+// Use like standard Storage API
 storage.setItem('key', 'value');
 const value = storage.getItem('key');
-
-// Listen for storage changes
-const removeListener = storage.addListener(event => {
-  console.log('Storage changed:', event);
-});
-
-// Remove listener when no longer needed
-removeListener();
 ```
 
 ### Key-based Storage with Caching
@@ -55,19 +50,22 @@ removeListener();
 ```typescript
 import { KeyStorage } from '@ahoo-wang/fetcher-storage';
 
-// Create a storage for a specific key
+// Create typed storage for a specific key
 const userStorage = new KeyStorage<{ name: string; age: number }>({
   key: 'user',
 });
 
-// Set and get values
+// Set and get values with automatic caching
 userStorage.set({ name: 'John', age: 30 });
 const user = userStorage.get(); // {name: 'John', age: 30}
 
 // Listen for changes to this specific key
 const removeListener = userStorage.addListener(event => {
-  console.log('User changed:', event.newValue);
+  console.log('User changed:', event.newValue, 'from:', event.oldValue);
 });
+
+// Clean up when done
+removeListener();
 ```
 
 ### Custom Serialization
@@ -75,58 +73,115 @@ const removeListener = userStorage.addListener(event => {
 ```typescript
 import { KeyStorage, JsonSerializer } from '@ahoo-wang/fetcher-storage';
 
+// Use JSON serialization (default)
 const jsonStorage = new KeyStorage<any>({
   key: 'data',
   serializer: new JsonSerializer(),
 });
 
-jsonStorage.set({ message: 'Hello World' });
-const data = jsonStorage.get(); // {message: 'Hello World'}
+jsonStorage.set({ message: 'Hello World', timestamp: Date.now() });
+const data = jsonStorage.get(); // {message: 'Hello World', timestamp: 1234567890}
 ```
 
-### Environment-specific Storage
+### In-Memory Storage
 
 ```typescript
-import {
-  BrowserListenableStorage,
-  InMemoryListenableStorage,
-} from '@ahoo-wang/fetcher-storage';
+import { InMemoryStorage } from '@ahoo-wang/fetcher-storage';
+
+// Create in-memory storage (works in any environment)
+const memoryStorage = new InMemoryStorage();
+
+// Use like standard Storage API
+memoryStorage.setItem('temp', 'data');
+console.log(memoryStorage.getItem('temp')); // 'data'
+console.log(memoryStorage.length); // 1
+```
 
-// Browser storage (wraps localStorage or sessionStorage)
-const browserStorage = new BrowserListenableStorage(localStorage);
+### Advanced Configuration
 
-// In-memory storage (works in any environment)
-const memoryStorage = new InMemoryListenableStorage();
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+// Custom storage and event bus
+const customStorage = new KeyStorage<string>({
+  key: 'custom',
+  storage: new InMemoryStorage(), // Use in-memory instead of localStorage
+  // eventBus: customEventBus, // Custom event bus for notifications
+});
 ```
 
-## API
+## API Reference
 
-### createListenableStorage()
+### Environment Utilities
 
-Factory function that automatically returns the appropriate storage implementation based on the environment:
+#### `isBrowser(): boolean`
 
-- Browser environment: `BrowserListenableStorage` wrapping `localStorage`
-- Non-browser environment: `InMemoryListenableStorage`
+Checks if the current environment is a browser.
 
-### ListenableStorage
+#### `getStorage(): Storage`
 
-Extends the native `Storage` interface with event listening capabilities:
+Returns the appropriate storage implementation:
 
-- `addListener(listener: StorageListener): RemoveStorageListener`
-- All standard `Storage` methods (`getItem`, `setItem`, `removeItem`, etc.)
+- Browser: `window.localStorage` (with availability check)
+- Non-browser: `InMemoryStorage` instance
 
 ### KeyStorage
 
-A storage wrapper for managing a single value associated with a specific key:
+A storage wrapper for managing typed values with caching and change notifications.
+
+```typescript
+new KeyStorage<T>(options
+:
+KeyStorageOptions<T>
+)
+```
+
+#### Options
 
-- Automatic caching with cache invalidation
-- Key-specific event listening
-- Custom serialization support
+- `key: string` - Storage key
+- `serializer?: Serializer<string, T>` - Custom serializer (default: JsonSerializer)
+- `storage?: Storage` - Custom storage (default: getStorage())
+- `eventBus?: TypedEventBus<StorageEvent<T>>` - Custom event bus
+
+#### Methods
+
+- `get(): T | null` - Get cached value
+- `set(value: T): void` - Set value with caching and notification
+- `remove(): void` - Remove value and clear cache
+- `addListener(handler: EventHandler<StorageEvent<T>>): RemoveStorageListener` - Add change listener
+
+### InMemoryStorage
+
+In-memory implementation of the Storage interface.
+
+```typescript
+new InMemoryStorage();
+```
+
+Implements all standard Storage methods with Map-based storage.
 
 ### Serializers
 
-- `JsonSerializer`: Serializes values to/from JSON strings
-- `IdentitySerializer`: Passes values through without modification
+#### `JsonSerializer`
+
+Serializes values to/from JSON strings.
+
+#### `typedIdentitySerializer<T>()`
+
+Identity serializer that passes values through unchanged.
+
+## TypeScript Support
+
+Full TypeScript support with generics and type inference:
+
+```typescript
+// Typed storage
+const userStorage = new KeyStorage<User>({ key: 'user' });
+
+// Type-safe operations
+userStorage.set({ id: 1, name: 'John' });
+const user = userStorage.get(); // User | null
+```
 
 ## License
 

package/README.zh-CN.md

@@ -8,17 +8,17 @@
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ahoo-wang%2Ffetcher-storage)](https://www.npmjs.com/package/@ahoo-wang/fetcher-storage)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
 
-一个轻量级的跨环境存储库，具有变更事件监听功能。为浏览器 localStorage/sessionStorage 和内存存储提供一致的 API，并支持变更通知。
+一个轻量级的跨环境存储库，具有基于键的存储和自动环境检测功能。为浏览器 localStorage 和内存存储提供一致的 API，并支持变更通知。
 
 ## 特性
 
 - 🌐 跨环境支持（浏览器和 Node.js）
 - 📦 超轻量级（~1KB gzip）
 - 🔔 存储变更事件监听
-- 🔄 自动环境检测
-- 🛠️ 基于键的存储和缓存
+- 🔄 自动环境检测和降级处理
+- 🛠️ 基于键的存储、缓存和序列化
 - 🔧 自定义序列化支持
-- 📝 TypeScript 支持
+- 📝 完整的 TypeScript 支持
 
 ## 安装
 
@@ -28,25 +28,20 @@ npm install @ahoo-wang/fetcher-storage
 
 ## 使用方法
 
-### 基本用法
+### 环境检测和存储选择
 
 ```typescript
-import { createListenableStorage } from '@ahoo-wang/fetcher-storage';
+import { getStorage, isBrowser } from '@ahoo-wang/fetcher-storage';
 
-// 自动选择合适的存储实现
-const storage = createListenableStorage();
+// 检查是否在浏览器环境中运行
+console.log('是否为浏览器:', isBrowser());
 
-// 像使用常规 Storage API 一样使用
+// 获取当前环境的合适存储
+const storage = getStorage(); // 浏览器中使用 localStorage，Node.js 中使用 InMemoryStorage
+
+// 像标准 Storage API 一样使用
 storage.setItem('key', 'value');
 const value = storage.getItem('key');
-
-// 监听存储变更
-const removeListener = storage.addListener(event => {
-  console.log('存储变更:', event);
-});
-
-// 不再需要时移除监听器
-removeListener();
 ```
 
 ### 基于键的存储和缓存
@@ -54,19 +49,22 @@ removeListener();
 ```typescript
 import { KeyStorage } from '@ahoo-wang/fetcher-storage';
 
-// 为特定键创建存储
+// 为特定键创建类型化的存储
 const userStorage = new KeyStorage<{ name: string; age: number }>({
   key: 'user',
 });
 
-// 设置和获取值
+// 设置和获取值，自动缓存
 userStorage.set({ name: 'John', age: 30 });
 const user = userStorage.get(); // {name: 'John', age: 30}
 
 // 监听此特定键的变更
 const removeListener = userStorage.addListener(event => {
-  console.log('用户变更:', event.newValue);
+  console.log('用户变更:', event.newValue, '来自:', event.oldValue);
 });
+
+// 使用完毕后清理
+removeListener();
 ```
 
 ### 自定义序列化
@@ -74,58 +72,112 @@ const removeListener = userStorage.addListener(event => {
 ```typescript
 import { KeyStorage, JsonSerializer } from '@ahoo-wang/fetcher-storage';
 
+// 使用 JSON 序列化（默认）
 const jsonStorage = new KeyStorage<any>({
   key: 'data',
   serializer: new JsonSerializer(),
 });
 
-jsonStorage.set({ message: 'Hello World' });
-const data = jsonStorage.get(); // {message: 'Hello World'}
+jsonStorage.set({ message: 'Hello World', timestamp: Date.now() });
+const data = jsonStorage.get(); // {message: 'Hello World', timestamp: 1234567890}
 ```
 
-### 环境特定的存储
+### 内存存储
 
 ```typescript
-import {
-  BrowserListenableStorage,
-  InMemoryListenableStorage,
-} from '@ahoo-wang/fetcher-storage';
+import { InMemoryStorage } from '@ahoo-wang/fetcher-storage';
 
-// 浏览器存储（包装 localStorage 或 sessionStorage）
-const browserStorage = new BrowserListenableStorage(localStorage);
+// 创建内存存储（在任何环境中都能工作）
+const memoryStorage = new InMemoryStorage();
 
-// 内存存储（在任何环境中都能工作）
-const memoryStorage = new InMemoryListenableStorage();
+// 像标准 Storage API 一样使用
+memoryStorage.setItem('temp', 'data');
+console.log(memoryStorage.getItem('temp')); // 'data'
+console.log(memoryStorage.length); // 1
 ```
 
-## API
+### 高级配置
 
-### createListenableStorage()
+```typescript
+import { KeyStorage, InMemoryStorage } from '@ahoo-wang/fetcher-storage';
 
-工厂函数，根据环境自动返回合适的存储实现：
+// 自定义存储和事件总线
+const customStorage = new KeyStorage<string>({
+  key: 'custom',
+  storage: new InMemoryStorage(), // 使用内存存储而不是 localStorage
+  // eventBus: customEventBus, // 自定义事件总线用于通知
+});
+```
+
+## API 参考
+
+### 环境工具
+
+#### `isBrowser(): boolean`
 
-- 浏览器环境：包装 localStorage 的 `BrowserListenableStorage`
-- 非浏览器环境：`InMemoryListenableStorage`
+检查当前环境是否为浏览器。
 
-### ListenableStorage
+#### `getStorage(): Storage`
 
-扩展了原生 `Storage` 接口，增加了事件监听功能：
+返回合适的存储实现：
 
-- `addListener(listener: StorageListener): RemoveStorageListener`
-- 所有标准 `Storage` 方法（`getItem`、`setItem`、`removeItem` 等）
+- 浏览器：`window.localStorage`（带可用性检查）
+- 非浏览器：`InMemoryStorage` 实例
 
 ### KeyStorage
 
-用于管理与特定键关联的单个值的存储包装器：
+用于管理类型化值、缓存和变更通知的存储包装器。
+
+```typescript
+new KeyStorage<T>(options: KeyStorageOptions<T>)
+```
+
+#### 选项
 
-- 自动缓存和缓存失效
-- 键特定的事件监听
-- 自定义序列化支持
+- `key: string` - 存储键
+- `serializer?: Serializer<string, T>` - 自定义序列化器（默认：JsonSerializer）
+- `storage?: Storage` - 自定义存储（默认：getStorage()）
+- `eventBus?: TypedEventBus<StorageEvent<T>>` - 自定义事件总线
+
+#### 方法
+
+- `get(): T | null` - 获取缓存的值
+- `set(value: T): void` - 设置值并缓存和通知
+- `remove(): void` - 移除值并清除缓存
+- `addListener(handler: EventHandler<StorageEvent<T>>): RemoveStorageListener` - 添加变更监听器
+
+### InMemoryStorage
+
+Storage 接口的内存实现。
+
+```typescript
+new InMemoryStorage();
+```
+
+使用 Map 实现所有标准 Storage 方法。
 
 ### 序列化器
 
-- `JsonSerializer`：将值序列化为 JSON 字符串
-- `IdentitySerializer`：不进行修改直接传递值
+#### `JsonSerializer`
+
+将值序列化为 JSON 字符串。
+
+#### `typedIdentitySerializer<T>()`
+
+恒等序列化器，直接传递值而不修改。
+
+## TypeScript 支持
+
+完整的 TypeScript 支持，包括泛型和类型推断：
+
+```typescript
+// 类型化存储
+const userStorage = new KeyStorage<User>({ key: 'user' });
+
+// 类型安全操作
+userStorage.set({ id: 1, name: 'John' });
+const user = userStorage.get(); // User | null
+```
 
 ## 许可证
 

package/dist/env.d.ts

@@ -1,2 +1,12 @@
+/**
+ * Checks if the current environment is a browser.
+ * @returns True if running in a browser environment, false otherwise
+ */
 export declare function isBrowser(): boolean;
+/**
+ * Gets the appropriate storage implementation based on the environment.
+ * Returns localStorage in browser environments if available, InMemoryStorage otherwise.
+ * @returns A Storage-compatible object
+ */
+export declare const getStorage: () => Storage;
 //# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAaA,wBAAgB,SAAS,IAAI,OAAO,CAEnC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,OAK7B,CAAC"}

package/dist/{inMemoryListenableStorage.d.ts → inMemoryStorage.d.ts}

@@ -1,11 +1,5 @@
-import { ListenableStorage, RemoveStorageListener, StorageListener } from './listenableStorage';
-/**
- * An in-memory implementation of ListenableStorage that works in any environment.
- * This implementation stores data in a Map and manually fires storage events when data changes.
- */
-export declare class InMemoryListenableStorage implements ListenableStorage {
+export declare class InMemoryStorage implements Storage {
     private readonly store;
-    private readonly listeners;
     /**
      * Gets the number of items stored in the storage.
      */
@@ -37,16 +31,5 @@ export declare class InMemoryListenableStorage implements ListenableStorage {
      * @param value - The value to set
      */
     setItem(key: string, value: string): void;
-    /**
-     * Adds a listener for storage changes.
-     * @param listener - The listener function to be called when storage changes
-     * @returns A function that can be called to remove the listener
-     */
-    addListener(listener: StorageListener): RemoveStorageListener;
-    /**
-     * Notifies all listeners of a storage change by creating and dispatching a StorageEvent.
-     * @param eventInit - The initialization object for the StorageEvent
-     */
-    private notifyListeners;
 }
-//# sourceMappingURL=inMemoryListenableStorage.d.ts.map
+//# sourceMappingURL=inMemoryStorage.d.ts.map

package/dist/inMemoryStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryStorage.d.ts","sourceRoot":"","sources":["../src/inMemoryStorage.ts"],"names":[],"mappings":"AAaA,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IAExD;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKnC;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKjC;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAG1C"}

package/dist/index.d.ts

@@ -1,7 +1,5 @@
 export * from './env';
-export * from './listenableStorage';
-export * from './browserListenableStorage';
-export * from './inMemoryListenableStorage';
 export * from './keyStorage';
+export * from './inMemoryStorage';
 export * from './serializer';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,OAAO,CAAC;AACtB,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC"}