Wow query hooks

Wow hooks specialize the same query executor with request/result types. They do not create query clients or build conditions for you. Use service-based variants with an execute function, or Fetcher variants with a required url and optional named/instance Fetcher.

Service hook	Fetcher hook	Request → result
useSingleQuery	useFetcherSingleQuery	SingleQueryRequest → R
useListQuery	useFetcherListQuery	ListQueryRequest → R[]
usePagedQuery	useFetcherPagedQuery	PagedQueryRequest → PagedList<R> (total, list)
useCountQuery	useFetcherCountQuery	Condition or FilterExpression → number
useListStreamQuery	useFetcherListStreamQuery	ListQueryRequest → ReadableStream of JsonServerSentEvent<R>

All support both legacy condition queries and filter queries through overloads; FIELDS restricts field names statically. Type arguments do not validate server JSON. The corresponding Use…Options and Use…Return interfaces inherit query state and, for Fetcher variants, Fetcher options. Defaults: autoExecute true, propagateError false, no initial query unless provided. Fetcher variants POST the query, default to JSON extraction; the stream variant forcibly uses JsonEventStreamResultExtractor after spreading options.

Pass the controller to the service client so superseded requests can stop I/O. Stream success means a ReadableStream was obtained, not that it was fully consumed. The Hook does not accumulate messages, close a reader, or retry a failed stream. Once request extraction resolves its controller may no longer be owned by the active executor; the consumer must cancel its reader/stream on replacement or unmount. Use EventStream consumption for that lifecycle.

Complete example

import { usePagedQuery } from '@ahoo-wang/fetcher-react';
import {
  SnapshotQueryClient,
  pagedQuery,
  filter,
} from '@ahoo-wang/fetcher-wow';
interface User {
  id: string;
  name: string;
}
const client = new SnapshotQueryClient<User>({ basePath: '/users' });
export function Users() {
  const query = usePagedQuery<User>({
    initialQuery: pagedQuery({ filter: filter.matchAll() }),
    execute: (request, attributes, controller) =>
      client.pagedState(request, attributes, controller),
  });
  return (
    <section>
      {query.error && <p role="alert">{query.error.message}</p>}
      <p>{query.result?.total ?? 0}</p>
      {query.result?.list.map(user => (
        <p key={user.id}>{user.name}</p>
      ))}
    </section>
  );
}

Service URLs in examples require application endpoints; type checking does not imply an external service was contacted.

Public signatures and types

These signatures follow declarations reachable from the current root entry. ? marks optional input; generics/interfaces only constrain compile-time types. Locate inherited and related types through the symbol index. Runtime defaults and failure behavior are described above.

useFetcherCountQuery

export function useFetcherCountQuery<
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherCountQueryOptions<FIELDS, E, Condition<FIELDS>>,
): UseFetcherCountQueryReturn<FIELDS, E, Condition<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherCountQuery.ts:89

export function useFetcherCountQuery<
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherCountQueryOptions<FIELDS, E, FilterExpression<FIELDS>>,
): UseFetcherCountQueryReturn<FIELDS, E, FilterExpression<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherCountQuery.ts:95

export function useFetcherCountQuery<
  FIELDS extends string = string,
  E = FetcherError,
  Q extends Condition<FIELDS> | FilterExpression<FIELDS> = Condition<FIELDS>,
>(
  options: UseFetcherCountQueryOptions<FIELDS, E, Q>,
): UseFetcherCountQueryReturn<FIELDS, E, Q>;

packages/react/src/wow/fetcher/useFetcherCountQuery.ts:101

UseFetcherCountQueryOptions

export interface UseFetcherCountQueryOptions<
  FIELDS extends string = string,
  E = FetcherError,
  Q extends Condition<FIELDS> | FilterExpression<FIELDS> = Condition<FIELDS>,
> extends UseFetcherQueryOptions<Q, number, E> {}

packages/react/src/wow/fetcher/useFetcherCountQuery.ts:29

UseFetcherCountQueryReturn

export interface UseFetcherCountQueryReturn<
  FIELDS extends string = string,
  E = FetcherError,
  Q extends Condition<FIELDS> | FilterExpression<FIELDS> = Condition<FIELDS>,
