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

types.ts

486 lines18.2 KB

1/* istanbul ignore file */
2​
3import type {
4 DefaultError,
5 DefinedInfiniteQueryObserverResult,
6 DefinedQueryObserverResult,
7 DistributiveOmit,
8 InfiniteData,
9 InfiniteQueryExecuteOptions,
10 InfiniteQueryObserverOptions,
11 InfiniteQueryObserverResult,
12 MutateFunction,
13 MutationObserverOptions,
14 MutationObserverResult,
15 OmitKeyof,
16 Override,
17 QueryExecuteOptions,
18 QueryKey,
19 QueryObserverOptions,
20 QueryObserverResult,
21 SkipToken,
22} from '@tanstack/query-core'
23​
24/**
25 * {@link UseBaseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
26 * relevant, e.g. when accepting options for any query in a helper function.
27 */
28export type AnyUseBaseQueryOptions = UseBaseQueryOptions<
29 any,
30 any,
31 any,
32 any,
33 any
35/**
36 * The options shared by `useQuery` and `useSuspenseQuery`. Extends {@link QueryObserverOptions} from
37 * `@tanstack/query-core` with the `react-query`-specific `subscribed` option.
38 * @template TQueryFnData - The type your `queryFn` resolves to.
39 * @template TError - The type of errors your `queryFn` may throw.
40 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
41 * `select` is used.
42 * @template TQueryData - The type of the data actually held in the query cache β€” the input to `select` and
43 * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
44 * @template TQueryKey - The type of your `queryKey`.
45 */
46export interface UseBaseQueryOptions<
47 TQueryFnData = unknown,
48 TError = DefaultError,
49 TData = TQueryFnData,
50 TQueryData = TQueryFnData,
51 TQueryKey extends QueryKey = QueryKey,
52> extends QueryObserverOptions<
53 TQueryFnData,
54 TError,
55 TData,
56 TQueryData,
57 TQueryKey
58> {
59 /**
60 * Set this to `false` to unsubscribe this observer from updates to the query cache.
61 * @defaultValue true
62 */
63 subscribed?: boolean
65​
66/**
67 * The options accepted by `usePrefetchQuery` β€” everything you can pass to `queryClient.query`, except `queryFn`
68 * is required unless a default query function has been defined.
69 * @template TQueryFnData - The type your `queryFn` resolves to.
70 * @template TError - The type of errors your `queryFn` may throw.
71 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
72 * `select` is used.
73 * @template TQueryData - The type of the data actually held in the query cache β€” the input to `select` and
74 * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
75 * @template TQueryKey - The type of your `queryKey`.
76 */
77export type UsePrefetchQueryOptions<
78 TQueryFnData = unknown,
79 TError = DefaultError,
80 TData = TQueryFnData,
81 TQueryData = TQueryFnData,
82 TQueryKey extends QueryKey = QueryKey,
83> = DistributiveOmit<
84 QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
85 'queryFn'
86> & {
87 /**
88 * `skipToken` is not allowed as a value here β€” a prefetch always needs a query function to actually run,
89 * unless a default query function has been defined.
90 */
91 queryFn?: Exclude<
92 QueryExecuteOptions<
93 TQueryFnData,
94 TError,
95 TData,
96 TQueryData,
97 TQueryKey
98 >['queryFn'],
99 SkipToken
100 >
102​
103/**
104 * The options accepted by `usePrefetchInfiniteQuery` β€” everything you can pass to `queryClient.infiniteQuery`,
105 * except `queryFn` is required unless a default query function has been defined.
106 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
107 * @template TError - The type of errors your `queryFn` may throw.
108 * @template TData - The type `data` ends up as after `select` runs. Defaults to `InfiniteData<TQueryFnData>`,
109 * the shape of all fetched pages plus their page params β€” a prefetch never reads `data` back out, so this
110 * parameter only matters if you reuse these options elsewhere with `select` applied.
111 * @template TQueryKey - The type of your `queryKey`.
112 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
113 */
114export type UsePrefetchInfiniteQueryOptions<
115 TQueryFnData = unknown,
116 TError = DefaultError,
117 TData = InfiniteData<TQueryFnData>,
118 TQueryKey extends QueryKey = QueryKey,
119 TPageParam = unknown,
120> = DistributiveOmit<
121 InfiniteQueryExecuteOptions<
122 TQueryFnData,
123 TError,
124 TData,
125 TQueryKey,
126 TPageParam
127 >,
128 'queryFn'
129> & {
130 /**
131 * `skipToken` is not allowed as a value here β€” a prefetch always needs a query function to actually run,
132 * unless a default query function has been defined.
133 */
134 queryFn?: Exclude<
135 InfiniteQueryExecuteOptions<
136 TQueryFnData,
137 TError,
138 TData,
139 TQueryKey,
140 TPageParam
141 >['queryFn'],
142 SkipToken
143 >
145​
146/**
147 * {@link UseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
148 * relevant, e.g. when accepting options for any query in a helper function.
149 */
150export type AnyUseQueryOptions = UseQueryOptions<any, any, any, any>
151/**
152 * The options accepted by `useQuery`. Same as {@link UseBaseQueryOptions}, minus `suspense` (which
153 * `react-query` derives from which hook you call rather than exposing as an option).
154 * @template TQueryFnData - The type your `queryFn` resolves to.
155 * @template TError - The type of errors your `queryFn` may throw.
156 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
157 * `select` is used.
158 * @template TQueryKey - The type of your `queryKey`.
159 */
160export interface UseQueryOptions<
161 TQueryFnData = unknown,
162 TError = DefaultError,
163 TData = TQueryFnData,
164 TQueryKey extends QueryKey = QueryKey,
165> extends OmitKeyof<
166 UseBaseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
167 'suspense'
168> {}
169​
170/**
171 * {@link UseSuspenseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
172 * relevant, e.g. when accepting options for any query in a helper function.
173 */
174export type AnyUseSuspenseQueryOptions = UseSuspenseQueryOptions<
175 any,
176 any,
177 any,
178 any
180/**
181 * The options accepted by `useSuspenseQuery`. Same as {@link UseQueryOptions}, minus `enabled`, `throwOnError`,
182 * and `placeholderData` β€” Suspense hooks cannot render a "disabled" or "placeholder" state, so those options
183 * don't apply.
184 * @template TQueryFnData - The type your `queryFn` resolves to.
185 * @template TError - The type of errors your `queryFn` may throw.
186 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
187 * `select` is used.
188 * @template TQueryKey - The type of your `queryKey`.
189 */
190export interface UseSuspenseQueryOptions<
191 TQueryFnData = unknown,
192 TError = DefaultError,
193 TData = TQueryFnData,
194 TQueryKey extends QueryKey = QueryKey,
195> extends OmitKeyof<
196 UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
197 'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
198> {
199 /**
200 * `skipToken` is not allowed here β€” Suspense hooks cannot render a "disabled" state, so a query function
201 * must always be provided, unless a default query function has been defined.
202 */
203 queryFn?: Exclude<
204 UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
205 SkipToken
206 >
208​
209/**
210 * {@link UseInfiniteQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
211 * relevant, e.g. when accepting options for any query in a helper function.
212 */
213export type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<
214 any,
215 any,
216 any,
217 any,
218 any
220/**
221 * The options accepted by `useInfiniteQuery`. Extends {@link InfiniteQueryObserverOptions} from
222 * `@tanstack/query-core` with the `react-query`-specific `subscribed` option, minus `suspense` (which
223 * `react-query` derives from which hook you call rather than exposing as an option).
224 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
225 * @template TError - The type of errors your `queryFn` may throw.
226 * @template TData - The type `data` ends up as after `select` runs β€” defaults to `InfiniteData<TQueryFnData>`,
227 * the shape of all fetched pages plus their page params.
228 * @template TQueryKey - The type of your `queryKey`.
229 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
230 */
231export interface UseInfiniteQueryOptions<
232 TQueryFnData = unknown,
233 TError = DefaultError,
234 TData = InfiniteData<TQueryFnData>,
235 TQueryKey extends QueryKey = QueryKey,
236 TPageParam = unknown,
237> extends OmitKeyof<
238 InfiniteQueryObserverOptions<
239 TQueryFnData,
240 TError,
241 TData,
242 TQueryKey,
243 TPageParam
244 >,
245 'suspense'
246> {
247 /**
248 * Set this to `false` to unsubscribe this observer from updates to the query cache.
249 * @defaultValue true
250 */
251 subscribed?: boolean
253​
254/**
255 * {@link UseSuspenseInfiniteQueryOptions} with all type parameters set to `any`, useful when the specific types
256 * aren't relevant, e.g. when accepting options for any query in a helper function.
257 */
258export type AnyUseSuspenseInfiniteQueryOptions =
259 UseSuspenseInfiniteQueryOptions<any, any, any, any, any>
260/**
261 * The options accepted by `useSuspenseInfiniteQuery`. Same as {@link UseInfiniteQueryOptions}, minus `enabled`,
262 * `throwOnError`, and `placeholderData` β€” Suspense hooks cannot render a "disabled" or "placeholder" state, so
263 * those options don't apply.
264 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
265 * @template TError - The type of errors your `queryFn` may throw.
266 * @template TData - The type `data` ends up as after `select` runs β€” defaults to `InfiniteData<TQueryFnData>`,
267 * the shape of all fetched pages plus their page params.
268 * @template TQueryKey - The type of your `queryKey`.
269 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
270 */
271export interface UseSuspenseInfiniteQueryOptions<
272 TQueryFnData = unknown,
273 TError = DefaultError,
274 TData = InfiniteData<TQueryFnData>,
275 TQueryKey extends QueryKey = QueryKey,
276 TPageParam = unknown,
277> extends OmitKeyof<
278 UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
279 'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
280> {
281 /**
282 * `skipToken` is not allowed here β€” Suspense hooks cannot render a "disabled" state, so a query function
283 * must always be provided, unless a default query function has been defined.
284 */
285 queryFn?: Exclude<
286 UseInfiniteQueryOptions<
287 TQueryFnData,
288 TError,
289 TData,
290 TQueryKey,
291 TPageParam
292 >['queryFn'],
293 SkipToken
294 >
296​
297/**
298 * The result of `useQuery` when `initialData` isn't set β€” `data` may be `undefined` while the query is
299 * `pending`. Re-exports {@link QueryObserverResult} from `@tanstack/query-core`. `useInfiniteQuery` returns
300 * {@link UseInfiniteQueryResult} instead.
301 * @template TData - The type `data` ends up as after `select` runs.
302 * @template TError - The type of errors your `queryFn` may throw.
303 */
304export type UseBaseQueryResult<
305 TData = unknown,
306 TError = DefaultError,
307> = QueryObserverResult<TData, TError>
308​
309/**
310 * The result of `useQuery`. Same as {@link UseBaseQueryResult}.
311 * @template TData - The type `data` ends up as after `select` runs.
312 * @template TError - The type of errors your `queryFn` may throw.
313 */
314export type UseQueryResult<
315 TData = unknown,
316 TError = DefaultError,
317> = UseBaseQueryResult<TData, TError>
318​
319/**
320 * The result of `useSuspenseQuery`. Same as {@link DefinedUseQueryResult}, minus `isPlaceholderData` β€” always
321 * `false` on that type, so this drops the dead field rather than an active state.
322 * @template TData - The type `data` ends up as after `select` runs.
323 * @template TError - The type of errors your `queryFn` may throw.
324 */
325export type UseSuspenseQueryResult<
326 TData = unknown,
327 TError = DefaultError,
328> = DistributiveOmit<
329 DefinedQueryObserverResult<TData, TError>,
330 'isPlaceholderData'
332​
333/**
334 * The result of `useQuery` when `initialData` is set, or of `useSuspenseQuery` before the `isPlaceholderData`
335 * omission β€” `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`).
336 * Re-exports {@link DefinedQueryObserverResult} from `@tanstack/query-core`.
337 * @template TData - The type `data` ends up as after `select` runs.
338 * @template TError - The type of errors your `queryFn` may throw.
339 */
340export type DefinedUseQueryResult<
341 TData = unknown,
342 TError = DefaultError,
343> = DefinedQueryObserverResult<TData, TError>
344​
345/**
346 * The result of `useInfiniteQuery` when `initialData` isn't set β€” `data` may be `undefined` while the query is
347 * `pending`. Re-exports {@link InfiniteQueryObserverResult} from `@tanstack/query-core`.
348 * @template TData - The type `data` ends up as after `select` runs.
349 * @template TError - The type of errors your `queryFn` may throw.
350 */
351export type UseInfiniteQueryResult<
352 TData = unknown,
353 TError = DefaultError,
354> = InfiniteQueryObserverResult<TData, TError>
355​
356/**
357 * The result of `useInfiniteQuery` when `initialData` is set β€” `data` is never `undefined` (unless a
358 * `select` changes `TData` to include `undefined`). Re-exports {@link DefinedInfiniteQueryObserverResult}
359 * from `@tanstack/query-core`.
360 * @template TData - The type `data` ends up as after `select` runs.
361 * @template TError - The type of errors your `queryFn` may throw.
362 */
363export type DefinedUseInfiniteQueryResult<
364 TData = unknown,
365 TError = DefaultError,
366> = DefinedInfiniteQueryObserverResult<TData, TError>
367​
368/**
369 * The result of `useSuspenseInfiniteQuery`. Same as {@link DefinedUseInfiniteQueryResult}, minus
370 * `isPlaceholderData` β€” Suspense hooks never render placeholder data.
371 * @template TData - The type `data` ends up as after `select` runs.
372 * @template TError - The type of errors your `queryFn` may throw.
373 */
374export type UseSuspenseInfiniteQueryResult<
375 TData = unknown,
376 TError = DefaultError,
377> = OmitKeyof<
378 DefinedInfiniteQueryObserverResult<TData, TError>,
379 'isPlaceholderData'
381​
382/**
383 * {@link UseMutationOptions} with all type parameters set to `any`, useful when the specific types aren't
384 * relevant, e.g. when accepting options for any mutation in a helper function.
385 */
386export type AnyUseMutationOptions = UseMutationOptions<any, any, any, any>
387/**
388 * The options accepted by `useMutation`. Same as {@link MutationObserverOptions} from `@tanstack/query-core`,
389 * minus the internal `_defaulted` flag.
390 * @template TData - The type your mutation function resolves to.
391 * @template TError - The type of errors your mutation function may throw.
392 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
393 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
394 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
395 */
396export interface UseMutationOptions<
397 TData = unknown,
398 TError = DefaultError,
399 TVariables = void,
400 TOnMutateResult = unknown,
401> extends OmitKeyof<
402 MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>,
403 '_defaulted'
404> {}
405​
406/**
407 * The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call
408 * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget β€” errors are surfaced
409 * through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation`
410 * rethrow them.
411 * @template TData - The type your mutation function resolves to.
412 * @template TError - The type of errors your mutation function may throw.
413 * @template TVariables - The type of the variable passed to `mutate`.
414 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
415 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
416 */
417export type UseMutateFunction<
418 TData = unknown,
419 TError = DefaultError,
420 TVariables = void,
421 TOnMutateResult = unknown,
422> = (
423 ...args: Parameters<
424 MutateFunction<TData, TError, TVariables, TOnMutateResult>
425 >
426) => void
427​
428/**
429 * The type of `mutateAsync`, as returned by `useMutation`. Similar to {@link UseMutateFunction}, but returns a
430 * promise which can be awaited.
431 * @template TData - The type your mutation function resolves to.
432 * @template TError - The type of errors your mutation function may throw.
433 * @template TVariables - The type of the variable passed to `mutateAsync`.
434 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
435 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
436 */
437export type UseMutateAsyncFunction<
438 TData = unknown,
439 TError = DefaultError,
440 TVariables = void,
441 TOnMutateResult = unknown,
442> = MutateFunction<TData, TError, TVariables, TOnMutateResult>
443​
444/**
445 * The result of `useMutation`. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with
446 * `mutate` narrowed to the fire-and-forget {@link UseMutateFunction} signature, plus the added `mutateAsync`.
447 * @template TData - The type your mutation function resolves to.
448 * @template TError - The type of errors your mutation function may throw.
449 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
450 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
451 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
452 */
453export type UseBaseMutationResult<
454 TData = unknown,
455 TError = DefaultError,
456 TVariables = unknown,
457 TOnMutateResult = unknown,
458> = Override<
459 MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
460 { mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult> }
461> & {
462 /**
463 * Similar to `mutate`, but returns a promise which can be awaited.
464 */
465 mutateAsync: UseMutateAsyncFunction<
466 TData,
467 TError,
468 TVariables,
469 TOnMutateResult
470 >
472​
473/**
474 * The result of `useMutation`. Same as {@link UseBaseMutationResult}.
475 * @template TData - The type your mutation function resolves to.
476 * @template TError - The type of errors your mutation function may throw.
477 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
478 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
479 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
480 */
481export type UseMutationResult<
482 TData = unknown,
483 TError = DefaultError,
484 TVariables = unknown,
485 TOnMutateResult = unknown,
486> = UseBaseMutationResult<TData, TError, TVariables, TOnMutateResult>