Mutation

Defined in: packages/query-core/src/mutation.ts:135

Represents a single mutation attempt. A Mutation holds the mutation's options, state (data/error/status), and the MutationObservers currently subscribed to it.

Instances are created and managed internally by MutationCache; application code typically interacts with mutations indirectly through QueryClient or a framework hook like useMutation. Direct access to a Mutation instance is possible via mutationCache.find()/getAll() for inspecting cache state.

const mutationCache = queryClient.getMutationCache()

const mutation = mutationCache.find({ mutationKey: ['addPost'] })

const mutationCache = queryClient.getMutationCache()

const mutation = mutationCache.find({ mutationKey: ['addPost'] })

• Removable

TData = unknown

TError = DefaultError

TVariables = unknown

TOnMutateResult = unknown

new Mutation<TData, TError, TVariables, TOnMutateResult>(config: MutationConfig<TData, TError, TVariables, TOnMutateResult>): Mutation<TData, TError, TVariables, TOnMutateResult>;

new Mutation<TData, TError, TVariables, TOnMutateResult>(config: MutationConfig<TData, TError, TVariables, TOnMutateResult>): Mutation<TData, TError, TVariables, TOnMutateResult>;

Defined in: packages/query-core/src/mutation.ts:152

MutationConfig<TData, TError, TVariables, TOnMutateResult>

Mutation<TData, TError, TVariables, TOnMutateResult>

Removable.constructor

Removable.constructor

gcTime: number;

gcTime: number;

Defined in: packages/query-core/src/removable.ts:7

Removable.gcTime

Removable.gcTime

readonly mutationId: number;

readonly mutationId: number;

Defined in: packages/query-core/src/mutation.ts:143

options: MutationOptions<TData, TError, TVariables, TOnMutateResult>;

options: MutationOptions<TData, TError, TVariables, TOnMutateResult>;

Defined in: packages/query-core/src/mutation.ts:142

state: MutationState<TData, TError, TVariables, TOnMutateResult>;

state: MutationState<TData, TError, TVariables, TOnMutateResult>;

Defined in: packages/query-core/src/mutation.ts:141

get meta(): Record<string, unknown> | undefined;

get meta(): Record<string, unknown> | undefined;

Defined in: packages/query-core/src/mutation.ts:179

The meta object passed in the mutation's options, if any.

Record<string, unknown> | undefined

protected clearGcTimeout(): void;

protected clearGcTimeout(): void;

Defined in: packages/query-core/src/removable.ts:32

void

Removable.clearGcTimeout

Removable.clearGcTimeout

continue(): Promise<unknown>;

continue(): Promise<unknown>;

Defined in: packages/query-core/src/mutation.ts:243

Resumes a mutation that is currently paused or was restored from a dehydrated, still-pending state.

• If this mutation has an active retryer (it paused mid-attempt, e.g. due to the network mode or scope-based queuing), its retryer is resumed.
• Otherwise, if the mutation's status is still pending (e.g. it was dehydrated while an attempt was in flight and never got a retryer in this instance), execute is called again with the last known variables.
• Otherwise the mutation has already settled and this resolves immediately without running anything again.

Promise<unknown>

// typically driven by reconnect handling, e.g. queryClient.resumePausedMutations()
const mutation = mutationCache.find({ mutationKey: ['addPost'] })
await mutation?.continue()

// typically driven by reconnect handling, e.g. queryClient.resumePausedMutations()
const mutation = mutationCache.find({ mutationKey: ['addPost'] })
await mutation?.continue()

Mutation#execute

destroy(): void;

destroy(): void;

Defined in: packages/query-core/src/removable.ts:10

void

Removable.destroy

Removable.destroy

execute(variables: TVariables): Promise<TData>;

execute(variables: TVariables): Promise<TData>;

Defined in: packages/query-core/src/mutation.ts:284

Runs the mutation function for the given variables through a retryer, and drives the mutation's state and lifecycle callbacks through to settlement.

If this mutation's state is already pending when execute is called (i.e. it was restored, still in-flight, from a dehydrated state), the onMutate step is skipped and a continue action is dispatched to unpause it; otherwise a pending action is dispatched first, then the mutation cache's onMutate and the mutation's own onMutate option are awaited in that order, and the resulting context is stored.

The mutation function is then run (subject to retry/retryDelay/ networkMode, and to the mutation cache's scope-based serialization). On success, the cache's onSuccess/onSettled callbacks run before the mutation's own onSuccess/onSettled options, a success action is dispatched, and the resolved data is returned. On failure, the same cache-then-option ordering is used for onError/onSettled, but each of those four callbacks is individually caught so that a throwing callback cannot mask the original error; an error action is then dispatched and the original error is re-thrown.

TVariables

Promise<TData>

// Called internally by `MutationObserver.mutate` and `Mutation.continue` —
// applications normally trigger mutations through those, not this method.
const data = await mutation.execute(variables)

// Called internally by `MutationObserver.mutate` and `Mutation.continue` —
// applications normally trigger mutations through those, not this method.
const data = await mutation.execute(variables)

Mutation#continue

protected optionalRemove(): void;

protected optionalRemove(): void;

Defined in: packages/query-core/src/mutation.ts:212

void

Removable.optionalRemove

Removable.optionalRemove

protected scheduleGc(): void;

protected scheduleGc(): void;

Defined in: packages/query-core/src/removable.ts:14

void

Removable.scheduleGc

Removable.scheduleGc

protected updateGcTime(newGcTime: number | undefined): void;

protected updateGcTime(newGcTime: number | undefined): void;

Defined in: packages/query-core/src/removable.ts:24

number | undefined

void

Removable.updateGcTime

Removable.updateGcTime