@ahoo-wang/fetcher-react 3.1.9 → 3.2.0

package/README.zh-CN.md

@@ -37,12 +37,13 @@
   - [useLatest Hook](#uselatest-hook)
   - [useRefs Hook](#userefs-hook)
   - [useKeyStorage Hook](#usekeystorage-hook)
+  - [useImmerKeyStorage Hook](#useimmerkeystorage-hook)
   - [Wow 查询 Hooks](#wow-查询-hooks)
-    - [useListQuery Hook](#uselistquery-hook)
-    - [usePagedQuery Hook](#usepagedquery-hook)
-    - [useSingleQuery Hook](#usesinglequery-hook)
-    - [useCountQuery Hook](#usecountquery-hook)
-    - [useListStreamQuery Hook](#useliststreamquery-hook)
+  - [useListQuery Hook](#uselistquery-hook)
+  - [usePagedQuery Hook](#usepagedquery-hook)
+  - [useSingleQuery Hook](#usesinglequery-hook)
+  - [useCountQuery Hook](#usecountquery-hook)
+  - [useListStreamQuery Hook](#useliststreamquery-hook)
 - [最佳实践](#最佳实践)
 - [API 参考](#api-参考)
 - [许可证](#许可证)
@@ -98,443 +99,262 @@ const MyComponent = () => {
 };
 ```
 
-#### 自动执行示例
+### useImmerKeyStorage Hook
 
-```typescript jsx
-import { useListQuery } from '@ahoo-wang/fetcher-react';
-
-const MyComponent = () => {
-  const { result, loading, error, execute, setCondition } = useListQuery({
-    initialQuery: { condition: {}, projection: {}, sort: [], limit: 10 },
-    execute: async (listQuery) => fetchListData(listQuery),
-    autoExecute: true, // 在组件挂载时自动执行
-  });
-
-  // 查询将在组件挂载时自动执行
-  // 您仍然可以通过 execute() 手动触发或更新条件
+🚀 **Immer 驱动的不可变状态管理** - `useImmerKeyStorage` hook 通过集成 Immer 的 `produce` 函数扩展了 `useKeyStorage`，允许开发者以直观的"可变"方式更新存储值，同时在底层保持不可变性。非常适合复杂对象的操作，具有自动存储同步功能。
 
-  if (loading) return <div>加载中...</div>;
-  if (error) return <div>错误: {error.message}</div>;
-
-  return (
-    <div>
-      <ul>
-        {result?.map((item, index) => (
-          <li key={index}>{item.name}</li>
-        ))}
-      </ul>
-    </div>
-  );
-};
-```
+#### 主要优势
 
-### 防抖 Hooks
+- **直观的变更语法**: 编写看起来可变的代码，但产生不可变更新
+- **深度对象支持**: 轻松处理嵌套对象和数组
+- **类型安全**: 完整的 TypeScript 支持和编译时错误检查
+- **性能优化**: 利用 Immer 的结构共享和最小化重渲染
+- **自动同步**: 变更自动持久化到存储并跨组件同步
 
-🚀 **高级 React 防抖库** - 强大的 hooks 将防抖与异步操作相结合，为 API 调用、用户交互和 Promise 执行提供无缝的速率限制。
+#### 使用场景
 
-#### useDebouncedCallback
+在需要以下情况时选择 `useImmerKeyStorage` 而不是 `useKeyStorage`：
 
-一个 React hook，为任何回调函数提供防抖版本，支持前缘/后缘执行选项。
+- 更新嵌套对象属性
+- 执行复杂的数组操作（push、splice 等）
+- 原子性地进行多个相关变更
+- 处理深度嵌套的数据结构
 
 ```typescript jsx
-import { useDebouncedCallback } from '@ahoo-wang/fetcher-react';
-
-const SearchComponent = () => {
-  const { run: debouncedSearch, cancel, isPending } = useDebouncedCallback(
-    async (query: string) => {
-      const response = await fetch(`/api/search?q=${query}`);
-      const results = await response.json();
-      console.log('搜索结果:', results);
-    },
-    { delay: 300 }
-  );
+import { KeyStorage } from '@ahoo-wang/fetcher-storage';
+import { useImmerKeyStorage } from '@ahoo-wang/fetcher-react';
 
-  const handleSearch = (query: string) => {
-    if (query.trim()) {
-      debouncedSearch(query);
-    } else {
-      cancel(); // 取消任何待处理的搜索
-    }
-  };
+const MyComponent = () => {
+  const prefsStorage = new KeyStorage<{
+    theme: string;
+    volume: number;
+    notifications: boolean;
+    shortcuts: { [key: string]: string };
+  }>({
+    key: 'user-prefs'
+  });
+
+  // 不使用默认值 - 可能为 null
+  const [prefs, updatePrefs, clearPrefs] = useImmerKeyStorage(prefsStorage);
 
   return (
     <div>
-      <input
-        type="text"
-        placeholder="搜索..."
-        onChange={(e) => handleSearch(e.target.value)}
-      />
-      {isPending() && <div>搜索中...</div>}
+      <p>主题: {prefs?.theme || '默认'}</p>
+      <button onClick={() => updatePrefs(draft => { draft.theme = 'dark'; })}>
+        切换到深色主题
+      </button>
+      <button onClick={() => updatePrefs(draft => { draft.volume += 10; })}>
+        增加音量
+      </button>
+      <button onClick={clearPrefs}>
+        清除偏好设置
+      </button>
     </div>
   );
 };
 ```
 
-**配置选项：**
-
-- `delay`: 执行前的延迟毫秒数（必需，正数）
-- `leading`: 第一次调用时立即执行（默认: false）
-- `trailing`: 最后一次调用后延迟执行（默认: true）
-
-#### useDebouncedExecutePromise
-
-将 Promise 执行与防抖功能相结合，非常适合 API 调用和异步操作。
+#### 使用默认值
 
 ```typescript jsx
-import { useDebouncedExecutePromise } from '@ahoo-wang/fetcher-react';
-
-const DataFetcher = () => {
-  const { loading, result, error, run } = useDebouncedExecutePromise({
-    debounce: { delay: 300 },
+const AudioControls = () => {
+  const settingsStorage = new KeyStorage<{ volume: number; muted: boolean }>({
+    key: 'audio-settings'
   });
 
-  const handleLoadUser = (userId: string) => {
-    run(async () => {
-      const response = await fetch(`/api/users/${userId}`);
-      return response.json();
-    });
-  };
+  // 使用默认值 - 保证不为 null
+  const [settings, updateSettings, resetSettings] = useImmerKeyStorage(
+    settingsStorage,
+    { volume: 50, muted: false }
+  );
 
   return (
     <div>
-      <button onClick={() => handleLoadUser('user123')}>
-        加载用户
+      <p>音量: {settings.volume}%</p>
+      <button onClick={() => updateSettings(draft => {
+        draft.volume = Math.min(100, draft.volume + 10);
+        draft.muted = false;
+      })}>
+        增加音量
+      </button>
+      <button onClick={() => updateSettings(draft => { draft.muted = !draft.muted; })}>
+        切换静音
+      </button>
+      <button onClick={resetSettings}>
+        重置为默认值
       </button>
-      {loading && <div>加载中...</div>}
-      {error && <div>错误: {error.message}</div>}
-      {result && <div>用户: {result.name}</div>}
     </div>
   );
 };
 ```
 
-#### useDebouncedFetcher
+#### 高级用法模式
 
-专门的 hook，将 HTTP 获取与防抖相结合，建立在核心获取器库之上。
+##### 批量更新
 
 ```typescript jsx
-import { useDebouncedFetcher } from '@ahoo-wang/fetcher-react';
-
-const SearchInput = () => {
-  const [query, setQuery] = useState('');
-  const { loading, result, error, run } = useDebouncedFetcher({
-    debounce: { delay: 300 },
-    onSuccess: (data) => {
-      setSearchResults(data.results);
-    }
+const updateUserProfile = () => {
+  updatePrefs(draft => {
+    draft.theme = 'dark';
+    draft.notifications = true;
+    draft.volume = 75;
   });
-
-  const handleChange = (value: string) => {
-    setQuery(value);
-    if (value.trim()) {
-      run({
-        url: '/api/search',
-        method: 'GET',
-        params: { q: value }
-      });
-    }
-  };
-
-  return (
-    <div>
-      <input
-        value={query}
-        onChange={(e) => handleChange(e.target.value)}
-        placeholder="搜索..."
-      />
-      {loading && <div>搜索中...</div>}
-      {error && <div>错误: {error.message}</div>}
-      {result && <SearchResults data={result} />}
-    </div>
-  );
 };
 ```
 
-**防抖策略：**
-
-- **前缘执行**: 第一次调用时立即执行，然后对后续调用进行防抖
-- **后缘执行**: 最后一次调用后延迟执行（默认行为）
-- **前缘 + 后缘**: 立即执行，如果再次调用则在延迟后再次执行
-
-### useExecutePromise Hook
-
-`useExecutePromise` hook 管理异步操作，具有自动状态处理、竞态条件保护和 promise 状态选项支持。
+##### 数组操作
 
 ```typescript jsx
-import { useExecutePromise } from '@ahoo-wang/fetcher-react';
-
-const MyComponent = () => {
-  const { loading, result, error, execute, reset } = useExecutePromise<string>();
+const todoStorage = new KeyStorage<{
+  todos: Array<{ id: number; text: string; done: boolean }>;
+}>({
+  key: 'todos',
+});
 
-  const fetchData = async () => {
-    const response = await fetch('/api/data');
-    return response.text();
-  };
+const [state, updateState] = useImmerKeyStorage(todoStorage, { todos: [] });
 
-  const handleFetch = () => {
-    execute(fetchData); // 使用 promise supplier
-  };
+// 添加新待办事项
+const addTodo = (text: string) => {
+  updateState(draft => {
+    draft.todos.push({
+      id: Date.now(),
+      text,
+      done: false,
+    });
+  });
+};
 
-  const handleDirectPromise = () => {
-    const promise = fetch('/api/data').then(res => res.text());
-    execute(promise); // 使用直接 promise
-  };
+// 切换待办事项状态
+const toggleTodo = (id: number) => {
+  updateState(draft => {
+    const todo = draft.todos.find(t => t.id === id);
+    if (todo) {
+      todo.done = !todo.done;
+    }
+  });
+};
 
-  if (loading) return <div>加载中...</div>;
-  if (error) return <div>错误: {error.message}</div>;
-  return (
-    <div>
-      <button onClick={handleFetch}>使用 Supplier 获取</button>
-      <button onClick={handleDirectPromise}>使用 Promise 获取</button>
-      <button onClick={reset}>重置</button>
-      {result && <p>{result}</p>}
-    </div>
-  );
+// 清除已完成的待办事项
+const clearCompleted = () => {
+  updateState(draft => {
+    draft.todos = draft.todos.filter(todo => !todo.done);
+  });
 };
 ```
 
-### usePromiseState Hook
-
-`usePromiseState` hook 提供 promise 操作的状态管理，无执行逻辑。支持静态选项和动态选项供应商。
+##### 嵌套对象更新
 
 ```typescript jsx
-import { usePromiseState, PromiseStatus } from '@ahoo-wang/fetcher-react';
-
-const MyComponent = () => {
-  const { status, loading, result, error, setSuccess, setError, setIdle } = usePromiseState<string>();
+const configStorage = new KeyStorage<{
+  ui: { theme: string; language: string };
+  features: { [key: string]: boolean };
+}>({
+  key: 'app-config',
+});
 
-  const handleSuccess = () => setSuccess('数据加载成功');
-  const handleError = () => setError(new Error('加载失败'));
+const [config, updateConfig] = useImmerKeyStorage(configStorage, {
+  ui: { theme: 'light', language: 'zh' },
+  features: {},
+});
 
-  return (
-    <div>
-      <button onClick={handleSuccess}>设置成功</button>
-      <button onClick={handleError}>设置错误</button>
-      <button onClick={setIdle}>重置</button>
-      <p>状态: {status}</p>
-      {loading && <p>加载中...</p>}
-      {result && <p>结果: {result}</p>}
-      {error && <p>错误: {error.message}</p>}
-    </div>
-  );
+// 更新嵌套属性
+const updateTheme = (theme: string) => {
+  updateConfig(draft => {
+    draft.ui.theme = theme;
+  });
 };
-```
-
-#### usePromiseState with Options Supplier
-
-```typescript jsx
-import { usePromiseState, PromiseStatus } from '@ahoo-wang/fetcher-react';
 
-const MyComponent = () => {
-  // 使用选项供应商进行动态配置
-  const optionsSupplier = () => ({
-    initialStatus: PromiseStatus.IDLE,
-    onSuccess: async (result: string) => {
-      await saveToAnalytics(result);
-      console.log('成功:', result);
-    },
-    onError: async (error) => {
-      await logErrorToServer(error);
-      console.error('错误:', error);
-    },
+const toggleFeature = (feature: string) => {
+  updateConfig(draft => {
+    draft.features[feature] = !draft.features[feature];
   });
-
-  const { setSuccess, setError } = usePromiseState<string>(optionsSupplier);
-
-  return (
-    <div>
-      <button onClick={() => setSuccess('动态成功!')}>设置成功</button>
-      <button onClick={() => setError(new Error('动态错误!'))}>设置错误</button>
-    </div>
-  );
 };
 ```
 
-### useRequestId Hook
-
-`useRequestId` hook 提供请求ID管理，用于防止异步操作中的竞态条件。
+##### 带验证的条件更新
 
 ```typescript jsx
-import { useRequestId } from '@ahoo-wang/fetcher-react';
-
-const MyComponent = () => {
-  const { generate, isLatest, invalidate } = useRequestId();
-
-  const handleFetch = async () => {
-    const requestId = generate();
-
-    try {
-      const result = await fetchData();
-
-      if (isLatest(requestId)) {
-        setData(result);
-      }
-    } catch (error) {
-      if (isLatest(requestId)) {
-        setError(error);
-      }
+const updateVolume = (newVolume: number) => {
+  updateSettings(draft => {
+    if (newVolume >= 0 && newVolume <= 100) {
+      draft.volume = newVolume;
+      draft.muted = false; // 音量改变时取消静音
     }
-  };
-
-  return (
-    <div>
-      <button onClick={handleFetch}>获取数据</button>
-      <button onClick={invalidate}>取消进行中</button>
-    </div>
-  );
+  });
 };
 ```
 
-### useLatest Hook
-
-`useLatest` hook 返回包含最新值的 ref 对象，用于在异步回调中访问当前值。
+##### 返回新值
 
 ```typescript jsx
-import { useLatest } from '@ahoo-wang/fetcher-react';
-
-const MyComponent = () => {
-  const [count, setCount] = useState(0);
-  const latestCount = useLatest(count);
-
-  const handleAsync = async () => {
-    await someAsyncOperation();
-    console.log('最新计数:', latestCount.current); // 始终是最新值
-  };
+// 替换整个状态
+const resetToFactorySettings = () => {
+  updateSettings(() => ({ volume: 50, muted: false }));
+};
 
-  return (
-    <div>
-      <p>计数: {count}</p>
-      <button onClick={() => setCount(c => c + 1)}>递增</button>
-      <button onClick={handleAsync}>异步记录</button>
-    </div>
-  );
+// 计算更新
+const setMaxVolume = () => {
+  updateSettings(draft => ({ ...draft, volume: 100, muted: false }));
 };
 ```
 
-### useRefs Hook
-
-`useRefs` hook 提供 Map-like 接口用于动态管理多个 React refs。它允许通过键注册、检索和管理 refs，并在组件卸载时自动清理。
+##### 错误处理
 
 ```typescript jsx
-import { useRefs } from '@ahoo-wang/fetcher-react';
-
-const MyComponent = () => {
-  const refs = useRefs<HTMLDivElement>();
-
-  const handleFocus = (key: string) => {
-    const element = refs.get(key);
-    element?.focus();
-  };
-
-  return (
-    <div>
-      <div ref={refs.register('first')} tabIndex={0}>第一个元素</div>
-      <div ref={refs.register('second')} tabIndex={0}>第二个元素</div>
-      <button onClick={() => handleFocus('first')}>聚焦第一个</button>
-      <button onClick={() => handleFocus('second')}>聚焦第二个</button>
-    </div>
-  );
+const safeUpdate = (updater: (draft: any) => void) => {
+  try {
+    updatePrefs(updater);
+  } catch (error) {
+    console.error('更新偏好设置失败:', error);
+    // 适当处理错误
+  }
 };
 ```
 
-关键特性：
+#### 最佳实践
 
-- **动态注册**: 使用字符串、数字或符号键注册 refs
-- **Map-like API**: 完整的 Map 接口，包括 get、set、has、delete 等
-- **自动清理**: 组件卸载时自动清空 refs
-- **类型安全**: 完整的 TypeScript 支持
+##### ✅ 推荐做法
 
-### useKeyStorage Hook
+- 用于复杂对象更新和数组操作
+- 利用 Immer 的 draft 变更编写可读代码
+- 在单个更新调用中组合多个相关变更
+- 对保证非空状态使用默认值
+- 在更新函数中适当处理错误
 
-`useKeyStorage` hook 为 KeyStorage 实例提供反应式状态管理。它订阅存储变化并返回当前值以及设置函数。可选接受默认值以在存储为空时使用。
+##### ❌ 避免做法
 
-```typescript jsx
-import { KeyStorage } from '@ahoo-wang/fetcher-storage';
-import { useKeyStorage } from '@ahoo-wang/fetcher-react';
-
-const MyComponent = () => {
-  const keyStorage = new KeyStorage<string>({ key: 'my-key' });
+- 不要直接用赋值修改 draft 参数（`draft = newValue`）
+- 不要在更新函数中执行副作用
+- 不要依赖对象比较的引用相等性
+- 不要用于简单的原始值更新（应使用 `useKeyStorage`）
 
-  // 不使用默认值 - 可能为 null
-  const [value, setValue] = useKeyStorage(keyStorage);
+##### 性能提示
 
-  return (
-    <div>
-      <p>当前值: {value || '未存储值'}</p>
-      <button onClick={() => setValue('新值')}>
-        更新值
-      </button>
-    </div>
-  );
-};
-```
+- 将相关更新批量处理以最小化存储操作
+- 当新状态依赖于之前状态时使用函数式更新
+- 如果更新函数经常重新创建，考虑使用 `useCallback`
+- 如果处理非常大的对象，请分析更新性能
 
-#### 使用默认值
+##### TypeScript 集成
 
 ```typescript jsx
-const MyComponent = () => {
-  const keyStorage = new KeyStorage<string>({ key: 'theme' });
-
-  // 使用默认值 - 保证不为 null
-  const [theme, setTheme] = useKeyStorage(keyStorage, 'light');
-
-  return (
-    <div className={theme}>
-      <p>当前主题: {theme}</p>
-      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
-        切换主题
-      </button>
-    </div>
-  );
+// 为更好的安全性定义严格类型
+type UserPreferences = {
+  theme: 'light' | 'dark' | 'auto';
+  volume: number; // 0-100
+  notifications: boolean;
+  shortcuts: Record<string, string>;
 };
-```
-
-### 更多示例
-
-```typescript jsx
-// 处理不同类型的值
-const numberStorage = new KeyStorage<number>({ key: 'counter' });
-const [count, setCount] = useKeyStorage(numberStorage, 0); // 默认为 0
-
-// 处理对象
-interface User {
-  id: string;
-  name: string;
-}
 
-const userStorage = new KeyStorage<User>({ key: 'current-user' });
-const [user, setUser] = useKeyStorage(userStorage, { id: '', name: '访客' });
-
-// 复杂状态管理
-const settingsStorage = new KeyStorage<{ volume: number; muted: boolean }>({
-  key: 'audio-settings',
-});
-const [settings, setSettings] = useKeyStorage(settingsStorage, {
-  volume: 50,
-  muted: false,
+const prefsStorage = new KeyStorage<UserPreferences>({
+  key: 'user-prefs',
 });
 
-// 更新特定属性
-const updateVolume = (newVolume: number) => {
-  setSettings({ ...settings, volume: newVolume });
-};
-```
-
-### 更多示例
+// TypeScript 将捕获无效更新
+const [prefs, updatePrefs] = useImmerKeyStorage(prefsStorage);
 
-```typescript jsx
-// 处理不同类型的值
-const numberStorage = new KeyStorage<number>({ key: 'counter' });
-const [count, setCount] = useKeyStorage(numberStorage);
-
-// 处理对象
-interface User {
-  id: string;
-  name: string;
-}
-
-const userStorage = new KeyStorage<User>({ key: 'current-user' });
-const [user, setUser] = useKeyStorage(userStorage);
+// 这将导致 TypeScript 错误：
+// updatePrefs(draft => { draft.theme = 'invalid'; });
 ```
 
 ## Wow 查询 Hooks
@@ -1057,6 +877,73 @@ function useKeyStorage<T>(
 
 - 包含当前存储值和更新函数的元组
 
+### useImmerKeyStorage
+
+```typescript
+// 不使用默认值 - 可能返回 null
+function useImmerKeyStorage<T>(
+  keyStorage: KeyStorage<T>,
+): [
+  T | null,
+  (updater: (draft: T | null) => T | null | void) => void,
+  () => void,
+];
+
+// 使用默认值 - 保证非空
+function useImmerKeyStorage<T>(
+  keyStorage: KeyStorage<T>,
+  defaultValue: T,
+): [T, (updater: (draft: T) => T | null | void) => void, () => void];
+```
+
+为 KeyStorage 实例提供 Immer 驱动的不可变状态管理的 React hook。通过集成 Immer 的 `produce` 函数扩展 `useKeyStorage`，允许直观的"可变"更新存储值，同时保持不可变性。
+
+**类型参数:**
+
+- `T`: 存储值的数据类型
+
+**参数:**
+
+- `keyStorage`: 要订阅和管理的 KeyStorage 实例。应该是稳定的引用（useRef、memo 或模块级实例）
+- `defaultValue` _(可选)_: 当存储为空时使用的默认值。提供时，hook 保证返回的值永远不会为 null
+
+**返回值:**
+
+包含以下元素的元组：
+
+- **当前值**: `T | null`（无默认值时）或 `T`（有默认值时）
+- **更新函数**: `(updater: (draft: T | null) => T | null | void) => void` - Immer 驱动的更新函数
+- **清除函数**: `() => void` - 删除存储值的函数
+
+**更新函数:**
+
+更新函数接收一个可以直接变更的 `draft` 参数。Immer 将从这些变更中产生不可变更新。更新函数也可以直接返回新值或 `null` 来清除存储。
+
+**示例:**
+
+```typescript
+// 基本对象更新
+const [user, updateUser] = useImmerKeyStorage(userStorage);
+updateUser(draft => {
+  if (draft) {
+    draft.name = 'John';
+    draft.age = 30;
+  }
+});
+
+// 数组操作
+const [todos, updateTodos] = useImmerKeyStorage(todosStorage, []);
+updateTodos(draft => {
+  draft.push({ id: 1, text: '新待办事项', done: false });
+});
+
+// 返回新值
+updateTodos(() => [{ id: 1, text: '重置待办事项', done: false }]);
+
+// 清除存储
+updateTodos(() => null);
+```
+
 ### useListQuery
 
 ```typescript