Advanced topic

Classes

DefaultedMutationOptions<TData, TVariables, TOnMutateResult> Advanced

Mutation options with every default resolved. Only QueryClient produces one, and final keeps it that way; read it from Mutation.options or MutationObserver.options to see what a mutation actually runs with.

DefaultedQueryObserverOptions<TQueryData, TData> Advanced

QueryObserverOptionsBase with every default resolved: DefaultedQueryOptions plus the observer-only options, what a QueryObserver actually runs on.

DefaultedQueryOptions<TQueryData> Advanced

QueryOptions with every default resolved: what a Query actually runs on, read back as Query.options.

FetchBehavior<TQueryData> Advanced

Rewrites how a fetch runs.

FetchContext<TQueryData> Advanced

The mutable description of one fetch, handed to a FetchBehavior, which may replace fetchFn to change what the fetch does.

FetchMore Advanced

Which end of an infinite query a fetch is extending. Travels in FetchOptions.meta, and so ends up in QueryState.fetchMeta.

FetchOptions Advanced

Overrides for one call of Query.fetch, leaving the query's options untouched.

MutationAction Advanced

A state transition. Sealed, so the reducer is exhaustive.

MutationAdded Advanced

A mutation was created and appended to the cache, which happens the moment mutate is called (or a restored mutation is built into the cache). TanStack Query calls this the added event.

MutationCacheEvent Advanced

Something happened to a mutation in the cache. The mutation-side twin of QueryCacheEvent, delivered to MutationCache.subscribe listeners.

MutationContinueAction Advanced

A paused run resumed — or a restored one was re-run. isPaused becomes false.

MutationErrorAction Advanced

The run failed for good and every error callback has run. Status becomes error, the data is cleared, and the failure count is bumped one last time.

MutationFailedAction Advanced

One attempt failed and will be retried. Records the count and the reason; status stays pending.

MutationObserverAdded Advanced

An observer subscribed to the mutation, which also cancels its pending collection. TanStack Query calls this the observerAdded event.

MutationObserverOptionsUpdated Advanced

An observer's options were replaced while it stayed attached to the same mutation — a rebuild that changed a callback or retry, say. TanStack Query calls this the observerOptionsUpdated event.

MutationObserverRef Advanced

What a Mutation needs from an observer.

MutationObserverRemoved Advanced

An observer unsubscribed from the mutation; when it was the last one, the collection timer has been armed by the time this fires. TanStack Query calls this the observerRemoved event.

MutationPauseAction Advanced

The retryer suspended the run: offline, backgrounded, or blocked by its scope. isPaused becomes true.

MutationPendingAction Advanced

A run started. Replaces the whole state: status pending, the run's variables, a fresh submittedAt, and isPaused when the run cannot start yet. Dispatched a second time once onMutate has run, when it produced a result or the run's pause changed meanwhile.

MutationRemoved Advanced

A mutation left the cache: garbage-collected after its last observer left, or removed through MutationCache.remove or MutationCache.clear. TanStack Query calls this the removed event.

MutationSuccessAction Advanced

The mutation function resolved and every success callback has run. Status becomes success and the error and failure count are cleared.

MutationUpdated Advanced

A mutation's state changed. Emitted for every dispatched MutationAction — pending, success, error, pause, continue and the rest. TanStack Query calls this the updated event.

QueryAction Advanced

One change to a query's state — what a QueryUpdated cache event says happened.

QueryAdded Advanced

A query was created and put into the cache, by QueryCache.build or QueryCache.add — the first time anything used its key. TanStack Query calls this event added.

QueryCacheEvent Advanced

Something happened to a query in the cache: what QueryCache.subscribe delivers to its listeners.

QueryContinueAction Advanced

A paused fetch resumed; fetchStatus is fetching again. TanStack Query calls this action continue.

QueryErrorAction Advanced

A fetch failed for good: retries exhausted, or cancelled with neither silent nor revert — a reverting cancel restores the earlier state through QuerySetStateAction instead. Moves status to error, ends the fetch and flags existing data as invalidated. TanStack Query calls this action error.

QueryFailedAction Advanced

One attempt failed and will be retried. Records the count and the reason without touching status or the data. TanStack Query calls this action failed.

QueryFetchAction Advanced

A fetch started. Resets the failure count, records meta, and moves fetchStatus to fetching — or paused, when the network mode forbids starting. TanStack Query calls this action fetch.

QueryInvalidateAction Advanced

The query was marked stale by QueryClient.invalidateQueries. Only isInvalidated changes; whether a refetch follows is the caller's decision. TanStack Query calls this action invalidate.

QueryObserverAdded Advanced

An observer subscribed to the query. Emitted the moment the observer attaches, which is also what cancels the query's pending garbage collection. TanStack Query calls this event observerAdded.

QueryObserverOptionsUpdated Advanced

An observer's options were replaced — a rebuild that changed staleTime, enabled or a callback, say. Emitted for every change of options, a key change included: moving an observer to a different key emits QueryObserverRemoved on the old query and QueryObserverAdded on the new one, and then this event on the new query. TanStack Query calls this event observerOptionsUpdated and orders it the same way.

QueryObserverRef Advanced

What a Query needs from an observer, without knowing what an observer is.

QueryObserverRemoved Advanced

An observer unsubscribed from the query. Emitted after the observer has been detached — and, when it was the last one, after the fetch in flight has been told to stop retrying and the garbage-collection timer has been started. TanStack Query calls this event observerRemoved.

QueryObserverResultsUpdated Advanced

An observer of the query delivered a new result to its listeners. Emitted once per delivery, after the listeners have run, so a devtools panel can mirror what the UI just saw. TanStack Query calls this event observerResultsUpdated.

QueryPauseAction Advanced

The fetch was suspended: the device is offline, or a retry is waiting for the app to return to the foreground. fetchStatus becomes paused. TanStack Query calls this action pause.

QueryRemoved Advanced

A query left the cache: it was garbage-collected after its gcTime without observers, or removed through QueryClient.removeQueries, QueryCache.remove or QueryCache.clear. TanStack Query calls this event removed.

QuerySetStateAction<TQueryData> Advanced

The whole state was replaced through Query.setState — a reset, a revert after cancellation, or a persistence layer restoring. TanStack Query calls this action setState.

QuerySuccessAction<TQueryData> Advanced

Data arrived: from a fetch, or from a manual write through QueryClient.setQueryData. Bumps dataUpdateCount, clears the error and the invalidation, and — unless manual — ends the fetch. TanStack Query calls this action success.

QueryUpdated Advanced

A query's state changed. Emitted for every QueryAction — fetch, success, error, invalidate, pause, and the rest — so this is the event a devtools panel or a persister keys its work off. TanStack Query calls this event updated.