Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

mutationOptions.md

214 lines7.1 KB

1---
2id: mutationOptions
3title: mutationOptions
4---
5​
6## Overview
7​
8```ts
9function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
10function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
11```
12​
13- [`WithRequired<CreateMutationOptions>` β†’ `WithRequired<CreateMutationOptions>`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `injectMutationState`.
14- [`Omit<CreateMutationOptions>` β†’ `Omit<CreateMutationOptions>`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No `mutationKey` is required on this overload β€” use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other filters, such as `status`.
15​
16See also: [Parameters](#parameters-summary) Β· [Returns](#returns-summary)
17​
18<a id="call-signature-1"></a>
19​
20## Call Signature
21​
22```ts
23function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
24```
25​
26Defined in: [packages/angular-query-experimental/src/mutation-options.ts:38](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/mutation-options.ts#L38)
27​
28You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A
29`mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
30`injectMutationState`.
31​
32### Type Parameters
33​
34#### TData
35​
36`TData` = `unknown`
37​
38#### TError
39​
40`TError` = `Error`
41​
42#### TVariables
43​
44`TVariables` = `void`
45​
46#### TOnMutateResult
47​
48`TOnMutateResult` = `unknown`
49​
50### Parameters
51​
52#### options
53​
54[`WithRequired`](../type-aliases/WithRequired.md)\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
55​
56The mutation options to use, identical to what you'd pass to `injectMutation`, with a
57required `mutationKey`.
58​
59### Returns
60​
61[`WithRequired`](../type-aliases/WithRequired.md)\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
62​
63The same options object, unchanged.
64​
65### See
66​
67[injectMutation](injectMutation.md) to run the mutation these options describe.
68​
69### Example
70​
71Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
72```angular-ts
73import { mutationOptions, injectMutationState } from '@tanstack/angular-query-experimental'
74​
75const createPostOptions = mutationOptions({
76 mutationKey: ['posts', 'create'],
77 mutationFn: createPost,
78})
79​
80@Component({
81 selector: 'saving-indicator',
82 template: `
83 @if (isCreatingPost()) {
84 <span>Saving…</span>
85 }
86 `,
87})
88export class SavingIndicator {
89 readonly #pendingCreates = injectMutationState(() => ({
90 filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
91 }))
92 readonly isCreatingPost = computed(() => this.#pendingCreates().length > 0)
94```
95​
96<a id="call-signature-2"></a>
97​
98## Call Signature
99​
100```ts
101function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
102```
103​
104Defined in: [packages/angular-query-experimental/src/mutation-options.ts:94](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/mutation-options.ts#L94)
105​
106You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No
107`mutationKey` is required on this overload β€” use this when you don't need to target the mutation via a
108`mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other
109filters, such as `status`.
110​
111### Type Parameters
112​
113#### TData
114​
115`TData` = `unknown`
116​
117#### TError
118​
119`TError` = `Error`
120​
121#### TVariables
122​
123`TVariables` = `void`
124​
125#### TOnMutateResult
126​
127`TOnMutateResult` = `unknown`
128​
129### Parameters
130​
131#### options
132​
133`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
134​
135The mutation options to use, identical to what you'd pass to `injectMutation`, without a
136`mutationKey`.
137​
138### Returns
139​
140`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
141​
142The same options object, unchanged.
143​
144### Remarks
145​
146See the other overload's example for looking a mutation up via `injectMutationState`.
147​
148### See
149​
150[injectMutation](injectMutation.md) to run the mutation these options describe.
151​
152### Example
153​
154Sharing options across services, so `QueriesService` stays the single place a mutation is defined:
155```angular-ts
156import { mutationOptions, injectMutation } from '@tanstack/angular-query-experimental'
157​
158@Injectable({ providedIn: 'root' })
159export class QueriesService {
160 readonly #queryClient = inject(QueryClient)
161​
162 updatePost(id: number) {
163 return mutationOptions({
164 mutationFn: (post: Partial<Post>) => putPost(id, post),
165 onSuccess: (newPost) => this.#queryClient.setQueryData(['posts', id], newPost),
166 })
167 }
169​
170@Component({
171 selector: 'post',
172 template: `<button (click)="save()">Save</button>`,
173})
174export class Post {
175 readonly queries = inject(QueriesService)
176 readonly id = signal(0)
177 readonly updatePostMutation = injectMutation(() => this.queries.updatePost(this.id()))
178​
179 save() {
180 this.updatePostMutation.mutate({ title: 'New Title' })
181 }
183```
184​
185<a id="parameters-summary"></a>
186​
187## Parameters
188​
189### options
190​
191`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
192​
193The mutation options to use, identical to what you'd pass to `injectMutation`, without a
194`mutationKey`.
195​
196<a id="options-properties"></a>
197​
198#### `options` properties
199​
200Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes.
201​
202<a id="returns-summary"></a>
203​
204## Returns
205​
206`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
207​
208The same options object, unchanged.
209​
210<a id="result-properties"></a>
211​
212### Result properties
213​
214Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes.