@ahoo-wang/fetcher-storage 2.9.6 → 2.9.8

package/README.zh-CN.md

@@ -107,8 +107,926 @@ const customStorage = new KeyStorage<string>({
   storage: new InMemoryStorage(), // 使用内存存储而不是 localStorage
   // eventBus: customEventBus, // 自定义事件总线用于通知
 });
+
+// 自定义序列化器处理复杂数据类型
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+class DateSerializer {
+  serialize(value: any): string {
+    return JSON.stringify(value, (key, val) =>
+      val instanceof Date ? { __type: 'Date', value: val.toISOString() } : val,
+    );
+  }
+
+  deserialize(value: string): any {
+    return JSON.parse(value, (key, val) =>
+      val && typeof val === 'object' && val.__type === 'Date'
+        ? new Date(val.value)
+        : val,
+    );
+  }
+}
+
+const dateStorage = new KeyStorage<{ createdAt: Date; data: string }>({
+  key: 'date-data',
+  serializer: new DateSerializer(),
+});
+```
+
+## 🚀 高级用法示例
+
+### 与 RxJS 集成的响应式存储
+
+创建与 RxJS 可观察对象集成的响应式存储：
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+import { BehaviorSubject, Observable } from 'rxjs';
+import { map, distinctUntilChanged } from 'rxjs/operators';
+
+class ReactiveKeyStorage<T> extends KeyStorage<T> {
+  private subject: BehaviorSubject<T | null>;
+
+  constructor(options: any) {
+    super(options);
+    this.subject = new BehaviorSubject<T | null>(this.get());
+  }
+
+  // 重写 set 以发出变更
+  set(value: T): void {
+    super.set(value);
+    this.subject.next(value);
+  }
+
+  // 获取可观察对象以进行响应式更新
+  asObservable(): Observable<T | null> {
+    return this.subject.asObservable();
+  }
+
+  // 获取特定属性的可观察对象
+  select<R>(selector: (value: T | null) => R): Observable<R> {
+    return this.subject.pipe(map(selector), distinctUntilChanged());
+  }
+}
+
+// 使用
+const userStorage = new ReactiveKeyStorage<{ name: string; theme: string }>({
+  key: 'user-preferences',
+});
+
+// 对所有变更做出响应
+userStorage.asObservable().subscribe(preferences => {
+  console.log('用户偏好已变更:', preferences);
+});
+
+// 对特定属性变更做出响应
+userStorage
+  .select(prefs => prefs?.theme)
+  .subscribe(theme => {
+    document.body.className = `theme-${theme}`;
+  });
+
+// 更新存储（将触发观察者）
+userStorage.set({ name: 'John', theme: 'dark' });
+```
+
+### 使用 Web Crypto API 的加密存储
+
+为敏感数据实现安全的加密存储：
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+class EncryptedSerializer {
+  private keyPromise: Promise<CryptoKey>;
+
+  constructor(password: string) {
+    this.keyPromise = this.deriveKey(password);
+  }
+
+  private async deriveKey(password: string): Promise<CryptoKey> {
+    const encoder = new TextEncoder();
+    const keyMaterial = await crypto.subtle.importKey(
+      'raw',
+      encoder.encode(password),
+      'PBKDF2',
+      false,
+      ['deriveBits', 'deriveKey'],
+    );
+
+    return crypto.subtle.deriveKey(
+      {
+        name: 'PBKDF2',
+        salt: encoder.encode('fetcher-storage-salt'),
+        iterations: 100000,
+        hash: 'SHA-256',
+      },
+      keyMaterial,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt', 'decrypt'],
+    );
+  }
+
+  async serialize(value: any): Promise<string> {
+    const key = await this.keyPromise;
+    const encoder = new TextEncoder();
+    const data = encoder.encode(JSON.stringify(value));
+
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const encrypted = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      key,
+      data,
+    );
+
+    // 合并 IV 和加密数据
+    const combined = new Uint8Array(iv.length + encrypted.byteLength);
+    combined.set(iv);
+    combined.set(new Uint8Array(encrypted), iv.length);
+
+    return btoa(String.fromCharCode(...combined));
+  }
+
+  async deserialize(value: string): Promise<any> {
+    const key = await this.keyPromise;
+    const combined = new Uint8Array(
+      atob(value)
+        .split('')
+        .map(c => c.charCodeAt(0)),
+    );
+
+    const iv = combined.slice(0, 12);
+    const encrypted = combined.slice(12);
+
+    const decrypted = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv },
+      key,
+      encrypted,
+    );
+
+    const decoder = new TextDecoder();
+    return JSON.parse(decoder.decode(decrypted));
+  }
+}
+
+// 使用（仅在安全上下文 - HTTPS 中工作）
+const secureStorage = new KeyStorage<any>({
+  key: 'sensitive-data',
+  serializer: new EncryptedSerializer('user-password'),
+});
+
+// 存储加密数据
+secureStorage.set({ apiKey: 'secret-key', tokens: ['token1', 'token2'] });
+
+// 检索解密数据
+const data = secureStorage.get();
+console.log(data); // { apiKey: 'secret-key', tokens: [...] }
+```
+
+### 存储迁移和版本控制
+
+跨应用版本处理存储模式迁移：
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+interface StorageVersion {
+  version: number;
+  migrate: (data: any) => any;
+}
+
+class VersionedKeyStorage<T> extends KeyStorage<T> {
+  private migrations: StorageVersion[] = [];
+
+  constructor(options: any, migrations: StorageVersion[] = []) {
+    super(options);
+    this.migrations = migrations.sort((a, b) => a.version - b.version);
+  }
+
+  get(): T | null {
+    const rawData = super.get();
+    if (!rawData) return null;
+
+    return this.migrateData(rawData);
+  }
+
+  private migrateData(data: any): T {
+    const currentVersion = data.__version || 0;
+    let migratedData = { ...data };
+
+    // 为干净数据移除版本标记
+    delete migratedData.__version;
+
+    // 按顺序应用迁移
+    for (const migration of this.migrations) {
+      if (currentVersion < migration.version) {
+        migratedData = migration.migrate(migratedData);
+        migratedData.__version = migration.version;
+      }
+    }
+
+    // 保存迁移数据
+    if (migratedData.__version !== currentVersion) {
+      super.set(migratedData);
+    }
+
+    delete migratedData.__version;
+    return migratedData;
+  }
+}
+
+// 定义迁移
+const migrations: StorageVersion[] = [
+  {
+    version: 1,
+    migrate: data => ({
+      ...data,
+      // 如果缺失则添加默认主题
+      theme: data.theme || 'light',
+    }),
+  },
+  {
+    version: 2,
+    migrate: data => ({
+      ...data,
+      // 重命名属性
+      preferences: data.settings || {},
+      settings: undefined,
+    }),
+  },
+  {
+    version: 3,
+    migrate: data => ({
+      ...data,
+      // 添加时间戳
+      createdAt: data.createdAt || new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    }),
+  },
+];
+
+// 使用
+const userPrefsStorage = new VersionedKeyStorage<{
+  name: string;
+  theme: string;
+  preferences: Record<string, any>;
+  createdAt: string;
+  updatedAt: string;
+}>(
+  {
+    key: 'user-preferences',
+  },
+  migrations,
+);
+
+// 数据将被自动迁移时访问
+const prefs = userPrefsStorage.get();
+```
+
+### 使用存储事件的跨标签页通信
+
+使用存储事件实现跨标签页通信：
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+interface TabMessage {
+  id: string;
+  type: string;
+  payload: any;
+  timestamp: number;
+  sourceTab: string;
+}
+
+class CrossTabMessenger {
+  private storage: KeyStorage<TabMessage[]>;
+  private tabId: string;
+  private listeners: Map<string, (message: TabMessage) => void> = new Map();
+
+  constructor(channelName: string = 'cross-tab-messages') {
+    this.tabId = `tab-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    this.storage = new KeyStorage<TabMessage[]>({
+      key: channelName,
+    });
+
+    // 监听存储变更
+    this.storage.addListener(messages => {
+      if (!messages) return;
+
+      // 处理新消息
+      messages.forEach(message => {
+        if (message.sourceTab !== this.tabId) {
+          this.notifyListeners(message.type, message);
+        }
+      });
+    });
+
+    // 如果为空则初始化存储
+    if (!this.storage.get()) {
+      this.storage.set([]);
+    }
+  }
+
+  // 向其他标签页广播消息
+  broadcast(type: string, payload: any) {
+    const messages = this.storage.get() || [];
+    const message: TabMessage = {
+      id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+      type,
+      payload,
+      timestamp: Date.now(),
+      sourceTab: this.tabId,
+    };
+
+    // 添加消息并保留最近消息
+    const updatedMessages = [...messages, message].slice(-50);
+    this.storage.set(updatedMessages);
+  }
+
+  // 监听消息
+  on(type: string, callback: (message: TabMessage) => void) {
+    this.listeners.set(type, callback);
+  }
+
+  // 移除监听器
+  off(type: string) {
+    this.listeners.delete(type);
+  }
+
+  private notifyListeners(type: string, message: TabMessage) {
+    const listener = this.listeners.get(type);
+    if (listener) {
+      listener(message);
+    }
+  }
+
+  // 获取当前标签页 ID
+  getTabId(): string {
+    return this.tabId;
+  }
+}
+
+// 使用
+const messenger = new CrossTabMessenger('app-messages');
+
+// 监听来自其他标签页的用户登录事件
+messenger.on('user-logged-in', message => {
+  console.log('用户从另一个标签页登录:', message.payload);
+  // 更新当前标签页的状态
+  updateUserState(message.payload.user);
+});
+
+// 广播用户操作
+function onUserLogin(user: any) {
+  messenger.broadcast('user-logged-in', { user, tabId: messenger.getTabId() });
+}
+```
+
+### 性能监控和分析
+
+为存储操作添加性能跟踪：
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+interface PerformanceMetrics {
+  operation: string;
+  duration: number;
+  timestamp: number;
+  success: boolean;
+  error?: string;
+}
+
+class MonitoredKeyStorage<T> extends KeyStorage<T> {
+  private metrics: PerformanceMetrics[] = [];
+  private readonly maxMetrics = 100;
+
+  constructor(options: any) {
+    super(options);
+  }
+
+  set(value: T): void {
+    const startTime = performance.now();
+    try {
+      super.set(value);
+      this.recordMetric('set', performance.now() - startTime, true);
+    } catch (error) {
+      this.recordMetric(
+        'set',
+        performance.now() - startTime,
+        false,
+        String(error),
+      );
+      throw error;
+    }
+  }
+
+  get(): T | null {
+    const startTime = performance.now();
+    try {
+      const result = super.get();
+      this.recordMetric('get', performance.now() - startTime, true);
+      return result;
+    } catch (error) {
+      this.recordMetric(
+        'get',
+        performance.now() - startTime,
+        false,
+        String(error),
+      );
+      throw error;
+    }
+  }
+
+  private recordMetric(
+    operation: string,
+    duration: number,
+    success: boolean,
+    error?: string,
+  ) {
+    this.metrics.push({
+      operation,
+      duration,
+      timestamp: Date.now(),
+      success,
+      error,
+    });
+
+    // 保留最近的指标
+    if (this.metrics.length > this.maxMetrics) {
+      this.metrics = this.metrics.slice(-this.maxMetrics);
+    }
+  }
+
+  // 获取性能统计
+  getPerformanceStats() {
+    const total = this.metrics.length;
+    const successful = this.metrics.filter(m => m.success).length;
+    const failed = total - successful;
+
+    const avgDuration =
+      this.metrics.reduce((sum, m) => sum + m.duration, 0) / total;
+    const maxDuration = Math.max(...this.metrics.map(m => m.duration));
+    const minDuration = Math.min(...this.metrics.map(m => m.duration));
+
+    return {
+      total,
+      successful,
+      failed,
+      successRate: successful / total,
+      avgDuration,
+      maxDuration,
+      minDuration,
+      recentErrors: this.metrics
+        .filter(m => !m.success)
+        .slice(-5)
+        .map(m => ({
+          operation: m.operation,
+          error: m.error,
+          timestamp: m.timestamp,
+        })),
+    };
+  }
+
+  // 导出指标以进行分析
+  exportMetrics(): PerformanceMetrics[] {
+    return [...this.metrics];
+  }
+
+  // 清除指标
+  clearMetrics() {
+    this.metrics = [];
+  }
+}
+
+// 使用
+const monitoredStorage = new MonitoredKeyStorage<any>({
+  key: 'app-data',
+});
+
+// 正常使用
+monitoredStorage.set({ user: 'john', settings: {} });
+const data = monitoredStorage.get();
+
+// 获取性能洞察
+const stats = monitoredStorage.getPerformanceStats();
+console.log('存储性能:', stats);
+
+// 导出以进行进一步分析
+const metrics = monitoredStorage.exportMetrics();
+```
+
+### 与状态管理库集成
+
+集成存储与流行状态管理解决方案的示例：
+
+#### 与 Redux 集成
+
+```typescript
+import { createStore, combineReducers } from 'redux';
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+// 存储支持的 reducer
+function createPersistentReducer(reducer: any, storageKey: string) {
+  const storage = new KeyStorage({
+    key: storageKey,
+  });
+
+  // 从存储加载初始状态
+  const initialState = storage.get() || reducer(undefined, { type: '@@INIT' });
+
+  return (state = initialState, action: any) => {
+    const newState = reducer(state, action);
+
+    // 持久化状态变更（防抖）
+    if (action.type !== '@@INIT') {
+      setTimeout(() => storage.set(newState), 100);
+    }
+
+    return newState;
+  };
+}
+
+// 使用
+const userReducer = (state = { name: '', loggedIn: false }, action: any) => {
+  switch (action.type) {
+    case 'LOGIN':
+      return { ...state, name: action.payload.name, loggedIn: true };
+    case 'LOGOUT':
+      return { ...state, name: '', loggedIn: false };
+    default:
+      return state;
+  }
+};
+
+const rootReducer = combineReducers({
+  user: createPersistentReducer(userReducer, 'redux-user-state'),
+});
+
+const store = createStore(rootReducer);
+
+// 状态将自动持久化和恢复
+```
+
+#### 与 Zustand 集成
+
+```typescript
+import { create } from 'zustand';
+import { subscribeWithSelector } from 'zustand/middleware';
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+interface AppState {
+  user: { name: string; email: string } | null;
+  theme: 'light' | 'dark';
+  login: (user: { name: string; email: string }) => void;
+  logout: () => void;
+  setTheme: (theme: 'light' | 'dark') => void;
+}
+
+const storage = new KeyStorage<AppState['user']>({
+  key: 'zustand-user',
+});
+
+export const useAppStore = create<AppState>()(
+  subscribeWithSelector((set, get) => ({
+    user: storage.get(),
+    theme: 'light',
+
+    login: user => {
+      set({ user });
+      storage.set(user);
+    },
+
+    logout: () => {
+      set({ user: null });
+      storage.set(null);
+    },
+
+    setTheme: theme => set({ theme }),
+  })),
+);
+
+// 自动持久化主题变更
+useAppStore.subscribe(
+  state => state.theme,
+  theme => {
+    const themeStorage = new KeyStorage({ key: 'app-theme' });
+    themeStorage.set(theme);
+  },
+);
+```
+
+## 实际示例
+
+### 用户会话管理
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+
+interface UserSession {
+  userId: string;
+  token: string;
+  expiresAt: Date;
+  preferences: Record<string, any>;
+}
+
+class SessionManager {
+  private sessionStorage = new KeyStorage<UserSession>({
+    key: 'user-session',
+  });
+
+  async login(credentials: LoginCredentials): Promise<UserSession> {
+    const response = await fetch('/api/login', {
+      method: 'POST',
+      body: JSON.stringify(credentials),
+    });
+    const session = await response.json();
+
+    this.sessionStorage.set(session);
+    return session;
+  }
+
+  getCurrentSession(): UserSession | null {
+    const session = this.sessionStorage.get();
+    if (!session) return null;
+
+    // 检查会话是否过期
+    if (new Date(session.expiresAt) < new Date()) {
+      this.logout();
+      return null;
+    }
+
+    return session;
+  }
+
+  logout(): void {
+    this.sessionStorage.remove();
+  }
+
+  updatePreferences(preferences: Record<string, any>): void {
+    const session = this.getCurrentSession();
+    if (session) {
+      this.sessionStorage.set({
+        ...session,
+        preferences: { ...session.preferences, ...preferences },
+      });
+    }
+  }
+}
+```
+
+### 跨标签页应用状态
+
+```typescript
+import {
+  KeyStorage,
+  BroadcastTypedEventBus,
+  SerialTypedEventBus,
+} from '@ahoo-wang/fetcher-storage';
+
+interface AppState {
+  theme: 'light' | 'dark';
+  language: string;
+  sidebarCollapsed: boolean;
+}
+
+class AppStateManager {
+  private stateStorage: KeyStorage<AppState>;
+
+  constructor() {
+    // 使用广播事件总线进行跨标签页同步
+    const eventBus = new BroadcastTypedEventBus(
+      new SerialTypedEventBus('app-state'),
+    );
+
+    this.stateStorage = new KeyStorage<AppState>({
+      key: 'app-state',
+      eventBus,
+    });
+
+    // 监听来自其他标签页的状态变更
+    this.stateStorage.addListener(event => {
+      if (event.newValue) {
+        this.applyStateToUI(event.newValue);
+      }
+    });
+  }
+
+  getState(): AppState {
+    return (
+      this.stateStorage.get() || {
+        theme: 'light',
+        language: 'en',
+        sidebarCollapsed: false,
+      }
+    );
+  }
+
+  updateState(updates: Partial<AppState>): void {
+    const currentState = this.getState();
+    const newState = { ...currentState, ...updates };
+    this.stateStorage.set(newState);
+    this.applyStateToUI(newState);
+  }
+
+  private applyStateToUI(state: AppState): void {
+    document.documentElement.setAttribute('data-theme', state.theme);
+    // 根据状态更新 UI 组件
+  }
+}
 ```
 
+### 表单自动保存
+
+```typescript
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+import { useEffect, useState } from 'react';
+
+interface FormData {
+  title: string;
+  content: string;
+  tags: string[];
+  lastSaved: Date;
+}
+
+function useAutoSaveForm(formId: string) {
+  const [formData, setFormData] = useState<Partial<FormData>>({});
+  const [lastSaved, setLastSaved] = useState<Date | null>(null);
+
+  const formStorage = new KeyStorage<Partial<FormData>>({
+    key: `form-autosave-${formId}`
+  });
+
+  // 挂载时加载保存的数据
+  useEffect(() => {
+    const saved = formStorage.get();
+    if (saved) {
+      setFormData(saved);
+      setLastSaved(saved.lastSaved || null);
+    }
+  }, [formStorage]);
+
+  // 变更时自动保存
+  useEffect(() => {
+    if (Object.keys(formData).length > 0) {
+      const dataToSave = {
+        ...formData,
+        lastSaved: new Date(),
+      };
+      formStorage.set(dataToSave);
+      setLastSaved(dataToSave.lastSaved);
+    }
+  }, [formData, formStorage]);
+
+  const clearAutoSave = () => {
+    formStorage.remove();
+    setFormData({});
+    setLastSaved(null);
+  };
+
+  return {
+    formData,
+    setFormData,
+    lastSaved,
+    clearAutoSave,
+  };
+}
+
+// 在组件中使用
+function ArticleEditor({ articleId }: { articleId: string }) {
+  const { formData, setFormData, lastSaved, clearAutoSave } = useAutoSaveForm(articleId);
+
+  return (
+    <div>
+      {lastSaved && (
+        <div className="autosave-indicator">
+          自动保存于 {lastSaved.toLocaleTimeString()}
+        </div>
+      )}
+
+      <input
+        value={formData.title || ''}
+        onChange={e => setFormData(prev => ({ ...prev, title: e.target.value }))}
+        placeholder="文章标题"
+      />
+
+      <textarea
+        value={formData.content || ''}
+        onChange={e => setFormData(prev => ({ ...prev, content: e.target.value }))}
+        placeholder="文章内容"
+      />
+
+      <button onClick={clearAutoSave}>清除自动保存</button>
+    </div>
+  );
+}
+```
+
+## 故障排除
+
+### 常见问题
+
+#### 存储配额超出
+
+```typescript
+// 处理存储配额错误
+try {
+  userStorage.set(largeData);
+} catch (error) {
+  if (error.name === 'QuotaExceededError') {
+    // 降级到内存存储或压缩数据
+    console.warn('存储配额超出，使用降级方案');
+    // 实现降级逻辑
+  }
+}
+```
+
+#### 跨标签页同步不工作
+
+```typescript
+// 确保 BroadcastChannel 被支持
+if ('BroadcastChannel' in window) {
+  const eventBus = new BroadcastTypedEventBus(
+    new SerialTypedEventBus('my-app'),
+  );
+  // 与 KeyStorage 一起使用
+} else {
+  console.warn('BroadcastChannel 不被支持，降级到仅本地存储');
+}
+```
+
+#### 序列化错误
+
+```typescript
+// 处理循环引用和复杂对象
+class SafeJsonSerializer implements Serializer<string, any> {
+  serialize(value: any): string {
+    // 移除循环引用或处理特殊情况
+    const safeValue = this.makeSerializable(value);
+    return JSON.stringify(safeValue);
+  }
+
+  deserialize(value: string): any {
+    return JSON.parse(value);
+  }
+
+  private makeSerializable(obj: any, seen = new WeakSet()): any {
+    if (obj === null || typeof obj !== 'object') return obj;
+    if (seen.has(obj)) return '[Circular]';
+
+    seen.add(obj);
+    const result: any = Array.isArray(obj) ? [] : {};
+
+    for (const key in obj) {
+      if (obj.hasOwnProperty(key)) {
+        result[key] = this.makeSerializable(obj[key], seen);
+      }
+    }
+
+    seen.delete(obj);
+    return result;
+  }
+}
+```
+
+#### 内存泄漏
+
+```typescript
+// 始终清理监听器
+class ComponentWithStorage {
+  private storage: KeyStorage<any>;
+  private removeListener: () => void;
+
+  constructor() {
+    this.storage = new KeyStorage({ key: 'component-data' });
+    this.removeListener = this.storage.addListener(event => {
+      // 处理变更
+    });
+  }
+
+  destroy() {
+    // 组件销毁时清理
+    this.removeListener();
+    this.storage.destroy?.(); // 如果可用
+  }
+}
+```
+
+### 性能提示
+
+- **使用合适的序列化器**：简单对象使用 JSON，复杂数据使用自定义序列化器
+- **批量操作**：尽可能将多个存储操作分组
+- **监控存储大小**：实施大小限制和清理策略
+- **临时数据使用内存存储**：避免持久化不必要的数据
+- **防抖频繁更新**：防止过度存储写入
+
+### 浏览器兼容性
+
+- **localStorage**：IE 8+，所有现代浏览器
+- **BroadcastChannel**：Chrome 54+，Firefox 38+，Safari 15.4+
+- **降级处理**：始终为不支持的功能提供降级方案
+
 ## API 参考
 
 ### 环境工具
@@ -166,6 +1084,20 @@ new InMemoryStorage();
 
 恒等序列化器，直接传递值而不修改。
 
+## 🧪 测试
+
+```bash
+# 运行测试
+pnpm test
+
+# 运行带覆盖率的测试
+pnpm test --coverage
+```
+
+## 🤝 贡献
+
+欢迎贡献！请查看 [贡献指南](https://github.com/Ahoo-Wang/fetcher/blob/main/CONTRIBUTING.md) 了解更多详情。
+
 ## TypeScript 支持
 
 完整的 TypeScript 支持，包括泛型和类型推断：
@@ -179,6 +1111,12 @@ userStorage.set({ id: 1, name: 'John' });
 const user = userStorage.get(); // User | null
 ```
 
-## 许可证
+## 📄 许可证
 
 [Apache 2.0](https://github.com/Ahoo-Wang/fetcher/blob/master/LICENSE)
+
+---
+
+<p align="center">
+  Fetcher 生态系统的一部分
+</p>

package/dist/index.es.js

@@ -107,15 +107,67 @@ class m {
       `KeyStorage:${this.key}`
     ), this.eventBus.on(this.keyStorageHandler);
   }
+  /**
+   * Adds a listener for storage changes.
+   *
+   * The listener will be called whenever the storage value changes,
+   * either locally or from other tabs/windows.
+   *
+   * @param listener - The event handler to be called when storage changes
+   * @returns A function that can be called to remove the listener
+   *
+   * @example
+   * ```typescript
+   * const storage = new KeyStorage<string>({ key: 'userName' });
+   * const removeListener = storage.addListener({
+   *   name: 'userNameChange',
+   *   handle: (event) => {
+   *     console.log('User name changed:', event.newValue);
+   *   }
+   * });
+   *
+   * // Later, to remove the listener
+   * removeListener();
+   * ```
+   */
   addListener(e) {
     return this.eventBus.on(e), () => this.eventBus.off(e.name);
   }
+  /**
+   * Retrieves the current value from storage.
+   *
+   * Uses caching to avoid repeated deserialization. If the value is not in cache,
+   * it retrieves it from the underlying storage and deserializes it.
+   *
+   * @returns The deserialized value, or null if no value exists in storage
+   *
+   * @example
+   * ```typescript
+   * const storage = new KeyStorage<string>({ key: 'userName' });
+   * const userName = storage.get();
+   * console.log(userName); // 'John Doe' or null
+   * ```
+   */
   get() {
     if (this.cacheValue)
       return this.cacheValue;
     const e = this.storage.getItem(this.key);
     return e ? (this.cacheValue = this.serializer.deserialize(e), this.cacheValue) : null;
   }
+  /**
+   * Stores a value in storage and notifies all listeners.
+   *
+   * Serializes the value, stores it in the underlying storage, updates the cache,
+   * and emits a change event to all registered listeners.
+   *
+   * @param value - The value to store (will be serialized before storage)
+   *
+   * @example
+   * ```typescript
+   * const storage = new KeyStorage<string>({ key: 'userName' });
+   * storage.set('John Doe');
+   * ```
+   */
   set(e) {
     const t = this.get(), s = this.serializer.serialize(e);
     this.storage.setItem(this.key, s), this.cacheValue = e, this.eventBus.emit({
@@ -123,6 +175,18 @@ class m {
       oldValue: t
     });
   }
+  /**
+   * Removes the value from storage and notifies all listeners.
+   *
+   * Removes the item from the underlying storage, clears the cache,
+   * and emits a change event indicating the value was removed.
+   *
+   * @example
+   * ```typescript
+   * const storage = new KeyStorage<string>({ key: 'userName' });
+   * storage.remove(); // Removes the stored value
+   * ```
+   */
   remove() {
     const e = this.get();
     this.storage.removeItem(this.key), this.cacheValue = null, this.eventBus.emit({
@@ -130,6 +194,20 @@ class m {
       newValue: null
     });
   }
+  /**
+   * Cleans up resources used by the KeyStorage instance.
+   *
+   * Removes the internal event handler from the event bus.
+   * Should be called when the KeyStorage instance is no longer needed
+   * to prevent memory leaks.
+   *
+   * @example
+   * ```typescript
+   * const storage = new KeyStorage<string>({ key: 'userName' });
+   * // ... use storage ...
+   * storage.destroy(); // Clean up resources
+   * ```
+   */
   destroy() {
     this.eventBus.off(this.keyStorageHandler.name);
   }

package/dist/index.es.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.es.js","sources":["../src/inMemoryStorage.ts","../src/env.ts","../src/serializer.ts","../src/keyStorage.ts"],"sourcesContent":["/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport class InMemoryStorage implements Storage {\n  private readonly store: Map<string, string> = new Map();\n\n  /**\n   * Gets the number of items stored in the storage.\n   */\n  get length(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Clears all items from the storage.\n   */\n  clear(): void {\n    this.store.clear();\n  }\n\n  /**\n   * Gets an item from the storage.\n   * @param key - The key of the item to retrieve\n   * @returns The value of the item, or null if the item does not exist\n   */\n  getItem(key: string): string | null {\n    const value = this.store.get(key);\n    return value !== undefined ? value : null;\n  }\n\n  /**\n   * Gets the key at the specified index.\n   * @param index - The index of the key to retrieve\n   * @returns The key at the specified index, or null if the index is out of bounds\n   */\n  key(index: number): string | null {\n    const keys = Array.from(this.store.keys());\n    return keys[index] || null;\n  }\n\n  /**\n   * Removes an item from the storage.\n   * @param key - The key of the item to remove\n   */\n  removeItem(key: string): void {\n    this.store.delete(key);\n  }\n\n  /**\n   * Sets an item in the storage.\n   * @param key - The key of the item to set\n   * @param value - The value to set\n   */\n  setItem(key: string, value: string): void {\n    this.store.set(key, value);\n  }\n}","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { InMemoryStorage } from './inMemoryStorage';\n\n/**\n * Checks if the current environment is a browser.\n * @returns True if running in a browser environment, false otherwise\n */\nexport function isBrowser(): boolean {\n  return typeof window !== 'undefined';\n}\n\n/**\n * Gets the appropriate storage implementation based on the environment.\n * Returns localStorage in browser environments if available, InMemoryStorage otherwise.\n * @returns A Storage-compatible object\n */\nexport const getStorage = (): Storage => {\n  if (isBrowser()) {\n    return window.localStorage;\n  }\n  return new InMemoryStorage();\n};\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Interface for serializing and deserializing values\n * @template Serialized The type of the serialized value\n * @template Deserialized The type of the deserialized value\n */\nexport interface Serializer<Serialized, Deserialized> {\n  /**\n   * Serializes a value to the specified format\n   * @param value The value to serialize\n   * @returns The serialized value\n   */\n  serialize(value: any): Serialized;\n\n  /**\n   * Deserializes a value from the specified format\n   * @param value The value to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: Serialized): Deserialized;\n}\n\n/**\n * Implementation of Serializer that uses JSON for serialization\n */\nexport class JsonSerializer implements Serializer<string, any> {\n  /**\n   * Serializes a value to a JSON string\n   * @param value The value to serialize\n   * @returns The JSON string representation of the value\n   */\n  serialize(value: any): string {\n    return JSON.stringify(value);\n  }\n\n  /**\n   * Deserializes a JSON string to a value\n   * @param value The JSON string to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: string): any {\n    return JSON.parse(value);\n  }\n}\n\n/**\n * Implementation of Serializer that performs no actual serialization\n * @template T The type of the value to pass through\n */\nexport class IdentitySerializer<T> implements Serializer<T, T> {\n  /**\n   * Returns the value as-is without serialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  serialize(value: T): T {\n    return value;\n  }\n\n  /**\n   * Returns the value as-is without deserialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  deserialize(value: T): T {\n    return value;\n  }\n}\n\n/**\n * Global instance of JsonSerializer\n */\nexport const jsonSerializer = new JsonSerializer();\n/**\n * Global instance of IdentitySerializer\n */\nexport const identitySerializer = new IdentitySerializer<any>();\n\nexport function typedIdentitySerializer<T>(): IdentitySerializer<T> {\n  return identitySerializer as IdentitySerializer<T>;\n}\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Serializer, typedIdentitySerializer } from './serializer';\nimport {\n  EventHandler, nameGenerator,\n  SerialTypedEventBus,\n  TypedEventBus,\n} from '@ahoo-wang/fetcher-eventbus';\nimport { getStorage } from './env';\n\nexport interface StorageEvent<Deserialized> {\n  newValue?: Deserialized | null;\n  oldValue?: Deserialized | null;\n}\n\n/**\n * A function that removes a storage listener when called.\n */\nexport type RemoveStorageListener = () => void;\n\nexport interface StorageListenable<Deserialized> {\n  /**\n   * Adds a listener for storage changes.\n   * @param listener - The listener function to be called when storage changes\n   * @returns A function that can be called to remove the listener\n   */\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener;\n}\n\n/**\n * Options for configuring KeyStorage\n */\nexport interface KeyStorageOptions<Deserialized> {\n  /**\n   * The key used to store and retrieve values from storage\n   */\n  key: string;\n\n  /**\n   * Optional serializer for converting values to and from storage format\n   * Defaults to IdentitySerializer if not provided\n   */\n  serializer?: Serializer<string, Deserialized>;\n\n  /**\n   * Optional storage instance. Defaults to localStorage\n   */\n  storage?: Storage;\n\n  /**\n   * Optional event bus for cross-tab communication. Defaults to SerialTypedEventBus\n   */\n  eventBus?: TypedEventBus<StorageEvent<Deserialized>>;\n}\n\n/**\n * A storage wrapper that manages a single value associated with a specific key\n * Provides caching and automatic cache invalidation when the storage value changes\n * @template Deserialized The type of the value being stored\n */\nexport class KeyStorage<Deserialized>\n  implements StorageListenable<Deserialized> {\n  private readonly key: string;\n  private readonly serializer: Serializer<string, Deserialized>;\n  private readonly storage: Storage;\n  private readonly eventBus: TypedEventBus<StorageEvent<Deserialized>>;\n  private cacheValue: Deserialized | null = null;\n  private readonly keyStorageHandler: EventHandler<StorageEvent<Deserialized>> = {\n    name: nameGenerator.generate('KeyStorage'),\n    handle: (event: StorageEvent<Deserialized>) => {\n      this.cacheValue = event.newValue ?? null;\n    },\n  };\n\n  /**\n   * Creates a new KeyStorage instance\n   * @param options Configuration options for the storage\n   */\n  constructor(options: KeyStorageOptions<Deserialized>) {\n    this.key = options.key;\n    this.serializer = options.serializer ?? typedIdentitySerializer();\n    this.storage = options.storage ?? getStorage();\n    this.eventBus =\n      options.eventBus ??\n      new SerialTypedEventBus<StorageEvent<Deserialized>>(\n        `KeyStorage:${this.key}`,\n      );\n    this.eventBus.on(this.keyStorageHandler);\n  }\n\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener {\n    this.eventBus.on(listener);\n    return () => this.eventBus.off(listener.name);\n  }\n\n  get(): Deserialized | null {\n    if (this.cacheValue) {\n      return this.cacheValue;\n    }\n    const value = this.storage.getItem(this.key);\n    if (!value) {\n      return null;\n    }\n    this.cacheValue = this.serializer.deserialize(value);\n    return this.cacheValue;\n  }\n\n  set(value: Deserialized): void {\n    const oldValue = this.get();\n    const serialized = this.serializer.serialize(value);\n    this.storage.setItem(this.key, serialized);\n    this.cacheValue = value;\n    this.eventBus.emit({\n      newValue: value,\n      oldValue: oldValue,\n    });\n  }\n\n  remove(): void {\n    const oldValue = this.get();\n    this.storage.removeItem(this.key);\n    this.cacheValue = null;\n    this.eventBus.emit({\n      oldValue: oldValue,\n      newValue: null,\n    });\n  }\n\n  destroy() {\n    this.eventBus.off(this.keyStorageHandler.name);\n  }\n}\n"],"names":["InMemoryStorage","key","value","index","isBrowser","getStorage","JsonSerializer","IdentitySerializer","jsonSerializer","identitySerializer","typedIdentitySerializer","KeyStorage","options","nameGenerator","event","SerialTypedEventBus","listener","oldValue","serialized"],"mappings":"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"}
+{"version":3,"file":"index.es.js","sources":["../src/inMemoryStorage.ts","../src/env.ts","../src/serializer.ts","../src/keyStorage.ts"],"sourcesContent":["/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport class InMemoryStorage implements Storage {\n  private readonly store: Map<string, string> = new Map();\n\n  /**\n   * Gets the number of items stored in the storage.\n   */\n  get length(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Clears all items from the storage.\n   */\n  clear(): void {\n    this.store.clear();\n  }\n\n  /**\n   * Gets an item from the storage.\n   * @param key - The key of the item to retrieve\n   * @returns The value of the item, or null if the item does not exist\n   */\n  getItem(key: string): string | null {\n    const value = this.store.get(key);\n    return value !== undefined ? value : null;\n  }\n\n  /**\n   * Gets the key at the specified index.\n   * @param index - The index of the key to retrieve\n   * @returns The key at the specified index, or null if the index is out of bounds\n   */\n  key(index: number): string | null {\n    const keys = Array.from(this.store.keys());\n    return keys[index] || null;\n  }\n\n  /**\n   * Removes an item from the storage.\n   * @param key - The key of the item to remove\n   */\n  removeItem(key: string): void {\n    this.store.delete(key);\n  }\n\n  /**\n   * Sets an item in the storage.\n   * @param key - The key of the item to set\n   * @param value - The value to set\n   */\n  setItem(key: string, value: string): void {\n    this.store.set(key, value);\n  }\n}","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { InMemoryStorage } from './inMemoryStorage';\n\n/**\n * Checks if the current environment is a browser.\n * @returns True if running in a browser environment, false otherwise\n */\nexport function isBrowser(): boolean {\n  return typeof window !== 'undefined';\n}\n\n/**\n * Gets the appropriate storage implementation based on the environment.\n * Returns localStorage in browser environments if available, InMemoryStorage otherwise.\n * @returns A Storage-compatible object\n */\nexport const getStorage = (): Storage => {\n  if (isBrowser()) {\n    return window.localStorage;\n  }\n  return new InMemoryStorage();\n};\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Interface for serializing and deserializing values\n * @template Serialized The type of the serialized value\n * @template Deserialized The type of the deserialized value\n */\nexport interface Serializer<Serialized, Deserialized> {\n  /**\n   * Serializes a value to the specified format\n   * @param value The value to serialize\n   * @returns The serialized value\n   */\n  serialize(value: any): Serialized;\n\n  /**\n   * Deserializes a value from the specified format\n   * @param value The value to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: Serialized): Deserialized;\n}\n\n/**\n * Implementation of Serializer that uses JSON for serialization\n */\nexport class JsonSerializer implements Serializer<string, any> {\n  /**\n   * Serializes a value to a JSON string\n   * @param value The value to serialize\n   * @returns The JSON string representation of the value\n   */\n  serialize(value: any): string {\n    return JSON.stringify(value);\n  }\n\n  /**\n   * Deserializes a JSON string to a value\n   * @param value The JSON string to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: string): any {\n    return JSON.parse(value);\n  }\n}\n\n/**\n * Implementation of Serializer that performs no actual serialization\n * @template T The type of the value to pass through\n */\nexport class IdentitySerializer<T> implements Serializer<T, T> {\n  /**\n   * Returns the value as-is without serialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  serialize(value: T): T {\n    return value;\n  }\n\n  /**\n   * Returns the value as-is without deserialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  deserialize(value: T): T {\n    return value;\n  }\n}\n\n/**\n * Global instance of JsonSerializer\n */\nexport const jsonSerializer = new JsonSerializer();\n/**\n * Global instance of IdentitySerializer\n */\nexport const identitySerializer = new IdentitySerializer<any>();\n\nexport function typedIdentitySerializer<T>(): IdentitySerializer<T> {\n  return identitySerializer as IdentitySerializer<T>;\n}\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Serializer, typedIdentitySerializer } from './serializer';\nimport {\n  EventHandler,\n  nameGenerator,\n  SerialTypedEventBus,\n  TypedEventBus,\n} from '@ahoo-wang/fetcher-eventbus';\nimport { getStorage } from './env';\n\nexport interface StorageEvent<Deserialized> {\n  newValue?: Deserialized | null;\n  oldValue?: Deserialized | null;\n}\n\n/**\n * A function that removes a storage listener when called.\n */\nexport type RemoveStorageListener = () => void;\n\nexport interface StorageListenable<Deserialized> {\n  /**\n   * Adds a listener for storage changes.\n   * @param listener - The listener function to be called when storage changes\n   * @returns A function that can be called to remove the listener\n   */\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener;\n}\n\n/**\n * Options for configuring KeyStorage\n */\nexport interface KeyStorageOptions<Deserialized> {\n  /**\n   * The key used to store and retrieve values from storage\n   */\n  key: string;\n\n  /**\n   * Optional serializer for converting values to and from storage format\n   * Defaults to IdentitySerializer if not provided\n   */\n  serializer?: Serializer<string, Deserialized>;\n\n  /**\n   * Optional storage instance. Defaults to localStorage\n   */\n  storage?: Storage;\n\n  /**\n   * Optional event bus for cross-tab communication. Defaults to SerialTypedEventBus\n   */\n  eventBus?: TypedEventBus<StorageEvent<Deserialized>>;\n}\n\n/**\n * A storage wrapper that manages a single value associated with a specific key\n * Provides caching and automatic cache invalidation when the storage value changes\n * @template Deserialized The type of the value being stored\n */\nexport class KeyStorage<Deserialized>\n  implements StorageListenable<Deserialized>\n{\n  private readonly key: string;\n  private readonly serializer: Serializer<string, Deserialized>;\n  private readonly storage: Storage;\n  private readonly eventBus: TypedEventBus<StorageEvent<Deserialized>>;\n  private cacheValue: Deserialized | null = null;\n  private readonly keyStorageHandler: EventHandler<StorageEvent<Deserialized>> =\n    {\n      name: nameGenerator.generate('KeyStorage'),\n      handle: (event: StorageEvent<Deserialized>) => {\n        this.cacheValue = event.newValue ?? null;\n      },\n    };\n\n  /**\n   * Creates a new KeyStorage instance\n   * @param options Configuration options for the storage\n   */\n  constructor(options: KeyStorageOptions<Deserialized>) {\n    this.key = options.key;\n    this.serializer = options.serializer ?? typedIdentitySerializer();\n    this.storage = options.storage ?? getStorage();\n    this.eventBus =\n      options.eventBus ??\n      new SerialTypedEventBus<StorageEvent<Deserialized>>(\n        `KeyStorage:${this.key}`,\n      );\n    this.eventBus.on(this.keyStorageHandler);\n  }\n\n  /**\n   * Adds a listener for storage changes.\n   *\n   * The listener will be called whenever the storage value changes,\n   * either locally or from other tabs/windows.\n   *\n   * @param listener - The event handler to be called when storage changes\n   * @returns A function that can be called to remove the listener\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * const removeListener = storage.addListener({\n   *   name: 'userNameChange',\n   *   handle: (event) => {\n   *     console.log('User name changed:', event.newValue);\n   *   }\n   * });\n   *\n   * // Later, to remove the listener\n   * removeListener();\n   * ```\n   */\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener {\n    this.eventBus.on(listener);\n    return () => this.eventBus.off(listener.name);\n  }\n\n  /**\n   * Retrieves the current value from storage.\n   *\n   * Uses caching to avoid repeated deserialization. If the value is not in cache,\n   * it retrieves it from the underlying storage and deserializes it.\n   *\n   * @returns The deserialized value, or null if no value exists in storage\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * const userName = storage.get();\n   * console.log(userName); // 'John Doe' or null\n   * ```\n   */\n  get(): Deserialized | null {\n    if (this.cacheValue) {\n      return this.cacheValue;\n    }\n    const value = this.storage.getItem(this.key);\n    if (!value) {\n      return null;\n    }\n    this.cacheValue = this.serializer.deserialize(value);\n    return this.cacheValue;\n  }\n\n  /**\n   * Stores a value in storage and notifies all listeners.\n   *\n   * Serializes the value, stores it in the underlying storage, updates the cache,\n   * and emits a change event to all registered listeners.\n   *\n   * @param value - The value to store (will be serialized before storage)\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * storage.set('John Doe');\n   * ```\n   */\n  set(value: Deserialized): void {\n    const oldValue = this.get();\n    const serialized = this.serializer.serialize(value);\n    this.storage.setItem(this.key, serialized);\n    this.cacheValue = value;\n    this.eventBus.emit({\n      newValue: value,\n      oldValue: oldValue,\n    });\n  }\n\n  /**\n   * Removes the value from storage and notifies all listeners.\n   *\n   * Removes the item from the underlying storage, clears the cache,\n   * and emits a change event indicating the value was removed.\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * storage.remove(); // Removes the stored value\n   * ```\n   */\n  remove(): void {\n    const oldValue = this.get();\n    this.storage.removeItem(this.key);\n    this.cacheValue = null;\n    this.eventBus.emit({\n      oldValue: oldValue,\n      newValue: null,\n    });\n  }\n\n  /**\n   * Cleans up resources used by the KeyStorage instance.\n   *\n   * Removes the internal event handler from the event bus.\n   * Should be called when the KeyStorage instance is no longer needed\n   * to prevent memory leaks.\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * // ... use storage ...\n   * storage.destroy(); // Clean up resources\n   * ```\n   */\n  destroy() {\n    this.eventBus.off(this.keyStorageHandler.name);\n  }\n}\n"],"names":["InMemoryStorage","key","value","index","isBrowser","getStorage","JsonSerializer","IdentitySerializer","jsonSerializer","identitySerializer","typedIdentitySerializer","KeyStorage","options","nameGenerator","event","SerialTypedEventBus","listener","oldValue","serialized"],"mappings":"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"}

package/dist/index.umd.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.umd.js","sources":["../src/inMemoryStorage.ts","../src/env.ts","../src/serializer.ts","../src/keyStorage.ts"],"sourcesContent":["/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport class InMemoryStorage implements Storage {\n  private readonly store: Map<string, string> = new Map();\n\n  /**\n   * Gets the number of items stored in the storage.\n   */\n  get length(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Clears all items from the storage.\n   */\n  clear(): void {\n    this.store.clear();\n  }\n\n  /**\n   * Gets an item from the storage.\n   * @param key - The key of the item to retrieve\n   * @returns The value of the item, or null if the item does not exist\n   */\n  getItem(key: string): string | null {\n    const value = this.store.get(key);\n    return value !== undefined ? value : null;\n  }\n\n  /**\n   * Gets the key at the specified index.\n   * @param index - The index of the key to retrieve\n   * @returns The key at the specified index, or null if the index is out of bounds\n   */\n  key(index: number): string | null {\n    const keys = Array.from(this.store.keys());\n    return keys[index] || null;\n  }\n\n  /**\n   * Removes an item from the storage.\n   * @param key - The key of the item to remove\n   */\n  removeItem(key: string): void {\n    this.store.delete(key);\n  }\n\n  /**\n   * Sets an item in the storage.\n   * @param key - The key of the item to set\n   * @param value - The value to set\n   */\n  setItem(key: string, value: string): void {\n    this.store.set(key, value);\n  }\n}","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { InMemoryStorage } from './inMemoryStorage';\n\n/**\n * Checks if the current environment is a browser.\n * @returns True if running in a browser environment, false otherwise\n */\nexport function isBrowser(): boolean {\n  return typeof window !== 'undefined';\n}\n\n/**\n * Gets the appropriate storage implementation based on the environment.\n * Returns localStorage in browser environments if available, InMemoryStorage otherwise.\n * @returns A Storage-compatible object\n */\nexport const getStorage = (): Storage => {\n  if (isBrowser()) {\n    return window.localStorage;\n  }\n  return new InMemoryStorage();\n};\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Interface for serializing and deserializing values\n * @template Serialized The type of the serialized value\n * @template Deserialized The type of the deserialized value\n */\nexport interface Serializer<Serialized, Deserialized> {\n  /**\n   * Serializes a value to the specified format\n   * @param value The value to serialize\n   * @returns The serialized value\n   */\n  serialize(value: any): Serialized;\n\n  /**\n   * Deserializes a value from the specified format\n   * @param value The value to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: Serialized): Deserialized;\n}\n\n/**\n * Implementation of Serializer that uses JSON for serialization\n */\nexport class JsonSerializer implements Serializer<string, any> {\n  /**\n   * Serializes a value to a JSON string\n   * @param value The value to serialize\n   * @returns The JSON string representation of the value\n   */\n  serialize(value: any): string {\n    return JSON.stringify(value);\n  }\n\n  /**\n   * Deserializes a JSON string to a value\n   * @param value The JSON string to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: string): any {\n    return JSON.parse(value);\n  }\n}\n\n/**\n * Implementation of Serializer that performs no actual serialization\n * @template T The type of the value to pass through\n */\nexport class IdentitySerializer<T> implements Serializer<T, T> {\n  /**\n   * Returns the value as-is without serialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  serialize(value: T): T {\n    return value;\n  }\n\n  /**\n   * Returns the value as-is without deserialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  deserialize(value: T): T {\n    return value;\n  }\n}\n\n/**\n * Global instance of JsonSerializer\n */\nexport const jsonSerializer = new JsonSerializer();\n/**\n * Global instance of IdentitySerializer\n */\nexport const identitySerializer = new IdentitySerializer<any>();\n\nexport function typedIdentitySerializer<T>(): IdentitySerializer<T> {\n  return identitySerializer as IdentitySerializer<T>;\n}\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Serializer, typedIdentitySerializer } from './serializer';\nimport {\n  EventHandler, nameGenerator,\n  SerialTypedEventBus,\n  TypedEventBus,\n} from '@ahoo-wang/fetcher-eventbus';\nimport { getStorage } from './env';\n\nexport interface StorageEvent<Deserialized> {\n  newValue?: Deserialized | null;\n  oldValue?: Deserialized | null;\n}\n\n/**\n * A function that removes a storage listener when called.\n */\nexport type RemoveStorageListener = () => void;\n\nexport interface StorageListenable<Deserialized> {\n  /**\n   * Adds a listener for storage changes.\n   * @param listener - The listener function to be called when storage changes\n   * @returns A function that can be called to remove the listener\n   */\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener;\n}\n\n/**\n * Options for configuring KeyStorage\n */\nexport interface KeyStorageOptions<Deserialized> {\n  /**\n   * The key used to store and retrieve values from storage\n   */\n  key: string;\n\n  /**\n   * Optional serializer for converting values to and from storage format\n   * Defaults to IdentitySerializer if not provided\n   */\n  serializer?: Serializer<string, Deserialized>;\n\n  /**\n   * Optional storage instance. Defaults to localStorage\n   */\n  storage?: Storage;\n\n  /**\n   * Optional event bus for cross-tab communication. Defaults to SerialTypedEventBus\n   */\n  eventBus?: TypedEventBus<StorageEvent<Deserialized>>;\n}\n\n/**\n * A storage wrapper that manages a single value associated with a specific key\n * Provides caching and automatic cache invalidation when the storage value changes\n * @template Deserialized The type of the value being stored\n */\nexport class KeyStorage<Deserialized>\n  implements StorageListenable<Deserialized> {\n  private readonly key: string;\n  private readonly serializer: Serializer<string, Deserialized>;\n  private readonly storage: Storage;\n  private readonly eventBus: TypedEventBus<StorageEvent<Deserialized>>;\n  private cacheValue: Deserialized | null = null;\n  private readonly keyStorageHandler: EventHandler<StorageEvent<Deserialized>> = {\n    name: nameGenerator.generate('KeyStorage'),\n    handle: (event: StorageEvent<Deserialized>) => {\n      this.cacheValue = event.newValue ?? null;\n    },\n  };\n\n  /**\n   * Creates a new KeyStorage instance\n   * @param options Configuration options for the storage\n   */\n  constructor(options: KeyStorageOptions<Deserialized>) {\n    this.key = options.key;\n    this.serializer = options.serializer ?? typedIdentitySerializer();\n    this.storage = options.storage ?? getStorage();\n    this.eventBus =\n      options.eventBus ??\n      new SerialTypedEventBus<StorageEvent<Deserialized>>(\n        `KeyStorage:${this.key}`,\n      );\n    this.eventBus.on(this.keyStorageHandler);\n  }\n\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener {\n    this.eventBus.on(listener);\n    return () => this.eventBus.off(listener.name);\n  }\n\n  get(): Deserialized | null {\n    if (this.cacheValue) {\n      return this.cacheValue;\n    }\n    const value = this.storage.getItem(this.key);\n    if (!value) {\n      return null;\n    }\n    this.cacheValue = this.serializer.deserialize(value);\n    return this.cacheValue;\n  }\n\n  set(value: Deserialized): void {\n    const oldValue = this.get();\n    const serialized = this.serializer.serialize(value);\n    this.storage.setItem(this.key, serialized);\n    this.cacheValue = value;\n    this.eventBus.emit({\n      newValue: value,\n      oldValue: oldValue,\n    });\n  }\n\n  remove(): void {\n    const oldValue = this.get();\n    this.storage.removeItem(this.key);\n    this.cacheValue = null;\n    this.eventBus.emit({\n      oldValue: oldValue,\n      newValue: null,\n    });\n  }\n\n  destroy() {\n    this.eventBus.off(this.keyStorageHandler.name);\n  }\n}\n"],"names":["InMemoryStorage","key","value","index","isBrowser","getStorage","JsonSerializer","IdentitySerializer","jsonSerializer","identitySerializer","typedIdentitySerializer","KeyStorage","options","nameGenerator","event","SerialTypedEventBus","listener","oldValue","serialized"],"mappings":"yTAaO,MAAMA,CAAmC,CAAzC,aAAA,CACL,KAAiB,UAAiC,GAAI,CAKtD,IAAI,QAAiB,CACnB,OAAO,KAAK,MAAM,IACpB,CAKA,OAAc,CACZ,KAAK,MAAM,MAAA,CACb,CAOA,QAAQC,EAA4B,CAClC,MAAMC,EAAQ,KAAK,MAAM,IAAID,CAAG,EAChC,OAAOC,IAAU,OAAYA,EAAQ,IACvC,CAOA,IAAIC,EAA8B,CAEhC,OADa,MAAM,KAAK,KAAK,MAAM,MAAM,EAC7BA,CAAK,GAAK,IACxB,CAMA,WAAWF,EAAmB,CAC5B,KAAK,MAAM,OAAOA,CAAG,CACvB,CAOA,QAAQA,EAAaC,EAAqB,CACxC,KAAK,MAAM,IAAID,EAAKC,CAAK,CAC3B,CACF,CC/CO,SAASE,GAAqB,CACnC,OAAO,OAAO,OAAW,GAC3B,CAOO,MAAMC,EAAa,IACpBD,IACK,OAAO,aAET,IAAIJ,ECKN,MAAMM,CAAkD,CAM7D,UAAUJ,EAAoB,CAC5B,OAAO,KAAK,UAAUA,CAAK,CAC7B,CAOA,YAAYA,EAAoB,CAC9B,OAAO,KAAK,MAAMA,CAAK,CACzB,CACF,CAMO,MAAMK,CAAkD,CAM7D,UAAUL,EAAa,CACrB,OAAOA,CACT,CAOA,YAAYA,EAAa,CACvB,OAAOA,CACT,CACF,CAKO,MAAMM,EAAiB,IAAIF,EAIrBG,EAAqB,IAAIF,EAE/B,SAASG,GAAoD,CAClE,OAAOD,CACT,CCnBO,MAAME,CACgC,CAiB3C,YAAYC,EAA0C,CAZtD,KAAQ,WAAkC,KAC1C,KAAiB,kBAA8D,CAC7E,KAAMC,EAAAA,cAAc,SAAS,YAAY,EACzC,OAASC,GAAsC,CAC7C,KAAK,WAAaA,EAAM,UAAY,IACtC,CAAA,EAQA,KAAK,IAAMF,EAAQ,IACnB,KAAK,WAAaA,EAAQ,YAAcF,EAAA,EACxC,KAAK,QAAUE,EAAQ,SAAWP,EAAA,EAClC,KAAK,SACHO,EAAQ,UACR,IAAIG,EAAAA,oBACF,cAAc,KAAK,GAAG,EAAA,EAE1B,KAAK,SAAS,GAAG,KAAK,iBAAiB,CACzC,CAEA,YACEC,EACuB,CACvB,YAAK,SAAS,GAAGA,CAAQ,EAClB,IAAM,KAAK,SAAS,IAAIA,EAAS,IAAI,CAC9C,CAEA,KAA2B,CACzB,GAAI,KAAK,WACP,OAAO,KAAK,WAEd,MAAMd,EAAQ,KAAK,QAAQ,QAAQ,KAAK,GAAG,EAC3C,OAAKA,GAGL,KAAK,WAAa,KAAK,WAAW,YAAYA,CAAK,EAC5C,KAAK,YAHH,IAIX,CAEA,IAAIA,EAA2B,CAC7B,MAAMe,EAAW,KAAK,IAAA,EAChBC,EAAa,KAAK,WAAW,UAAUhB,CAAK,EAClD,KAAK,QAAQ,QAAQ,KAAK,IAAKgB,CAAU,EACzC,KAAK,WAAahB,EAClB,KAAK,SAAS,KAAK,CACjB,SAAUA,EACV,SAAAe,CAAA,CACD,CACH,CAEA,QAAe,CACb,MAAMA,EAAW,KAAK,IAAA,EACtB,KAAK,QAAQ,WAAW,KAAK,GAAG,EAChC,KAAK,WAAa,KAClB,KAAK,SAAS,KAAK,CACjB,SAAAA,EACA,SAAU,IAAA,CACX,CACH,CAEA,SAAU,CACR,KAAK,SAAS,IAAI,KAAK,kBAAkB,IAAI,CAC/C,CACF"}
+{"version":3,"file":"index.umd.js","sources":["../src/inMemoryStorage.ts","../src/env.ts","../src/serializer.ts","../src/keyStorage.ts"],"sourcesContent":["/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport class InMemoryStorage implements Storage {\n  private readonly store: Map<string, string> = new Map();\n\n  /**\n   * Gets the number of items stored in the storage.\n   */\n  get length(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Clears all items from the storage.\n   */\n  clear(): void {\n    this.store.clear();\n  }\n\n  /**\n   * Gets an item from the storage.\n   * @param key - The key of the item to retrieve\n   * @returns The value of the item, or null if the item does not exist\n   */\n  getItem(key: string): string | null {\n    const value = this.store.get(key);\n    return value !== undefined ? value : null;\n  }\n\n  /**\n   * Gets the key at the specified index.\n   * @param index - The index of the key to retrieve\n   * @returns The key at the specified index, or null if the index is out of bounds\n   */\n  key(index: number): string | null {\n    const keys = Array.from(this.store.keys());\n    return keys[index] || null;\n  }\n\n  /**\n   * Removes an item from the storage.\n   * @param key - The key of the item to remove\n   */\n  removeItem(key: string): void {\n    this.store.delete(key);\n  }\n\n  /**\n   * Sets an item in the storage.\n   * @param key - The key of the item to set\n   * @param value - The value to set\n   */\n  setItem(key: string, value: string): void {\n    this.store.set(key, value);\n  }\n}","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { InMemoryStorage } from './inMemoryStorage';\n\n/**\n * Checks if the current environment is a browser.\n * @returns True if running in a browser environment, false otherwise\n */\nexport function isBrowser(): boolean {\n  return typeof window !== 'undefined';\n}\n\n/**\n * Gets the appropriate storage implementation based on the environment.\n * Returns localStorage in browser environments if available, InMemoryStorage otherwise.\n * @returns A Storage-compatible object\n */\nexport const getStorage = (): Storage => {\n  if (isBrowser()) {\n    return window.localStorage;\n  }\n  return new InMemoryStorage();\n};\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Interface for serializing and deserializing values\n * @template Serialized The type of the serialized value\n * @template Deserialized The type of the deserialized value\n */\nexport interface Serializer<Serialized, Deserialized> {\n  /**\n   * Serializes a value to the specified format\n   * @param value The value to serialize\n   * @returns The serialized value\n   */\n  serialize(value: any): Serialized;\n\n  /**\n   * Deserializes a value from the specified format\n   * @param value The value to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: Serialized): Deserialized;\n}\n\n/**\n * Implementation of Serializer that uses JSON for serialization\n */\nexport class JsonSerializer implements Serializer<string, any> {\n  /**\n   * Serializes a value to a JSON string\n   * @param value The value to serialize\n   * @returns The JSON string representation of the value\n   */\n  serialize(value: any): string {\n    return JSON.stringify(value);\n  }\n\n  /**\n   * Deserializes a JSON string to a value\n   * @param value The JSON string to deserialize\n   * @returns The deserialized value\n   */\n  deserialize(value: string): any {\n    return JSON.parse(value);\n  }\n}\n\n/**\n * Implementation of Serializer that performs no actual serialization\n * @template T The type of the value to pass through\n */\nexport class IdentitySerializer<T> implements Serializer<T, T> {\n  /**\n   * Returns the value as-is without serialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  serialize(value: T): T {\n    return value;\n  }\n\n  /**\n   * Returns the value as-is without deserialization\n   * @param value The value to pass through\n   * @returns The same value that was passed in\n   */\n  deserialize(value: T): T {\n    return value;\n  }\n}\n\n/**\n * Global instance of JsonSerializer\n */\nexport const jsonSerializer = new JsonSerializer();\n/**\n * Global instance of IdentitySerializer\n */\nexport const identitySerializer = new IdentitySerializer<any>();\n\nexport function typedIdentitySerializer<T>(): IdentitySerializer<T> {\n  return identitySerializer as IdentitySerializer<T>;\n}\n","/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Serializer, typedIdentitySerializer } from './serializer';\nimport {\n  EventHandler,\n  nameGenerator,\n  SerialTypedEventBus,\n  TypedEventBus,\n} from '@ahoo-wang/fetcher-eventbus';\nimport { getStorage } from './env';\n\nexport interface StorageEvent<Deserialized> {\n  newValue?: Deserialized | null;\n  oldValue?: Deserialized | null;\n}\n\n/**\n * A function that removes a storage listener when called.\n */\nexport type RemoveStorageListener = () => void;\n\nexport interface StorageListenable<Deserialized> {\n  /**\n   * Adds a listener for storage changes.\n   * @param listener - The listener function to be called when storage changes\n   * @returns A function that can be called to remove the listener\n   */\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener;\n}\n\n/**\n * Options for configuring KeyStorage\n */\nexport interface KeyStorageOptions<Deserialized> {\n  /**\n   * The key used to store and retrieve values from storage\n   */\n  key: string;\n\n  /**\n   * Optional serializer for converting values to and from storage format\n   * Defaults to IdentitySerializer if not provided\n   */\n  serializer?: Serializer<string, Deserialized>;\n\n  /**\n   * Optional storage instance. Defaults to localStorage\n   */\n  storage?: Storage;\n\n  /**\n   * Optional event bus for cross-tab communication. Defaults to SerialTypedEventBus\n   */\n  eventBus?: TypedEventBus<StorageEvent<Deserialized>>;\n}\n\n/**\n * A storage wrapper that manages a single value associated with a specific key\n * Provides caching and automatic cache invalidation when the storage value changes\n * @template Deserialized The type of the value being stored\n */\nexport class KeyStorage<Deserialized>\n  implements StorageListenable<Deserialized>\n{\n  private readonly key: string;\n  private readonly serializer: Serializer<string, Deserialized>;\n  private readonly storage: Storage;\n  private readonly eventBus: TypedEventBus<StorageEvent<Deserialized>>;\n  private cacheValue: Deserialized | null = null;\n  private readonly keyStorageHandler: EventHandler<StorageEvent<Deserialized>> =\n    {\n      name: nameGenerator.generate('KeyStorage'),\n      handle: (event: StorageEvent<Deserialized>) => {\n        this.cacheValue = event.newValue ?? null;\n      },\n    };\n\n  /**\n   * Creates a new KeyStorage instance\n   * @param options Configuration options for the storage\n   */\n  constructor(options: KeyStorageOptions<Deserialized>) {\n    this.key = options.key;\n    this.serializer = options.serializer ?? typedIdentitySerializer();\n    this.storage = options.storage ?? getStorage();\n    this.eventBus =\n      options.eventBus ??\n      new SerialTypedEventBus<StorageEvent<Deserialized>>(\n        `KeyStorage:${this.key}`,\n      );\n    this.eventBus.on(this.keyStorageHandler);\n  }\n\n  /**\n   * Adds a listener for storage changes.\n   *\n   * The listener will be called whenever the storage value changes,\n   * either locally or from other tabs/windows.\n   *\n   * @param listener - The event handler to be called when storage changes\n   * @returns A function that can be called to remove the listener\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * const removeListener = storage.addListener({\n   *   name: 'userNameChange',\n   *   handle: (event) => {\n   *     console.log('User name changed:', event.newValue);\n   *   }\n   * });\n   *\n   * // Later, to remove the listener\n   * removeListener();\n   * ```\n   */\n  addListener(\n    listener: EventHandler<StorageEvent<Deserialized>>,\n  ): RemoveStorageListener {\n    this.eventBus.on(listener);\n    return () => this.eventBus.off(listener.name);\n  }\n\n  /**\n   * Retrieves the current value from storage.\n   *\n   * Uses caching to avoid repeated deserialization. If the value is not in cache,\n   * it retrieves it from the underlying storage and deserializes it.\n   *\n   * @returns The deserialized value, or null if no value exists in storage\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * const userName = storage.get();\n   * console.log(userName); // 'John Doe' or null\n   * ```\n   */\n  get(): Deserialized | null {\n    if (this.cacheValue) {\n      return this.cacheValue;\n    }\n    const value = this.storage.getItem(this.key);\n    if (!value) {\n      return null;\n    }\n    this.cacheValue = this.serializer.deserialize(value);\n    return this.cacheValue;\n  }\n\n  /**\n   * Stores a value in storage and notifies all listeners.\n   *\n   * Serializes the value, stores it in the underlying storage, updates the cache,\n   * and emits a change event to all registered listeners.\n   *\n   * @param value - The value to store (will be serialized before storage)\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * storage.set('John Doe');\n   * ```\n   */\n  set(value: Deserialized): void {\n    const oldValue = this.get();\n    const serialized = this.serializer.serialize(value);\n    this.storage.setItem(this.key, serialized);\n    this.cacheValue = value;\n    this.eventBus.emit({\n      newValue: value,\n      oldValue: oldValue,\n    });\n  }\n\n  /**\n   * Removes the value from storage and notifies all listeners.\n   *\n   * Removes the item from the underlying storage, clears the cache,\n   * and emits a change event indicating the value was removed.\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * storage.remove(); // Removes the stored value\n   * ```\n   */\n  remove(): void {\n    const oldValue = this.get();\n    this.storage.removeItem(this.key);\n    this.cacheValue = null;\n    this.eventBus.emit({\n      oldValue: oldValue,\n      newValue: null,\n    });\n  }\n\n  /**\n   * Cleans up resources used by the KeyStorage instance.\n   *\n   * Removes the internal event handler from the event bus.\n   * Should be called when the KeyStorage instance is no longer needed\n   * to prevent memory leaks.\n   *\n   * @example\n   * ```typescript\n   * const storage = new KeyStorage<string>({ key: 'userName' });\n   * // ... use storage ...\n   * storage.destroy(); // Clean up resources\n   * ```\n   */\n  destroy() {\n    this.eventBus.off(this.keyStorageHandler.name);\n  }\n}\n"],"names":["InMemoryStorage","key","value","index","isBrowser","getStorage","JsonSerializer","IdentitySerializer","jsonSerializer","identitySerializer","typedIdentitySerializer","KeyStorage","options","nameGenerator","event","SerialTypedEventBus","listener","oldValue","serialized"],"mappings":"yTAaO,MAAMA,CAAmC,CAAzC,aAAA,CACL,KAAiB,UAAiC,GAAI,CAKtD,IAAI,QAAiB,CACnB,OAAO,KAAK,MAAM,IACpB,CAKA,OAAc,CACZ,KAAK,MAAM,MAAA,CACb,CAOA,QAAQC,EAA4B,CAClC,MAAMC,EAAQ,KAAK,MAAM,IAAID,CAAG,EAChC,OAAOC,IAAU,OAAYA,EAAQ,IACvC,CAOA,IAAIC,EAA8B,CAEhC,OADa,MAAM,KAAK,KAAK,MAAM,MAAM,EAC7BA,CAAK,GAAK,IACxB,CAMA,WAAWF,EAAmB,CAC5B,KAAK,MAAM,OAAOA,CAAG,CACvB,CAOA,QAAQA,EAAaC,EAAqB,CACxC,KAAK,MAAM,IAAID,EAAKC,CAAK,CAC3B,CACF,CC/CO,SAASE,GAAqB,CACnC,OAAO,OAAO,OAAW,GAC3B,CAOO,MAAMC,EAAa,IACpBD,IACK,OAAO,aAET,IAAIJ,ECKN,MAAMM,CAAkD,CAM7D,UAAUJ,EAAoB,CAC5B,OAAO,KAAK,UAAUA,CAAK,CAC7B,CAOA,YAAYA,EAAoB,CAC9B,OAAO,KAAK,MAAMA,CAAK,CACzB,CACF,CAMO,MAAMK,CAAkD,CAM7D,UAAUL,EAAa,CACrB,OAAOA,CACT,CAOA,YAAYA,EAAa,CACvB,OAAOA,CACT,CACF,CAKO,MAAMM,EAAiB,IAAIF,EAIrBG,EAAqB,IAAIF,EAE/B,SAASG,GAAoD,CAClE,OAAOD,CACT,CClBO,MAAME,CAEb,CAkBE,YAAYC,EAA0C,CAbtD,KAAQ,WAAkC,KAC1C,KAAiB,kBACf,CACE,KAAMC,EAAAA,cAAc,SAAS,YAAY,EACzC,OAASC,GAAsC,CAC7C,KAAK,WAAaA,EAAM,UAAY,IACtC,CAAA,EAQF,KAAK,IAAMF,EAAQ,IACnB,KAAK,WAAaA,EAAQ,YAAcF,EAAA,EACxC,KAAK,QAAUE,EAAQ,SAAWP,EAAA,EAClC,KAAK,SACHO,EAAQ,UACR,IAAIG,EAAAA,oBACF,cAAc,KAAK,GAAG,EAAA,EAE1B,KAAK,SAAS,GAAG,KAAK,iBAAiB,CACzC,CAyBA,YACEC,EACuB,CACvB,YAAK,SAAS,GAAGA,CAAQ,EAClB,IAAM,KAAK,SAAS,IAAIA,EAAS,IAAI,CAC9C,CAiBA,KAA2B,CACzB,GAAI,KAAK,WACP,OAAO,KAAK,WAEd,MAAMd,EAAQ,KAAK,QAAQ,QAAQ,KAAK,GAAG,EAC3C,OAAKA,GAGL,KAAK,WAAa,KAAK,WAAW,YAAYA,CAAK,EAC5C,KAAK,YAHH,IAIX,CAgBA,IAAIA,EAA2B,CAC7B,MAAMe,EAAW,KAAK,IAAA,EAChBC,EAAa,KAAK,WAAW,UAAUhB,CAAK,EAClD,KAAK,QAAQ,QAAQ,KAAK,IAAKgB,CAAU,EACzC,KAAK,WAAahB,EAClB,KAAK,SAAS,KAAK,CACjB,SAAUA,EACV,SAAAe,CAAA,CACD,CACH,CAcA,QAAe,CACb,MAAMA,EAAW,KAAK,IAAA,EACtB,KAAK,QAAQ,WAAW,KAAK,GAAG,EAChC,KAAK,WAAa,KAClB,KAAK,SAAS,KAAK,CACjB,SAAAA,EACA,SAAU,IAAA,CACX,CACH,CAgBA,SAAU,CACR,KAAK,SAAS,IAAI,KAAK,kBAAkB,IAAI,CAC/C,CACF"}

package/dist/keyStorage.d.ts

@@ -55,10 +55,88 @@ export declare class KeyStorage<Deserialized> implements StorageListenable<Deser
      * @param options Configuration options for the storage
      */
     constructor(options: KeyStorageOptions<Deserialized>);
+    /**
+     * Adds a listener for storage changes.
+     *
+     * The listener will be called whenever the storage value changes,
+     * either locally or from other tabs/windows.
+     *
+     * @param listener - The event handler to be called when storage changes
+     * @returns A function that can be called to remove the listener
+     *
+     * @example
+     * ```typescript
+     * const storage = new KeyStorage<string>({ key: 'userName' });
+     * const removeListener = storage.addListener({
+     *   name: 'userNameChange',
+     *   handle: (event) => {
+     *     console.log('User name changed:', event.newValue);
+     *   }
+     * });
+     *
+     * // Later, to remove the listener
+     * removeListener();
+     * ```
+     */
     addListener(listener: EventHandler<StorageEvent<Deserialized>>): RemoveStorageListener;
+    /**
+     * Retrieves the current value from storage.
+     *
+     * Uses caching to avoid repeated deserialization. If the value is not in cache,
+     * it retrieves it from the underlying storage and deserializes it.
+     *
+     * @returns The deserialized value, or null if no value exists in storage
+     *
+     * @example
+     * ```typescript
+     * const storage = new KeyStorage<string>({ key: 'userName' });
+     * const userName = storage.get();
+     * console.log(userName); // 'John Doe' or null
+     * ```
+     */
     get(): Deserialized | null;
+    /**
+     * Stores a value in storage and notifies all listeners.
+     *
+     * Serializes the value, stores it in the underlying storage, updates the cache,
+     * and emits a change event to all registered listeners.
+     *
+     * @param value - The value to store (will be serialized before storage)
+     *
+     * @example
+     * ```typescript
+     * const storage = new KeyStorage<string>({ key: 'userName' });
+     * storage.set('John Doe');
+     * ```
+     */
     set(value: Deserialized): void;
+    /**
+     * Removes the value from storage and notifies all listeners.
+     *
+     * Removes the item from the underlying storage, clears the cache,
+     * and emits a change event indicating the value was removed.
+     *
+     * @example
+     * ```typescript
+     * const storage = new KeyStorage<string>({ key: 'userName' });
+     * storage.remove(); // Removes the stored value
+     * ```
+     */
     remove(): void;
+    /**
+     * Cleans up resources used by the KeyStorage instance.
+     *
+     * Removes the internal event handler from the event bus.
+     * Should be called when the KeyStorage instance is no longer needed
+     * to prevent memory leaks.
+     *
+     * @example
+     * ```typescript
+     * const storage = new KeyStorage<string>({ key: 'userName' });
+     * // ... use storage ...
+     * storage.destroy(); // Clean up resources
+     * ```
+     */
     destroy(): void;
 }
 //# sourceMappingURL=keyStorage.d.ts.map

package/dist/keyStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyStorage.d.ts","sourceRoot":"","sources":["../src/keyStorage.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,UAAU,EAA2B,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,YAAY,EAEZ,aAAa,EACd,MAAM,6BAA6B,CAAC;AAGrC,MAAM,WAAW,YAAY,CAAC,YAAY;IACxC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,IAAI,CAAC;AAE/C,MAAM,WAAW,iBAAiB,CAAC,YAAY;IAC7C;;;;OAIG;IACH,WAAW,CACT,QAAQ,EAAE,YAAY,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,GACjD,qBAAqB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,YAAY;IAC7C;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE9C;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,qBAAa,UAAU,CAAC,YAAY,CAClC,YAAW,iBAAiB,CAAC,YAAY,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAKhC;IAEF;;;OAGG;gBACS,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC;IAYpD,WAAW,CACT,QAAQ,EAAE,YAAY,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,GACjD,qBAAqB;IAKxB,GAAG,IAAI,YAAY,GAAG,IAAI;IAY1B,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAW9B,MAAM,IAAI,IAAI;IAUd,OAAO;CAGR"}
+{"version":3,"file":"keyStorage.d.ts","sourceRoot":"","sources":["../src/keyStorage.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,UAAU,EAA2B,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,YAAY,EAGZ,aAAa,EACd,MAAM,6BAA6B,CAAC;AAGrC,MAAM,WAAW,YAAY,CAAC,YAAY;IACxC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,IAAI,CAAC;AAE/C,MAAM,WAAW,iBAAiB,CAAC,YAAY;IAC7C;;;;OAIG;IACH,WAAW,CACT,QAAQ,EAAE,YAAY,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,GACjD,qBAAqB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,YAAY;IAC7C;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE9C;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,qBAAa,UAAU,CAAC,YAAY,CAClC,YAAW,iBAAiB,CAAC,YAAY,CAAC;IAE1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAM9B;IAEJ;;;OAGG;gBACS,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC;IAYpD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,WAAW,CACT,QAAQ,EAAE,YAAY,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,GACjD,qBAAqB;IAKxB;;;;;;;;;;;;;;OAcG;IACH,GAAG,IAAI,YAAY,GAAG,IAAI;IAY1B;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAW9B;;;;;;;;;;;OAWG;IACH,MAAM,IAAI,IAAI;IAUd;;;;;;;;;;;;;OAaG;IACH,OAAO;CAGR"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher-storage",
-  "version": "2.9.6",
+  "version": "2.9.8",
   "description": "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.",
   "keywords": [
     "storage",