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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2024] [ahoo wang <ahoowang@qq.com>]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,253 @@
+# `@ahoo-wang/wow-react`
+
+React hooks for [Wow](https://github.com/Ahoo-Wang/Wow) queries: single, list,
+paged, count and list-stream. They keep a query, its result, loading and error
+as React state, on the query types of `@ahoo-wang/wow-client`.
+
+## Requirements
+
+- **React 19.3 or later.** The package is compiled with the React Compiler and
+  imports `react/compiler-runtime`, which only React 19 has; React 18 is not
+  supported.
+- Node.js 22.12 or later for tooling and server rendering; any browser React 19
+  supports.
+- `@ahoo-wang/wow-client` of the same minor version as this package.
+- TypeScript 6 or later (CI tests 6.0 through the latest 7.x) with
+  `"moduleResolution": "bundler"` or `"module": "nodenext"`.
+
+## Install
+
+```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` is a peer of `@ahoo-wang/wow-client`, not of
+this package.
+
+The version follows Wow, so a minor release may contain breaking changes: keep the Wow packages on one minor with `save-prefix=~` or `--save-exact`, as [version ranges](https://wow.ahoo.me/guide/typescript/compatibility#version-ranges) explains.
+
+The hooks run their own request state machine: `@ahoo-wang/fetcher-react` is
+not needed, and neither is `@ahoo-wang/fetcher-wow`.
+
+The package ships ES modules only. CommonJS code on Node.js 22.12+ can still
+`require('@ahoo-wang/wow-react')`, because Node.js loads ES modules through
+`require`.
+
+## With a query client
+
+The `use*Query` hooks take an `execute` function. A query client method —
+`SnapshotQueryClient` of `@ahoo-wang/wow-client`, or the one a generated
+`…QueryClientFactory` creates — has exactly the `(query, attributes, abort)`
+shape `execute` takes, so the client supplies the URL, the headers and the
+response handling, and nothing is hand-written. The clients bind their
+methods, so `execute: client.pagedState` works as is; a method of an object
+of your own needs `.bind(object)` or an arrow function:
+
+```tsx
+import {
+  filter,
+  pagedQuery,
+  type SnapshotQueryClient,
+} from '@ahoo-wang/wow-client';
+import { usePagedQuery } from '@ahoo-wang/wow-react';
+
+interface OrderState {
+  id: string;
+  status: string;
+}
+// The fields a query may name; a generated client exports this type.
+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">Unable to load orders</p>;
+  if (loading || !result) return <p>Loading…</p>;
+  return (
+    <ul>
+      {result.list.map(order => (
+        <li key={order.id}>{order.status}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Pass the client's fields type as the second type argument, as above: a
+generated client's fields are narrower than `string`, and TypeScript does not
+infer them from `execute` once the first type argument is written. Hand
+`abortController` on: a newer query, `abort()`, `reset()` and an unmount then
+cancel the request. A snapshot query filters the snapshot document, whose state lives
+under `state`, so a state field is `state.status`, not `status`.
+
+Aggregations have no hook yet; a generic `useQuery` and aggregation hooks are
+planned for 9.3. Until then call `client.aggregate` in an effect and abort it on
+cleanup, as the
+[reference page](https://wow.ahoo.me/reference/typescript/wow-react/#aggregations)
+shows.
+
+Cursor queries have no hook yet either. Run one through `useSingleQuery`, with
+the page as the result: pass `CursorPage<R>` and `CursorQuery<Fields>` as the
+type arguments and `client.cursorState` (or `client.cursor`) as `execute`, and
+move to the next page with `setQuery({ ...query, cursor: result.nextCursor })`
+while `nextCursor` is not `null`.
+
+## With an endpoint URL
+
+The `useFetcher*Query` hooks POST the query to a URL through a Fetcher instead:
+
+```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 },
+    }),
+  });
+  // …render as above
+}
+```
+
+`fetcher` is a Fetcher or the name of a registered one; without it the default
+Fetcher sends the request. The snapshot routes of an aggregate are
+`{aggregate}/snapshot/{single|list|paged}[/state]` and
+`{aggregate}/snapshot/count`, behind the context alias and the owner or tenant
+path when the aggregate has them.
+
+## Streaming a list
+
+`useListStreamQuery` and `useFetcherListStreamQuery` read a list as
+server-sent events and keep the rows as they arrive. `listQuery()` sends a
+`limit` only when given one: Wow 9.1.5 and later then apply their default list
+size, while Wow 8.11 to 9.1.3 reject the query with HTTP 400, so pass `limit`
+for those servers.
+
+```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}>Stop</button>}
+      {done && <p>{items.length} orders</p>}
+    </>
+  );
+}
+```
+
+| Field     | Meaning                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `items`   | The rows of the current query received so far, in order. A new query starts empty; `reset()` empties it.                        |
+| `done`    | The stream ended normally: `items` holds every row. The same as `status === 'success'`.                                         |
+| `loading` | From the request until the stream ends, fails or is aborted.                                                                    |
+| `error`   | A failed request (`FetcherError`), or a `WowError` with the server's `errorCode` when the server sends an error event midway.   |
+| `abort()` | Stops the stream and keeps the rows received. `reset()` stops it and empties `items`. `execute()` runs the current query again. |
+
+The hook owns the stream: it reads it, renders the rows at most about once a
+frame (every 16 ms) however many arrive, and cancels it when a newer query starts, on `abort()` or
+`reset()`, and on unmount. Components never hold a reader, so the hook is safe
+under StrictMode. `useFetcherListStreamQuery` sends `Accept: text/event-stream`,
+which a Wow server needs to answer with a stream; with `useListStreamQuery`,
+pass a client's `listStream` or `listStateStream` as `execute`.
+
+## State and errors
+
+Every hook runs its query on mount and whenever `query` (compared by content)
+or `setQuery()` changes it, and a `useFetcher*` hook also when `url` or
+`fetcher` changes; 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 result. A controlled `query` set back to `undefined`
+(`id ? singleQuery(…) : undefined`) aborts the request in flight and goes
+`idle`, keeping the last result; nothing runs until a query is given again. `onSuccess` and `onError` are called with the
+result and the error.
+
+A failed request and `abort()` keep the last `result`, so a failed refresh does
+not blank the screen; `reset()` aborts the request in flight and clears
+`result` and `error`. A hook that runs on mount renders its first frame, on the
+server too, as `loading`.
+
+Every hook returns `status`, `loading`, `result` (`items` and `done` for a
+stream), `error`, `execute`, `abort`, `reset`, `getQuery` and `setQuery`. The
+option and return types of each hook extend `QueryHookOptions` and
+`QueryHookReturn`, which this package declares and exports with `QueryStatus`
+and `QueryExecutor`. `status` is the plain string union
+`'idle' | 'loading' | 'success' | 'error'`, so a component's props or a test
+can write a literal.
+
+`error` is typed `Error` unless you pass the `E` type argument: a failed
+request rejects with a `FetcherError`, an error event in a stream with a
+`WowError`, and your own `execute` with whatever it throws. `toWowError` from
+`@ahoo-wang/wow-client` reads the server's `ErrorInfo` from a failed request:
+
+```ts
+import { ErrorCodes, toWowError } from '@ahoo-wang/wow-client';
+
+const wowError = await toWowError(error);
+if (wowError?.errorCode === ErrorCodes.NOT_FOUND) {
+  // …
+}
+```
+
+## Hooks
+
+| Hook                                              | Query                         | Result                              |
+| ------------------------------------------------- | ----------------------------- | ----------------------------------- |
+| `useSingleQuery`, `useFetcherSingleQuery`         | `singleQuery(…)`              | `result`: one item                  |
+| `useListQuery`, `useFetcherListQuery`             | `listQuery(…)`                | `result`: the rows                  |
+| `usePagedQuery`, `useFetcherPagedQuery`           | `pagedQuery(…)`               | `result`: `{ total, list }`         |
+| `useCountQuery`, `useFetcherCountQuery`           | a `filter.*` expression       | `result`: the count                 |
+| `useListStreamQuery`, `useFetcherListStreamQuery` | `listQuery(…)`, as SSE events | `items` as they arrive, then `done` |
+
+The query types default to the `filter` API of `@ahoo-wang/wow-client`. Each
+hook also accepts the deprecated Condition queries of
+`@ahoo-wang/wow-client/legacy`, which Wow 8.10 servers need; that overload goes
+in v10.
+
+Moved from `@ahoo-wang/fetcher-react` (its Wow hooks) in Wow 9; the version
+follows Wow.
+
+## Documentation
+
+- [TypeScript guide](https://wow.ahoo.me/guide/typescript/)
+- [wow-react reference](https://wow.ahoo.me/reference/typescript/wow-react/)
+- [Interactive query hook stories](https://wow.ahoo.me/storybook/?path=/docs/react-hooks-wow-queries--docs)
+
+[中文](./README.zh-CN.md) · [License](https://github.com/Ahoo-Wang/Wow/blob/main/LICENSE)