@ahoo-wang/fetcher-react 3.3.8 → 3.4.0

package/README.zh-CN.md

@@ -39,11 +39,16 @@
 - [useEventSubscription Hook](#useeventsubscription-hook)
 - [useKeyStorage Hook](#usekeystorage-hook)
   - [useImmerKeyStorage Hook](#useimmerkeystorage-hook)
-  - [Wow 查询 Hooks](#wow-查询-hooks)
+- [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)
 - [最佳实践](#最佳实践)
 - [API 参考](#api-参考)
@@ -512,6 +517,454 @@ const MyComponent = () => {
 };
 ```
 
+### useFetcherCountQuery Hook
+
+`useFetcherCountQuery` hook 是使用 Fetcher 库执行计数查询的专用 React hook。它专为需要检索匹配特定条件的记录数量的场景而设计，返回表示计数的数字。
+
+```typescript jsx
+import { useFetcherCountQuery } from '@ahoo-wang/fetcher-react';
+import { all } from '@ahoo-wang/fetcher-wow';
+
+function UserCountComponent() {
+  const { data: count, loading, error, execute } = useFetcherCountQuery({
+    url: '/api/users/count',
+    initialQuery: all(),
+    autoExecute: true,
+  });
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <div>活跃用户总数: {count}</div>
+      <button onClick={execute}>刷新计数</button>
+    </div>
+  );
+}
+```
+
+#### 自动执行示例
+
+```typescript jsx
+import { useFetcherCountQuery } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const { data: count, loading, error, execute } = useFetcherCountQuery({
+    url: '/api/users/count',
+    initialQuery: { status: 'active' },
+    autoExecute: true, // 组件挂载时自动执行
+  });
+
+  // 查询将在组件挂载时自动执行
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <p>活跃用户总数: {count}</p>
+    </div>
+  );
+};
+```
+
+### useFetcherPagedQuery Hook
+
+`useFetcherPagedQuery` hook 是使用 Fetcher 库执行分页查询的专用 React hook。它专为需要检索匹配查询条件的分页数据的场景而设计，返回包含当前页面项目以及分页元数据的 PagedList。
+
+```typescript jsx
+import { useFetcherPagedQuery } from '@ahoo-wang/fetcher-react';
+import { pagedQuery, contains, pagination, desc } from '@ahoo-wang/fetcher-wow';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+function UserListComponent() {
+  const {
+    data: pagedList,
+    loading,
+    error,
+    execute,
+    setQuery,
+    getQuery
+  } = useFetcherPagedQuery<User, keyof User>({
+    url: '/api/users/paged',
+    initialQuery: pagedQuery({
+      condition: contains('name', 'John'),
+      sort: [desc('createdAt')],
+      pagination: pagination({ index: 1, size: 10 })
+    }),
+    autoExecute: true,
+  });
+
+  const goToPage = (page: number) => {
+    const currentQuery = getQuery();
+    setQuery({
+      ...currentQuery,
+      pagination: { ...currentQuery.pagination, index: page }
+    });
+  };
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>用户</h2>
+      <ul>
+        {pagedList.list.map(user => (
+          <li key={user.id}>{user.name} - {user.email}</li>
+        ))}
+      </ul>
+      <div>
+        <span>总数: {pagedList.total} 用户</span>
+        <button onClick={() => goToPage(1)} disabled={pagedList.pagination.index === 1}>
+          第一页
+        </button>
+        <button onClick={() => goToPage(pagedList.pagination.index - 1)} disabled={pagedList.pagination.index === 1}>
+          上一页
+        </button>
+        <span>第 {pagedList.pagination.index} 页</span>
+        <button onClick={() => goToPage(pagedList.pagination.index + 1)}>
+          下一页
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+#### 自动执行示例
+
+```typescript jsx
+import { useFetcherPagedQuery } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const { data: pagedList, loading, error, execute } = useFetcherPagedQuery({
+    url: '/api/products/paged',
+    initialQuery: {
+      condition: { category: 'electronics' },
+      pagination: { index: 1, size: 20 },
+      projection: {},
+      sort: []
+    },
+    autoExecute: true, // 组件挂载时自动执行
+  });
+
+  // 查询将在组件挂载时自动执行
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>产品</h2>
+      <div>总数: {pagedList.total}</div>
+      <ul>
+        {pagedList.list.map(product => (
+          <li key={product.id}>{product.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+```
+
+### useFetcherListQuery Hook
+
+`useFetcherListQuery` hook 是使用 Fetcher 库执行列表查询的专用 React hook。它专为获取项目列表而设计，支持通过 ListQuery 类型进行过滤、排序和分页，返回结果数组。
+
+```typescript jsx
+import { useFetcherListQuery } from '@ahoo-wang/fetcher-react';
+import { listQuery, contains, desc } from '@ahoo-wang/fetcher-wow';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string;
+}
+
+function UserListComponent() {
+  const {
+    loading,
+    result: users,
+    error,
+    execute,
+    setQuery,
+    getQuery,
+  } = useFetcherListQuery<User, keyof User>({
+    url: '/api/users/list',
+    initialQuery: listQuery({
+      condition: contains('name', 'John'),
+      sort: [desc('createdAt')],
+      limit: 10,
+    }),
+    autoExecute: true,
+  });
+
+  const loadMore = () => {
+    const currentQuery = getQuery();
+    setQuery({
+      ...currentQuery,
+      limit: (currentQuery.limit || 10) + 10,
+    });
+  };
+
+  if (loading) return <div>正在加载用户...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>用户 ({users?.length || 0})</h2>
+      <ul>
+        {users?.map(user => (
+          <li key={user.id}>
+            {user.name} - {user.email}
+          </li>
+        ))}
+      </ul>
+      <button onClick={loadMore}>加载更多</button>
+      <button onClick={execute}>刷新列表</button>
+    </div>
+  );
+}
+```
+
+#### 自动执行示例
+
+```typescript jsx
+import { useFetcherListQuery } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const { result: products, loading, error, execute } = useFetcherListQuery({
+    url: '/api/products/list',
+    initialQuery: {
+      condition: { category: 'electronics' },
+      projection: {},
+      sort: [],
+      limit: 20
+    },
+    autoExecute: true, // 组件挂载时自动执行
+  });
+
+  // 查询将在组件挂载时自动执行
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>产品</h2>
+      <ul>
+        {products?.map(product => (
+          <li key={product.id}>{product.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+```
+
+### useFetcherListStreamQuery Hook
+
+`useFetcherListStreamQuery` hook 是使用 Fetcher 库通过服务器发送事件执行列表流查询的专用 React hook。它专为需要检索匹配列表查询条件的数据流场景而设计，返回 JSON 服务器发送事件的 ReadableStream，用于实时数据流式传输。
+
+```typescript jsx
+import { useFetcherListStreamQuery } from '@ahoo-wang/fetcher-react';
+import { listQuery, contains } from '@ahoo-wang/fetcher-wow';
+import { JsonServerSentEvent } from '@ahoo-wang/fetcher-eventstream';
+import { useEffect, useRef } from 'react';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+function UserStreamComponent() {
+  const { data: stream, loading, error, execute } = useFetcherListStreamQuery<User, 'id' | 'name'>({
+    url: '/api/users/stream',
+    initialQuery: listQuery({
+      condition: contains('name', 'John'),
+      limit: 10,
+    }),
+    autoExecute: true,
+  });
+
+  const messagesRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (stream) {
+      const reader = stream.getReader();
+      const readStream = async () => {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            // 处理 JsonServerSentEvent<User>
+            const newUser = value.data;
+            if (messagesRef.current) {
+              const div = document.createElement('div');
+              div.textContent = `新用户: ${newUser.name}`;
+              messagesRef.current.appendChild(div);
+            }
+          }
+        } catch (err) {
+          console.error('流错误:', err);
+        }
+      };
+      readStream();
+    }
+  }, [stream]);
+
+  if (loading) return <div>正在加载流...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <div ref={messagesRef}></div>
+      <button onClick={execute}>重新启动流</button>
+    </div>
+  );
+}
+```
+
+#### 自动执行示例
+
+```typescript jsx
+import { useFetcherListStreamQuery } from '@ahoo-wang/fetcher-react';
+import { useEffect, useRef } from 'react';
+
+const MyComponent = () => {
+  const { data: stream, loading, error, execute } = useFetcherListStreamQuery({
+    url: '/api/notifications/stream',
+    initialQuery: {
+      condition: { type: 'important' },
+      limit: 50
+    },
+    autoExecute: true, // 组件挂载时自动执行
+  });
+
+  const notificationsRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (stream) {
+      const reader = stream.getReader();
+      const processStream = async () => {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            const notification = value.data;
+            if (notificationsRef.current) {
+              const notificationDiv = document.createElement('div');
+              notificationDiv.textContent = `通知: ${notification.message}`;
+              notificationsRef.current.appendChild(notificationDiv);
+            }
+          }
+        } catch (err) {
+          console.error('流处理错误:', err);
+        }
+      };
+      processStream();
+    }
+  }, [stream]);
+
+  // 流将在组件挂载时自动启动
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>实时通知</h2>
+      <div ref={notificationsRef}></div>
+    </div>
+  );
+};
+```
+
+### useFetcherSingleQuery Hook
+
+`useFetcherSingleQuery` hook 是使用 Fetcher 库执行单个项目查询的专用 React hook。它专为获取单个项目而设计，支持通过 SingleQuery 类型进行过滤和排序，返回单个结果项目。
+
+```typescript jsx
+import { useFetcherSingleQuery } from '@ahoo-wang/fetcher-react';
+import { singleQuery, eq } from '@ahoo-wang/fetcher-wow';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string;
+}
+
+function UserProfileComponent({ userId }: { userId: string }) {
+  const {
+    loading,
+    result: user,
+    error,
+    execute,
+  } = useFetcherSingleQuery<User, keyof User>({
+    url: `/api/users/${userId}`,
+    initialQuery: singleQuery({
+      condition: eq('id', userId),
+    }),
+    autoExecute: true,
+  });
+
+  if (loading) return <div>正在加载用户...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+  if (!user) return <div>未找到用户</div>;
+
+  return (
+    <div>
+      <h2>{user.name}</h2>
+      <p>邮箱: {user.email}</p>
+      <p>创建时间: {user.createdAt}</p>
+      <button onClick={execute}>刷新</button>
+    </div>
+  );
+}
+```
+
+#### 自动执行示例
+
+```typescript jsx
+import { useFetcherSingleQuery } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const { result: product, loading, error, execute } = useFetcherSingleQuery({
+    url: '/api/products/featured',
+    initialQuery: {
+      condition: { featured: true },
+      projection: {},
+      sort: []
+    },
+    autoExecute: true, // 组件挂载时自动执行
+  });
+
+  // 查询将在组件挂载时自动执行
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+  if (!product) return <div>未找到产品</div>;
+
+  return (
+    <div>
+      <h2>特色产品</h2>
+      <div>{product.name}</div>
+      <div>{product.description}</div>
+    </div>
+  );
+};
+```
+
 ### useListStreamQuery Hook
 
 `useListStreamQuery` hook 管理列表流查询，返回服务器发送事件的 readable stream。
@@ -1085,6 +1538,156 @@ function useCountQuery<FIELDS extends string = string, E = FetcherError>(
 
 包含 promise 状态、execute 函数以及条件设置器的对象。
 
+### useFetcherCountQuery
+
+```typescript
+function useFetcherCountQuery<FIELDS extends string = string, E = FetcherError>(
+  options: UseFetcherCountQueryOptions<FIELDS, E>,
+): UseFetcherCountQueryReturn<FIELDS, E>;
+```
+
+使用 Fetcher 库执行计数查询的 React hook。它包装了 useFetcherQuery hook 并专门用于计数操作，返回表示计数的数字。
+
+**类型参数:**
+
+- `FIELDS`: 可在条件中使用的字段的字符串联合类型
+- `E`: 可能抛出的错误类型（默认为 `FetcherError`）
+
+**参数:**
+
+- `options`: 计数查询的配置选项，包括条件、fetcher 实例和其他查询设置
+  - `url`: 从中获取计数的 URL
+  - `initialQuery`: 计数查询的初始条件
+  - `autoExecute`: 是否在组件挂载时自动执行查询（默认为 false）
+
+**返回值:**
+
+包含查询结果（作为数字的计数）、加载状态、错误状态和实用函数的对象。
+
+### useFetcherPagedQuery
+
+```typescript
+function useFetcherPagedQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherPagedQueryOptions<R, FIELDS, E>,
+): UseFetcherPagedQueryReturn<R, FIELDS, E>;
+```
+
+使用 Fetcher 库执行分页查询的 React hook。它包装了 useFetcherQuery hook 并专门用于分页操作，返回包含项目和分页元数据的 PagedList。
+
+**类型参数:**
+
+- `R`: 分页列表中每个项目包含的资源或实体的类型
+- `FIELDS`: 可在分页查询中使用的字段的字符串联合类型
+- `E`: 可能抛出的错误类型（默认为 `FetcherError`）
+
+**参数:**
+
+- `options`: 分页查询的配置选项，包括分页查询参数、fetcher 实例和其他查询设置
+  - `url`: 从中获取分页数据的 URL
+  - `initialQuery`: 初始分页查询配置
+  - `autoExecute`: 是否在组件挂载时自动执行查询（默认为 false）
+
+**返回值:**
+
+包含查询结果（包含项目和分页信息的 PagedList）、加载状态、错误状态和实用函数的对象。
+
+### useFetcherListQuery
+
+```typescript
+function useFetcherListQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherListQueryOptions<R, FIELDS, E>,
+): UseFetcherListQueryReturn<R, FIELDS, E>;
+```
+
+使用 fetcher 库在 wow 框架中执行列表查询的 React hook。它包装了 useFetcherQuery hook 并专门用于列表操作，返回结果数组，支持过滤、排序和分页。
+
+**类型参数:**
+
+- `R`: 结果数组中单个项目的类型（例如，User、Product）
+- `FIELDS`: 列表查询中可用于过滤、排序和分页的字段
+- `E`: 可能抛出的错误类型（默认为 `FetcherError`）
+
+**参数:**
+
+- `options`: 列表查询的配置选项，包括列表查询参数、fetcher 实例和其他查询设置
+  - `url`: 从中获取列表数据的 URL
+  - `initialQuery`: 初始列表查询配置
+  - `autoExecute`: 是否在组件挂载时自动执行查询（默认为 false）
+
+**返回值:**
+
+包含查询结果（项目数组）、加载状态、错误状态和实用函数的对象。
+
+### useFetcherListStreamQuery
+
+```typescript
+function useFetcherListStreamQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherListStreamQueryOptions<R, FIELDS, E>,
+): UseFetcherListStreamQueryReturn<R, FIELDS, E>;
+```
+
+使用 Fetcher 库通过服务器发送事件执行列表流查询的 React hook。它包装了 useFetcherQuery hook 并专门用于流式操作，返回 JSON 服务器发送事件的 ReadableStream，用于实时数据流式传输。
+
+**类型参数:**
+
+- `R`: 流中每个事件包含的资源或实体的类型
+- `FIELDS`: 列表查询中可用于过滤、排序和分页的字段
+- `E`: 可能抛出的错误类型（默认为 `FetcherError`）
+
+**参数:**
+
+- `options`: 列表流查询的配置选项，包括列表查询参数、fetcher 实例和其他查询设置
+  - `url`: 从中获取流数据的 URL
+  - `initialQuery`: 初始列表查询配置
+  - `autoExecute`: 是否在组件挂载时自动执行查询（默认为 false）
+
+**返回值:**
+
+包含查询结果（JSON 服务器发送事件的 ReadableStream）、加载状态、错误状态和实用函数的对象。
+
+### useFetcherSingleQuery
+
+```typescript
+function useFetcherSingleQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherSingleQueryOptions<R, FIELDS, E>,
+): UseFetcherSingleQueryReturn<R, FIELDS, E>;
+```
+
+使用 fetcher 库在 wow 框架中执行单个项目查询的 React hook。它包装了 useFetcherQuery hook 并专门用于单个项目操作，返回单个结果项目，支持过滤和排序。
+
+**类型参数:**
+
+- `R`: 结果项目的类型（例如，User、Product）
+- `FIELDS`: 单个查询中可用于过滤和排序的字段
+- `E`: 可能抛出的错误类型（默认为 `FetcherError`）
+
+**参数:**
+
+- `options`: 单个查询的配置选项，包括单个查询参数、fetcher 实例和其他查询设置
+  - `url`: 从中获取单个项目的 URL
+  - `initialQuery`: 初始单个查询配置
+  - `autoExecute`: 是否在组件挂载时自动执行查询（默认为 false）
+
+**返回值:**
+
+包含查询结果（单个项目）、加载状态、错误状态和实用函数的对象。
+
 ### useListStreamQuery
 
 ```typescript