@tanstack/preact-query 5.102.2 → 5.102.4

package/src/IsRestoringProvider.ts

@@ -3,5 +3,17 @@ import { useContext } from 'preact/hooks'
 
 const IsRestoringContext = createContext(false)
 
+/**
+ * If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
+ * check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
+ * race conditions between the restore and mounting queries.
+ *
+ * @returns `true` while a persisted client is being restored, `false` otherwise.
+ */
 export const useIsRestoring = () => useContext(IsRestoringContext)
+
+/**
+ * The Provider that `PersistQueryClientProvider` uses to signal whether a persisted client is currently
+ * being restored, read by `useIsRestoring`.
+ */
 export const IsRestoringProvider = IsRestoringContext.Provider

package/src/QueryClientProvider.tsx

@@ -3,10 +3,21 @@ import { createContext } from 'preact'
 import type { ComponentChildren, VNode } from 'preact'
 import { useContext, useEffect } from 'preact/hooks'
 
+/**
+ * The context that `useQueryClient` reads from. `QueryClientProvider` is the normal way to set it.
+ */
 export const QueryClientContext = createContext<QueryClient | undefined>(
   undefined,
 )
 
+/**
+ * The `useQueryClient` hook returns the current `QueryClient` instance.
+ *
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The current `QueryClient` instance.
+ * @throws If no `queryClient` argument is passed and no `QueryClientProvider` is found in the component tree.
+ */
 export const useQueryClient = (queryClient?: QueryClient) => {
   const client = useContext(QueryClientContext)
 
@@ -21,11 +32,41 @@ export const useQueryClient = (queryClient?: QueryClient) => {
   return client
 }
 
+/**
+ * The props accepted by `QueryClientProvider`.
+ */
 export type QueryClientProviderProps = {
+  /**
+   * **Required**
+   *
+   * The `QueryClient` instance to provide.
+   */
   client: QueryClient
+  /**
+   * The components that get access to the provided `QueryClient`.
+   */
   children?: ComponentChildren
 }
 
+/**
+ * Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application. Also
+ * calls `client.mount()`/`client.unmount()` as this component mounts/unmounts, which subscribes the client to
+ * focus/online events (resuming any paused mutations and refetching as needed when the app regains focus or
+ * comes back online).
+ *
+ * @returns The provided `children`, wrapped so they can read the `QueryClient` via `useQueryClient`.
+ *
+ * @example
+ * ```tsx
+ * import { QueryClient, QueryClientProvider } from '@tanstack/preact-query'
+ *
+ * const queryClient = new QueryClient()
+ *
+ * function App() {
+ *   return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
+ * }
+ * ```
+ */
 export const QueryClientProvider = ({
   client,
   children,

package/src/QueryErrorResetBoundary.tsx

@@ -3,13 +3,34 @@ import type { ComponentChildren } from 'preact'
 import { useContext, useState } from 'preact/hooks'
 
 // CONTEXT
+
+/**
+ * Resets any query errors within the boundary, so queries know they can try again.
+ */
 export type QueryErrorResetFunction = () => void
+
+/**
+ * Returns whether the boundary has been reset and not yet cleared.
+ */
 export type QueryErrorIsResetFunction = () => boolean
+
+/**
+ * Clears the reset state, so queries know not to try again until the boundary is reset again.
+ */
 export type QueryErrorClearResetFunction = () => void
 
 export interface QueryErrorResetBoundaryValue {
+  /**
+   * Clears the reset state, so queries know not to try again until the boundary is reset again.
+   */
   clearReset: QueryErrorClearResetFunction
+  /**
+   * Returns whether the boundary has been reset and not yet cleared.
+   */
   isReset: QueryErrorIsResetFunction
+  /**
+   * Resets any query errors within the boundary, so queries know they can try again.
+   */
   reset: QueryErrorResetFunction
 }
 
@@ -32,19 +53,107 @@ const QueryErrorResetBoundaryContext = createContext(createValue())
 
 // HOOK
 
+/**
+ * This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
+ * defined it will reset them globally.
+ *
+ * @returns The boundary's {@link QueryErrorResetBoundaryValue}.
+ *
+ * @example
+ * ```tsx
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import type { ComponentChildren } from 'preact'
+ * import { useQueryErrorResetBoundary } from '@tanstack/preact-query'
+ *
+ * function App({ children }: { children: ComponentChildren }) {
+ *   const { reset } = useQueryErrorResetBoundary()
+ *   const [error, resetError] = useErrorBoundary(() => reset())
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         There was an error!
+ *         <button onClick={() => resetError()}>Try again</button>
+ *       </div>
+ *     )
+ *   }
+ *
+ *   return children
+ * }
+ * ```
+ */
 export const useQueryErrorResetBoundary = () =>
   useContext(QueryErrorResetBoundaryContext)
 
 // COMPONENT
 
+/**
+ * A render-prop function usable as `children` on `QueryErrorResetBoundary`.
+ *
+ * @param value - The boundary's {@link QueryErrorResetBoundaryValue}.
+ * @returns The children to render.
+ */
 export type QueryErrorResetBoundaryFunction = (
   value: QueryErrorResetBoundaryValue,
 ) => ComponentChildren
 
+/**
+ * The props accepted by `QueryErrorResetBoundary`.
+ */
 export interface QueryErrorResetBoundaryProps {
+  /**
+   * Either a plain node, or a function that receives the boundary's {@link QueryErrorResetBoundaryValue} and
+   * returns a node.
+   */
   children: QueryErrorResetBoundaryFunction | ComponentChildren
 }
 
+/**
+ * When using `suspense` or `throwOnError` in your queries, you need a way to let queries know that you want to
+ * try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
+ * reset any query errors within the boundaries of the component.
+ *
+ * @returns The `children`, rendered as-is, or called with the boundary's {@link QueryErrorResetBoundaryValue}
+ * if `children` is a function.
+ *
+ * @example
+ * ```tsx
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import type { ComponentChildren } from 'preact'
+ * import { QueryErrorResetBoundary } from '@tanstack/preact-query'
+ *
+ * function ErrorBoundary({
+ *   children,
+ *   reset,
+ * }: {
+ *   children: ComponentChildren
+ *   reset: () => void
+ * }) {
+ *   const [error, resetError] = useErrorBoundary(() => reset())
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         There was an error!
+ *         <button onClick={() => resetError()}>Try again</button>
+ *       </div>
+ *     )
+ *   }
+ *
+ *   return children
+ * }
+ *
+ * const App = () => (
+ *   <QueryErrorResetBoundary>
+ *     {({ reset }) => (
+ *       <ErrorBoundary reset={reset}>
+ *         <Page />
+ *       </ErrorBoundary>
+ *     )}
+ *   </QueryErrorResetBoundary>
+ * )
+ * ```
+ */
 export const QueryErrorResetBoundary = ({
   children,
 }: QueryErrorResetBoundaryProps) => {

package/src/infiniteQueryOptions.ts

@@ -11,6 +11,17 @@ import type {
 
 import type { UseInfiniteQueryOptions } from './types'
 
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when no `initialData` is set — `data`
+ * may be `undefined` while the query is `pending`.
+ *
+ * @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 type UndefinedInitialDataInfiniteOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -24,6 +35,13 @@ export type UndefinedInitialDataInfiniteOptions<
   TQueryKey,
   TPageParam
 > & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData?:
     | undefined
     | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
@@ -32,6 +50,18 @@ export type UndefinedInitialDataInfiniteOptions<
       >
 }
 
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when no `initialData` is set and
+ * `queryFn` is not `skipToken` — same as {@link UndefinedInitialDataInfiniteOptions}, but `queryFn` may not be
+ * `skipToken`.
+ *
+ * @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 type UnusedSkipTokenInfiniteOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -42,6 +72,10 @@ export type UnusedSkipTokenInfiniteOptions<
   UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
+   * you don't intend to run the query yet, omit `queryFn` or use a default query function instead.
+   */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
       TQueryFnData,
@@ -54,6 +88,17 @@ export type UnusedSkipTokenInfiniteOptions<
   >
 }
 
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is set — `data` is
+ * never `undefined`.
+ *
+ * @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 type DefinedInitialDataInfiniteOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -67,12 +112,48 @@ export type DefinedInitialDataInfiniteOptions<
   TQueryKey,
   TPageParam
 > & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData:
     | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
     | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
     | undefined
 }
 
+/**
+ * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+ * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * This overload is selected when `initialData` is set.
+ *
+ * @see {@link useInfiniteQuery} to run an infinite query with these options.
+ * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * export const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ *   initialData: { pages: [], pageParams: [] },
+ * })
+ *
+ * function Projects() {
+ *   const { data } = useInfiniteQuery(projectsOptions)
+ *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ * }
+ * ```
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -96,6 +177,59 @@ export function infiniteQueryOptions<
 > &
   QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
+/**
+ * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+ * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ *
+ * export const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import {
+ *   infiniteQueryOptions,
+ *   noop,
+ *   useInfiniteQuery,
+ * } from '@tanstack/preact-query'
+ *
+ * export const commentsOptions = (postId: string) =>
+ *   infiniteQueryOptions({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ * function Comments({ postId }: { postId: string }) {
+ *   const result = useInfiniteQuery(commentsOptions(postId))
+ *   if (!result.isSuccess) return 'Loading...'
+ *   return (
+ *     <>
+ *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+ *     </>
+ *   )
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+ * ```
+ *
+ * @see {@link useInfiniteQuery} to run an infinite query with these options.
+ * @param options - The {@link UnusedSkipTokenInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -119,6 +253,59 @@ export function infiniteQueryOptions<
 > &
   QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
+/**
+ * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+ * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ *
+ * export const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import {
+ *   infiniteQueryOptions,
+ *   noop,
+ *   useInfiniteQuery,
+ * } from '@tanstack/preact-query'
+ *
+ * export const commentsOptions = (postId: string) =>
+ *   infiniteQueryOptions({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ * function Comments({ postId }: { postId: string }) {
+ *   const result = useInfiniteQuery(commentsOptions(postId))
+ *   if (!result.isSuccess) return 'Loading...'
+ *   return (
+ *     <>
+ *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+ *     </>
+ *   )
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+ * ```
+ *
+ * @see {@link useInfiniteQuery} to run an infinite query with these options.
+ * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,

package/src/mutationOptions.ts

@@ -2,6 +2,50 @@ import type { DefaultError, WithRequired } from '@tanstack/query-core'
 
 import type { UseMutationOptions } from './types'
 
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A
+ * `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
+ * `useMutationState`.
+ *
+ * @see {@link useMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, with a
+ * required `mutationKey`.
+ * @returns The same options object, unchanged.
+ *
+ * @example
+ * ```tsx
+ * import { mutationOptions, useMutation } from '@tanstack/preact-query'
+ *
+ * export const createPostOptions = mutationOptions({
+ *   mutationKey: ['posts', 'create'],
+ *   mutationFn: createPost,
+ * })
+ *
+ * function CreatePost() {
+ *   const mutation = useMutation(createPostOptions)
+ *   return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
+ * }
+ * ```
+ *
+ * @example
+ * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
+ * ```tsx
+ * import { mutationOptions, useMutationState } from '@tanstack/preact-query'
+ *
+ * const createPostOptions = mutationOptions({
+ *   mutationKey: ['posts', 'create'],
+ *   mutationFn: createPost,
+ * })
+ *
+ * function SavingIndicator() {
+ *   const isCreatingPost = useMutationState({
+ *     filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+ *   }).length > 0
+ *
+ *   return isCreatingPost ? <span>Saving…</span> : null
+ * }
+ * ```
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -16,6 +60,30 @@ export function mutationOptions<
   UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,
   'mutationKey'
 >
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
+ * `mutationKey` is required on this overload — use this when you don't need to look the mutation up later
+ * (e.g. with `useMutationState`).
+ *
+ * @see {@link useMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
+ * `mutationKey`.
+ * @returns The same options object, unchanged.
+ *
+ * @example
+ * ```tsx
+ * import { mutationOptions, useMutation } from '@tanstack/preact-query'
+ *
+ * export const createPostOptions = mutationOptions({
+ *   mutationFn: createPost,
+ * })
+ *
+ * function CreatePost() {
+ *   const mutation = useMutation(createPostOptions)
+ *   return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
+ * }
+ * ```
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,