> extends UseQueryReturn<Q, number, E> {}

packages/react/src/wow/fetcher/useFetcherCountQuery.ts:44

useFetcherListQuery

export function useFetcherListQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherListQueryOptions<R, FIELDS, E, ListQuery<FIELDS>>,
): UseFetcherListQueryReturn<R, FIELDS, E, ListQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherListQuery.ts:128

export function useFetcherListQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherListQueryOptions<R, FIELDS, E, FilterListQuery<FIELDS>>,
): UseFetcherListQueryReturn<R, FIELDS, E, FilterListQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherListQuery.ts:135

export function useFetcherListQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
>(
  options: UseFetcherListQueryOptions<R, FIELDS, E, Q>,
): UseFetcherListQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/fetcher/useFetcherListQuery.ts:142

UseFetcherListQueryOptions

export interface UseFetcherListQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseFetcherQueryOptions<Q, R[], E> {}

packages/react/src/wow/fetcher/useFetcherListQuery.ts:32

UseFetcherListQueryReturn

export interface UseFetcherListQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseQueryReturn<Q, R[], E> {}

packages/react/src/wow/fetcher/useFetcherListQuery.ts:47

useFetcherListStreamQuery

export function useFetcherListStreamQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherListStreamQueryOptions<R, FIELDS, E, ListQuery<FIELDS>>,
): UseFetcherListStreamQueryReturn<R, FIELDS, E, ListQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherListStreamQuery.ts:140

export function useFetcherListStreamQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherListStreamQueryOptions<
    R,
    FIELDS,
    E,
    FilterListQuery<FIELDS>
  >,
): UseFetcherListStreamQueryReturn<R, FIELDS, E, FilterListQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherListStreamQuery.ts:147

export function useFetcherListStreamQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
>(
  options: UseFetcherListStreamQueryOptions<R, FIELDS, E, Q>,
): UseFetcherListStreamQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/fetcher/useFetcherListStreamQuery.ts:159

UseFetcherListStreamQueryOptions

export interface UseFetcherListStreamQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseFetcherQueryOptions<
  Q,
  ReadableStream<JsonServerSentEvent<R>>,
  E
> {}

packages/react/src/wow/fetcher/useFetcherListStreamQuery.ts:36

UseFetcherListStreamQueryReturn

export interface UseFetcherListStreamQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseQueryReturn<Q, ReadableStream<JsonServerSentEvent<R>>, E> {}

packages/react/src/wow/fetcher/useFetcherListStreamQuery.ts:57

useFetcherPagedQuery

export function useFetcherPagedQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherPagedQueryOptions<R, FIELDS, E, PagedQuery<FIELDS>>,
): UseFetcherPagedQueryReturn<R, FIELDS, E, PagedQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherPagedQuery.ts:140

export function useFetcherPagedQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherPagedQueryOptions<R, FIELDS, E, FilterPagedQuery<FIELDS>>,
): UseFetcherPagedQueryReturn<R, FIELDS, E, FilterPagedQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherPagedQuery.ts:147

export function useFetcherPagedQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends PagedQueryRequest<FIELDS> = PagedQuery<FIELDS>,
>(
  options: UseFetcherPagedQueryOptions<R, FIELDS, E, Q>,
): UseFetcherPagedQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/fetcher/useFetcherPagedQuery.ts:154

UseFetcherPagedQueryOptions

export interface UseFetcherPagedQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends PagedQueryRequest<FIELDS> = PagedQuery<FIELDS>,
> extends UseFetcherQueryOptions<Q, PagedList<R>, E> {}

packages/react/src/wow/fetcher/useFetcherPagedQuery.ts:35

UseFetcherPagedQueryReturn

export interface UseFetcherPagedQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends PagedQueryRequest<FIELDS> = PagedQuery<FIELDS>,
> extends UseQueryReturn<Q, PagedList<R>, E> {}

packages/react/src/wow/fetcher/useFetcherPagedQuery.ts:52

useFetcherSingleQuery

export function useFetcherSingleQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherSingleQueryOptions<R, FIELDS, E, SingleQuery<FIELDS>>,
): UseFetcherSingleQueryReturn<R, FIELDS, E, SingleQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherSingleQuery.ts:113

