@ahoo-wang/wow-react 9.2.0-rc.0

package/README.zh-CN.md

@@ -0,0 +1,231 @@
+# `@ahoo-wang/wow-react`
+
+面向 [Wow](https://github.com/Ahoo-Wang/Wow) 查询的 React hook：单条、列表、分页、计数和
+列表流。它们把查询、结果、加载中与错误保存为 React 状态，建立在
+`@ahoo-wang/wow-client` 的查询类型之上。
+
+## 环境要求
+
+- **React 19.3 及以上。** 本包用 React Compiler 编译，产物导入只有 React 19 才有的
+  `react/compiler-runtime`；不支持 React 18。
+- 工具链与服务端渲染需要 Node.js 22.12 及以上；浏览器以 React 19 支持的为准。
+- `@ahoo-wang/wow-client` 与本包的次版本号一致。
+- TypeScript 6 或更高版本（CI 测试 6.0 到最新的 7.x），使用 `"moduleResolution": "bundler"` 或
+  `"module": "nodenext"`。
+
+## 安装
+
+```bash
+pnpm add react react-dom @ahoo-wang/fetcher @ahoo-wang/fetcher-eventstream \
+  @ahoo-wang/wow-client @ahoo-wang/wow-react
+```
+
+`@ahoo-wang/fetcher-eventstream` 是 `@ahoo-wang/wow-client` 的 peer，不是本包的。
+
+版本号跟随 Wow，次版本可能带有破坏性改动：用 `save-prefix=~` 或 `--save-exact` 让 Wow 包停在同一个次版本上，见[版本范围](https://wow.ahoo.me/zh/guide/typescript/compatibility#版本范围)。
+
+这些 hook 自带请求状态机：不需要 `@ahoo-wang/fetcher-react`，也不需要
+`@ahoo-wang/fetcher-wow`。
+
+本包只发布 ES 模块。Node.js 22.12+ 上的 CommonJS 代码仍可以
+`require('@ahoo-wang/wow-react')`，因为 Node.js 能通过 `require` 加载 ES 模块。
+
+## 配合查询客户端
+
+`use*Query` 这组 hook 接收一个 `execute` 函数。查询客户端的方法——
+`@ahoo-wang/wow-client` 的 `SnapshotQueryClient`，或生成的 `…QueryClientFactory`
+创建的客户端——签名恰好是 `execute` 需要的 `(query, attributes, abort)`，于是 URL、
+请求头和响应处理都由客户端负责，不用手写。这些客户端的方法已绑定到实例上，所以
+`execute: client.pagedState` 可以直接写；自己对象上的方法要 `.bind(对象)` 或包一层
+箭头函数：
+
+```tsx
+import {
+  filter,
+  pagedQuery,
+  type SnapshotQueryClient,
+} from '@ahoo-wang/wow-client';
+import { usePagedQuery } from '@ahoo-wang/wow-react';
+
+interface OrderState {
+  id: string;
+  status: string;
+}
+// 查询可用的字段；生成的客户端会导出这个类型。
+type OrderFields = 'aggregateId' | 'state.status';
+
+export function PaidOrders({
+  client,
+  page,
+}: {
+  client: SnapshotQueryClient<OrderState, OrderFields>;
+  page: number;
+}) {
+  const { result, loading, error } = usePagedQuery<OrderState, OrderFields>({
+    query: pagedQuery({
+      filter: filter.eq('state.status', 'PAID'),
+      pagination: { index: page, size: 20 },
+    }),
+    execute: client.pagedState,
+  });
+
+  if (error) return <p role="alert">订单加载失败</p>;
+  if (loading || !result) return <p>加载中…</p>;
+  return (
+    <ul>
+      {result.list.map(order => (
+        <li key={order.id}>{order.status}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+像上面这样把客户端的字段类型作为第二个类型参数传入：生成的客户端字段比 `string` 窄，
+而一旦写出第一个类型参数，TypeScript 就不会再从 `execute` 推断它。
+记得把 `abortController` 传下去：这样新的查询、`abort()`、`reset()` 和组件卸载都会取消请求。
+快照查询过滤的是快照文档，聚合状态在它的 `state` 字段下，所以状态字段写作
+`state.status`，而不是 `status`。
+
+聚合查询暂时没有 Hook，通用的 `useQuery` 与聚合 Hook 计划在 9.3 提供。在此之前，在
+effect 里调用 `client.aggregate`，并在清理函数里中止它，写法见
+[参考页](https://wow.ahoo.me/zh/reference/typescript/wow-react/#聚合查询)。
+
+游标查询也还没有 Hook。用 `useSingleQuery` 运行它，把一页当作结果：类型参数传
+`CursorPage<R>` 与 `CursorQuery<Fields>`，`execute` 传 `client.cursorState`（或
+`client.cursor`）；`nextCursor` 不为 `null` 时，用
+`setQuery({ ...query, cursor: result.nextCursor })` 翻到下一页。
+
+## 配合端点 URL
+
+`useFetcher*Query` 这组 hook 则通过 Fetcher 把查询 POST 到一个 URL：
+
+```tsx
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { filter, pagedQuery } from '@ahoo-wang/wow-client';
+import { useFetcherPagedQuery } from '@ahoo-wang/wow-react';
+
+const fetcher = new Fetcher({ baseURL: 'https://api.example.com/' });
+
+export function PaidOrders() {
+  const { result, loading, error } = useFetcherPagedQuery<OrderState>({
+    fetcher,
+    url: 'order/snapshot/paged/state',
+    initialQuery: pagedQuery({
+      filter: filter.eq('state.status', 'PAID'),
+      pagination: { index: 1, size: 20 },
+    }),
+  });
+  // …渲染同上
+}
+```
+
+`fetcher` 可以是 Fetcher 实例，也可以是已注册 Fetcher 的名字；省略时用默认 Fetcher。
+一个聚合的快照路由是 `{aggregate}/snapshot/{single|list|paged}[/state]` 与
+`{aggregate}/snapshot/count`；聚合有上下文别名、owner 或租户路径时，路由前面还要加上它们。
+
+## 流式读取列表
+
+`useListStreamQuery` 与 `useFetcherListStreamQuery` 以服务端推送事件（SSE）读取列表，
+行一到就保存下来。`listQuery()` 只在给出 `limit` 时才发送它：Wow 9.1.5 及以后此时用
+默认列表大小，Wow 8.11～9.1.3 则以 HTTP 400 拒绝，对这些服务端请传 `limit`：
+
+```tsx
+import { filter, listQuery } from '@ahoo-wang/wow-client';
+import { useFetcherListStreamQuery } from '@ahoo-wang/wow-react';
+
+export function PaidOrderFeed() {
+  const { items, done, loading, error, abort } =
+    useFetcherListStreamQuery<OrderState>({
+      fetcher,
+      url: 'order/snapshot/list/state',
+      initialQuery: listQuery({
+        filter: filter.eq('state.status', 'PAID'),
+        limit: 100,
+      }),
+    });
+
+  if (error) return <p role="alert">{error.message}</p>;
+  return (
+    <>
+      <ul>
+        {items.map(order => (
+          <li key={order.id}>{order.id}</li>
+        ))}
+      </ul>
+      {loading && <button onClick={abort}>停止</button>}
+      {done && <p>共 {items.length} 个订单</p>}
+    </>
+  );
+}
+```
+
+| 字段      | 含义                                                                                            |
+| --------- | ----------------------------------------------------------------------------------------------- |
+| `items`   | 当前查询到目前为止收到的行，按到达顺序。新查询从空列表开始；`reset()` 清空它。                  |
+| `done`    | 流正常结束，`items` 已包含全部行。等同于 `status === 'success'`。                               |
+| `loading` | 从发出请求直到流结束、出错或被中止。                                                            |
+| `error`   | 请求失败时是 `FetcherError`；服务端在流中途发来错误事件时是带服务端 `errorCode` 的 `WowError`。 |
+| `abort()` | 停止读取流并保留已收到的行。`reset()` 停止并清空 `items`。`execute()` 重新执行当前查询。        |
+
+流由 hook 自己持有：它负责读取，无论到达多少行，最多约每帧（16 毫秒）渲染一次，并在新查询开始、
+调用 `abort()` 或 `reset()`、组件卸载时取消流。组件不接触 reader，所以在 StrictMode 下
+也是安全的。`useFetcherListStreamQuery` 会发送 `Accept: text/event-stream`——Wow
+服务端要看到这个请求头才会以流的形式响应；用 `useListStreamQuery` 时，把客户端的
+`listStream` 或 `listStateStream` 作为 `execute` 传入。
+
+## 状态与错误
+
+每个 hook 在挂载时执行查询，之后 `query` 选项（按内容比较）或 `setQuery()` 改变查询时
+再次执行，`useFetcher*` hook 在 `url` 或 `fetcher` 变化时也会再次执行；设置
+`autoExecute: false` 则只在调用 `execute()` 时执行。新的查询会中止正在进行的请求，所以
+迟到的响应不会覆盖较新的结果。受控的 `query` 重新变为 `undefined` 时（如
+`id ? singleQuery(…) : undefined`），中止进行中的请求并回到 `idle`，保留上一次结果；
+再给出查询之前不会执行。`onSuccess`、`onError` 分别以结果和错误为参数调用。
+
+请求失败和 `abort()` 都保留上一次的 `result`，刷新失败不会让界面变空白；`reset()`
+会中止进行中的请求，并清空 `result` 与 `error`。挂载即执行的 hook 首帧（服务端也一样）
+就是 `loading`。
+
+每个 hook 都返回 `status`、`loading`、`result`（流式 hook 为 `items` 与 `done`）、
+`error`、`execute`、`abort`、`reset`、`getQuery` 和 `setQuery`。各 hook 的选项与返回
+类型都扩展本包声明并导出的 `QueryHookOptions` 与 `QueryHookReturn`，同时导出的还有
+`QueryStatus` 与 `QueryExecutor`。`status` 是普通的字符串联合类型
+`'idle' | 'loading' | 'success' | 'error'`，组件 props 或测试里可以直接写字面量。
+
+`error` 的类型默认是 `Error`，需要更窄时传入类型参数 `E`：请求失败时是
+`FetcherError`，流中的错误事件是 `WowError`，自定义的 `execute` 则是它抛出的任何错误。
+`@ahoo-wang/wow-client` 的 `toWowError` 能从失败的请求中读出服务端的 `ErrorInfo`：
+
+```ts
+import { ErrorCodes, toWowError } from '@ahoo-wang/wow-client';
+
+const wowError = await toWowError(error);
+if (wowError?.errorCode === ErrorCodes.NOT_FOUND) {
+  // …
+}
+```
+
+## Hook 一览
+
+| Hook                                              | 查询                        | 结果                            |
+| ------------------------------------------------- | --------------------------- | ------------------------------- |
+| `useSingleQuery`、`useFetcherSingleQuery`         | `singleQuery(…)`            | `result`：一条                  |
+| `useListQuery`、`useFetcherListQuery`             | `listQuery(…)`              | `result`：若干行                |
+| `usePagedQuery`、`useFetcherPagedQuery`           | `pagedQuery(…)`             | `result`：`{ total, list }`     |
+| `useCountQuery`、`useFetcherCountQuery`           | 一个 `filter.*` 表达式      | `result`：记录数                |
+| `useListStreamQuery`、`useFetcherListStreamQuery` | `listQuery(…)`，以 SSE 事件 | `items` 陆续到达，结束后 `done` |
+
+查询类型默认使用 `@ahoo-wang/wow-client` 的 `filter` API。每个 hook 也接受
+`@ahoo-wang/wow-client/legacy` 中已弃用的 Condition 查询（Wow 8.10 服务端需要）；
+这个重载将在 v10 移除。
+
+在 Wow 9 中从 `@ahoo-wang/fetcher-react`（其中的 Wow hook）迁移而来；版本号跟随 Wow。
+
+## 文档
+
+- [TypeScript 指南](https://wow.ahoo.me/zh/guide/typescript/)
+- [wow-react 参考](https://wow.ahoo.me/zh/reference/typescript/wow-react/)
+- [交互式查询 hook Story](https://wow.ahoo.me/storybook/?path=/docs/react-hooks-wow-queries--docs)
+
+[English](./README.md) · [许可证](https://github.com/Ahoo-Wang/Wow/blob/main/LICENSE)

package/dist/hooks/useCountQuery.d.ts

@@ -0,0 +1,61 @@
+import { FilterExpression } from '@ahoo-wang/wow-client';
+import { Condition } from '@ahoo-wang/wow-client/legacy';
+import { QueryHookOptions, QueryHookReturn } from '../types.js';
+/**
+ * Options of {@link useCountQuery}: a filter and an `execute` that resolves to
+ * how many rows it matches.
+ *
+ * @template FIELDS - The field names the filter may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The filter type: `FilterExpression` by default
+ */
+export interface UseCountQueryOptions<FIELDS extends string = string, E = Error, Q extends Condition<FIELDS> | FilterExpression<FIELDS> = FilterExpression<FIELDS>> extends QueryHookOptions<Q, number, E> {
+}
+/**
+ * What {@link useCountQuery} returns: the count as `result`.
+ *
+ * @template FIELDS - The field names the filter may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The filter type: `FilterExpression` by default
+ */
+export interface UseCountQueryReturn<FIELDS extends string = string, E = Error, Q extends Condition<FIELDS> | FilterExpression<FIELDS> = FilterExpression<FIELDS>> extends QueryHookReturn<Q, number, E> {
+}
+/**
+ * Counts what a filter matches through your own `execute` function and keeps
+ * the count as state: typically a query client's `count`.
+ *
+ * `execute` receives the filter, the `attributes` option and an
+ * `AbortController`; hand the controller on so that a newer query, `abort()`
+ * or an unmount cancels the request. The count runs on mount and whenever
+ * `query` or `setQuery()` changes the filter; set `autoExecute: false` to run
+ * it only through `execute()`.
+ *
+ * Returns `result` (the count, or `undefined` before the first success),
+ * `loading`, `error`, `status`, `execute`, `abort`, `reset`, `getQuery` and
+ * `setQuery`.
+ *
+ * @template FIELDS - The field names the filter may use. With a client whose
+ *   fields are narrower than `string`, as a generated client's are, pass
+ *   them here; inferred from the first filter, they would admit only its
+ *   fields in `setQuery()`
+ * @template E - The error type, `Error` by default
+ *
+ * @example
+ * ```tsx
+ * import { filter, type SnapshotQueryClient } from '@ahoo-wang/wow-client';
+ * import { useCountQuery } from '@ahoo-wang/wow-react';
+ *
+ * function PaidCount({ client }: { client: SnapshotQueryClient<OrderState, OrderFields> }) {
+ *   const { result, error } = useCountQuery<OrderFields>({
+ *     initialQuery: filter.eq('state.status', 'PAID'),
+ *     execute: (query, attributes, abortController) =>
+ *       client.count(query, attributes, abortController),
+ *   });
+ *   if (error) return <p role="alert">{error.message}</p>;
+ *   return <p>{result ?? '…'} paid orders</p>;
+ * }
+ * ```
+ */
+export declare function useCountQuery<FIELDS extends string = string, E = Error>(options: UseCountQueryOptions<FIELDS, E, FilterExpression<FIELDS>>): UseCountQueryReturn<FIELDS, E, FilterExpression<FIELDS>>;
+export declare function useCountQuery<FIELDS extends string = string, E = Error>(options: UseCountQueryOptions<FIELDS, E, Condition<FIELDS>>): UseCountQueryReturn<FIELDS, E, Condition<FIELDS>>;
+export declare function useCountQuery<FIELDS extends string = string, E = Error, Q extends Condition<FIELDS> | FilterExpression<FIELDS> = FilterExpression<FIELDS>>(options: UseCountQueryOptions<FIELDS, E, Q>): UseCountQueryReturn<FIELDS, E, Q>;

package/dist/hooks/useFetcherCountQuery.d.ts

@@ -0,0 +1,65 @@
+import { FilterExpression } from '@ahoo-wang/wow-client';
+import { Condition } from '@ahoo-wang/wow-client/legacy';
+import { Endpoint } from '../internal/endpoint.js';
+import { QueryHookOptions, QueryHookReturn } from '../types.js';
+/**
+ * Options of {@link useFetcherCountQuery}: those of every query hook, with
+ * the endpoint and the Fetcher in place of `execute`.
+ *
+ * @template FIELDS - The field names the filter may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The filter type: `FilterExpression` by default
+ */
+export interface UseFetcherCountQueryOptions<FIELDS extends string = string, E = Error, Q extends Condition<FIELDS> | FilterExpression<FIELDS> = FilterExpression<FIELDS>> extends Omit<QueryHookOptions<Q, number, E>, 'execute'>, Endpoint {
+}
+/**
+ * What {@link useFetcherCountQuery} returns: the count as `result`.
+ *
+ * @template FIELDS - The field names the filter may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The filter type: `FilterExpression` by default
+ */
+export interface UseFetcherCountQueryReturn<FIELDS extends string = string, E = Error, Q extends Condition<FIELDS> | FilterExpression<FIELDS> = FilterExpression<FIELDS>> extends QueryHookReturn<Q, number, E> {
+}
+/**
+ * POSTs a filter to a Wow count endpoint through a Fetcher and keeps the
+ * count as state.
+ *
+ * `url` is resolved against the Fetcher's `baseURL`; `fetcher` is a Fetcher
+ * or the name of a registered one, the default Fetcher when omitted. The
+ * count runs on mount and whenever `query` or `setQuery()` changes the
+ * filter; set `autoExecute: false` to run it only through `execute()`. A
+ * newer filter aborts the request in flight, so a late response never
+ * overwrites a newer one; an unmount aborts it too.
+ *
+ * A change of `url`, or of `fetcher`, runs the query again. A Fetcher is
+ * compared by its name, or by its `baseURL` when it has none, so one created
+ * inline in render does not run it on every render.
+ *
+ * Returns `result` (the count, or `undefined` before the first success),
+ * `loading`, `error`, `status`, `execute`, `abort`, `reset`, `getQuery` and
+ * `setQuery`. A failed request sets `error` to a `FetcherError`;
+ * `toWowError(error)` from `@ahoo-wang/wow-client` reads the server's
+ * `errorCode` from it.
+ *
+ * @template FIELDS - The field names the filter may use
+ * @template E - The error type, `Error` by default
+ *
+ * @example
+ * ```tsx
+ * import { filter } from '@ahoo-wang/wow-client';
+ * import { useFetcherCountQuery } from '@ahoo-wang/wow-react';
+ *
+ * function PaidCount() {
+ *   const { result, error } = useFetcherCountQuery({
+ *     url: 'order/snapshot/count',
+ *     initialQuery: filter.eq('state.status', 'PAID'),
+ *   });
+ *   if (error) return <p role="alert">{error.message}</p>;
+ *   return <p>{result ?? '…'} paid orders</p>;
+ * }
+ * ```
+ */
+export declare function useFetcherCountQuery<FIELDS extends string = string, E = Error>(options: UseFetcherCountQueryOptions<FIELDS, E, FilterExpression<FIELDS>>): UseFetcherCountQueryReturn<FIELDS, E, FilterExpression<FIELDS>>;
+export declare function useFetcherCountQuery<FIELDS extends string = string, E = Error>(options: UseFetcherCountQueryOptions<FIELDS, E, Condition<FIELDS>>): UseFetcherCountQueryReturn<FIELDS, E, Condition<FIELDS>>;
+export declare function useFetcherCountQuery<FIELDS extends string = string, E = Error, Q extends Condition<FIELDS> | FilterExpression<FIELDS> = FilterExpression<FIELDS>>(options: UseFetcherCountQueryOptions<FIELDS, E, Q>): UseFetcherCountQueryReturn<FIELDS, E, Q>;

package/dist/hooks/useFetcherListQuery.d.ts

@@ -0,0 +1,78 @@
+import { FilterListQuery } from '@ahoo-wang/wow-client';
+import { ListQuery, ListQueryRequest } from '@ahoo-wang/wow-client/legacy';
+import { Endpoint } from '../internal/endpoint.js';
+import { QueryHookOptions, QueryHookReturn } from '../types.js';
+/**
+ * Options of {@link useFetcherListQuery}: those of every query hook, with the
+ * endpoint and the Fetcher in place of `execute`.
+ *
+ * @template R - One row of the list
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The query type: `FilterListQuery` by default
+ */
+export interface UseFetcherListQueryOptions<R, FIELDS extends string = string, E = Error, Q extends ListQueryRequest<FIELDS> = FilterListQuery<FIELDS>> extends Omit<QueryHookOptions<Q, R[], E>, 'execute'>, Endpoint {
+}
+/**
+ * What {@link useFetcherListQuery} returns: the rows as `result`.
+ *
+ * @template R - One row of the list
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The query type: `FilterListQuery` by default
+ */
+export interface UseFetcherListQueryReturn<R, FIELDS extends string = string, E = Error, Q extends ListQueryRequest<FIELDS> = FilterListQuery<FIELDS>> extends QueryHookReturn<Q, R[], E> {
+}
+/**
+ * POSTs a list query to a Wow endpoint through a Fetcher and keeps the rows
+ * as state.
+ *
+ * `url` is resolved against the Fetcher's `baseURL`; `fetcher` is a Fetcher
+ * or the name of a registered one, the default Fetcher when omitted. The
+ * query runs on mount and whenever `query` or `setQuery()` changes it; set
+ * `autoExecute: false` to run it only through `execute()`. A newer query
+ * aborts the request in flight, so a late response never overwrites a newer
+ * one; an unmount aborts it too.
+ *
+ * A change of `url`, or of `fetcher`, runs the query again. A Fetcher is
+ * compared by its name, or by its `baseURL` when it has none, so one created
+ * inline in render does not run it on every render.
+ *
+ * Returns `result` (the rows, or `undefined` before the first success),
+ * `loading`, `error`, `status`, `execute`, `abort`, `reset`, `getQuery` and
+ * `setQuery`. A failed request sets `error` to a `FetcherError`;
+ * `toWowError(error)` from `@ahoo-wang/wow-client` reads the server's
+ * `errorCode` from it.
+ *
+ * @template R - One row of the list
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ *
+ * @example
+ * ```tsx
+ * import { desc, filter, listQuery } from '@ahoo-wang/wow-client';
+ * import { useFetcherListQuery } from '@ahoo-wang/wow-react';
+ *
+ * function LatestOrders() {
+ *   const { result, loading, error, execute } = useFetcherListQuery<OrderState>({
+ *     url: 'order/snapshot/list/state',
+ *     initialQuery: listQuery({
+ *       filter: filter.eq('state.status', 'PAID'),
+ *       sort: [desc('createTime')],
+ *       limit: 20,
+ *     }),
+ *   });
+ *   if (error) return <p role="alert">{error.message}</p>;
+ *   if (loading || !result) return <p>Loading…</p>;
+ *   return (
+ *     <>
+ *       <ul>{result.map(order => <li key={order.id}>{order.id}</li>)}</ul>
+ *       <button onClick={execute}>Refresh</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFetcherListQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherListQueryOptions<R, FIELDS, E, FilterListQuery<FIELDS>>): UseFetcherListQueryReturn<R, FIELDS, E, FilterListQuery<FIELDS>>;
+export declare function useFetcherListQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherListQueryOptions<R, FIELDS, E, ListQuery<FIELDS>>): UseFetcherListQueryReturn<R, FIELDS, E, ListQuery<FIELDS>>;
+export declare function useFetcherListQuery<R, FIELDS extends string = string, E = Error, Q extends ListQueryRequest<FIELDS> = FilterListQuery<FIELDS>>(options: UseFetcherListQueryOptions<R, FIELDS, E, Q>): UseFetcherListQueryReturn<R, FIELDS, E, Q>;

package/dist/hooks/useFetcherListStreamQuery.d.ts

@@ -0,0 +1,63 @@
+import { FilterListQuery } from '@ahoo-wang/wow-client';
+import { ListQuery, ListQueryRequest } from '@ahoo-wang/wow-client/legacy';
+import { Endpoint } from '../internal/endpoint.js';
+import { UseListStreamQueryOptions, UseListStreamQueryReturn } from './useListStreamQuery.js';
+/**
+ * Options of {@link useFetcherListStreamQuery}: those of `useListStreamQuery`,
+ * with the endpoint and the Fetcher in place of `execute`.
+ *
+ * @template R - One row of the stream: the `data` of each event
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default: a failed request
+ *   rejects with a `FetcherError`, an error event in the stream with a
+ *   `WowError`
+ * @template Q - The query type: `FilterListQuery` by default
+ */
+export interface UseFetcherListStreamQueryOptions<R, FIELDS extends string = string, E = Error, Q extends ListQueryRequest<FIELDS> = FilterListQuery<FIELDS>> extends Omit<UseListStreamQueryOptions<R, FIELDS, E, Q>, 'execute'>, Endpoint {
+}
+/**
+ * What {@link useFetcherListStreamQuery} returns; see
+ * {@link UseListStreamQueryReturn}.
+ */
+export interface UseFetcherListStreamQueryReturn<R, FIELDS extends string = string, E = Error, Q extends ListQueryRequest<FIELDS> = FilterListQuery<FIELDS>> extends UseListStreamQueryReturn<R, FIELDS, E, Q> {
+}
+/**
+ * Streams the rows of a list query from a Wow list endpoint and keeps them as
+ * state; see `useListStreamQuery` for the state it returns.
+ *
+ * It POSTs the query to `url` through `fetcher` (the default Fetcher when
+ * omitted) with `Accept: text/event-stream`, the header a Wow server needs to
+ * answer with an event stream rather than JSON. An error event in the stream
+ * ends it with a `WowError` in `error`.
+ *
+ * A change of `url`, or of `fetcher`, runs the query again. A Fetcher is
+ * compared by its name, or by its `baseURL` when it has none, so one created
+ * inline in render does not run it on every render.
+ *
+ * @template R - One row of the stream: the `data` of each event
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type
+ *
+ * @example
+ * ```tsx
+ * import { filter, listQuery } from '@ahoo-wang/wow-client';
+ * import { useFetcherListStreamQuery } from '@ahoo-wang/wow-react';
+ *
+ * function PaidOrders() {
+ *   const { items, done, loading, error } = useFetcherListStreamQuery<OrderState>({
+ *     url: 'order/snapshot/list/state',
+ *     initialQuery: listQuery({ filter: filter.eq('state.status', 'PAID') }),
+ *   });
+ *   if (error) return <p role="alert">{error.message}</p>;
+ *   return (
+ *     <>
+ *       <ul>{items.map(order => <li key={order.id}>{order.id}</li>)}</ul>
+ *       {loading ? <p>Loading…</p> : done && <p>{items.length} orders</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFetcherListStreamQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherListStreamQueryOptions<R, FIELDS, E, FilterListQuery<FIELDS>>): UseFetcherListStreamQueryReturn<R, FIELDS, E, FilterListQuery<FIELDS>>;
+export declare function useFetcherListStreamQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherListStreamQueryOptions<R, FIELDS, E, ListQuery<FIELDS>>): UseFetcherListStreamQueryReturn<R, FIELDS, E, ListQuery<FIELDS>>;
+export declare function useFetcherListStreamQuery<R, FIELDS extends string = string, E = Error, Q extends ListQueryRequest<FIELDS> = FilterListQuery<FIELDS>>(options: UseFetcherListStreamQueryOptions<R, FIELDS, E, Q>): UseFetcherListStreamQueryReturn<R, FIELDS, E, Q>;

package/dist/hooks/useFetcherPagedQuery.d.ts

@@ -0,0 +1,73 @@
+import { FilterPagedQuery, PagedList } from '@ahoo-wang/wow-client';
+import { PagedQuery, PagedQueryRequest } from '@ahoo-wang/wow-client/legacy';
+import { Endpoint } from '../internal/endpoint.js';
+import { QueryHookOptions, QueryHookReturn } from '../types.js';
+/**
+ * Options of {@link useFetcherPagedQuery}: those of every query hook, with
+ * the endpoint and the Fetcher in place of `execute`.
+ *
+ * @template R - One row of the page
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The query type: `FilterPagedQuery` by default
+ */
+export interface UseFetcherPagedQueryOptions<R, FIELDS extends string = string, E = Error, Q extends PagedQueryRequest<FIELDS> = FilterPagedQuery<FIELDS>> extends Omit<QueryHookOptions<Q, PagedList<R>, E>, 'execute'>, Endpoint {
+}
+/**
+ * What {@link useFetcherPagedQuery} returns: the page (`total` and `list`)
+ * as `result`.
+ *
+ * @template R - One row of the page
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The query type: `FilterPagedQuery` by default
+ */
+export interface UseFetcherPagedQueryReturn<R, FIELDS extends string = string, E = Error, Q extends PagedQueryRequest<FIELDS> = FilterPagedQuery<FIELDS>> extends QueryHookReturn<Q, PagedList<R>, E> {
+}
+/**
+ * POSTs a paged query to a Wow endpoint through a Fetcher and keeps the page
+ * as state.
+ *
+ * `url` is resolved against the Fetcher's `baseURL`; `fetcher` is a Fetcher
+ * or the name of a registered one, the default Fetcher when omitted. The
+ * query runs on mount and whenever `query` or `setQuery()` changes it — turn
+ * pages with `setQuery()`; set `autoExecute: false` to run it only through
+ * `execute()`. A newer query aborts the request in flight, so a late response
+ * never overwrites a newer one; an unmount aborts it too.
+ *
+ * A change of `url`, or of `fetcher`, runs the query again. A Fetcher is
+ * compared by its name, or by its `baseURL` when it has none, so one created
+ * inline in render does not run it on every render.
+ *
+ * Returns `result` (`{ total, list }`, or `undefined` before the first
+ * success), `loading`, `error`, `status`, `execute`, `abort`, `reset`,
+ * `getQuery` and `setQuery`. A failed request sets `error` to a
+ * `FetcherError`; `toWowError(error)` from `@ahoo-wang/wow-client` reads the
+ * server's `errorCode` from it.
+ *
+ * @template R - One row of the page
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ *
+ * @example
+ * ```tsx
+ * import { filter, pagedQuery } from '@ahoo-wang/wow-client';
+ * import { useFetcherPagedQuery } from '@ahoo-wang/wow-react';
+ *
+ * function PaidOrders({ page }: { page: number }) {
+ *   const { result, loading, error } = useFetcherPagedQuery<OrderState>({
+ *     url: 'order/snapshot/paged/state',
+ *     query: pagedQuery({
+ *       filter: filter.eq('state.status', 'PAID'),
+ *       pagination: { index: page, size: 20 },
+ *     }),
+ *   });
+ *   if (error) return <p role="alert">{error.message}</p>;
+ *   if (loading || !result) return <p>Loading…</p>;
+ *   return <p>{result.list.length} of {result.total}</p>;
+ * }
+ * ```
+ */
+export declare function useFetcherPagedQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherPagedQueryOptions<R, FIELDS, E, FilterPagedQuery<FIELDS>>): UseFetcherPagedQueryReturn<R, FIELDS, E, FilterPagedQuery<FIELDS>>;
+export declare function useFetcherPagedQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherPagedQueryOptions<R, FIELDS, E, PagedQuery<FIELDS>>): UseFetcherPagedQueryReturn<R, FIELDS, E, PagedQuery<FIELDS>>;
+export declare function useFetcherPagedQuery<R, FIELDS extends string = string, E = Error, Q extends PagedQueryRequest<FIELDS> = FilterPagedQuery<FIELDS>>(options: UseFetcherPagedQueryOptions<R, FIELDS, E, Q>): UseFetcherPagedQueryReturn<R, FIELDS, E, Q>;

