TanStack Query · Reference · all subjects

mutationcache

10 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 and options

MutationCache is imported from '@tanstack/react-query'. It accepts an options object with four optional callback properties: onError, onSuccess, onSettled, and onMutate. Each callback can return Promise<unknown> | unknown and will be awaited if a Promise is returned.

MutationCache onError callback

onError is an optional callback with signature (error: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is called if some mutation encounters an error.

MutationCache onSuccess callback

onSuccess is an optional callback with signature (data: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is called if some mutation is successful.

MutationCache onSettled callback

onSettled is an optional callback with signature (data: unknown | undefined, error: unknown | null, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is called if some mutation is settled, either successful or errored.

MutationCache onMutate callback

onMutate is an optional callback with signature (variables: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown. It is called before some mutation executes. Unlike other callbacks, onMutate does not allow returning a result.

Global callbacks always called unlike defaultOptions

The onError, onSuccess, onSettled and onMutate callbacks on the MutationCache handle events at a global level. They differ from defaultOptions provided to the QueryClient in two ways: global callbacks will always be called even if individual Mutations override them with defaultOptions, and onMutate does not allow returning a result on the cache-level callback.

MutationCache.getAll method

The getAll method returns all mutations within the cache as a Mutation[] array. It returns Mutation instances from the cache and is not typically needed for most applications but can help when needing more information about a mutation in rare scenarios.

MutationCache.subscribe method

The subscribe method takes a callback function with signature (mutation?: MutationCacheNotifyEvent) => void. The callback is called whenever the mutation cache is updated. It returns an unsubscribe function with signature () => void that unsubscribes the callback from the mutation cache.

MutationCache.clear method

The clear method clears the mutation cache entirely and starts fresh. It takes no parameters and returns nothing.

MutationCache usage note

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

Give your agent this brain