@ahoo-wang/fetcher-react 3.4.1 → 3.4.3

package/README.zh-CN.md

@@ -26,30 +26,39 @@
 - [安装](#安装)
 - [快速开始](#快速开始)
 - [使用方法](#使用方法)
-  - [useFetcher Hook](#usefetcher-hook)
+  - [核心 Hooks](#核心-hooks)
+    - [useFetcher](#usefetcher-hook)
+    - [useExecutePromise](#useexecutepromise)
+    - [usePromiseState](#usepromisestate)
   - [防抖 Hooks](#防抖-hooks)
     - [useDebouncedCallback](#usedebouncedcallback)
     - [useDebouncedExecutePromise](#usedebouncedexecutepromise)
     - [useDebouncedFetcher](#usedebouncedfetcher)
-  - [useExecutePromise Hook](#useexecutepromise-hook)
-  - [usePromiseState Hook](#usepromisestate-hook)
-  - [useRequestId Hook](#userequestid-hook)
-  - [useLatest Hook](#uselatest-hook)
-- [useRefs Hook](#userefs-hook)
-- [useEventSubscription Hook](#useeventsubscription-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)
-  - [useFetcherCountQuery Hook](#usefetchercountquery-hook)
-  - [useFetcherPagedQuery Hook](#usefetcherpagedquery-hook)
-  - [useFetcherListQuery Hook](#usefetcherlistquery-hook)
-  - [useFetcherListStreamQuery Hook](#usefetcherliststreamquery-hook)
-  - [useFetcherSingleQuery Hook](#usefetchersinglequery-hook)
-  - [useListStreamQuery Hook](#useliststreamquery-hook)
+    - [useDebouncedFetcherQuery](#usedebouncedfetcherquery)
+    - [useDebouncedQuery](#usedebouncedquery)
+  - [工具 Hooks](#工具-hooks)
+    - [useRequestId](#userequestid)
+    - [useLatest](#uselatest)
+    - [useRefs](#userefs)
+  - [存储 Hooks](#存储-hooks)
+    - [useKeyStorage](#usekeystorage)
+    - [useImmerKeyStorage](#useimmerkeystorage-hook)
+  - [事件 Hooks](#事件-hooks)
+    - [useEventSubscription](#useeventsubscription-hook)
+  - [Wow 查询 Hooks](#wow-查询-hooks)
+    - [基础查询 Hooks](#基础查询-hooks)
+      - [useListQuery](#uselistquery-hook)
+      - [usePagedQuery](#usepagedquery-hook)
+      - [useSingleQuery](#usesinglequery-hook)
+      - [useCountQuery](#usecountquery-hook)
+    - [获取查询 Hooks](#获取查询-hooks)
+      - [useFetcherListQuery](#usefetcherlistquery-hook)
+      - [useFetcherPagedQuery](#usefetcherpagedquery-hook)
+      - [useFetcherSingleQuery](#usefetchersinglequery-hook)
+      - [useFetcherCountQuery](#usefetchercountquery-hook)
+    - [流查询 Hooks](#流查询-hooks)
+      - [useListStreamQuery](#useliststreamquery-hook)
+      - [useFetcherListStreamQuery](#usefetcherliststreamquery-hook)
 - [最佳实践](#最佳实践)
 - [API 参考](#api-参考)
 - [许可证](#许可证)
@@ -62,7 +71,7 @@ npm install @ahoo-wang/fetcher-react
 
 ### 要求
 
-- React 16.8+ (hooks 支持)
+- React 19.0+ (hooks 支持)
 - TypeScript 4.0+ (完整类型安全)
 
 ## 快速开始
@@ -90,7 +99,9 @@ function App() {
 
 ## 使用方法
 
-### useFetcher Hook
+### 核心 Hooks
+
+#### useFetcher Hook
 
 `useFetcher` hook 提供完整的数据获取功能，具有自动状态管理、竞态条件保护和灵活的配置选项。
 
@@ -367,7 +378,9 @@ const [prefs, updatePrefs] = useImmerKeyStorage(prefsStorage);
 
 Wow 查询 Hooks 提供高级数据查询功能，具有内置的状态管理，用于条件、投影、排序、分页和限制。这些 hooks 专为与 `@ahoo-wang/fetcher-wow` 包配合使用而设计，用于复杂的查询操作。
 
-### useListQuery Hook
+### 基础查询 Hooks
+
+#### useListQuery Hook
 
 `useListQuery` hook 管理列表查询，具有条件、投影、排序和限制的状态管理。
 
@@ -517,7 +530,9 @@ const MyComponent = () => {
 };
 ```
 
-### useFetcherCountQuery Hook
+### 获取查询 Hooks
+
+#### useFetcherCountQuery Hook
 
 `useFetcherCountQuery` hook 是使用 Fetcher 库执行计数查询的专用 React hook。它专为需要检索匹配特定条件的记录数量的场景而设计，返回表示计数的数字。
 
@@ -965,7 +980,9 @@ const MyComponent = () => {
 };
 ```
 
-### useListStreamQuery Hook
+### 流查询 Hooks
+
+#### useListStreamQuery Hook
 
 `useListStreamQuery` hook 管理列表流查询，返回服务器发送事件的 readable stream。
 
@@ -1140,6 +1157,246 @@ function useDebouncedFetcher<R, E = FetcherError>(
 - `cancel`: 取消任何待处理防抖执行的函数
 - `isPending`: 布尔值，表示防抖调用是否待处理
 
+#### useDebouncedFetcherQuery
+
+```typescript
+function useDebouncedFetcherQuery<Q, R, E = FetcherError>(
+  options: UseDebouncedFetcherQueryOptions<Q, R, E>,
+): UseDebouncedFetcherQueryReturn<Q, R, E>;
+```
+
+将基于查询的 HTTP 获取与防抖相结合，非常适合搜索输入和动态查询场景，您希望根据查询参数防抖 API 调用。
+
+```typescript jsx
+import { useDebouncedFetcherQuery } from '@ahoo-wang/fetcher-react';
+
+interface SearchQuery {
+  keyword: string;
+  limit: number;
+  filters?: { category?: string };
+}
+
+interface SearchResult {
+  items: Array<{ id: string; title: string }>;
+  total: number;
+}
+
+const SearchComponent = () => {
+  const {
+    loading,
+    result,
+    error,
+    run,
+    cancel,
+    isPending,
+    setQuery,
+    getQuery,
+  } = useDebouncedFetcherQuery<SearchQuery, SearchResult>({
+    url: '/api/search',
+    initialQuery: { keyword: '', limit: 10 },
+    debounce: { delay: 300 }, // 防抖 300ms
+    autoExecute: false, // 挂载时不执行
+  });
+
+  const handleSearch = (keyword: string) => {
+    setQuery({ keyword, limit: 10 }); // 如果 autoExecute 为 true，这将触发防抖执行
+  };
+
+  const handleManualSearch = () => {
+    run(); // 使用当前查询手动防抖执行
+  };
+
+  const handleCancel = () => {
+    cancel(); // 取消任何待处理的防抖执行
+  };
+
+  if (loading) return <div>搜索中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <input
+        type="text"
+        onChange={(e) => handleSearch(e.target.value)}
+        placeholder="搜索..."
+      />
+      <button onClick={handleManualSearch} disabled={isPending()}>
+        {isPending() ? '搜索中...' : '搜索'}
+      </button>
+      <button onClick={handleCancel}>取消</button>
+      {result && (
+        <div>
+          找到 {result.total} 项:
+          {result.items.map(item => (
+            <div key={item.id}>{item.title}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+**主要特性:**
+
+- **查询状态管理**: 使用 `setQuery` 和 `getQuery` 自动查询参数处理
+- **防抖执行**: 在快速用户输入期间防止过多 API 调用
+- **自动执行**: 可选的在查询参数更改时自动执行
+- **手动控制**: `run()` 用于手动执行，`cancel()` 用于取消
+- **待处理状态**: `isPending()` 检查防抖调用是否排队
+
+**类型参数:**
+
+- `Q`: 查询参数的类型
+- `R`: 获取结果的类型
+- `E`: 错误的类型（默认为 FetcherError）
+
+**参数:**
+
+- `options`: 扩展 `UseFetcherQueryOptions` 和 `DebounceCapable` 的配置对象
+  - `url`: API 端点 URL（必需）
+  - `initialQuery`: 初始查询参数（必需）
+  - `autoExecute?`: 查询参数更改时是否自动执行
+  - `debounce`: 防抖配置（delay、leading、trailing）
+  - HTTP 请求选项（method、headers、timeout 等）
+
+**返回:**
+
+包含以下内容的对象：
+
+- `loading`: 布尔值，表示获取当前是否正在执行
+- `result`: 获取的解析值
+- `error`: 执行期间发生的任何错误
+- `status`: 当前执行状态
+- `reset`: 重置获取器状态的函数
+- `abort`: 中止当前操作的函数
+- `getQuery`: 获取当前查询参数的函数
+- `setQuery`: 更新查询参数的函数
+- `run`: 使用当前查询执行防抖获取的函数
+- `cancel`: 取消任何待处理防抖执行的函数
+- `isPending`: 返回布尔值表示防抖执行当前是否待处理的函数
+
+#### useDebouncedQuery
+
+将通用查询执行与防抖相结合，非常适合自定义查询操作，您希望根据查询参数防抖执行。
+
+```typescript jsx
+import { useDebouncedQuery } from '@ahoo-wang/fetcher-react';
+
+interface SearchQuery {
+  keyword: string;
+  limit: number;
+  filters?: { category?: string };
+}
+
+interface SearchResult {
+  items: Array<{ id: string; title: string }>;
+  total: number;
+}
+
+const SearchComponent = () => {
+  const {
+    loading,
+    result,
+    error,
+    run,
+    cancel,
+    isPending,
+    setQuery,
+    getQuery,
+  } = useDebouncedQuery<SearchQuery, SearchResult>({
+    initialQuery: { keyword: '', limit: 10 },
+    execute: async (query) => {
+      const response = await fetch('/api/search', {
+        method: 'POST',
+        body: JSON.stringify(query),
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return response.json();
+    },
+    debounce: { delay: 300 }, // 防抖 300ms
+    autoExecute: false, // 挂载时不执行
+  });
+
+  const handleSearch = (keyword: string) => {
+    setQuery({ keyword, limit: 10 }); // 如果 autoExecute 为 true，这将触发防抖执行
+  };
+
+  const handleManualSearch = () => {
+    run(); // 使用当前查询手动防抖执行
+  };
+
+  const handleCancel = () => {
+    cancel(); // 取消任何待处理的防抖执行
+  };
+
+  if (loading) return <div>搜索中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <input
+        type="text"
+        onChange={(e) => handleSearch(e.target.value)}
+        placeholder="搜索..."
+      />
+      <button onClick={handleManualSearch} disabled={isPending()}>
+        {isPending() ? '搜索中...' : '搜索'}
+      </button>
+      <button onClick={handleCancel}>取消</button>
+      {result && (
+        <div>
+          找到 {result.total} 项:
+          {result.items.map(item => (
+            <div key={item.id}>{item.title}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+**主要特性:**
+
+- **查询状态管理**: 使用 `setQuery` 和 `getQuery` 自动查询参数处理
+- **防抖执行**: 在快速查询更改期间防止过多操作
+- **自动执行**: 可选的在查询参数更改时自动执行
+- **手动控制**: `run()` 用于手动执行，`cancel()` 用于取消
+- **待处理状态**: `isPending()` 检查防抖调用是否排队
+- **自定义执行**: 灵活的 execute 函数用于任何查询操作
+
+**类型参数:**
+
+- `Q`: 查询参数的类型
+- `R`: 结果的类型
+- `E`: 错误的类型（默认为 FetcherError）
+
+**参数:**
+
+- `options`: 扩展 `UseQueryOptions` 和 `DebounceCapable` 的配置对象
+  - `initialQuery`: 初始查询参数（必需）
+  - `execute`: 使用参数执行查询的函数
+  - `autoExecute?`: 挂载时或查询参数更改时是否自动执行
+  - `debounce`: 防抖配置（delay、leading、trailing）
+  - 所有来自 `UseExecutePromiseOptions` 的选项
+
+**返回:**
+
+包含以下内容的对象：
+
+- `loading`: 布尔值，表示查询当前是否正在执行
+- `result`: 查询的解析值
+- `error`: 执行期间发生的任何错误
+- `status`: 当前执行状态
+- `reset`: 重置查询状态的函数
+- `abort`: 中止当前操作的函数
+- `getQuery`: 获取当前查询参数的函数
+- `setQuery`: 更新查询参数的函数
+- `run`: 使用当前参数执行防抖查询的函数
+- `cancel`: 取消任何待处理防抖执行的函数
+- `isPending`: 返回布尔值表示防抖执行当前是否待处理的函数
+
 ### useFetcher
 
 ```typescript
@@ -1242,7 +1499,9 @@ function usePromiseState<R = unknown, E = unknown>(
 - `setError`: 设置状态为 ERROR 并提供错误
 - `setIdle`: 设置状态为 IDLE
 
-### useRequestId
+### 工具 Hooks
+
+#### useRequestId
 
 ```typescript
 function useRequestId(): UseRequestIdReturn;
@@ -1313,7 +1572,9 @@ React hook，用于使用 Map-like 接口管理多个 refs，允许通过键动
 - `RefKey = string | number | symbol`
 - `UseRefsReturn<T> extends Iterable<[RefKey, T]>`
 
-### useEventSubscription Hook
+### 事件 Hooks
+
+#### useEventSubscription Hook
 
 `useEventSubscription` hook 为类型化事件总线提供了 React 接口。它自动管理订阅生命周期，同时提供手动控制功能以增加灵活性。
 
@@ -1354,7 +1615,9 @@ function MyComponent() {
 - **错误处理**: 对失败的订阅尝试记录警告
 - **事件总线集成**: 与 `@ahoo-wang/fetcher-eventbus` TypedEventBus 实例无缝配合
 
-### useKeyStorage
+### 存储 Hooks
+
+#### useKeyStorage
 
 ```typescript jsx
 function useKeyStorage<T>(