katanakit-js / Mutation

Class: Mutation<TData, TError, TVariables, TOnMutateResult>

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:789

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.

Example

const mutationCache = queryClient.getMutationCache()

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

Extends

• Removable

Type Parameters

Type Parameter	Default type
TData	unknown
TError	DefaultError
TVariables	unknown
TOnMutateResult	unknown

Constructors

Constructor

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

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:794

Parameters

Parameter	Type
config	MutationConfig<TData, TError, TVariables, TOnMutateResult>

Returns

Mutation<TData, TError, TVariables, TOnMutateResult>

Overrides

Removable.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
gcTime	public	number	Removable.gcTime	node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/removable-0GzhW1PK.d.ts:8
mutationId	readonly	number	-	node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:793
options	public	MutationOptions<TData, TError, TVariables, TOnMutateResult>	-	node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:792
state	public	MutationState<TData, TError, TVariables, TOnMutateResult>	-	node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:791

Accessors

meta

Get Signature

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

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:800

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

Returns

Record<string, unknown> | undefined

Methods

clearGcTimeout()

protected clearGcTimeout(): void;

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/removable-0GzhW1PK.d.ts:17

Returns

void

Inherited from

Removable.clearGcTimeout

---

continue()

continue(): Promise<unknown>;

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:827

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.

Returns

Promise<unknown>

Example

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

See

Mutation#execute

---

destroy()

destroy(): void;

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/removable-0GzhW1PK.d.ts:14

Clears the pending garbage collection timeout, so the entry is no longer scheduled for removal. A subclass may override this to release what it holds on to as well — Query also cancels any in-flight fetch.

Returns

void

Inherited from

Removable.destroy

---

execute()

execute(variables): Promise<TData>;

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:858

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.

Parameters

Parameter	Type
variables	TVariables

Returns

Promise<TData>

Example

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

See

Mutation#continue

---

optionalRemove()

protected optionalRemove(): void;

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/hydration-B9t5w6NC.d.ts:805

Returns

void

Overrides

Removable.optionalRemove

---

scheduleGc()

protected scheduleGc(): void;

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/removable-0GzhW1PK.d.ts:15

Returns

void

Inherited from

Removable.scheduleGc

---

updateGcTime()

protected updateGcTime(newGcTime): void;

Defined in: node_modules/.bun/@tanstack+query-core@5.104.1/node_modules/@tanstack/query-core/build/modern/removable-0GzhW1PK.d.ts:16

Parameters

Parameter	Type
newGcTime	number | undefined

Returns

void

Inherited from

Removable.updateGcTime