package/dist/hooks/useFetcherSingleQuery.d.ts

@@ -0,0 +1,69 @@
+import { FilterSingleQuery } from '@ahoo-wang/wow-client';
+import { SingleQuery, SingleQueryRequest } from '@ahoo-wang/wow-client/legacy';
+import { Endpoint } from '../internal/endpoint.js';
+import { QueryHookOptions, QueryHookReturn } from '../types.js';
+/**
+ * Options of {@link useFetcherSingleQuery}: those of every query hook, with
+ * the endpoint and the Fetcher in place of `execute`.
+ *
+ * @template R - The item the query returns
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The query type: `FilterSingleQuery` by default
+ */
+export interface UseFetcherSingleQueryOptions<R, FIELDS extends string = string, E = Error, Q extends SingleQueryRequest<FIELDS> = FilterSingleQuery<FIELDS>> extends Omit<QueryHookOptions<Q, R, E>, 'execute'>, Endpoint {
+}
+/**
+ * What {@link useFetcherSingleQuery} returns: the item as `result`.
+ *
+ * @template R - The item the query returns
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ * @template Q - The query type: `FilterSingleQuery` by default
+ */
+export interface UseFetcherSingleQueryReturn<R, FIELDS extends string = string, E = Error, Q extends SingleQueryRequest<FIELDS> = FilterSingleQuery<FIELDS>> extends QueryHookReturn<Q, R, E> {
+}
+/**
+ * POSTs a single query to a Wow endpoint through a Fetcher and keeps the
+ * result as state.
+ *
+ * `url` is resolved against the Fetcher's `baseURL`; `fetcher` is a Fetcher
+ * or the name of a registered one, the default Fetcher when omitted. The
+ * query runs on mount and whenever `query` or `setQuery()` changes it; set
+ * `autoExecute: false` to run it only through `execute()`. A newer query
+ * aborts the request in flight, so a late response never overwrites a newer
+ * one; an unmount aborts it too.
+ *
+ * A change of `url`, or of `fetcher`, runs the query again. A Fetcher is
+ * compared by its name, or by its `baseURL` when it has none, so one created
+ * inline in render does not run it on every render.
+ *
+ * Returns `result` (the item, or `undefined` before the first success),
+ * `loading`, `error`, `status`, `execute`, `abort`, `reset`, `getQuery` and
+ * `setQuery`. A failed request sets `error` to a `FetcherError`;
+ * `toWowError(error)` from `@ahoo-wang/wow-client` reads the server's
+ * `errorCode` from it.
+ *
+ * @template R - The item the query returns
+ * @template FIELDS - The field names the query may use
+ * @template E - The error type, `Error` by default
+ *
+ * @example
+ * ```tsx
+ * import { filter, singleQuery } from '@ahoo-wang/wow-client';
+ * import { useFetcherSingleQuery } from '@ahoo-wang/wow-react';
+ *
+ * function OrderStatus({ id }: { id: string }) {
+ *   const { result, loading, error } = useFetcherSingleQuery<OrderState>({
+ *     url: 'order/snapshot/single/state',
+ *     query: singleQuery({ filter: filter.id(id) }),
+ *   });
+ *   if (error) return <p role="alert">{error.message}</p>;
+ *   if (loading || !result) return <p>Loading…</p>;
+ *   return <p>{result.status}</p>;
+ * }
+ * ```
+ */
+export declare function useFetcherSingleQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherSingleQueryOptions<R, FIELDS, E, FilterSingleQuery<FIELDS>>): UseFetcherSingleQueryReturn<R, FIELDS, E, FilterSingleQuery<FIELDS>>;
+export declare function useFetcherSingleQuery<R, FIELDS extends string = string, E = Error>(options: UseFetcherSingleQueryOptions<R, FIELDS, E, SingleQuery<FIELDS>>): UseFetcherSingleQueryReturn<R, FIELDS, E, SingleQuery<FIELDS>>;
+export declare function useFetcherSingleQuery<R, FIELDS extends string = string, E = Error, Q extends SingleQueryRequest<FIELDS> = FilterSingleQuery<FIELDS>>(options: UseFetcherSingleQueryOptions<R, FIELDS, E, Q>): UseFetcherSingleQueryReturn<R, FIELDS, E, Q>;