InfiniteQueryObserver

Defined in: packages/query-core/src/infiniteQueryObserver.ts:40

An InfiniteQueryObserver extends QueryObserver to observe and switch between infinite queries. It augments the base QueryObserverResult with infinite-query-specific fields and methods, such as hasNextPage and fetchNextPage, and is the primitive that framework adapters (e.g. useInfiniteQuery) build their hooks on top of.

Example#

const observer = new InfiniteQueryObserver(queryClient, {
  queryKey: ['projects'],
  queryFn: ({ pageParam }) => fetchProjects(pageParam),
  initialPageParam: 0,
  getNextPageParam: (lastPage) => lastPage.nextCursor,
})

const unsubscribe = observer.subscribe((result) => console.log(result))

Extends#

• QueryObserver<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>

Type Parameters#

TQueryFnData#

TQueryFnData = unknown

TError#

TError = DefaultError

TData#

TData = InfiniteData<TQueryFnData>

TQueryKey#

TQueryKey extends QueryKey = QueryKey

TPageParam#

TPageParam = unknown

Constructors#

Constructor#

new InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>(client: QueryClient, options: InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>;

Defined in: packages/query-core/src/infiniteQueryObserver.ts:82

Parameters#

client#

QueryClient

options#

InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

Returns#

InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>

Overrides#

QueryObserver.constructor

Properties#

getCurrentResult#

getCurrentResult: ReplaceReturnType<() => QueryObserverResult<TData, TError>, InfiniteQueryObserverResult<TData, TError>>;

Defined in: packages/query-core/src/infiniteQueryObserver.ts:59

Returns the most recently computed QueryObserverResult for the observed query. This is a point-in-time read; to be notified of updates as they happen, subscribe to the observer instead (its inherited subscribe method).

Returns#

The current result.

Example#

const result = observer.getCurrentResult()
console.log(result.status, result.data)

Overrides#

QueryObserver.getCurrentResult

options#

options: QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>;

Defined in: packages/query-core/src/queryObserver.ts:88

Inherited from#

QueryObserver.options

subscribe()#

subscribe: (listener: InfiniteQueryObserverListener) => () => void;

Defined in: packages/query-core/src/infiniteQueryObserver.ts:54

Registers a listener to be called on every update this object notifies about. Returns a function that removes the listener again — call it to stop listening. The base class never drops a listener on its own, though some subclasses clear all of theirs in destroy().

Parameters#

listener#

InfiniteQueryObserverListener

Called on each update, with whatever the subclass passes to its subscribers.

Returns#

A function that removes the listener.

(): void;

Returns#

void

Example#

const unsubscribe = subscribable.subscribe(() => {
  // react to the update
})

unsubscribe()

Overrides#

QueryObserver.subscribe

Methods#

destroy()#

destroy(): void;

Defined in: packages/query-core/src/queryObserver.ts:162

Stops observing the current query: clears all listeners, cancels the stale and refetch-interval timers, and removes this observer from the query it was observing.

Returns#

void

Inherited from#

QueryObserver.destroy

fetchNextPage()#

fetchNextPage(options?: FetchNextPageOptions): Promise<InfiniteQueryObserverResult<TData, TError>>;

Defined in: packages/query-core/src/infiniteQueryObserver.ts:165

Fetches the next page of the infinite query and returns a promise that resolves with the resulting InfiniteQueryObserverResult. The page param used for the fetch is determined by getNextPageParam, which receives the current pages/page params and whose result also determines hasNextPage.

Parameters#

options?#

FetchNextPageOptions

Set cancelRefetch to false to ignore the call while a fetch is running, and throwOnError to true to reject when the fetch fails.

Returns#

Promise<InfiniteQueryObserverResult<TData, TError>>

A promise that resolves with the result after the next page is fetched. With cancelRefetch: false, a running fetch is reused instead, so the next page may not be fetched.

Example#

const { hasNextPage } = observer.getCurrentResult()

if (hasNextPage) {
  await observer.fetchNextPage()
}

See#

InfiniteQueryObserver#fetchPreviousPage

fetchOptimistic()#

fetchOptimistic(options: QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>): Promise<QueryObserverResult<TData, TError>>;

Defined in: packages/query-core/src/queryObserver.ts:407

Fetches a query defined by the given options without affecting this observer's own tracked query or result, and returns a promise that resolves with the QueryObserverResult for that fetch. This is useful for prefetching data that another observer (e.g. a query about to be navigated to) will need, ahead of time.

Parameters#

options#

QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>

The observer options of the query to fetch.

Returns#

Promise<QueryObserverResult<TData, TError>>

A promise that resolves with the result for the fetched query.

Example#

const result = await observer.fetchOptimistic({
  queryKey: ['posts', 2],
  queryFn: () => fetchPost(2),
})
console.log(result.data)

Inherited from#

QueryObserver.fetchOptimistic

fetchPreviousPage()#

fetchPreviousPage(options?: FetchPreviousPageOptions): Promise<InfiniteQueryObserverResult<TData, TError>>;

Defined in: packages/query-core/src/infiniteQueryObserver.ts:196

Fetches the previous page of the infinite query and returns a promise that resolves with the resulting InfiniteQueryObserverResult. The page param used for the fetch is determined by getPreviousPageParam, which receives the current pages/page params and whose result also determines hasPreviousPage.

Parameters#

options?#

FetchPreviousPageOptions

Set cancelRefetch to false to ignore the call while a fetch is running, and throwOnError to true to reject when the fetch fails.

Returns#

Promise<InfiniteQueryObserverResult<TData, TError>>

A promise that resolves with the result after the previous page is fetched. With cancelRefetch: false, a running fetch is reused instead, so the previous page may not be fetched.

Example#

const { hasPreviousPage } = observer.getCurrentResult()

if (hasPreviousPage) {
  await observer.fetchPreviousPage()
}

See#

InfiniteQueryObserver#fetchNextPage

getCurrentQuery()#

getCurrentQuery(): Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>;

Defined in: packages/query-core/src/queryObserver.ts:366

Returns the Query instance this observer is currently observing.

Returns#

Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>

The observed query.

Inherited from#

QueryObserver.getCurrentQuery

getOptimisticResult()#

getOptimisticResult(options: DefaultedInfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): InfiniteQueryObserverResult<TData, TError>;

Defined in: packages/query-core/src/infiniteQueryObserver.ts:129

The infinite-query counterpart of QueryObserver#getOptimisticResult, marking the options as an infinite query before delegating to it. Called by framework adapters (e.g. useInfiniteQuery) ahead of subscribing, to compute the current InfiniteQueryObserverResult synchronously.

Parameters#

options#

DefaultedInfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

The defaulted infinite query observer options to compute the result for.

Returns#

InfiniteQueryObserverResult<TData, TError>

The result for the given options.

Overrides#

QueryObserver.getOptimisticResult

hasListeners()#

hasListeners(): boolean;

Defined in: packages/query-core/src/subscribable.ts:43

Returns true while at least one listener is registered, false once they have all unsubscribed.

Returns#

boolean

true if at least one listener is registered.

Inherited from#

QueryObserver.hasListeners

refetch()#

refetch(options: RefetchOptions): Promise<QueryObserverResult<TData, TError>>;

Defined in: packages/query-core/src/queryObserver.ts:382

Refetches the observed query and returns a promise that resolves with the resulting QueryObserverResult.

Parameters#

options#

RefetchOptions = {}

Set cancelRefetch to false to keep a running fetch instead of cancelling it, and throwOnError to true to reject when the refetch fails.

Returns#

Promise<QueryObserverResult<TData, TError>>

A promise that resolves with the result after the refetch.

Example#

const result = await observer.refetch({ cancelRefetch: false })
console.log(result.data)

Inherited from#

QueryObserver.refetch

setOptions()#

setOptions(options: InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): void;

Defined in: packages/query-core/src/infiniteQueryObserver.ts:108

Updates the observer's options. Behaves the same as QueryObserver.setOptions, additionally marking the options as belonging to an infinite query before delegating to the base implementation.

Parameters#

options#

InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

The new infinite query observer options.

Returns#

void

Overrides#

QueryObserver.setOptions

shouldFetchOnReconnect()#

shouldFetchOnReconnect(): boolean;

Defined in: packages/query-core/src/queryObserver.ts:135

Returns whether the observed query is currently stale and configured (via the refetchOnReconnect option) to refetch when the network reconnects.

Returns#

boolean

true if the observer should refetch the query on reconnect.

Inherited from#

QueryObserver.shouldFetchOnReconnect

shouldFetchOnWindowFocus()#

shouldFetchOnWindowFocus(): boolean;

Defined in: packages/query-core/src/queryObserver.ts:149

Returns whether the observed query is currently stale and configured (via the refetchOnWindowFocus option) to refetch when the window regains focus.

Returns#

boolean

true if the observer should refetch the query on window focus.

Inherited from#

QueryObserver.shouldFetchOnWindowFocus

trackProp()#

trackProp(key: 
  | "error"
  | "data"
  | "isError"
  | "isPending"
  | "isLoading"
  | "isLoadingError"
  | "isRefetchError"
  | "isSuccess"
  | "isPlaceholderData"
  | "status"
  | "dataUpdatedAt"
  | "errorUpdatedAt"
  | "failureCount"
  | "failureReason"
  | "errorUpdateCount"
  | "isFetched"
  | "isFetchedAfterMount"
  | "isFetching"
  | "isInitialLoading"
  | "isPaused"
  | "isRefetching"
  | "isStale"
  | "isEnabled"
  | "refetch"
  | "fetchStatus"): void;

Defined in: packages/query-core/src/queryObserver.ts:358

Records that the given QueryObserverResult property was read, so a subsequent update only notifies this observer if a tracked property actually changed. Normally called indirectly via QueryObserver#trackResult's proxy; exposed directly for adapters that track property access themselves (e.g. through their own reactivity system) instead of via the proxy.

Parameters#

key#

The name of the property that was read.

"error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus"

Returns#

void

Inherited from#

QueryObserver.trackProp

trackResult()#

trackResult(result: QueryObserverResult<TData, TError>, onPropTracked?: (key: 
  | "error"
  | "data"
  | "isError"
  | "isPending"
  | "isLoading"
  | "isLoadingError"
  | "isRefetchError"
  | "isSuccess"
  | "isPlaceholderData"
  | "status"
  | "dataUpdatedAt"
  | "errorUpdatedAt"
  | "failureCount"
  | "failureReason"
  | "errorUpdateCount"
  | "isFetched"
  | "isFetchedAfterMount"
  | "isFetching"
  | "isInitialLoading"
  | "isPaused"
  | "isRefetching"
  | "isStale"
  | "isEnabled"
  | "refetch"
| "fetchStatus") => void): QueryObserverResult<TData, TError>;

Defined in: packages/query-core/src/queryObserver.ts:338

Wraps a QueryObserverResult in a Proxy that records which properties are read, via QueryObserver#trackProp (and an optional onPropTracked callback). Used by framework adapters when notifyOnChangeProps is not set, to implement its default "only re-render on properties you actually read" behavior.

Parameters#

result#

QueryObserverResult<TData, TError>

The result to wrap.

onPropTracked?#

(key: | "error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus") => void

Called with the name of each property that is read.

Returns#

QueryObserverResult<TData, TError>

A proxy of result that tracks property reads.

Inherited from#

QueryObserver.trackResult

updateResult()#

updateResult(): void;

Defined in: packages/query-core/src/queryObserver.ts:745

Recomputes and stores the current result from the current query/options, notifying listeners if it changed. Framework adapters call this right after subscribing to make sure no query update was missed in the gap between creating the observer and subscribing to it.

Returns#

void

Inherited from#

QueryObserver.updateResult