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

InfiniteQueryObserver.md

715 lines18.5 KB

1---
2id: InfiniteQueryObserver
3title: InfiniteQueryObserver
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8Defined in: [packages/query-core/src/infiniteQueryObserver.ts:40](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L40)
9​
10An `InfiniteQueryObserver` extends `QueryObserver` to observe and switch
11between infinite queries. It augments the base `QueryObserverResult` with
12infinite-query-specific fields and methods, such as `hasNextPage` and
13`fetchNextPage`, and is the primitive that framework adapters (e.g.
14`useInfiniteQuery`) build their hooks on top of.
15​
16## Example
17​
18```ts
19const observer = new InfiniteQueryObserver(queryClient, {
20 queryKey: ['projects'],
21 queryFn: ({ pageParam }) => fetchProjects(pageParam),
22 initialPageParam: 0,
23 getNextPageParam: (lastPage) => lastPage.nextCursor,
24})
25​
26const unsubscribe = observer.subscribe((result) => console.log(result))
27```
28​
29## Extends
30​
31- [`QueryObserver`](QueryObserver.md)\<`TQueryFnData`, `TError`, `TData`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>
32​
33## Type Parameters
34​
35### TQueryFnData
36​
37`TQueryFnData` = `unknown`
38​
39### TError
40​
41`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
42​
43### TData
44​
45`TData` = [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>
46​
47### TQueryKey
48​
49`TQueryKey` *extends* [`QueryKey`](../type-aliases/QueryKey.md) = [`QueryKey`](../type-aliases/QueryKey.md)
50​
51### TPageParam
52​
53`TPageParam` = `unknown`
54​
55## Constructors
56​
57### Constructor
58​
59```ts
60new InfiniteQueryObserver<TQueryFnData = unknown, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(client: QueryClient, options: InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>;
61```
62​
63Defined in: [packages/query-core/src/infiniteQueryObserver.ts:82](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L82)
64​
65#### Parameters
66​
67##### client
68​
69`QueryClient`
70​
71##### options
72​
73`InfiniteQueryObserverOptions`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
74​
75#### Returns
76​
77`InfiniteQueryObserver`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
78​
79#### Overrides
80​
81[`QueryObserver`](QueryObserver.md).[`constructor`](QueryObserver.md#constructor)
82​
83## Properties
84​
85### getCurrentResult
86​
87```ts
88getCurrentResult: ReplaceReturnType<() => QueryObserverResult<TData, TError>, InfiniteQueryObserverResult<TData, TError>>;
89```
90​
91Defined in: [packages/query-core/src/infiniteQueryObserver.ts:59](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L59)
92​
93Returns the most recently computed `QueryObserverResult` for the
94observed query. This is a point-in-time read; to be notified of updates
95as they happen, subscribe to the observer instead (its inherited
96`subscribe` method).
97​
98#### Returns
99​
100The observer's latest result.
101​
102#### Example
103​
104```ts
105const result = observer.getCurrentResult()
106console.log(result.status, result.data)
107```
108​
109#### Overrides
110​
111```ts
112QueryObserver.getCurrentResult
113```
114​
115***
116​
117### options
118​
119```ts
120options: QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>;
121```
122​
123Defined in: [packages/query-core/src/queryObserver.ts:88](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L88)
124​
125#### Inherited from
126​
127[`QueryObserver`](QueryObserver.md).[`options`](QueryObserver.md#options)
128​
129***
130​
131### subscribe
132​
133```ts
134subscribe: (listener: InfiniteQueryObserverListener) => () => void;
135```
136​
137Defined in: [packages/query-core/src/infiniteQueryObserver.ts:54](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L54)
138​
139Registers a listener to be called on every update this object notifies about. Returns a function
140that removes the listener again β€” call it to stop listening. The base class never drops a listener
141on its own, though some subclasses clear all of theirs in `destroy()`.
142​
143#### Parameters
144​
145##### listener
146​
147`InfiniteQueryObserverListener`
148​
149Called on each update, with whatever the subclass passes to its subscribers.
150​
151#### Returns
152​
153A function that removes the listener.
154​
155() => `void`
156​
157#### Example
158​
159```ts
160const unsubscribe = subscribable.subscribe(() => {
161 // react to the update
162})
163​
164unsubscribe()
165```
166​
167#### Overrides
168​
169```ts
170QueryObserver.subscribe
171```
172​
173## Methods
174​
175### destroy()
176​
177```ts
178destroy(): void;
179```
180​
181Defined in: [packages/query-core/src/queryObserver.ts:166](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L166)
182​
183Stops observing the current query: clears all listeners, cancels the
184stale and refetch-interval timers, and removes this observer from the
185query it was observing.
186​
187#### Returns
188​
189`void`
190​
191#### Inherited from
192​
193[`QueryObserver`](QueryObserver.md).[`destroy`](QueryObserver.md#destroy)
194​
195***
196​
197### fetchNextPage()
198​
199```ts
200fetchNextPage(options?: FetchNextPageOptions): Promise<InfiniteQueryObserverResult<TData, TError>>;
201```
202​
203Defined in: [packages/query-core/src/infiniteQueryObserver.ts:165](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L165)
204​
205Fetches the next page of the infinite query and returns a promise that
206resolves with the resulting `InfiniteQueryObserverResult`. The page
207param used for the fetch is determined by `getNextPageParam`, which
208receives the current pages/page params and whose result also determines
209`hasNextPage`.
210​
211#### Parameters
212​
213##### options?
214​
215[`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)
216​
217Set `cancelRefetch` to `false` to ignore the call while a fetch is running,
218and `throwOnError` to `true` to reject when the fetch fails.
219​
220#### Returns
221​
222`Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\>
223​
224A promise that resolves with the result after the next page is fetched. With
225`cancelRefetch: false`, a running fetch is reused instead, so the next page may not be fetched.
226​
227#### See
228​
229[InfiniteQueryObserver#fetchPreviousPage](#fetchpreviouspage)
230​
231#### Example
232​
233```ts
234const { hasNextPage } = observer.getCurrentResult()
235​
236if (hasNextPage) {
237 await observer.fetchNextPage()
239```
240​
241***
242​
243### fetchOptimistic()
244​
245```ts
246fetchOptimistic(options: QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>): Promise<QueryObserverResult<TData, TError>>;
247```
248​
249Defined in: [packages/query-core/src/queryObserver.ts:411](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L411)
250​
251Fetches a query defined by the given options without affecting this
252observer's own tracked query or result, and returns a promise that
253resolves with the `QueryObserverResult` for that fetch. This is useful
254for prefetching data that another observer (e.g. a query about to be
255navigated to) will need, ahead of time.
256​
257#### Parameters
258​
259##### options
260​
261`QueryObserverOptions`\<`TQueryFnData`, `TError`, `TData`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>
262​
263The observer options of the query to fetch.
264​
265#### Returns
266​
267`Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\>
268​
269A promise that resolves with the result for the fetched query.
270​
271#### Example
272​
273```ts
274const result = await observer.fetchOptimistic({
275 queryKey: ['posts', 2],
276 queryFn: () => fetchPost(2),
277})
278console.log(result.data)
279```
280​
281#### Inherited from
282​
283[`QueryObserver`](QueryObserver.md).[`fetchOptimistic`](QueryObserver.md#fetchoptimistic)
284​
285***
286​
287### fetchPreviousPage()
288​
289```ts
290fetchPreviousPage(options?: FetchPreviousPageOptions): Promise<InfiniteQueryObserverResult<TData, TError>>;
291```
292​
293Defined in: [packages/query-core/src/infiniteQueryObserver.ts:196](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L196)
294​
295Fetches the previous page of the infinite query and returns a promise
296that resolves with the resulting `InfiniteQueryObserverResult`. The page
297param used for the fetch is determined by `getPreviousPageParam`, which
298receives the current pages/page params and whose result also determines
299`hasPreviousPage`.
300​
301#### Parameters
302​
303##### options?
304​
305[`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)
306​
307Set `cancelRefetch` to `false` to ignore the call while a fetch is running,
308and `throwOnError` to `true` to reject when the fetch fails.
309​
310#### Returns
311​
312`Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\>
313​
314A promise that resolves with the result after the previous page is fetched. With
315`cancelRefetch: false`, a running fetch is reused instead, so the previous page may not be fetched.
316​
317#### See
318​
319[InfiniteQueryObserver#fetchNextPage](#fetchnextpage)
320​
321#### Example
322​
323```ts
324const { hasPreviousPage } = observer.getCurrentResult()
325​
326if (hasPreviousPage) {
327 await observer.fetchPreviousPage()
329```
330​
331***
332​
333### getCurrentQuery()
334​
335```ts
336getCurrentQuery(): Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>;
337```
338​
339Defined in: [packages/query-core/src/queryObserver.ts:370](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L370)
340​
341Returns the `Query` instance this observer is currently observing.
342​
343#### Returns
344​
345[`Query`](Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>
346​
347The observed query.
348​
349#### Inherited from
350​
351[`QueryObserver`](QueryObserver.md).[`getCurrentQuery`](QueryObserver.md#getcurrentquery)
352​
353***
354​
355### getOptimisticResult()
356​
357```ts
358getOptimisticResult(options: DefaultedInfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): InfiniteQueryObserverResult<TData, TError>;
359```
360​
361Defined in: [packages/query-core/src/infiniteQueryObserver.ts:129](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L129)
362​
363The infinite-query counterpart of [QueryObserver#getOptimisticResult](QueryObserver.md#getoptimisticresult), marking the
364options as an infinite query before delegating to it. Called by framework adapters (e.g.
365`useInfiniteQuery`) ahead of subscribing, to compute the current `InfiniteQueryObserverResult`
366synchronously.
367​
368#### Parameters
369​
370##### options
371​
372[`DefaultedInfiniteQueryObserverOptions`](../type-aliases/DefaultedInfiniteQueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
373​
374The defaulted infinite query observer options to compute the result for.
375​
376#### Returns
377​
378[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>
379​
380The result for the given options.
381​
382#### Overrides
383​
384[`QueryObserver`](QueryObserver.md).[`getOptimisticResult`](QueryObserver.md#getoptimisticresult)
385​
386***
387​
388### hasListeners()
389​
390```ts
391hasListeners(): boolean;
392```
393​
394Defined in: [packages/query-core/src/subscribable.ts:46](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L46)
395​
396Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
397​
398#### Returns
399​
400`boolean`
401​
402`true` if at least one listener is registered.
403​
404#### Inherited from
405​
406[`QueryObserver`](QueryObserver.md).[`hasListeners`](QueryObserver.md#haslisteners)
407​
408***
409​
410### refetch()
411​
412```ts
413refetch(options?: RefetchOptions): Promise<QueryObserverResult<TData, TError>>;
414```
415​
416Defined in: [packages/query-core/src/queryObserver.ts:386](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L386)
417​
418Refetches the observed query and returns a promise that resolves with
419the resulting `QueryObserverResult`.
420​
421#### Parameters
422​
423##### options?
424​
425[`RefetchOptions`](../interfaces/RefetchOptions.md) = `{}`
426​
427Set `cancelRefetch` to `false` to keep a running fetch instead of cancelling
428it, and `throwOnError` to `true` to reject when the refetch fails.
429​
430#### Returns
431​
432`Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\>
433​
434A promise that resolves with the result after the refetch.
435​
436#### Example
437​
438```ts
439const result = await observer.refetch({ cancelRefetch: false })
440console.log(result.data)
441```
442​
443#### Inherited from
444​
445[`QueryObserver`](QueryObserver.md).[`refetch`](QueryObserver.md#refetch)
446​
447***
448​
449### setOptions()
450​
451```ts
452setOptions(options: InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): void;
453```
454​
455Defined in: [packages/query-core/src/infiniteQueryObserver.ts:108](https://github.com/TanStack/query/blob/main/packages/query-core/src/infiniteQueryObserver.ts#L108)
456​
457Updates the observer's options. Behaves the same as
458`QueryObserver.setOptions`, additionally marking the options as
459belonging to an infinite query before delegating to the base
460implementation.
461​
462#### Parameters
463​
464##### options
465​
466`InfiniteQueryObserverOptions`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
467​
468The new infinite query observer options.
469​
470#### Returns
471​
472`void`
473​
474#### Overrides
475​
476[`QueryObserver`](QueryObserver.md).[`setOptions`](QueryObserver.md#setoptions)
477​
478***
479​
480### shouldFetchOnReconnect()
481​
482```ts
483shouldFetchOnReconnect(): boolean;
484```
485​
486Defined in: [packages/query-core/src/queryObserver.ts:139](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L139)
487​
488Returns whether the observed query is currently stale and configured
489(via the `refetchOnReconnect` option) to refetch when the network
490reconnects.
491​
492#### Returns
493​
494`boolean`
495​
496`true` if the observer should refetch the query on reconnect.
497​
498#### Inherited from
499​
500[`QueryObserver`](QueryObserver.md).[`shouldFetchOnReconnect`](QueryObserver.md#shouldfetchonreconnect)
501​
502***
503​
504### shouldFetchOnWindowFocus()
505​
506```ts
507shouldFetchOnWindowFocus(): boolean;
508```
509​
510Defined in: [packages/query-core/src/queryObserver.ts:153](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L153)
511​
512Returns whether the observed query is currently stale and configured
513(via the `refetchOnWindowFocus` option) to refetch when the window
514regains focus.
515​
516#### Returns
517​
518`boolean`
519​
520`true` if the observer should refetch the query on window focus.
521​
522#### Inherited from
523​
524[`QueryObserver`](QueryObserver.md).[`shouldFetchOnWindowFocus`](QueryObserver.md#shouldfetchonwindowfocus)
525​
526***
527​
528### trackProp()
529​
530```ts
531trackProp(key:
532 | "error"
533 | "fetchStatus"
534 | "status"
535 | "data"
536 | "isError"
537 | "isPending"
538 | "isLoading"
539 | "isLoadingError"
540 | "isRefetchError"
541 | "isSuccess"
542 | "isPlaceholderData"
543 | "dataUpdatedAt"
544 | "errorUpdatedAt"
545 | "failureCount"
546 | "failureReason"
547 | "errorUpdateCount"
548 | "isFetched"
549 | "isFetchedAfterMount"
550 | "isFetching"
551 | "isInitialLoading"
552 | "isPaused"
553 | "isRefetching"
554 | "isStale"
555 | "isEnabled"
556 | "refetch"): void;
557```
558​
559Defined in: [packages/query-core/src/queryObserver.ts:362](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L362)
560​
561Records that the given `QueryObserverResult` property was read, so a subsequent update only
562notifies this observer if a tracked property actually changed. Normally called indirectly via
563[QueryObserver#trackResult](QueryObserver.md#trackresult)'s proxy; exposed directly for adapters that track property
564access themselves (e.g. through their own reactivity system) instead of via the proxy.
565​
566#### Parameters
567​
568##### key
569​
570 \| `"error"`
571 \| `"fetchStatus"`
572 \| `"status"`
573 \| `"data"`
574 \| `"isError"`
575 \| `"isPending"`
576 \| `"isLoading"`
577 \| `"isLoadingError"`
578 \| `"isRefetchError"`
579 \| `"isSuccess"`
580 \| `"isPlaceholderData"`
581 \| `"dataUpdatedAt"`
582 \| `"errorUpdatedAt"`
583 \| `"failureCount"`
584 \| `"failureReason"`
585 \| `"errorUpdateCount"`
586 \| `"isFetched"`
587 \| `"isFetchedAfterMount"`
588 \| `"isFetching"`
589 \| `"isInitialLoading"`
590 \| `"isPaused"`
591 \| `"isRefetching"`
592 \| `"isStale"`
593 \| `"isEnabled"`
594 \| `"refetch"`
595​
596The name of the property that was read.
597​
598#### Returns
599​
600`void`
601​
602#### Inherited from
603​
604[`QueryObserver`](QueryObserver.md).[`trackProp`](QueryObserver.md#trackprop)
605​
606***
607​
608### trackResult()
609​
610```ts
611trackResult(result: QueryObserverResult<TData, TError>, onPropTracked?: (key:
612 | "error"
613 | "fetchStatus"
614 | "status"
615 | "data"
616 | "isError"
617 | "isPending"
618 | "isLoading"
619 | "isLoadingError"
620 | "isRefetchError"
621 | "isSuccess"
622 | "isPlaceholderData"
623 | "dataUpdatedAt"
624 | "errorUpdatedAt"
625 | "failureCount"
626 | "failureReason"
627 | "errorUpdateCount"
628 | "isFetched"
629 | "isFetchedAfterMount"
630 | "isFetching"
631 | "isInitialLoading"
632 | "isPaused"
633 | "isRefetching"
634 | "isStale"
635 | "isEnabled"
636| "refetch") => void): QueryObserverResult<TData, TError>;
637```
638​
639Defined in: [packages/query-core/src/queryObserver.ts:342](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L342)
640​
641Wraps a `QueryObserverResult` in a `Proxy` that records which properties are read, via
642[QueryObserver#trackProp](QueryObserver.md#trackprop) (and an optional `onPropTracked` callback). Used by framework
643adapters when `notifyOnChangeProps` is not set, to implement its default "only re-render on
644properties you actually read" behavior.
645​
646#### Parameters
647​
648##### result
649​
650[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>
651​
652The result to wrap.
653​
654##### onPropTracked?
655​
656(`key`:
657 \| `"error"`
658 \| `"fetchStatus"`
659 \| `"status"`
660 \| `"data"`
661 \| `"isError"`
662 \| `"isPending"`
663 \| `"isLoading"`
664 \| `"isLoadingError"`
665 \| `"isRefetchError"`
666 \| `"isSuccess"`
667 \| `"isPlaceholderData"`
668 \| `"dataUpdatedAt"`
669 \| `"errorUpdatedAt"`
670 \| `"failureCount"`
671 \| `"failureReason"`
672 \| `"errorUpdateCount"`
673 \| `"isFetched"`
674 \| `"isFetchedAfterMount"`
675 \| `"isFetching"`
676 \| `"isInitialLoading"`
677 \| `"isPaused"`
678 \| `"isRefetching"`
679 \| `"isStale"`
680 \| `"isEnabled"`
681 \| `"refetch"`) => `void`
682​
683Called with the name of each property that is read.
684​
685#### Returns
686​
687[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>
688​
689A proxy of `result` that tracks property reads.
690​
691#### Inherited from
692​
693[`QueryObserver`](QueryObserver.md).[`trackResult`](QueryObserver.md#trackresult)
694​
695***
696​
697### updateResult()
698​
699```ts
700updateResult(): void;
701```
702​
703Defined in: [packages/query-core/src/queryObserver.ts:763](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryObserver.ts#L763)
704​
705Recomputes and stores the current result from the current query/options, notifying listeners
706if it changed. Framework adapters call this right after subscribing to make sure no query
707update was missed in the gap between creating the observer and subscribing to it.
708​
709#### Returns
710​
711`void`
712​
713#### Inherited from
714​
715[`QueryObserver`](QueryObserver.md).[`updateResult`](QueryObserver.md#updateresult)