@tanstack/react-query 5.102.8 → 5.103.0

package/src/infiniteQueryOptions.ts

@@ -10,6 +10,17 @@ import type {
 } from '@tanstack/query-core'
 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,
@@ -23,6 +34,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>>
@@ -31,6 +49,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,
@@ -41,6 +71,12 @@ 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, set `enabled: false` — omitting `queryFn` alone still triggers a
+   * fetch that fails with "Missing queryFn" unless `enabled` is `false` or a default query function has been
+   * defined. A default query function only supplies `queryFn`; it doesn't defer the fetch on its own.
+   */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
       TQueryFnData,
@@ -53,6 +89,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,
@@ -66,12 +113,60 @@ 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.
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
+ * automatically as the user scrolls.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-query'
+ *
+ * export const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ *   initialData: { pages: [], pageParams: [] },
+ * })
+ *
+ * function Projects() {
+ *   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
+ *   const { data, isError, error } = useInfiniteQuery(projectsOptions)
+ *
+ *   return (
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -95,6 +190,45 @@ 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.
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
+ * automatically as the user scrolls.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `postId`:
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-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 { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ *
+ * @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,
@@ -118,6 +252,45 @@ 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.
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages (from a button click or
+ * automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `postId`:
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-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 { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ *
+ * @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

@@ -1,6 +1,35 @@
 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
+ * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
+ * ```tsx
+ * import { mutationOptions, useMutationState } from '@tanstack/react-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,
@@ -15,6 +44,32 @@ 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 target the mutation via a
+ * `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters,
+ * such as `status`.
+ *
+ * @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.
+ * @remarks See the other overload's example for looking a mutation up via `useMutationState`.
+ *
+ * @example
+ * ```tsx
+ * import { mutationOptions, useMutation } from '@tanstack/react-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,

package/src/queryOptions.ts

@@ -10,18 +10,43 @@ import type {
 } from '@tanstack/query-core'
 import type { UseQueryOptions } from './types'
 
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set — `data` may be
+ * `undefined` while the query is `pending`.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UndefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  /**
+   * 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
     | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
     | NonUndefinedGuard<TQueryFnData>
 }
 
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set and `queryFn` is
+ * not `skipToken` — same as {@link UndefinedInitialDataOptions}, but `queryFn` may not be `skipToken`.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UnusedSkipTokenOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -31,24 +56,89 @@ export type UnusedSkipTokenOptions<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   '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, set `enabled: false` — omitting `queryFn` alone still triggers a
+   * fetch that fails with "Missing queryFn" unless `enabled` is `false` or a default query function has been
+   * defined. A default query function only supplies `queryFn`; it doesn't defer the fetch on its own.
+   */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
     SkipToken | undefined
   >
 }
 
+/**
+ * The options accepted by the `queryOptions` overload selected when `initialData` is set — `data` is never
+ * `undefined`.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type DefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryFn'> & {
+  /**
+   * 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<TQueryFnData>
     | (() => NonUndefinedGuard<TQueryFnData>)
+  /**
+   * Optional here, but omitting it is only safe when no fetch will be attempted — for example with
+   * `enabled: false`, or when a default query function has been defined. Otherwise, an enabled query with no
+   * `queryFn` still tries to fetch and fails with a "Missing queryFn" error; `initialData` does not prevent this.
+   */
   queryFn?: QueryFunction<TQueryFnData, TQueryKey>
 }
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
+ * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/react-query'
+ *
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ *   initialData: [],
+ * })
+ *
+ * function Posts() {
+ *   // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
+ *   // so the list stays visible alongside the error.
+ *   const { data, isError, error } = useQuery(postsOptions)
+ *
+ *   return (
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -59,6 +149,37 @@ export function queryOptions<
 ): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
+ * @param options - The {@link UnusedSkipTokenOptions} to use — everything you can pass to `useQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/react-query'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data, isPending, isError, error } = useQuery(postOptions(id))
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <h1>{data.title}</h1>
+ * }
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -69,6 +190,60 @@ export function queryOptions<
 ): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
+ * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks This is the only overload that accepts `queryFn: skipToken`, shown below.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/react-query'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data, isPending, isError, error } = useQuery(postOptions(id))
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <h1>{data.title}</h1>
+ * }
+ * ```
+ *
+ * @example
+ * A factory that disables the query, type safe, until `postId` is set:
+ * ```tsx
+ * import { queryOptions, skipToken, useQuery } from '@tanstack/react-query'
+ *
+ * export const postOptions = (postId: number | undefined) =>
+ *   queryOptions({
+ *     queryKey: ['post', postId],
+ *     queryFn: postId != null ? () => fetchPost(postId) : skipToken,
+ *   })
+ *
+ * function Post({ postId }: { postId: number | undefined }) {
+ *   const { data, isLoading, isError, error } = useQuery(postOptions(postId))
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,