React

React hooks connect an asynchronous operation to one mounted component: state, execution, query-driven refresh and optional debounce. They do not provide a shared response cache. Start with an explicit action; add automatic queries only when input changes should issue requests.

One model runs through every hook: a request is identified by its AbortController, and only the current one may write state. State is one value { status, loading, result, error }; execute never rejects and resolves to the state the execution ended in. Queries are controlled: the query lives in your state and the hook executes when its content changes.

Choose an entry

Need	Entry	What you own
Click to issue HTTP	useFetcher	Request URL, Fetcher and result extractor. Render result; branch on the state execute resolves to.
Execute another Promise API	useExecutePromise	Supplier and forwarding its controller signal to I/O.
Fetch on query changes	useQuery / useFetcherQuery	The query, held in your own state; undefined means not ready. Automatic execution defaults to true.
Delay search while typing	Debounced hooks	Required delay; a debounced query adds pending and flush(), and abort() stops the active request.
Wrap an existing service	API hook factories	Service object and methods; create hooks outside render.
Only track someone else's state	usePromiseState	Execution, cleanup and stale-result handling remain outside this state-only hook.

Subpath entries

Entry	Exports	Loads
@ahoo-wang/fetcher-react	Every hook and component on these pages	All declared peers below
@ahoo-wang/fetcher-react/core	Promise and query state, debounced callbacks, values and queries, useLatest, useStableValue	React only; no @ahoo-wang/* package
@ahoo-wang/fetcher-react/fetcher	useFetcher, useFetcherQuery, useDebouncedFetcher, useDebouncedFetcherQuery and their option types	@ahoo-wang/fetcher; no CoSec, storage or event bus

The subpaths are ESM-only; the root entry also ships a UMD build. They share one module graph with the root entry, so a hook or PromiseStatus imported from /core is the same value as the one imported from the root. The symbol index marks which subpath exports each symbol. Declared peers are still installation requirements when you import a subpath; the subpath only limits what your bundle loads.

Installation prerequisites

pnpm add @ahoo-wang/fetcher @ahoo-wang/fetcher-cosec @ahoo-wang/fetcher-eventbus @ahoo-wang/fetcher-react @ahoo-wang/fetcher-storage react react-dom

The library package declares Node >=18.20.8; repository development requires Node >=22.12.0 and pnpm 10.34.5. The command includes all transitive internal peers (React → CoSec → storage → event bus). Direct runtime dependencies (dequal, immer) are installed automatically. The external peer is React ^19.0.0; install the renderer your app uses (react-dom in the browser). Peers are installation requirements even when a particular feature is unused. Consumers do not need to duplicate the repository React Compiler toolchain.

Changed in 6.0

The hooks were reworked around the model above (breaking). Removed: the fullscreen hooks, useRefs, useForceUpdate, useMounted, useRequestId, useQueryState, the propagateError option, initialQuery/setQuery/getQuery and onBeforeExecute. Each topic page notes what changed for its hooks; Latest and stable values lists what to use instead of the removed utilities.

Wow query hooks and data monitoring

The Wow query hooks (useListQuery, usePagedQuery, useFetcherListQuery and the rest) and the data-monitor hooks (useDataMonitor, DataMonitorService) remain only in the 5.x line (npm 5.1.x, branch 5.x). From 6.0 the Wow hooks live in @ahoo-wang/wow-react in the Wow repository (typescript/, documentation); it is on npm from Wow 9.2.0, and 9.2.1 or later accepts fetcher 6. The data-monitor hooks were retired together with @ahoo-wang/fetcher-viewer.

Runnable core example

For setup, fixtures and expected results follow the guide.

/*
 * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].
 * 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.
 */

import { Fetcher, ResultExtractors } from '@ahoo-wang/fetcher';
import { useFetcher } from '@ahoo-wang/fetcher-react';
import { useMemo } from 'react';

interface User {
  id: string;
  name: string;
}

type Result = User[] | { status: string };

export function ReactRequests({ baseURL = '/api' }: { baseURL?: string }) {
  const fetcher = useMemo(() => new Fetcher({ baseURL }), [baseURL]);
  const request = useFetcher<Result>({
    fetcher,
    resultExtractor: ResultExtractors.Json,
  });

  const output = request.loading
    ? request.status
    : request.error
      ? `Error · ${request.error.name}`
      : Array.isArray(request.result)
        ? request.result.map(user => user.name).join(', ')
        : (request.result?.status ?? request.status);

  return (
    <section
      aria-label="React requests"
      style={{ display: 'grid', gap: '0.75rem', maxWidth: '24rem' }}
    >
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>
        <button onClick={() => void request.execute({ url: '/users' })}>
          Load
        </button>
        <button onClick={() => void request.execute({ url: '/error' })}>
          Fail
        </button>
        <button onClick={() => void request.execute({ url: '/slow' })}>
          Load slow
        </button>
        <button disabled={!request.loading} onClick={request.abort}>
          Cancel
        </button>
      </div>
      <output aria-live="polite">{output}</output>
    </section>
  );
}

Topics

• Fetcher hooks
• Promise and query state
• API hook factories
• Debounced execution
• Storage and event subscriptions
• Security hooks and route guards
• Latest and stable values
• Complete symbol index

State and resource ownership · Failure and cancellation boundaries