MutationCache

The MutationCache stores and manages all mutations.

The MutationCache is responsible for storing and managing all Mutation instances. It’s the underlying storage mechanism used by QueryClient for mutations.

Constructor

Creates a new MutationCache instance.

const mutationCache = new MutationCache(config?: MutationCacheConfig)

config · MutationCacheConfig

Configuration options for the MutationCache

Show properties

onError · (error: Error, variables: unknown, onMutateResult: unknown, mutation: Mutation, context: MutationFunctionContext) => void | Promise<unknown>

Global error handler called when any mutation encounters an error.

onSuccess · (data: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, context: MutationFunctionContext) => void | Promise<unknown>

Global success handler called when any mutation succeeds.

onMutate · (variables: unknown, mutation: Mutation, context: MutationFunctionContext) => void | Promise<unknown>

Global handler called before any mutation executes.

onSettled · (data: unknown | undefined, error: Error | null, variables: unknown, onMutateResult: unknown, mutation: Mutation, context: MutationFunctionContext) => void | Promise<unknown>

Global settled handler called when any mutation completes (success or error).

Example

import { MutationCache } from '@tanstack/query-core'

const mutationCache = new MutationCache({
  onError: (error, variables, onMutateResult, mutation) => {
    console.error('Mutation failed:', error)
  },
  onSuccess: (data, variables, onMutateResult, mutation) => {
    console.log('Mutation succeeded:', data)
  },
})

Methods

build

Builds a new mutation instance.

build<TData, TError, TVariables, TOnMutateResult>(
  client: QueryClient,
  options: MutationOptions<TData, TError, TVariables, TOnMutateResult>,
  state?: MutationState<TData, TError, TVariables, TOnMutateResult>
): Mutation<TData, TError, TVariables, TOnMutateResult>

client · QueryClient · required

The QueryClient instance.

options · MutationOptions · required

Options for the mutation.

state · MutationState

Optional initial state for the mutation.

Mutation · Mutation

Returns a new Mutation instance.

add

Adds a mutation to the cache.

add(mutation: Mutation): void

mutation · Mutation · required

The mutation instance to add.

remove

Removes a mutation from the cache.

remove(mutation: Mutation): void

mutation · Mutation · required

The mutation instance to remove.

clear

Clears all mutations from the cache.

clear(): void

Example

mutationCache.clear()

getAll

Returns all mutations in the cache.

getAll(): Array<Mutation>

Array<Mutation> · Array

Returns an array of all Mutation instances in the cache.

find

Finds a single mutation matching the provided filters.

find<TData, TError, TVariables, TOnMutateResult>(
  filters: MutationFilters
): Mutation<TData, TError, TVariables, TOnMutateResult> | undefined

filters · MutationFilters · required

Filters to match mutations.

Show properties

mutationKey · MutationKey

Mutation key to match.

exact · boolean

Whether to match the mutation key exactly. Default is true.

status · 'idle' | 'pending' | 'error' | 'success'

Filter by mutation status.

predicate · (mutation: Mutation) => boolean

Custom predicate function.

Mutation | undefined · Mutation

Returns the first matching Mutation instance, or undefined if not found.

findAll

Finds all mutations matching the provided filters.

findAll(filters?: MutationFilters): Array<Mutation>

filters · MutationFilters

Filters to match mutations. If not provided, returns all mutations.

Array<Mutation> · Array

Returns an array of all matching Mutation instances.

Example

// Find all pending mutations
const pendingMutations = mutationCache.findAll({ status: 'pending' })

// Find mutations with a specific key
const todoMutations = mutationCache.findAll({ 
  mutationKey: ['todos'] 
})

// Find mutations with custom predicate
const mutations = mutationCache.findAll({
  predicate: (mutation) => mutation.state.isPaused
})

notify

Notifies all cache listeners of an event.

notify(event: MutationCacheNotifyEvent): void

event · MutationCacheNotifyEvent · required

The event to notify listeners about.

subscribe

Subscribes to cache events.

subscribe(listener: MutationCacheListener): () => void

listener · (event: MutationCacheNotifyEvent) => void · required

Function called when cache events occur.

() => void · function

Returns an unsubscribe function.

Example

const unsubscribe = mutationCache.subscribe((event) => {
  console.log('Mutation cache event:', event.type)
  
  if (event.type === 'added') {
    console.log('Mutation added:', event.mutation.mutationId)
  } else if (event.type === 'updated') {
    console.log('Mutation updated:', event.mutation.state.status)
  }
})

// Later, unsubscribe
unsubscribe()

resumePausedMutations

Resumes all paused mutations.

resumePausedMutations(): Promise<unknown>

Promise<unknown> · Promise

Returns a promise that resolves when all paused mutations have been resumed.

Example

await mutationCache.resumePausedMutations()

Events

The MutationCache emits the following events:

added

Fired when a mutation is added to the cache.

{
  type: 'added'
  mutation: Mutation
}

removed

Fired when a mutation is removed from the cache.

{
  type: 'removed'
  mutation: Mutation
}

updated

Fired when a mutation is updated.

{
  type: 'updated'
  mutation: Mutation
  action: Action
}

observerAdded

Fired when an observer is added to a mutation.

{
  type: 'observerAdded'
  mutation: Mutation
  observer: MutationObserver
}

observerRemoved

Fired when an observer is removed from a mutation.

{
  type: 'observerRemoved'
  mutation: Mutation
  observer: MutationObserver
}

observerOptionsUpdated

Fired when observer options are updated.

{
  type: 'observerOptionsUpdated'
  mutation?: Mutation
  observer: MutationObserver
}

Mutation Scopes

The MutationCache supports mutation scoping, which allows you to control the order of mutation execution. Mutations with the same scope ID will execute sequentially.

canRun

Checks if a mutation can run based on its scope.

canRun(mutation: Mutation): boolean

mutation · Mutation · required

The mutation to check.

boolean · boolean

Returns true if the mutation can run, false if it must wait for another mutation in the same scope.

runNext

Runs the next pending mutation in the same scope.

runNext(mutation: Mutation): Promise<unknown>

mutation · Mutation · required

The mutation that just completed.

Promise<unknown> · Promise

Returns a promise that resolves when the next mutation continues.

Usage with QueryClient

While you can use MutationCache directly, it’s typically used through a QueryClient:

import { QueryClient, MutationCache } from '@tanstack/query-core'

// Custom cache with event handlers
const mutationCache = new MutationCache({
  onSuccess: (data) => {
    console.log('Global mutation success:', data)
  },
  onError: (error) => {
    console.error('Global mutation error:', error)
  },
})

// Use custom cache with QueryClient
const queryClient = new QueryClient({
  mutationCache,
})