The QueryCache
is the storage mechanism for TanStack Query. It stores all the data, meta information and state of queries it contains.
Normally, you will not interact with the QueryCache directly and instead use the QueryClient
for a specific cache.
import { QueryCache } from '@tanstack/react-query'
const queryCache = new QueryCache({ onError: (error) => { console.log(error) }, onSuccess: (data) => { console.log(data) }, onSettled: (data, error) => { console.log(data, error) },})
const query = queryCache.find(['posts'])
Its available methods are:
Options
onError?: (error: unknown, query: Query) => void
onSuccess?: (data: unknown, query: Query) => void
onSettled?:
(data: unknown | undefined, error: unknown | null, query: Query) => void
The onError
, onSuccess
and onSettled
callbacks on the QueryCache can be used to handle these events on a global level. They are different to defaultOptions
provided to the QueryClient because:
defaultOptions
can be overridden by each Query - the global callbacks will always be called.defaultOptions
callbacks will be called once for each Observer, while the global callbacks will only be called once per Query.queryCache.find
find
is a slightly more advanced synchronous method that can be used to get an existing query instance from the cache. This instance not only contains all the state for the query, but all of the instances, and underlying guts of the query as well. If the query does not exist, undefined
will be returned.
Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios (eg. Looking at the query.state.dataUpdatedAt timestamp to decide whether a query is fresh enough to be used as an initial value)
const query = queryCache.find(queryKey)
Options
queryKey?: QueryKey
: Query Keysfilters?: QueryFilters
: Query FiltersReturns
Query
queryCache.findAll
findAll
is even more advanced synchronous method that can be used to get existing query instances from the cache that partially match query key. If queries do not exist, empty array will be returned.
Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios
const queries = queryCache.findAll(queryKey)
Options
queryKey?: QueryKey
: Query Keysfilters?: QueryFilters
: Query FiltersReturns
Query[]
queryCache.subscribe
The subscribe
method can be used to subscribe to the query cache as a whole and be informed of safe/known updates to the cache like query states changing or queries being updated, added or removed
const callback = (event) => { console.log(event.type, event.query)}
const unsubscribe = queryCache.subscribe(callback)
Options
callback: (event: QueryCacheNotifyEvent) => void
query.setState
, queryClient.removeQueries
, etc). Out of scope mutations to the cache are not encouraged and will not fire subscription callbacksReturns
unsubscribe: Function => void
queryCache.clear
The clear
method can be used to clear the cache entirely and start fresh.
queryCache.clear()
To get a better understanding how the QueryCache works internally, have a look at #18: Inside React Query from the Community Resources.
Fast track your learning and
take the offical React Query course ↗️
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.