@tanstack/preact-query 5.102.3 → 5.102.5

package/src/types.ts

@@ -20,6 +20,10 @@ import type {
   SkipToken,
 } from '@tanstack/query-core'
 
+/**
+ * {@link UseBaseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseBaseQueryOptions = UseBaseQueryOptions<
   any,
   any,
@@ -27,6 +31,18 @@ export type AnyUseBaseQueryOptions = UseBaseQueryOptions<
   any,
   any
 >
+/**
+ * The options shared by `useQuery` and `useSuspenseQuery`. Extends {@link QueryObserverOptions} from
+ * `@tanstack/query-core` with the `preact-query`-specific `subscribed` option.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryData - The type of the data actually held in the query cache — the input to `select` and
+ * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface UseBaseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -42,11 +58,24 @@ export interface UseBaseQueryOptions<
 > {
   /**
    * Set this to `false` to unsubscribe this observer from updates to the query cache.
-   * Defaults to `true`.
+   *
+   * @defaultValue true
    */
   subscribed?: boolean
 }
 
+/**
+ * The options accepted by `usePrefetchQuery` — everything you can pass to `queryClient.query`, except `queryFn`
+ * is required unless a default query function has been defined.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryData - The type of the data actually held in the query cache — the input to `select` and
+ * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UsePrefetchQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -57,6 +86,10 @@ export type UsePrefetchQueryOptions<
   QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+   * unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     QueryExecuteOptions<
       TQueryFnData,
@@ -69,6 +102,18 @@ export type UsePrefetchQueryOptions<
   >
 }
 
+/**
+ * The options accepted by `usePrefetchInfiniteQuery` — everything you can pass to `queryClient.infiniteQuery`,
+ * except `queryFn` is required unless a default query function has been defined.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` (a single page)
+ * here, since a prefetch never reads `data` back out — this parameter only matters if you reuse these options
+ * elsewhere with `select` applied.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export type UsePrefetchInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -85,6 +130,10 @@ export type UsePrefetchInfiniteQueryOptions<
   >,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+   * unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     InfiniteQueryExecuteOptions<
       TQueryFnData,
@@ -97,7 +146,21 @@ export type UsePrefetchInfiniteQueryOptions<
   >
 }
 
+/**
+ * {@link UseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseQueryOptions = UseQueryOptions<any, any, any, any>
+/**
+ * The options accepted by `useQuery`. Same as {@link UseBaseQueryOptions}, minus `suspense` (which
+ * `preact-query` derives from which hook you call rather than exposing as an option).
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface UseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -108,12 +171,27 @@ export interface UseQueryOptions<
   'suspense'
 > {}
 
+/**
+ * {@link UseSuspenseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseSuspenseQueryOptions = UseSuspenseQueryOptions<
   any,
   any,
   any,
   any
 >
+/**
+ * The options accepted by `useSuspenseQuery`. Same as {@link UseQueryOptions}, minus `enabled`, `throwOnError`,
+ * and `placeholderData` — Suspense hooks cannot render a "disabled" or "placeholder" state, so those options
+ * don't apply.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface UseSuspenseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -123,12 +201,20 @@ export interface UseSuspenseQueryOptions<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
 > {
+  /**
+   * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+   * must always be provided, unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
     SkipToken
   >
 }
 
+/**
+ * {@link UseInfiniteQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<
   any,
   any,
@@ -136,6 +222,18 @@ export type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<
   any,
   any
 >
+/**
+ * The options accepted by `useInfiniteQuery`. Extends {@link InfiniteQueryObserverOptions} from
+ * `@tanstack/query-core` with the `preact-query`-specific `subscribed` option, minus `suspense` (which
+ * `preact-query` derives from which hook you call rather than exposing as an option).
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs — defaults to `InfiniteData<TQueryFnData>`,
+ * the shape of all fetched pages plus their page params.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export interface UseInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -154,13 +252,30 @@ export interface UseInfiniteQueryOptions<
 > {
   /**
    * Set this to `false` to unsubscribe this observer from updates to the query cache.
-   * Defaults to `true`.
+   *
+   * @defaultValue true
    */
   subscribed?: boolean
 }
 
