snapshot of https://github.com/TanStack/query.git (main, 2026-09-16; blobs > 131072B omitted)

docs/framework/preact/reference/classes/Mutation.md

@@ -0,0 +1,330 @@
+---
+id: Mutation
+title: Mutation
+---
+
+Defined in: [packages/query-core/src/mutation.ts:135](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L135)
+
+Represents a single mutation attempt. A `Mutation` holds the mutation's
+options, state (data/error/status), and the `MutationObserver`s 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
+
+```ts
+const mutationCache = queryClient.getMutationCache()
+
+const mutation = mutationCache.find({ mutationKey: ['addPost'] })
+```
+
+## Extends
+
+- `Removable`
+
+## Type Parameters
+
+### TData
+
+`TData` = `unknown`
+
+### TError
+
+`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
+
+### TVariables
+
+`TVariables` = `unknown`
+
+### TOnMutateResult
+
+`TOnMutateResult` = `unknown`
+
+## Constructors
+
+### Constructor
+
+```ts
+new Mutation<TData, TError, TVariables, TOnMutateResult>(config): Mutation<TData, TError, TVariables, TOnMutateResult>;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:152](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L152)
+
+#### Parameters
+
+##### config
+
+`MutationConfig`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
+
+#### Returns
+
+`Mutation`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
+
+#### Overrides
+
+```ts
+Removable.constructor
+```
+
+## Properties
+
+### gcTime
+
+```ts
+gcTime: number;
+```
+
+Defined in: [packages/query-core/src/removable.ts:7](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L7)
+
+#### Inherited from
+
+```ts
+Removable.gcTime
+```
+
+***
+
+### mutationId
+
+```ts
+readonly mutationId: number;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:143](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L143)
+
+***
+
+### options
+
+```ts
+options: MutationOptions<TData, TError, TVariables, TOnMutateResult>;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:142](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L142)
+
+***
+
+### state
+
+```ts
+state: MutationState<TData, TError, TVariables, TOnMutateResult>;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:141](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L141)
+
+## Accessors
+
+### meta
+
+#### Get Signature
+
+```ts
+get meta(): Record<string, unknown> | undefined;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:179](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L179)
+
+The `meta` object passed in the mutation's options, if any.
+
+##### Returns
+
+`Record`\<`string`, `unknown`\> \| `undefined`
+
+## Methods
+
+### clearGcTimeout()
+
+```ts
+protected clearGcTimeout(): void;
+```
+
+Defined in: [packages/query-core/src/removable.ts:32](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L32)
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+```ts
+Removable.clearGcTimeout
+```
+
+***
+
+### continue()
+
+```ts
+continue(): Promise<unknown>;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:243](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L243)
+
+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
+
+```ts
+// typically driven by reconnect handling, e.g. queryClient.resumePausedMutations()
+const mutation = mutationCache.find({ mutationKey: ['addPost'] })
+await mutation?.continue()
+```
+
+#### See
+
+[Mutation#execute](#execute)
+
+***
+
+### destroy()
+
+```ts
+destroy(): void;
+```
+
+Defined in: [packages/query-core/src/removable.ts:10](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L10)
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+```ts
+Removable.destroy
+```
+
+***
+
+### execute()
+
+```ts
+execute(variables): Promise<TData>;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:284](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L284)
+
+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
+
+##### variables
+
+`TVariables`
+
+#### Returns
+
+`Promise`\<`TData`\>
+
+#### Example
+
+```ts
+// 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](#continue)
+
+***
+
+### optionalRemove()
+
+```ts
+protected optionalRemove(): void;
+```
+
+Defined in: [packages/query-core/src/mutation.ts:212](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L212)
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+```ts
+Removable.optionalRemove
+```
+
+***
+
+### scheduleGc()
+
+```ts
+protected scheduleGc(): void;
+```
+
+Defined in: [packages/query-core/src/removable.ts:14](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L14)
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+```ts
+Removable.scheduleGc
+```
+
+***
+
+### updateGcTime()
+
+```ts
+protected updateGcTime(newGcTime): void;
+```
+
+Defined in: [packages/query-core/src/removable.ts:24](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L24)
+
+#### Parameters
+
+##### newGcTime
+
+`number` | `undefined`
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+```ts
+Removable.updateGcTime
+```