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

InfiniteQueryObserver.md

718 lines18.7 KB

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