+/**
+ * {@link UseSuspenseInfiniteQueryOptions} with all type parameters set to `any`, useful when the specific types
+ * aren't relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseSuspenseInfiniteQueryOptions =
   UseSuspenseInfiniteQueryOptions<any, any, any, any, any>
+/**
+ * The options accepted by `useSuspenseInfiniteQuery`. Same as {@link UseInfiniteQueryOptions}, minus `enabled`,
+ * `throwOnError`, and `placeholderData` — Suspense hooks cannot render a "disabled" or "placeholder" state, so
+ * those options don't apply.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs — defaults to `InfiniteData<TQueryFnData>`,
+ * the shape of all fetched pages plus their page params.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export interface UseSuspenseInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -171,6 +286,10 @@ export interface UseSuspenseInfiniteQueryOptions<
   UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
   'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
 > {
+  /**
+   * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+   * must always be provided, unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
       TQueryFnData,
@@ -183,16 +302,37 @@ export interface UseSuspenseInfiniteQueryOptions<
   >
 }
 
+/**
+ * The result of `useQuery` when `initialData` isn't set — `data` may be `undefined` while the query is
+ * `pending`. Re-exports {@link QueryObserverResult} from `@tanstack/query-core`. `useInfiniteQuery` returns
+ * {@link UseInfiniteQueryResult} instead.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseBaseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = QueryObserverResult<TData, TError>
 
+/**
+ * The result of `useQuery`. Same as {@link UseBaseQueryResult}.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = UseBaseQueryResult<TData, TError>
 
+/**
+ * The result of `useSuspenseQuery`. Same as {@link DefinedUseQueryResult}, minus `isPlaceholderData` — always
+ * `false` on that type, so this drops the dead field rather than an active state.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseSuspenseQueryResult<
   TData = unknown,
   TError = DefaultError,
@@ -201,21 +341,50 @@ export type UseSuspenseQueryResult<
   'isPlaceholderData'
 >
 
+/**
+ * The result of `useQuery` when `initialData` is set, or of `useSuspenseQuery` before the `isPlaceholderData`
+ * omission — `data` is never `undefined`. Re-exports {@link DefinedQueryObserverResult} from
+ * `@tanstack/query-core`.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type DefinedUseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = DefinedQueryObserverResult<TData, TError>
 
+/**
+ * The result of `useInfiniteQuery` when `initialData` isn't set — `data` may be `undefined` while the query is
+ * `pending`. Re-exports {@link InfiniteQueryObserverResult} from `@tanstack/query-core`.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = InfiniteQueryObserverResult<TData, TError>
 
+/**
+ * The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined`. Re-exports
+ * {@link DefinedInfiniteQueryObserverResult} from `@tanstack/query-core`.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type DefinedUseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = DefinedInfiniteQueryObserverResult<TData, TError>
 
+/**
+ * The result of `useSuspenseInfiniteQuery`. Same as {@link DefinedUseInfiniteQueryResult}, minus
+ * `isPlaceholderData` — Suspense hooks never render placeholder data.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseSuspenseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
@@ -224,7 +393,21 @@ export type UseSuspenseInfiniteQueryResult<
   'isPlaceholderData'
 >
 
+/**
+ * {@link UseMutationOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any mutation in a helper function.
+ */
 export type AnyUseMutationOptions = UseMutationOptions<any, any, any, any>
+/**
+ * The options accepted by `useMutation`. Same as {@link MutationObserverOptions} from `@tanstack/query-core`,
+ * minus the internal `_defaulted` flag.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export interface UseMutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -235,6 +418,17 @@ export interface UseMutationOptions<
   '_defaulted'
 > {}
 
+/**
+ * The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call
+ * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced
+ * through the mutation result, not thrown.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseMutateFunction<
   TData = unknown,
   TError = DefaultError,
@@ -246,6 +440,16 @@ export type UseMutateFunction<
   >
 ) => void
 
+/**
+ * The type of `mutateAsync`, as returned by `useMutation`. Similar to {@link UseMutateFunction}, but returns a
+ * promise which can be awaited.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseMutateAsyncFunction<
   TData = unknown,
   TError = DefaultError,
@@ -253,6 +457,16 @@ export type UseMutateAsyncFunction<
   TOnMutateResult = unknown,
 > = MutateFunction<TData, TError, TVariables, TOnMutateResult>
 
+/**
+ * The result of `useMutation`. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with
+ * `mutate` narrowed to the fire-and-forget {@link UseMutateFunction} signature, plus the added `mutateAsync`.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseBaseMutationResult<
   TData = unknown,
   TError = DefaultError,
@@ -262,6 +476,9 @@ export type UseBaseMutationResult<
   MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
   { mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult> }
 > & {
+  /**
+   * Similar to `mutate`, but returns a promise which can be awaited.
+   */
   mutateAsync: UseMutateAsyncFunction<
     TData,
     TError,
