0
Fork 0
mirror of https://github.com/TanStack/query.git synced 2026-11-16 22:50:20 +00:00
query/docs/reference/MutationCache.md
Josh a2151d28e1
feat(query-core): add context to mutationfn & mutation callbacks (#9615)
* feat(query-core): add context to mutationfn

Co-Authored-By: travikk <627275+travikk@users.noreply.github.com>

* fix(query-core): mutation onSuccess scope param should also be undefined

Co-Authored-By: travikk <627275+travikk@users.noreply.github.com>

* feat: add scope deprecate context on mutation state

* feat(query-core): add mutation context to all mutation callbacks

* chore: pr amends

Co-Authored-By: Dominik Dorfmeister <1021430+TkDodo@users.noreply.github.com>

* test(unit): update to handle context in mutation callbacks

* chore: rename to onMutateResult

* chore: revert context deprecation on MutationState

---------

Co-authored-by: travikk <627275+travikk@users.noreply.github.com>
Co-authored-by: Dominik Dorfmeister <1021430+TkDodo@users.noreply.github.com>
Co-authored-by: Dominik Dorfmeister <office@dorfmeister.cc>
2025-09-16 10:22:43 +02:00

3.3 KiB

id title
MutationCache 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)
  },
})

Its available methods are:

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

Global callbacks

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.

mutationCache.getAll

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()

Returns

  • Mutation[]
    • Mutation instances from the cache

mutationCache.subscribe

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)

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.

mutationCache.clear

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

mutationCache.clear()