MutationCache overview
The MutationCache is the storage for mutations. Normally, you will not interact with the MutationCache directly and instead use the QueryClient. It is imported from '@tanstack/react-query'.
TanStack Query · Reference · all subjects
querycache & mutationcache
26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
MutationCache constructor with options
MutationCache is instantiated with new MutationCache({options}). The constructor accepts onError, onSuccess, onSettled, and onMutate callbacks.
MutationCache options: onError
onError option has signature (error: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is optional and called when a mutation encounters an error. If you return a Promise from it, it will be awaited.
MutationCache options: onSuccess
onSuccess option has signature (data: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is optional and called when a mutation is successful. If you return a Promise from it, it will be awaited.
MutationCache options: onSettled
onSettled option has signature (data: unknown | undefined, error: unknown | null, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is optional and called when a mutation is settled (either successful or errored). If you return a Promise from it, it will be awaited.
MutationCache options: onMutate
onMutate option has signature (variables: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is optional and called before a mutation executes. If you return a Promise from it, it will be awaited. Unlike the other callbacks, onMutate does not allow returning a result at the global level.
Global callbacks vs defaultOptions
The onError, onSuccess, onSettled and onMutate callbacks on the MutationCache differ from defaultOptions provided to the QueryClient because: defaultOptions can be overridden by each Mutation, but global callbacks will always be called. Additionally, onMutate does not allow returning a result at the global level.
MutationCache.getAll method
getAll() returns all mutations within the cache. It returns Mutation[] - Mutation instances from the cache. This is not typically needed for most applications but can be useful when needing more information about a mutation in rare scenarios.
MutationCache.subscribe method
subscribe(callback) subscribes to the mutation cache as a whole and is informed of safe/known updates to the cache like mutation states changing or mutations being updated, added or removed. The callback parameter is (mutation?: MutationCacheNotifyEvent) => void and is called any time the mutation cache is updated. It returns an unsubscribe function of type Function => void.
MutationCache.clear method
clear() clears the entire mutation cache and starts fresh. It takes no parameters.
MutationCache available methods
MutationCache has three available methods: getAll, subscribe, and clear.
MutationCache constructor example
Example of creating a MutationCache: import { MutationCache } from '@tanstack/react-query'; const mutationCache = new MutationCache({ onError: (error) => { console.log(error) }, onSuccess: (data) => { console.log(data) }, });
mutationCache.getAll usage example
Example of using getAll: const mutations = mutationCache.getAll(); Returns all mutations currently in the cache as Mutation instances.
mutationCache.subscribe usage example
Example of subscribing to mutation cache: const callback = (event) => { console.log(event.type, event.mutation) }; const unsubscribe = mutationCache.subscribe(callback);
mutationCache.clear usage example
Example of clearing the mutation cache: mutationCache.clear();
QueryCache is the storage mechanism for all query data
The QueryCache 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.
QueryCache constructor options
QueryCache can be instantiated with three optional callback options: onError (error: unknown, query: Query) => void called when a query encounters an error; onSuccess (data: unknown, query: Query) => void called when a query is successful; onSettled (data: unknown | undefined, error: unknown | null, query: Query) => void called when a query is settled (either successful or errored).
QueryCache.find method
queryCache.find is a synchronous method that returns an existing query instance from the cache. It takes a filters parameter of type QueryFilters with a queryKey property. If the query does not exist, undefined is returned. The returned query instance contains all the state for the query and all of its instances and underlying details.
QueryCache.findAll method
queryCache.findAll is a synchronous method that returns existing query instances from the cache that partially match a query key. It takes an optional filters parameter of type QueryFilters. If queries do not exist, an empty array is returned. The return type is Query[].
QueryCache.subscribe method
queryCache.subscribe can be used to subscribe to the query cache as a whole and be informed of safe and known updates. It takes a callback function of type (event: QueryCacheNotifyEvent) => void that is called when the cache is updated via tracked mechanisms like query.setState or queryClient.removeQueries. The method returns an unsubscribe function that removes the callback from the query cache.
QueryCache.clear method
queryCache.clear is a method that clears the cache entirely and allows starting fresh. It takes no parameters.
How to access QueryCache from QueryClient
According to the documentation, you normally do not interact with the QueryCache directly and instead use the QueryClient for a specific cache. The QueryCache is the underlying storage mechanism that the QueryClient manages.
QueryCache example with callbacks
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({ queryKey: ['posts'] })
QueryCache.subscribe example
const callback = (event) => { console.log(event.type, event.query) } const unsubscribe = queryCache.subscribe(callback)
How to access QueryCache from QueryClient
Access the QueryCache from a QueryClient instance by calling the getQueryCache() method, which returns the query cache this client is connected to.
How to access MutationCache from QueryClient
Access the MutationCache from a QueryClient instance by calling the getMutationCache() method, which returns the mutation cache this client is connected to.