export function useFetcherSingleQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseFetcherSingleQueryOptions<
    R,
    FIELDS,
    E,
    FilterSingleQuery<FIELDS>
  >,
): UseFetcherSingleQueryReturn<R, FIELDS, E, FilterSingleQuery<FIELDS>>;

packages/react/src/wow/fetcher/useFetcherSingleQuery.ts:120

export function useFetcherSingleQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends SingleQueryRequest<FIELDS> = SingleQuery<FIELDS>,
>(
  options: UseFetcherSingleQueryOptions<R, FIELDS, E, Q>,
): UseFetcherSingleQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/fetcher/useFetcherSingleQuery.ts:132

UseFetcherSingleQueryOptions

export interface UseFetcherSingleQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends SingleQueryRequest<FIELDS> = SingleQuery<FIELDS>,
> extends UseFetcherQueryOptions<Q, R, E> {}

packages/react/src/wow/fetcher/useFetcherSingleQuery.ts:33

UseFetcherSingleQueryReturn

export interface UseFetcherSingleQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends SingleQueryRequest<FIELDS> = SingleQuery<FIELDS>,
> extends UseQueryReturn<Q, R, E> {}

packages/react/src/wow/fetcher/useFetcherSingleQuery.ts:49

useCountQuery

export function useCountQuery<FIELDS extends string = string, E = FetcherError>(
  options: UseCountQueryOptions<FIELDS, E, Condition<FIELDS>>,
): UseCountQueryReturn<FIELDS, E, Condition<FIELDS>>;

packages/react/src/wow/useCountQuery.ts:61

export function useCountQuery<FIELDS extends string = string, E = FetcherError>(
  options: UseCountQueryOptions<FIELDS, E, FilterExpression<FIELDS>>,
): UseCountQueryReturn<FIELDS, E, FilterExpression<FIELDS>>;

packages/react/src/wow/useCountQuery.ts:64

export function useCountQuery<
  FIELDS extends string = string,
  E = FetcherError,
  Q extends Condition<FIELDS> | FilterExpression<FIELDS> = Condition<FIELDS>,
>(
  options: UseCountQueryOptions<FIELDS, E, Q>,
): UseCountQueryReturn<FIELDS, E, Q>;

packages/react/src/wow/useCountQuery.ts:67

UseCountQueryOptions

export interface UseCountQueryOptions<
  FIELDS extends string = string,
  E = FetcherError,
  Q extends Condition<FIELDS> | FilterExpression<FIELDS> = Condition<FIELDS>,
> extends UseQueryOptions<Q, number, E> {}

packages/react/src/wow/useCountQuery.ts:25

UseCountQueryReturn

export interface UseCountQueryReturn<
  FIELDS extends string = string,
  E = FetcherError,
  Q extends Condition<FIELDS> | FilterExpression<FIELDS> = Condition<FIELDS>,
> extends UseQueryReturn<Q, number, E> {}

packages/react/src/wow/useCountQuery.ts:38

useListQuery

export function useListQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseListQueryOptions<R, FIELDS, E, ListQuery<FIELDS>>,
): UseListQueryReturn<R, FIELDS, E, ListQuery<FIELDS>>;

packages/react/src/wow/useListQuery.ts:75

export function useListQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseListQueryOptions<R, FIELDS, E, FilterListQuery<FIELDS>>,
): UseListQueryReturn<R, FIELDS, E, FilterListQuery<FIELDS>>;

packages/react/src/wow/useListQuery.ts:82

export function useListQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
>(
  options: UseListQueryOptions<R, FIELDS, E, Q>,
): UseListQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/useListQuery.ts:89

UseListQueryOptions

export interface UseListQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseQueryOptions<Q, R[], E> {}

packages/react/src/wow/useListQuery.ts:31

UseListQueryReturn

export interface UseListQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseQueryReturn<Q, R[], E> {}

packages/react/src/wow/useListQuery.ts:46

useListStreamQuery

export function useListStreamQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseListStreamQueryOptions<R, FIELDS, E, ListQuery<FIELDS>>,
): UseListStreamQueryReturn<R, FIELDS, E, ListQuery<FIELDS>>;

