@ahoo-wang/fetcher-storage 1.6.6 → 1.6.8

package/README.md

@@ -0,0 +1,126 @@
+# @ahoo-wang/fetcher-storage
+
+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.
+
+[![NPM version](https://img.shields.io/npm/v/@ahoo-wang/fetcher-storage.svg?style=flat-square)](https://www.npmjs.com/package/@ahoo-wang/fetcher-storage)
+[![NPM downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher-storage.svg?style=flat-square)](https://www.npmjs.com/package/@ahoo-wang/fetcher-storage)
+[![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher-storage.svg?style=flat-square)](https://github.com/Ahoo-Wang/fetcher/blob/master/LICENSE)
+
+## Features
+
+- 🌐 Cross-environment support (Browser & Node.js)
+- 📦 Ultra-lightweight (~1KB gzip)
+- 🔔 Storage change event listening
+- 🔄 Automatic environment detection
+- 🛠️ Key-based storage with caching
+- 🔧 Custom serialization support
+- 📝 TypeScript support
+
+## Installation
+
+```bash
+npm install @ahoo-wang/fetcher-storage
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createListenableStorage } from '@ahoo-wang/fetcher-storage';
+
+// Automatically selects the appropriate storage implementation
+const storage = createListenableStorage();
+
+// Use like regular 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
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+// Create a storage for a specific key
+const userStorage = new KeyStorage<{ name: string, age: number }>({
+  key: 'user'
+});
+
+// Set and get values
+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);
+});
+```
+
+### Custom Serialization
+
+```typescript
+import { KeyStorage, JsonSerializer } from '@ahoo-wang/fetcher-storage';
+
+const jsonStorage = new KeyStorage<any>({
+  key: 'data',
+  serializer: new JsonSerializer()
+});
+
+jsonStorage.set({ message: 'Hello World' });
+const data = jsonStorage.get(); // {message: 'Hello World'}
+```
+
+### Environment-specific Storage
+
+```typescript
+import { BrowserListenableStorage, InMemoryListenableStorage } from '@ahoo-wang/fetcher-storage';
+
+// Browser storage (wraps localStorage or sessionStorage)
+const browserStorage = new BrowserListenableStorage(localStorage);
+
+// In-memory storage (works in any environment)
+const memoryStorage = new InMemoryListenableStorage();
+```
+
+## API
+
+### createListenableStorage()
+
+Factory function that automatically returns the appropriate storage implementation based on the environment:
+
+- Browser environment: `BrowserListenableStorage` wrapping `localStorage`
+- Non-browser environment: `InMemoryListenableStorage`
+
+### ListenableStorage
+
+Extends the native `Storage` interface with event listening capabilities:
+
+- `addListener(listener: StorageListener): RemoveStorageListener`
+- All standard `Storage` methods (`getItem`, `setItem`, `removeItem`, etc.)
+
+### KeyStorage
+
+A storage wrapper for managing a single value associated with a specific key:
+
+- Automatic caching with cache invalidation
+- Key-specific event listening
+- Custom serialization support
+
+### Serializers
+
+- `JsonSerializer`: Serializes values to/from JSON strings
+- `IdentitySerializer`: Passes values through without modification
+
+## License
+
+[Apache 2.0](https://github.com/Ahoo-Wang/fetcher/blob/master/LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,125 @@
+# @ahoo-wang/fetcher-storage
+
+一个轻量级的跨环境存储库，具有变更事件监听功能。为浏览器 localStorage/sessionStorage 和内存存储提供一致的 API，并支持变更通知。
+
+[![NPM version](https://img.shields.io/npm/v/@ahoo-wang/fetcher-storage.svg?style=flat-square)](https://www.npmjs.com/package/@ahoo-wang/fetcher-storage)
+[![NPM downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher-storage.svg?style=flat-square)](https://www.npmjs.com/package/@ahoo-wang/fetcher-storage)
+[![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher-storage.svg?style=flat-square)](https://github.com/Ahoo-Wang/fetcher/blob/master/LICENSE)
+
+## 特性
+
+- 🌐 跨环境支持（浏览器和 Node.js）
+- 📦 超轻量级（~1KB gzip）
+- 🔔 存储变更事件监听
+- 🔄 自动环境检测
+- 🛠️ 基于键的存储和缓存
+- 🔧 自定义序列化支持
+- 📝 TypeScript 支持
+
+## 安装
+
+```bash
+npm install @ahoo-wang/fetcher-storage
+```
+
+## 使用方法
+
+### 基本用法
+
+```typescript
+import { createListenableStorage } from '@ahoo-wang/fetcher-storage';
+
+// 自动选择合适的存储实现
+const storage = createListenableStorage();
+
+// 像使用常规 Storage API 一样使用
+storage.setItem('key', 'value');
+const value = storage.getItem('key');
+
+// 监听存储变更
+const removeListener = storage.addListener((event) => {
+  console.log('存储变更:', event);
+});
+
+// 不再需要时移除监听器
+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);
+});
+```
+
+### 自定义序列化
+
+```typescript
+import { KeyStorage, JsonSerializer } from '@ahoo-wang/fetcher-storage';
+
+const jsonStorage = new KeyStorage<any>({
+  key: 'data',
+  serializer: new JsonSerializer()
+});
+
+jsonStorage.set({ message: 'Hello World' });
+const data = jsonStorage.get(); // {message: 'Hello World'}
+```
+
+### 环境特定的存储
+
+```typescript
+import { BrowserListenableStorage, InMemoryListenableStorage } from '@ahoo-wang/fetcher-storage';
+
+// 浏览器存储（包装 localStorage 或 sessionStorage）
+const browserStorage = new BrowserListenableStorage(localStorage);
+
+// 内存存储（在任何环境中都能工作）
+const memoryStorage = new InMemoryListenableStorage();
+```
+
+## API
+
+### createListenableStorage()
+
+工厂函数，根据环境自动返回合适的存储实现：
+
+- 浏览器环境：包装 localStorage 的 `BrowserListenableStorage`
+- 非浏览器环境：`InMemoryListenableStorage`
+
+### ListenableStorage
+
+扩展了原生 `Storage` 接口，增加了事件监听功能：
+
+- `addListener(listener: StorageListener): RemoveStorageListener`
+- 所有标准 `Storage` 方法（`getItem`、`setItem`、`removeItem` 等）
+
+### KeyStorage
+
+用于管理与特定键关联的单个值的存储包装器：
+
+- 自动缓存和缓存失效
+- 键特定的事件监听
+- 自定义序列化支持
+
+### 序列化器
+
+- `JsonSerializer`：将值序列化为 JSON 字符串
+- `IdentitySerializer`：不进行修改直接传递值
+
+## 许可证
+
+[Apache 2.0](https://github.com/Ahoo-Wang/fetcher/blob/master/LICENSE)

package/package.json

@@ -1,24 +1,19 @@
 {
   "name": "@ahoo-wang/fetcher-storage",
-  "version": "1.6.6",
-  "description": "Ultra-lightweight HTTP client with built-in path parameters, query parameters, and Axios-like API. The foundation of the Fetcher ecosystem with powerful interceptor system and LLM streaming API support.",
+  "version": "1.6.8",
+  "description": "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.",
   "keywords": [
-    "fetch",
-    "http",
-    "client",
-    "axios",
-    "ultra-lightweight",
-    "modular",
-    "typescript",
-    "interceptor",
-    "llm",
-    "streaming",
-    "sse",
-    "server-sent-events"
+    "storage",
+    "localStorage",
+    "sessionStorage",
+    "memory-storage",
+    "event-listener",
+    "cross-environment",
+    "typescript"
   ],
   "author": "Ahoo-Wang",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/Ahoo-Wang/fetcher/tree/master/packages/fetcher",
+  "homepage": "https://github.com/Ahoo-Wang/fetcher/tree/master/packages/storage",
   "repository": {
     "type": "git",
     "url": "https://github.com/Ahoo-Wang/fetcher.git",