MutationCache

The MutationCache is the storage for mutations.

Normally, you will not interact with the MutationCache directly and instead use the QueryClient.

import { MutationCache } from '@tanstack/react-query' const mutationCache = new MutationCache({ onError: (error) => { console.log(error) }, onSuccess: (data) => { console.log(data) }, }) 

import { MutationCache } from '@tanstack/react-query' const mutationCache = new MutationCache({ onError: (error) => { console.log(error) }, onSuccess: (data) => { console.log(data) }, }) 

Its available methods are:

• getAll
• subscribe
• clear

Options

• onError?: (error: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown
  • Optional
  • This function will be called if some mutation encounters an error.
  • If you return a Promise from it, it will be awaited
• onSuccess?: (data: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown
  • Optional
  • This function will be called if some mutation is successful.
  • If you return a Promise from it, it will be awaited
• onSettled?: (data: unknown | undefined, error: unknown | null, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown
  • Optional
  • This function will be called if some mutation is settled (either successful or errored).
  • If you return a Promise from it, it will be awaited
• onMutate?: (variables: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown
  • Optional
  • This function will be called before some mutation executes.
  • If you return a Promise from it, it will be awaited

The onError, onSuccess, onSettled and onMutate callbacks on the MutationCache 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 Mutation - the global callbacks will always be called.
• onMutate does not allow returning a result.

getAll returns all mutations within the cache.

Note: This is not typically needed for most applications, but can come in handy when needing more information about a mutation in rare scenarios

const mutations = mutationCache.getAll() 

const mutations = mutationCache.getAll() 

Returns

• Mutation[]
  • Mutation instances from the cache

The subscribe method can be used to subscribe to the mutation cache as a whole and be informed of safe/known updates to the cache like mutation states changing or mutations being updated, added or removed.

const callback = (event) => { console.log(event.type, event.mutation) } const unsubscribe = mutationCache.subscribe(callback) 

const callback = (event) => { console.log(event.type, event.mutation) } const unsubscribe = mutationCache.subscribe(callback) 

Options

• callback: (mutation?: MutationCacheNotifyEvent) => void
  • This function will be called with the mutation cache any time it is updated.

Returns

• unsubscribe: Function => void
  • This function will unsubscribe the callback from the mutation cache.

The clear method can be used to clear the cache entirely and start fresh.

mutationCache.clear() 

mutationCache.clear()