Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

infiniteQueryOptions.ts

309 lines11.5 KB

1import type {
2 DefaultError,
3 InfiniteData,
4 InitialDataFunction,
5 NonUndefinedGuard,
6 OmitKeyof,
7 QueryKey,
8 QueryKeyWithDataTag,
9 SkipToken,
10} from '@tanstack/query-core'
11import type { UseInfiniteQueryOptions } from './types'
12​
13/**
14 * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is omitted, may be
15 * `undefined`, or is a function that may return `undefined` β€” `data` may be `undefined` while the query is
16 * `pending`.
17 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
18 * @template TError - The type of errors your `queryFn` may throw.
19 * @template TData - The type `data` ends up as after `select` runs β€” defaults to `InfiniteData<TQueryFnData>`,
20 * the shape of all fetched pages plus their page params.
21 * @template TQueryKey - The type of your `queryKey`.
22 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
23 */
24export type UndefinedInitialDataInfiniteOptions<
25 TQueryFnData,
26 TError = DefaultError,
27 TData = InfiniteData<TQueryFnData>,
28 TQueryKey extends QueryKey = QueryKey,
29 TPageParam = unknown,
30> = UseInfiniteQueryOptions<
31 TQueryFnData,
32 TError,
33 TData,
34 TQueryKey,
35 TPageParam
36> & {
37 /**
38 * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
39 * created or cached yet). If set to a function, the function will be called **once** during the shared/root
40 * query initialization, and be expected to synchronously return the initial data. Initial data is
41 * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
42 * cache.
43 */
44 initialData?:
45 | undefined
46 | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
47 | InitialDataFunction<
48 NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
49 >
51​
52/**
53 * The options accepted by the `infiniteQueryOptions` overload selected when `queryFn` is not `skipToken` and
54 * `initialData` is omitted, may be `undefined`, or is a function that may return `undefined` β€” same as
55 * {@link UndefinedInitialDataInfiniteOptions}, but `queryFn` may not be `skipToken`.
56 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
57 * @template TError - The type of errors your `queryFn` may throw.
58 * @template TData - The type `data` ends up as after `select` runs β€” defaults to `InfiniteData<TQueryFnData>`,
59 * the shape of all fetched pages plus their page params.
60 * @template TQueryKey - The type of your `queryKey`.
61 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
62 */
63export type UnusedSkipTokenInfiniteOptions<
64 TQueryFnData,
65 TError = DefaultError,
66 TData = InfiniteData<TQueryFnData>,
67 TQueryKey extends QueryKey = QueryKey,
68 TPageParam = unknown,
69> = OmitKeyof<
70 UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
71 'queryFn'
72> & {
73 /**
74 * `skipToken` is not allowed as a value here β€” this overload is selected when `initialData` is omitted, may
75 * be `undefined`, or is a function that may return `undefined`. If you don't intend to run the query yet,
76 * set `enabled: false` β€” omitting `queryFn` alone still triggers a fetch that fails with "Missing queryFn"
77 * unless `enabled` is `false` or a default query function has been defined. A default query function only
78 * supplies `queryFn`; it doesn't defer the fetch on its own.
79 */
80 queryFn?: Exclude<
81 UseInfiniteQueryOptions<
82 TQueryFnData,
83 TError,
84 TData,
85 TQueryKey,
86 TPageParam
87 >['queryFn'],
88 SkipToken | undefined
89 >
91​
92/**
93 * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is known to be
94 * defined β€” `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`).
95 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
96 * @template TError - The type of errors your `queryFn` may throw.
97 * @template TData - The type `data` ends up as after `select` runs β€” defaults to `InfiniteData<TQueryFnData>`,
98 * the shape of all fetched pages plus their page params.
99 * @template TQueryKey - The type of your `queryKey`.
100 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
101 */
102export type DefinedInitialDataInfiniteOptions<
103 TQueryFnData,
104 TError = DefaultError,
105 TData = InfiniteData<TQueryFnData>,
106 TQueryKey extends QueryKey = QueryKey,
107 TPageParam = unknown,
108> = UseInfiniteQueryOptions<
109 TQueryFnData,
110 TError,
111 TData,
112 TQueryKey,
113 TPageParam
114> & {
115 /**
116 * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
117 * created or cached yet). If set to a function, the function will be called **once** during the shared/root
118 * query initialization, and be expected to synchronously return the initial data. Initial data is
119 * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
120 * cache.
121 */
122 initialData:
123 | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
124 | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
126​
127/**
128 * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
129 * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
130 * `options.queryKey` is required and is the query key to generate options for.
131 *
132 * This overload is selected when `initialData` is known to be defined.
133 * @param options - The {@link DefinedInitialDataInfiniteOptions} to use β€” everything you can pass to `useInfiniteQuery`, with `initialData` known to be defined.
134 * @returns The same options object, typed so that `queryKey` carries the inferred data type.
135 * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
136 * automatically as the user scrolls.
137 * @see {@link useInfiniteQuery} to run an infinite query with these options.
138 * @example
139 * ```tsx
140 * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-query'
141 *
142 * export const projectsOptions = infiniteQueryOptions({
143 * queryKey: ['projects'],
144 * queryFn: ({ pageParam }) => fetchProjects(pageParam),
145 * initialPageParam: 0,
146 * getNextPageParam: (lastPage) => lastPage.nextId,
147 * initialData: { pages: [], pageParams: [] },
148 * })
149 *
150 * function Projects() {
151 * // `data` is never `undefined`, thanks to `initialData` β€” even if a refetch fails, so the
152 * // list stays visible alongside the error.
153 * const { data, isError, error } = useInfiniteQuery(projectsOptions)
154 *
155 * return (
156 * <div>
157 * {isError ? <span>Error: {error.message}</span> : null}
158 * <ul>
159 * {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
160 * </ul>
161 * </div>
162 * )
163 * }
164 * ```
165 */
166export function infiniteQueryOptions<
167 TQueryFnData,
168 TError = DefaultError,
169 TData = InfiniteData<TQueryFnData>,
170 TQueryKey extends QueryKey = QueryKey,
171 TPageParam = unknown,
172>(
173 options: DefinedInitialDataInfiniteOptions<
174 TQueryFnData,
175 TError,
176 TData,
177 TQueryKey,
178 TPageParam
179 >,
180): DefinedInitialDataInfiniteOptions<
181 TQueryFnData,
182 TError,
183 TData,
184 TQueryKey,
185 TPageParam
186> &
187 QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
188​
189/**
190 * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
191 * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
192 * `options.queryKey` is required and is the query key to generate options for.
193 * @param options - The {@link UnusedSkipTokenInfiniteOptions} to use β€” everything you can pass to `useInfiniteQuery`.
194 * @returns The same options object, typed so that `queryKey` carries the inferred data type.
195 * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
196 * automatically as the user scrolls.
197 * @see {@link useInfiniteQuery} to run an infinite query with these options.
198 * @example
199 * A parameterized factory, so the same options object can be reused per `postId`:
200 * ```tsx
201 * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-query'
202 *
203 * export const commentsOptions = (postId: string) =>
204 * infiniteQueryOptions({
205 * queryKey: ['post', postId, 'comments'],
206 * queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
207 * initialPageParam: 0,
208 * getNextPageParam: (lastPage) => lastPage.nextId,
209 * })
210 *
211 * function Comments({ postId }: { postId: string }) {
212 * const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
213 *
214 * if (isPending) return 'Loading...'
215 * if (isError) return <span>Error: {error.message}</span>
216 *
217 * return (
218 * <ul>
219 * {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
220 * </ul>
221 * )
222 * }
223 * ```
224 */
225export function infiniteQueryOptions<
226 TQueryFnData,
227 TError = DefaultError,
228 TData = InfiniteData<TQueryFnData>,
229 TQueryKey extends QueryKey = QueryKey,
230 TPageParam = unknown,
231>(
232 options: UnusedSkipTokenInfiniteOptions<
233 TQueryFnData,
234 TError,
235 TData,
236 TQueryKey,
237 TPageParam
238 >,
239): UnusedSkipTokenInfiniteOptions<
240 TQueryFnData,
241 TError,
242 TData,
243 TQueryKey,
244 TPageParam
245> &
246 QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
247​
248/**
249 * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
250 * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
251 * `options.queryKey` is required and is the query key to generate options for.
252 * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use β€” everything you can pass to `useInfiniteQuery`.
253 * @returns The same options object, typed so that `queryKey` carries the inferred data type.
254 * @remarks See {@link useInfiniteQuery} for examples that fetch further pages (from a button click or
255 * automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set.
256 * @see {@link useInfiniteQuery} to run an infinite query with these options.
257 * @example
258 * A parameterized factory, so the same options object can be reused per `postId`:
259 * ```tsx
260 * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-query'
261 *
262 * export const commentsOptions = (postId: string) =>
263 * infiniteQueryOptions({
264 * queryKey: ['post', postId, 'comments'],
265 * queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
266 * initialPageParam: 0,
267 * getNextPageParam: (lastPage) => lastPage.nextId,
268 * })
269 *
270 * function Comments({ postId }: { postId: string }) {
271 * const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
272 *
273 * if (isPending) return 'Loading...'
274 * if (isError) return <span>Error: {error.message}</span>
275 *
276 * return (
277 * <ul>
278 * {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
279 * </ul>
280 * )
281 * }
282 * ```
283 */
284export function infiniteQueryOptions<
285 TQueryFnData,
286 TError = DefaultError,
287 TData = InfiniteData<TQueryFnData>,
288 TQueryKey extends QueryKey = QueryKey,
289 TPageParam = unknown,
290>(
291 options: UndefinedInitialDataInfiniteOptions<
292 TQueryFnData,
293 TError,
294 TData,
295 TQueryKey,
296 TPageParam
297 >,
298): UndefinedInitialDataInfiniteOptions<
299 TQueryFnData,
300 TError,
301 TData,
302 TQueryKey,
303 TPageParam
304> &
305 QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
306​
307export function infiniteQueryOptions(options: unknown) {
308 return options