packages/react/src/wow/useListStreamQuery.ts:76

export function useListStreamQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseListStreamQueryOptions<R, FIELDS, E, FilterListQuery<FIELDS>>,
): UseListStreamQueryReturn<R, FIELDS, E, FilterListQuery<FIELDS>>;

packages/react/src/wow/useListStreamQuery.ts:83

export function useListStreamQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
>(
  options: UseListStreamQueryOptions<R, FIELDS, E, Q>,
): UseListStreamQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/useListStreamQuery.ts:90

UseListStreamQueryOptions

export interface UseListStreamQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseQueryOptions<Q, ReadableStream<JsonServerSentEvent<R>>, E> {}

packages/react/src/wow/useListStreamQuery.ts:32

UseListStreamQueryReturn

export interface UseListStreamQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends ListQueryRequest<FIELDS> = ListQuery<FIELDS>,
> extends UseQueryReturn<Q, ReadableStream<JsonServerSentEvent<R>>, E> {}

packages/react/src/wow/useListStreamQuery.ts:47

usePagedQuery

export function usePagedQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UsePagedQueryOptions<R, FIELDS, E, PagedQuery<FIELDS>>,
): UsePagedQueryReturn<R, FIELDS, E, PagedQuery<FIELDS>>;

packages/react/src/wow/usePagedQuery.ts:77

export function usePagedQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UsePagedQueryOptions<R, FIELDS, E, FilterPagedQuery<FIELDS>>,
): UsePagedQueryReturn<R, FIELDS, E, FilterPagedQuery<FIELDS>>;

packages/react/src/wow/usePagedQuery.ts:84

export function usePagedQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends PagedQueryRequest<FIELDS> = PagedQuery<FIELDS>,
>(
  options: UsePagedQueryOptions<R, FIELDS, E, Q>,
): UsePagedQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/usePagedQuery.ts:91

UsePagedQueryOptions

export interface UsePagedQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends PagedQueryRequest<FIELDS> = PagedQuery<FIELDS>,
> extends UseQueryOptions<Q, PagedList<R>, E> {}

packages/react/src/wow/usePagedQuery.ts:32

UsePagedQueryReturn

export interface UsePagedQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends PagedQueryRequest<FIELDS> = PagedQuery<FIELDS>,
> extends UseQueryReturn<Q, PagedList<R>, E> {}

packages/react/src/wow/usePagedQuery.ts:47

useSingleQuery

export function useSingleQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseSingleQueryOptions<R, FIELDS, E, SingleQuery<FIELDS>>,
): UseSingleQueryReturn<R, FIELDS, E, SingleQuery<FIELDS>>;

packages/react/src/wow/useSingleQuery.ts:75

export function useSingleQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
>(
  options: UseSingleQueryOptions<R, FIELDS, E, FilterSingleQuery<FIELDS>>,
): UseSingleQueryReturn<R, FIELDS, E, FilterSingleQuery<FIELDS>>;

packages/react/src/wow/useSingleQuery.ts:82

export function useSingleQuery<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends SingleQueryRequest<FIELDS> = SingleQuery<FIELDS>,
>(
  options: UseSingleQueryOptions<R, FIELDS, E, Q>,
): UseSingleQueryReturn<R, FIELDS, E, Q>;

packages/react/src/wow/useSingleQuery.ts:89

UseSingleQueryOptions

export interface UseSingleQueryOptions<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends SingleQueryRequest<FIELDS> = SingleQuery<FIELDS>,
> extends UseQueryOptions<Q, R, E> {}

packages/react/src/wow/useSingleQuery.ts:31

UseSingleQueryReturn

export interface UseSingleQueryReturn<
  R,
  FIELDS extends string = string,
  E = FetcherError,
  Q extends SingleQueryRequest<FIELDS> = SingleQuery<FIELDS>,
> extends UseQueryReturn<Q, R, E> {}

packages/react/src/wow/useSingleQuery.ts:46

Related topics

Fetcher hooks · Promise and query state · API hook factories · Debounced execution · Storage and event subscriptions · Security hooks and route guards · Monitoring, refs and fullscreen