@@ -270,6 +487,15 @@ export type UseBaseMutationResult<
   >
 }
 
+/**
+ * The result of `useMutation`. Same as {@link UseBaseMutationResult}.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseMutationResult<
   TData = unknown,
   TError = DefaultError,

package/src/useInfiniteQuery.ts

@@ -18,6 +18,40 @@ import type {
 } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * This overload is selected when `initialData` is set.
+ *
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
+ * actions, or add conditions like `hasNextPage && !isFetching`.
+ * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
+ * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+ * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+ * `isFetchingPreviousPage`.
+ *
+ * @example
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   const { data } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *     initialData: { pages: [], pageParams: [] },
+ *   })
+ *
+ *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ * }
+ * ```
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
@@ -35,6 +69,49 @@ export function useInfiniteQuery<
   queryClient?: QueryClient,
 ): DefinedUseInfiniteQueryResult<TData, TError>
 
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
+ * actions, or add conditions like `hasNextPage && !isFetching`.
+ * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
+ * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+ * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+ * `isFetchingPreviousPage`.
+ *
+ * @example
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   return (
+ *     <button
+ *       onClick={() => fetchNextPage()}
+ *       disabled={!hasNextPage || isFetching}
+ *     >
+ *       {isFetchingNextPage
+ *         ? 'Loading more...'
+ *         : hasNextPage
+ *           ? 'Load More'
+ *           : 'Nothing more to load'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
@@ -52,6 +129,49 @@ export function useInfiniteQuery<
   queryClient?: QueryClient,
 ): UseInfiniteQueryResult<TData, TError>
 
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
+ * actions, or add conditions like `hasNextPage && !isFetching`.
+ * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
+ * @param options - The {@link UseInfiniteQueryOptions} to use — everything you can pass to `useInfiniteQuery`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+ * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+ * `isFetchingPreviousPage`.
+ *
+ * @example
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   return (
+ *     <button
+ *       onClick={() => fetchNextPage()}
+ *       disabled={!hasNextPage || isFetching}
+ *     >
+ *       {isFetchingNextPage
+ *         ? 'Loading more...'
+ *         : hasNextPage
+ *           ? 'Load More'
+ *           : 'Nothing more to load'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,

package/src/useIsFetching.ts

@@ -5,6 +5,40 @@ import { useCallback } from 'preact/hooks'
 import { useQueryClient } from './QueryClientProvider'
 import { useSyncExternalStore } from './utils'
 
+/**
+ * `useIsFetching` is an optional hook that returns the `number` of the queries that your application is loading or
+ * fetching in the background (useful for app-wide loading indicators).
+ *
+ * @param filters - The {@link QueryFilters} to narrow down the matched queries.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be the `number` of the queries that your application is currently loading or fetching in the
+ * background.
+ *
+ * @example
+ * ```tsx
+ * import { useIsFetching } from '@tanstack/preact-query'
+ *
+ * // How many queries are fetching?
+ * const isFetching = useIsFetching()
+ * // How many queries matching the posts prefix are fetching?
+ * const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+ * ```
+ *
+ * @example
+ * A global loading indicator for any query fetching in the background, not just the ones on screen:
+ * ```tsx
+ * import { useIsFetching } from '@tanstack/preact-query'
+ *
+ * function GlobalLoadingIndicator() {
+ *   const isFetching = useIsFetching()
+ *
+ *   return isFetching ? (
+ *     <div>Queries are fetching in the background...</div>
+ *   ) : null
+ * }
+ * ```
+ */
 export function useIsFetching(
   filters?: QueryFilters,
   queryClient?: QueryClient,