TanStack Query

In the mutation's onSuccess, call queryClient.invalidateQueries({ queryKey: ['todos'] }). Every query whose key starts with 'todos' is marked stale; those currently rendered refetch in the background at once, the rest refetch when next mounted.

mutate starts the mutation and returns nothing; errors are caught internally and surface through callbacks and the hook's error state. mutateAsync returns a promise that resolves with the data or rejects with the error, so you must catch it yourself.

useInfiniteQuery fetches the first page with initialPageParam, then asks getNextPageParam(lastPage, allPages, lastPageParam, allPageParams) for each next param. Returning undefined or null sets hasNextPage to false. Pages accumulate in data.pages and data.pageParams.

The key is the cache identity, and ['todos'] never changes, so every filter shares one entry and a filter change starts no fetch. Put every variable the queryFn uses into the key, such as ['todos', 'list', { status }].

staleTime (default 0) sets how long fetched data counts as fresh, skipping mount, focus and reconnect refetches; gcTime (default 5 minutes, formerly cacheTime) sets how long a query with no mounted observers stays in memory before deletion.

status answers whether the query has data: pending, error or success. fetchStatus answers whether the queryFn is running: fetching, paused or idle. They vary independently, so success can pair with fetching and pending can pair with idle or paused.

Without options it matches every query whose key starts with 'todos', element by element, with objects matched by the properties you pass. exact: true matches only the identical key; predicate receives each Query and must also return true.

onMutate runs before the mutationFn, then onSuccess or onError, then onSettled; returned promises are awaited. Callbacks passed to mutate() run after those, only while the component is mounted, and only for the latest mutate call.

Each page number is a new query key, so its entry starts pending with no data. Setting placeholderData: keepPreviousData shows the previous page's data while the next one loads, with isPlaceholderData true until the real page arrives.

In onMutate, cancel in-flight fetches for the list, snapshot it with getQueryData, write the flipped flag with setQueryData and return the snapshot. In onError, write the snapshot back. In onSettled, invalidate the list so it matches the server.

Set refetchInterval on useQuery: a number of milliseconds polls on a fixed timer, and a function receiving the query can return false once the job is complete, which stops polling. Hidden tabs skip polling unless refetchIntervalInBackground is true.

initialData is written to the cache as real data and ages under staleTime as if just fetched; placeholderData is shown only to that observer while the query has no data, and is never cached.

On the client a failed query is retried 3 times by default, waiting about 1, 2 and 4 seconds between attempts. The error surfaces only after the fourth attempt fails; until then status stays pending and failureCount climbs.

select transforms or picks from the cached data for one observer; the cache keeps the raw queryFn result. It reruns only when the data or the select function's reference changes, so an inline function runs every render unless it is hoisted or memoized.

Every matched query is marked invalidated; refetchType only chooses which of them refetch now: 'active' (default), 'inactive', 'all' or 'none'. Unobserved matches are left stale and refetch when a component next mounts them.

setQueryData synchronously writes data for one exact key, creating the entry if needed, marks it successful and fresh, and notifies observers. Returning undefined leaves the cache untouched. Mutating old data in place keeps the same reference, so dependent UI can miss the change.

While isPending is true, render mutation.variables as a provisional item next to the query's data. Keep the mutation pending until the refetch finishes by returning invalidateQueries from onSettled. On error, variables remain, so show a retry.

It refetches all ten pages one after another, starting from the first stored param and computing each next param from the freshly fetched page. maxPages caps how many pages are kept, so a refetch requests at most that many.

Build every key from one factory, nested from general to specific: ['todos'], then ['todos', 'list'] with filters, then ['todos', 'detail', id]. Nesting lets one prefix address a whole group, and queryOptions() keeps each key with its queryFn and type.

Keys are compared by a deterministic hash: JSON.stringify with plain-object properties sorted. Object property order does not matter, but array order and value types do, so the number 5 and the string '5' produce different cache entries.

Default staleTime 0 makes all cached data stale and refetchOnWindowFocus defaults to true, so returning to the tab refetches every active query. Set realistic staleTime values rather than disabling focus refetching globally.

Under the default networkMode 'online', a query that should fetch after an offline event is not started: it is status pending with fetchStatus paused, so isLoading is false. It resumes on reconnect; render isPaused, or pick 'always' or 'offlineFirst'.

The onSuccess callback calls invalidateQueries without returning its promise, so the mutation settles as soon as the POST succeeds while the refetch is still running. Return or await the invalidateQueries promise; the mutation then stays pending until the list has refetched.

Repeated sentinel callbacks call fetchNextPage while a fetch is running, and its default cancelRefetch: true cancels that fetch and starts another for the same page. Guard the call with hasNextPage && !isFetching, or pass { cancelRefetch: false }.

new Date() serializes to a new timestamp on every render, so each render builds a new key, misses the cache and sends a request. Compute the date once, in state or as a day string.

Structural sharing deep-compares refetched data with the cached data and keeps old references for every unchanged part, so an identical response leaves data's reference unchanged. Disable it with structuralSharing: false for very large payloads or non-JSON data.