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

types.ts

569 lines19.9 KB

1/* istanbul ignore file */
2​
3import type { Signal } from '@angular/core'
4import type {
5 DefaultError,
6 DefinedInfiniteQueryObserverResult,
7 DefinedQueryObserverResult,
8 InfiniteQueryObserverOptions,
9 InfiniteQueryObserverResult,
10 MutateFunction,
11 MutationObserverOptions,
12 MutationObserverResult,
13 OmitKeyof,
14 Override,
15 QueryKey,
16 QueryObserverOptions,
17 QueryObserverResult,
18} from '@tanstack/query-core'
19import type {
20 InfiniteQueryResultFields,
21 MutationResultFields,
22 QueryResultFields,
23} from './utils/result-fields'
24import type { MapToSignals } from './utils/signal-proxy'
25​
26type SignalFunction<T extends () => any> = T & Signal<ReturnType<T>>
27​
28/**
29 * The options accepted by `injectQuery`, with cache data projected through an optional `select`. Same as
30 * {@link QueryObserverOptions} from `@tanstack/query-core`, minus `notifyOnChangeProps`, `suspense`, and
31 * `throwOnError`: Angular owns result notifications and exposes errors through signals rather than error
32 * boundaries.
33 * @template TQueryFnData - The type your `queryFn` resolves to.
34 * @template TError - The type of errors your `queryFn` may throw.
35 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
36 * `select` is used.
37 * @template TQueryKey - The type of your `queryKey`.
38 */
39export type CreateQueryOptions<
40 TQueryFnData = unknown,
41 TError = DefaultError,
42 TData = TQueryFnData,
43 TQueryKey extends QueryKey = QueryKey,
44> = OmitKeyof<
45 QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
46 'notifyOnChangeProps' | 'suspense' | 'throwOnError'
48​
49type CreateStatusBasedQueryResult<
50 TStatus extends QueryObserverResult['status'],
51 TData = unknown,
52 TError = DefaultError,
53> = Extract<QueryObserverResult<TData, TError>, { status: TStatus }>
54​
55type CreateStatusBasedDefinedQueryResult<
56 TStatus extends DefinedQueryObserverResult['status'],
57 TData = unknown,
58 TError = DefaultError,
59> = Extract<DefinedQueryObserverResult<TData, TError>, { status: TStatus }>
60​
61type CreateStatusBasedInfiniteQueryResult<
62 TStatus extends InfiniteQueryObserverResult['status'],
63 TData = unknown,
64 TError = DefaultError,
65> = Extract<InfiniteQueryObserverResult<TData, TError>, { status: TStatus }>
66​
67type CreateStatusBasedDefinedInfiniteQueryResult<
68 TStatus extends DefinedInfiniteQueryObserverResult['status'],
69 TData = unknown,
70 TError = DefaultError,
71> = Extract<
72 DefinedInfiniteQueryObserverResult<TData, TError>,
73 { status: TStatus }
75​
76/**
77 * Signal-backed guards that narrow a query result and its data and error fields by status: the
78 * `isSuccess`/`isError`/`isPending` methods on a query result. Unlike `react-query`'s derived booleans, each
79 * is a `Signal` you call to read its current boolean value reactively, and the call is also a type guard β€”
80 * `if (query.isSuccess())` β€” so that `query.data` narrows away `undefined` inside the branch, the same way
81 * `status` narrowing works on the plain object `react-query` returns.
82 * @template TData - The type `data` ends up as after `select` runs.
83 * @template TError - The type of errors your `queryFn` may throw.
84 */
85export interface BaseQueryNarrowing<TData = unknown, TError = DefaultError> {
86 /**
87 * Returns whether the result is successful and narrows its data and error signals.
88 */
89 isSuccess: SignalFunction<
90 () => this is CreateBaseQueryResult<
91 TData,
92 TError,
93 CreateStatusBasedQueryResult<'success', TData, TError>
94 >
95 >
96 /**
97 * Returns whether the result failed and narrows its data and error signals.
98 */
99 isError: SignalFunction<
100 () => this is CreateBaseQueryResult<
101 TData,
102 TError,
103 CreateStatusBasedQueryResult<'error', TData, TError>
104 >
105 >
106 /**
107 * Narrows the result to the pending state when that state is possible.
108 */
109 isPending: SignalFunction<
110 () => this is CreateBaseQueryResult<
111 TData,
112 TError,
113 CreateStatusBasedQueryResult<'pending', TData, TError>
114 >
115 >
117​
118/**
119 * Signal-backed guards for a query whose initial data excludes the pending state.
120 */
121export interface DefinedQueryNarrowing<TData = unknown, TError = DefaultError> {
122 /**
123 * Returns whether the result is successful and narrows its data and error signals.
124 */
125 isSuccess: SignalFunction<
126 () => this is DefinedCreateQueryResult<
127 TData,
128 TError,
129 CreateStatusBasedDefinedQueryResult<'success', TData, TError>
130 >
131 >
132 /**
133 * Returns whether the result failed and narrows its data and error signals.
134 */
135 isError: SignalFunction<
136 () => this is DefinedCreateQueryResult<
137 TData,
138 TError,
139 CreateStatusBasedDefinedQueryResult<'error', TData, TError>
140 >
141 >
142 /**
143 * Narrows the result to the pending state when that state is possible.
144 */
145 isPending: SignalFunction<() => this is never>
147​
148/**
149 * Signal-backed guards that narrow a paginated query result by its current status.
150 */
151export interface BaseInfiniteQueryNarrowing<
152 TData = unknown,
153 TError = DefaultError,
154> {
155 /**
156 * Returns whether the result is successful and narrows its data and error signals.
157 */
158 isSuccess: SignalFunction<
159 (
160 this: CreateInfiniteQueryResult<TData, TError>,
161 ) => this is CreateInfiniteQueryResult<
162 TData,
163 TError,
164 CreateStatusBasedInfiniteQueryResult<'success', TData, TError>
165 >
166 >
167 /**
168 * Returns whether the result failed and narrows its data and error signals.
169 */
170 isError: SignalFunction<
171 (
172 this: CreateInfiniteQueryResult<TData, TError>,
173 ) => this is CreateInfiniteQueryResult<
174 TData,
175 TError,
176 CreateStatusBasedInfiniteQueryResult<'error', TData, TError>
177 >
178 >
179 /**
180 * Narrows the result to the pending state when that state is possible.
181 */
182 isPending: SignalFunction<
183 (
184 this: CreateInfiniteQueryResult<TData, TError>,
185 ) => this is CreateInfiniteQueryResult<
186 TData,
187 TError,
188 CreateStatusBasedInfiniteQueryResult<'pending', TData, TError>
189 >
190 >
192​
193/**
194 * Signal-backed guards for a paginated query whose initial data excludes the pending state.
195 */
196export interface DefinedInfiniteQueryNarrowing<
197 TData = unknown,
198 TError = DefaultError,
199> {
200 /**
201 * Returns whether the result is successful and narrows its data and error signals.
202 */
203 isSuccess: SignalFunction<
204 (
205 this: DefinedCreateInfiniteQueryResult<TData, TError>,
206 ) => this is DefinedCreateInfiniteQueryResult<
207 TData,
208 TError,
209 CreateStatusBasedDefinedInfiniteQueryResult<'success', TData, TError>
210 >
211 >
212 /**
213 * Returns whether the result failed and narrows its data and error signals.
214 */
215 isError: SignalFunction<
216 (
217 this: DefinedCreateInfiniteQueryResult<TData, TError>,
218 ) => this is DefinedCreateInfiniteQueryResult<
219 TData,
220 TError,
221 CreateStatusBasedDefinedInfiniteQueryResult<'error', TData, TError>
222 >
223 >
224 /**
225 * Narrows the result to the pending state when that state is possible.
226 */
227 isPending: SignalFunction<
228 (this: DefinedCreateInfiniteQueryResult<TData, TError>) => this is never
229 >
231​
232/**
233 * The options accepted by `injectInfiniteQuery`, including page parameters and pagination callbacks. Same as
234 * {@link InfiniteQueryObserverOptions} from `@tanstack/query-core` β€” for the infinite-query-specific options
235 * (`getNextPageParam`, `initialPageParam`, etc.) β€” minus `notifyOnChangeProps`, `suspense`, and
236 * `throwOnError`, like {@link CreateQueryOptions}.
237 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
238 * @template TError - The type of errors your `queryFn` may throw.
239 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` here, though
240 * `injectInfiniteQuery` itself defaults it to `InfiniteData<TQueryFnData>` β€” the shape `data` actually has
241 * when no `select` is used.
242 * @template TQueryKey - The type of your `queryKey`.
243 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
244 */
245export interface CreateInfiniteQueryOptions<
246 TQueryFnData = unknown,
247 TError = DefaultError,
248 TData = TQueryFnData,
249 TQueryKey extends QueryKey = QueryKey,
250 TPageParam = unknown,
251> extends OmitKeyof<
252 InfiniteQueryObserverOptions<
253 TQueryFnData,
254 TError,
255 TData,
256 TQueryKey,
257 TPageParam
258 >,
259 'notifyOnChangeProps' | 'suspense' | 'throwOnError'
260> {}
261​
262/**
263 * The result of `injectQuery` when `initialData` isn't set β€” `data` may be `undefined` while the query is
264 * `pending`. Same shape as {@link QueryObserverResult} from `@tanstack/query-core`, but value fields (like
265 * `data`, `error`, `status`) are exposed as a `Signal` β€” read them with `query.data()`, not `query.data` β€”
266 * while function fields (like `refetch`) are called directly, unchanged. `isSuccess`/`isError`/`isPending`
267 * are {@link BaseQueryNarrowing} type-guard methods rather than plain booleans.
268 * `injectInfiniteQuery` returns {@link CreateInfiniteQueryResult} instead.
269 * @template TData - The type `data` ends up as after `select` runs.
270 * @template TError - The type of errors your `queryFn` may throw.
271 */
272export type CreateBaseQueryResult<
273 TData = unknown,
274 TError = DefaultError,
275 TState extends QueryObserverResult<TData, TError> = QueryObserverResult<
276 TData,
277 TError
278 >,
279> = BaseQueryNarrowing<TData, TError> &
280 MapToSignals<
281 OmitKeyof<TState, keyof BaseQueryNarrowing, 'safely'>,
282 QueryResultFields
283 >
284​
285/**
286 * The result of `injectQuery`. Same as {@link CreateBaseQueryResult}.
287 * @template TData - The type `data` ends up as after `select` runs.
288 * @template TError - The type of errors your `queryFn` may throw.
289 */
290export type CreateQueryResult<
291 TData = unknown,
292 TError = DefaultError,
293> = CreateBaseQueryResult<TData, TError>
294​
295/**
296 * The result of `injectQuery` when `initialData` is set β€” `data` is never `undefined`. Same shape as
297 * {@link DefinedQueryObserverResult} from `@tanstack/query-core`, but value fields are exposed as a
298 * `Signal` while function fields are called directly, unchanged.
299 * @template TData - The type `data` ends up as after `select` runs.
300 * @template TError - The type of errors your `queryFn` may throw.
301 */
302export type DefinedCreateQueryResult<
303 TData = unknown,
304 TError = DefaultError,
305 TState extends DefinedQueryObserverResult<TData, TError> =
306 DefinedQueryObserverResult<TData, TError>,
307> = DefinedQueryNarrowing<TData, TError> &
308 MapToSignals<
309 OmitKeyof<TState, keyof DefinedQueryNarrowing, 'safely'>,
310 QueryResultFields
311 >
312​
313/**
314 * The result of `injectInfiniteQuery` when `initialData` isn't set β€” `data` may be `undefined` while the
315 * query is `pending`. Same shape as {@link InfiniteQueryObserverResult} from `@tanstack/query-core`, but
316 * value fields are exposed as a `Signal` while function fields (like `fetchNextPage`) are called directly,
317 * unchanged.
318 * @template TData - The type `data` ends up as after `select` runs.
319 * @template TError - The type of errors your `queryFn` may throw.
320 */
321export type CreateInfiniteQueryResult<
322 TData = unknown,
323 TError = DefaultError,
324 TState extends InfiniteQueryObserverResult<TData, TError> =
325 InfiniteQueryObserverResult<TData, TError>,
326> = BaseInfiniteQueryNarrowing<TData, TError> &
327 MapToSignals<TState, InfiniteQueryResultFields>
328​
329/**
330 * The result of `injectInfiniteQuery` when `initialData` is set β€” `data` is never `undefined`. Same shape as
331 * {@link DefinedInfiniteQueryObserverResult} from `@tanstack/query-core`, but value fields are exposed as a
332 * `Signal` while function fields are called directly, unchanged.
333 * @template TData - The type `data` ends up as after `select` runs.
334 * @template TError - The type of errors your `queryFn` may throw.
335 */
336export type DefinedCreateInfiniteQueryResult<
337 TData = unknown,
338 TError = DefaultError,
339 TDefinedInfiniteQueryObserver extends DefinedInfiniteQueryObserverResult<
340 TData,
341 TError
342 > = DefinedInfiniteQueryObserverResult<TData, TError>,
343> = DefinedInfiniteQueryNarrowing<TData, TError> &
344 MapToSignals<TDefinedInfiniteQueryObserver, InfiniteQueryResultFields>
345​
346/**
347 * The options accepted by `injectMutation`. Same as {@link MutationObserverOptions} from
348 * `@tanstack/query-core`, minus the internal `_defaulted` flag.
349 * @template TData - The type your mutation function resolves to.
350 * @template TError - The type of errors your mutation function may throw.
351 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
352 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
353 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
354 */
355export interface CreateMutationOptions<
356 TData = unknown,
357 TError = DefaultError,
358 TVariables = void,
359 TOnMutateResult = unknown,
360> extends OmitKeyof<
361 MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>,
362 '_defaulted' | 'throwOnError'
363> {}
364​
365/**
366 * The type of `mutate`, as returned by `injectMutation`. Forwards the variables (and an optional per-call
367 * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget β€” errors are surfaced
368 * through the mutation result, not thrown.
369 * @template TData - The type your mutation function resolves to.
370 * @template TError - The type of errors your mutation function may throw.
371 * @template TVariables - The type of the variable passed to `mutate`.
372 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
373 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
374 */
375export type CreateMutateFunction<
376 TData = unknown,
377 TError = DefaultError,
378 TVariables = void,
379 TOnMutateResult = unknown,
380> = (
381 ...args: Parameters<
382 MutateFunction<TData, TError, TVariables, TOnMutateResult>
383 >
384) => void
385​
386/**
387 * The type of `mutateAsync`, as returned by `injectMutation`. Similar to {@link CreateMutateFunction}, but
388 * returns a promise which can be awaited.
389 * @template TData - The type your mutation function resolves to.
390 * @template TError - The type of errors your mutation function may throw.
391 * @template TVariables - The type of the variable passed to `mutateAsync`.
392 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
393 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
394 */
395export type CreateMutateAsyncFunction<
396 TData = unknown,
397 TError = DefaultError,
398 TVariables = void,
399 TOnMutateResult = unknown,
400> = MutateFunction<TData, TError, TVariables, TOnMutateResult>
401​
402/**
403 * The pre-`Signal` shape {@link CreateMutationResult} is built from β€” not what `injectMutation` actually
404 * returns. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with `mutate` narrowed to the
405 * fire-and-forget {@link CreateMutateFunction} signature, plus the added `mutateAsync`.
406 * @template TData - The type your mutation function resolves to.
407 * @template TError - The type of errors your mutation function may throw.
408 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
409 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
410 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
411 */
412export type CreateBaseMutationResult<
413 TData = unknown,
414 TError = DefaultError,
415 TVariables = unknown,
416 TOnMutateResult = unknown,
417> = Override<
418 MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
419 { mutate: CreateMutateFunction<TData, TError, TVariables, TOnMutateResult> }
420> & {
421 /**
422 * Similar to `mutate`, but returns a promise which can be awaited.
423 */
424 mutateAsync: CreateMutateAsyncFunction<
425 TData,
426 TError,
427 TVariables,
428 TOnMutateResult
429 >
431​
432type CreateStatusBasedMutationResult<
433 TStatus extends CreateBaseMutationResult['status'],
434 TData = unknown,
435 TError = DefaultError,
436 TVariables = unknown,
437 TOnMutateResult = unknown,
438> = Extract<
439 CreateBaseMutationResult<TData, TError, TVariables, TOnMutateResult>,
440 { status: TStatus }
442​
443/**
444 * Signal-backed guards that narrow mutation data, errors, and variables by the current status: the
445 * `isSuccess`/`isError`/`isPending`/`isIdle` methods on a mutation result. Each is a `Signal` you call to
446 * read its current boolean value reactively, and the call is also a type guard β€” `if (mutation.isSuccess())`
447 * β€” so that `mutation.data` narrows away `undefined` inside the branch.
448 * @template TData - The type your mutation function resolves to.
449 * @template TError - The type of errors your mutation function may throw.
450 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
451 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
452 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
453 */
454export interface BaseMutationNarrowing<
455 TData = unknown,
456 TError = DefaultError,
457 TVariables = unknown,
458 TOnMutateResult = unknown,
459> {
460 /**
461 * Whether the mutation is in the `success` state. Calling it narrows the result to that state.
462 */
463 isSuccess: SignalFunction<
464 (
465 this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>,
466 ) => this is CreateMutationResult<
467 TData,
468 TError,
469 TVariables,
470 TOnMutateResult,
471 CreateStatusBasedMutationResult<
472 'success',
473 TData,
474 TError,
475 TVariables,
476 TOnMutateResult
477 >
478 >
479 >
480 /**
481 * Whether the mutation is in the `error` state. Calling it narrows the result to that state.
482 */
483 isError: SignalFunction<
484 (
485 this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>,
486 ) => this is CreateMutationResult<
487 TData,
488 TError,
489 TVariables,
490 TOnMutateResult,
491 CreateStatusBasedMutationResult<
492 'error',
493 TData,
494 TError,
495 TVariables,
496 TOnMutateResult
497 >
498 >
499 >
500 /**
501 * Whether the mutation is in the `pending` state. Calling it narrows the result to that state.
502 */
503 isPending: SignalFunction<
504 (
505 this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>,
506 ) => this is CreateMutationResult<
507 TData,
508 TError,
509 TVariables,
510 TOnMutateResult,
511 CreateStatusBasedMutationResult<
512 'pending',
513 TData,
514 TError,
515 TVariables,
516 TOnMutateResult
517 >
518 >
519 >
520 /**
521 * Whether the mutation is in the `idle` state. Calling it narrows the result to that state.
522 */
523 isIdle: SignalFunction<
524 (
525 this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>,
526 ) => this is CreateMutationResult<
527 TData,
528 TError,
529 TVariables,
530 TOnMutateResult,
531 CreateStatusBasedMutationResult<
532 'idle',
533 TData,
534 TError,
535 TVariables,
536 TOnMutateResult
537 >
538 >
539 >
541​
542/**
543 * The result of `injectMutation`. Based on {@link CreateBaseMutationResult}, but value fields are exposed as
544 * a `Signal` β€” read them with `mutation.data()`, not `mutation.data` β€” while function fields (`mutate`,
545 * `mutateAsync`, `reset`) are called directly, unchanged. `isSuccess`/`isError`/`isPending`/`isIdle` are
546 * {@link BaseMutationNarrowing} type-guard methods rather than plain booleans.
547 * @template TData - The type your mutation function resolves to.
548 * @template TError - The type of errors your mutation function may throw.
549 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
550 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
551 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
552 */
553export type CreateMutationResult<
554 TData = unknown,
555 TError = DefaultError,
556 TVariables = unknown,
557 TOnMutateResult = unknown,
558 TState = CreateStatusBasedMutationResult<
559 CreateBaseMutationResult['status'],
560 TData,
561 TError,
562 TVariables,
563 TOnMutateResult
564 >,
565> = BaseMutationNarrowing<TData, TError, TVariables, TOnMutateResult> &
566 MapToSignals<
567 OmitKeyof<TState, keyof BaseMutationNarrowing, 'safely'>,
568 MutationResultFields
569 >