Monitor cache notifications
Observe application-wide mutation activity for logging, metrics, or debugging.
TanStack · Class
MutationCache
MutationCache stores mutations and is normally accessed through QueryClient. It supports inspecting, filtering, clearing, and subscribing to mutation-cache updates.
How it works
MutationCache stores mutation instances and is normally managed through QueryClient rather than accessed directly. You can inspect all or filtered mutations, remove everything, or subscribe to notifications about mutations being added, removed, or updated.
Syntax
new MutationCache(config?: MutationCacheConfig): MutationCacheParameters
| Name | Type | Description |
|---|---|---|
config | MutationCacheConfig | Optional configuration used to initialize the cache. |
Returns
A MutationCache instance from the constructor; getAll() returns all mutations, find() returns a matching mutation or undefined, findAll() returns matching mutations, and subscribe() returns an unsubscribe function.
Key points
- It is the cache layer that holds mutation instances.
- Subscriptions report recognized cache changes through the inherited Subscribable mechanism.
- Relevant notifications include mutation additions, removals, and updates.
- The constructor accepts an optional MutationCacheConfig and returns a new MutationCache.
- clear() empties the cache completely.
- getAll() provides the complete collection of stored mutations.
- subscribe() registers a callback for each update the cache reports.
Common mistakes
- Prefer QueryClient for ordinary mutation-cache interaction; direct access is intended for specialized inspection or cache-level behavior.
- Always retain and invoke the function returned by subscribe when the observer is no longer needed.
Example: Inspect and observe a mutation cache
import { QueryClient } from '@tanstack/query-core'
const queryClient = new QueryClient()
const mutationCache = queryClient.getMutationCache()
const unsubscribe = mutationCache.subscribe((event) => {
console.log(event.type)
})
const pending = mutationCache.findAll({ status: 'pending' })
console.log(pending.length)
unsubscribe()Obtains the client-owned cache, observes cache notifications, and filters mutations by pending status.
When to use it
Query mutation state
Inspect mutations currently waiting to finish or matching a mutation key.
Clear mutation storage
Remove all stored mutation instances when resetting client state.
Interview questions
QWhat is MutationCache and how is it normally accessed?
MutationCache is the storage for mutations and is owned by QueryClient. A client creates a default cache unless one is supplied, and getMutationCache() returns the connected instance.
Follow-up: How would you inspect only pending mutations? Call getMutationCache().findAll({ status: 'pending' }); it returns the mutations matching those filters.
QHow do the cache inspection methods differ?
getAll() returns every mutation currently held by the cache. find() retrieves one matching mutation, while findAll() retrieves all matching mutations.
Follow-up: What should code expect when no mutation matches? find() yields undefined, whereas findAll() yields an empty array.
QHow can code observe and reset MutationCache?
subscribe() registers a listener for cache notifications, including mutations being added, removed, or updated. It returns an unsubscribe function that stops that listener.
Follow-up: How can a cache be reset completely? Call clear(), which removes all mutations from the cache.
Related
QueryClientMutationMutationCacheConfigMutationFiltersSubscribable