feat(query-core): add context to mutationfn & mutation callbacks

docs/framework/angular/guides/mutations.md

@@ -89,20 +89,20 @@ export class TodosComponent {
 ```ts
 mutation = injectMutation(() => ({
   mutationFn: addTodo,
-  onMutate: (variables) => {
+  onMutate: (variables, context) => {
     // A mutation is about to happen!
 
-    // Optionally return a context containing data to use when for example rolling back
+    // Optionally return a result containing data to use when for example rolling back
     return { id: 1 }
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // An error happened!
-    console.log(`rolling back optimistic update with id ${context.id}`)
+    console.log(`rolling back optimistic update with id ${onMutateResult.id}`)
   },
-  onSuccess: (data, variables, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // Boom baby!
   },
-  onSettled: (data, error, variables, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // Error or success... doesn't matter!
   },
 }))
@@ -129,25 +129,25 @@ mutation = injectMutation(() => ({
 ```ts
 mutation = injectMutation(() => ({
   mutationFn: addTodo,
-  onSuccess: (data, variables, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // I will fire first
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // I will fire first
   },
-  onSettled: (data, error, variables, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // I will fire first
   },
 }))
 
 mutation.mutate(todo, {
-  onSuccess: (data, variables, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // I will fire second!
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // I will fire second!
   },
-  onSettled: (data, error, variables, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // I will fire second!
   },
 })
@@ -160,15 +160,15 @@ mutation.mutate(todo, {
 export class Example {
   mutation = injectMutation(() => ({
     mutationFn: addTodo,
-    onSuccess: (data, variables, context) => {
+    onSuccess: (data, variables, onMutateResult, context) => {
       // Will be called 3 times
     },
   }))
 
   doMutations() {
     ;['Todo 1', 'Todo 2', 'Todo 3'].forEach((todo) => {
       this.mutation.mutate(todo, {
-        onSuccess: (data, variables, context) => {
+        onSuccess: (data, variables, onMutateResult, context) => {
           // Will execute only once, for the last mutation (Todo 3),
           // regardless which mutation resolves first
         },
@@ -213,31 +213,31 @@ const queryClient = new QueryClient()
 // Define the "addTodo" mutation
 queryClient.setMutationDefaults(['addTodo'], {
   mutationFn: addTodo,
-  onMutate: async (variables) => {
+  onMutate: async (variables, context) => {
     // Cancel current queries for the todos list
-    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    await context.client.cancelQueries({ queryKey: ['todos'] })
 
     // Create optimistic todo
     const optimisticTodo = { id: uuid(), title: variables.title }
 
     // Add optimistic todo to todos list
-    queryClient.setQueryData(['todos'], (old) => [...old, optimisticTodo])
+    context.client.setQueryData(['todos'], (old) => [...old, optimisticTodo])
 
-    // Return context with the optimistic todo
+    // Return result with the optimistic todo
     return { optimisticTodo }
   },
-  onSuccess: (result, variables, context) => {
+  onSuccess: (result, variables, onMutateResult, context) => {
     // Replace optimistic todo in the todos list with the result
-    queryClient.setQueryData(['todos'], (old) =>
+    context.client.setQueryData(['todos'], (old) =>
       old.map((todo) =>
-        todo.id === context.optimisticTodo.id ? result : todo,
+        todo.id === onMutateResult.optimisticTodo.id ? result : todo,
       ),
     )
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // Remove optimistic todo from the todos list
-    queryClient.setQueryData(['todos'], (old) =>
-      old.filter((todo) => todo.id !== context.optimisticTodo.id),
+    context.client.setQueryData(['todos'], (old) =>
+      old.filter((todo) => todo.id !== onMutateResult.optimisticTodo.id),
     )
   },
   retry: 3,

docs/framework/angular/guides/optimistic-updates.md

@@ -87,28 +87,28 @@ queryClient = inject(QueryClient)
 updateTodo = injectMutation(() => ({
   mutationFn: updateTodo,
   // When mutate is called:
-  onMutate: async (newTodo) => {
+  onMutate: async (newTodo, context) => {
     // Cancel any outgoing refetches
     // (so they don't overwrite our optimistic update)
-    await this.queryClient.cancelQueries({ queryKey: ['todos'] })
+    await context.client.cancelQueries({ queryKey: ['todos'] })
 
     // Snapshot the previous value
-    const previousTodos = client.getQueryData(['todos'])
+    const previousTodos = context.client.getQueryData(['todos'])
 
     // Optimistically update to the new value
-    this.queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+    context.client.setQueryData(['todos'], (old) => [...old, newTodo])
 
-    // Return a context object with the snapshotted value
+    // Return a result object with the snapshotted value
     return { previousTodos }
   },
   // If the mutation fails,
-  // use the context returned from onMutate to roll back
-  onError: (err, newTodo, context) => {
-    client.setQueryData(['todos'], context.previousTodos)
+  // use the result returned from onMutate to roll back
+  onError: (err, newTodo, onMutateResult, context) => {
+    context.client.setQueryData(['todos'], onMutateResult.previousTodos)
   },
   // Always refetch after error or success:
-  onSettled: () => {
-    this.queryClient.invalidateQueries({ queryKey: ['todos'] })
+  onSettled: (data, error, variables, onMutateResult, context) => {
+    context.client.invalidateQueries({ queryKey: ['todos'] })
   },
 }))
 ```
@@ -122,30 +122,30 @@ queryClient = inject(QueryClient)
 updateTodo = injectMutation(() => ({
   mutationFn: updateTodo,
   // When mutate is called:
-  onMutate: async (newTodo) => {
+  onMutate: async (newTodo, context) => {
     // Cancel any outgoing refetches
     // (so they don't overwrite our optimistic update)
-    await this.queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
+    await context.client.cancelQueries({ queryKey: ['todos', newTodo.id] })
 
     // Snapshot the previous value
-    const previousTodo = this.queryClient.getQueryData(['todos', newTodo.id])
+    const previousTodo = context.client.getQueryData(['todos', newTodo.id])
 
     // Optimistically update to the new value
-    this.queryClient.setQueryData(['todos', newTodo.id], newTodo)
+    context.client.setQueryData(['todos', newTodo.id], newTodo)
 
-    // Return a context with the previous and new todo
+    // Return a result with the previous and new todo
     return { previousTodo, newTodo }
   },
-  // If the mutation fails, use the context we returned above
-  onError: (err, newTodo, context) => {
-    this.queryClient.setQueryData(
-      ['todos', context.newTodo.id],
-      context.previousTodo,
+  // If the mutation fails, use the result we returned above
+  onError: (err, newTodo, onMutateResult, context) => {
+    context.client.setQueryData(
+      ['todos', onMutateResult.newTodo.id],
+      onMutateResult.previousTodo,
     )
   },
   // Always refetch after error or success:
-  onSettled: (newTodo) => {
-    this.queryClient.invalidateQueries({ queryKey: ['todos', newTodo.id] })
+  onSettled: (newTodo, error, variables, onMutateResult, context) => {
+    context.client.invalidateQueries({ queryKey: ['todos', newTodo.id] })
   },
 }))
 ```
@@ -157,7 +157,7 @@ updateTodo = injectMutation(() => ({
 injectMutation({
   mutationFn: updateTodo,
   // ...
-  onSettled: (newTodo, error, variables, context) => {
+  onSettled: (newTodo, error, variables, onMutateResult, context) => {
     if (error) {
       // do something
     }

docs/framework/angular/reference/functions/injectmutation.md

@@ -8,10 +8,10 @@ title: injectMutation
 # Function: injectMutation()
 
 ```ts
-function injectMutation<TData, TError, TVariables, TContext>(
+function injectMutation<TData, TError, TVariables, TOnMutateResult>(
   injectMutationFn,
   options?,
-): CreateMutationResult<TData, TError, TVariables, TContext>
+): CreateMutationResult<TData, TError, TVariables, TOnMutateResult>
 ```
 
 Defined in: [inject-mutation.ts:44](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/inject-mutation.ts#L44)
@@ -28,13 +28,13 @@ Unlike queries, mutations are not run automatically.
 
 • **TVariables** = `void`
 
-• **TContext** = `unknown`
+• **TOnMutateResult** = `unknown`
 
 ## Parameters
 
 ### injectMutationFn
 
-() => [`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TContext`\>
+() => [`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
 
 A function that returns mutation options.
 
@@ -46,6 +46,6 @@ Additional configuration
 
 ## Returns
 
-[`CreateMutationResult`](../../type-aliases/createmutationresult.md)\<`TData`, `TError`, `TVariables`, `TContext`\>
+[`CreateMutationResult`](../../type-aliases/createmutationresult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
 
 The mutation.

docs/framework/angular/reference/functions/mutationoptions.md

@@ -45,10 +45,10 @@ The mutation options.
 ## Call Signature
 
 ```ts
-function mutationOptions<TData, TError, TVariables, TContext>(
+function mutationOptions<TData, TError, TVariables, TOnMutateResult>(
   options,
 ): WithRequired<
-  CreateMutationOptions<TData, TError, TVariables, TContext>,
+  CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
   'mutationKey'
 >
 ```
@@ -94,19 +94,19 @@ class ComponentOrService {
 
 • **TVariables** = `void`
 
-• **TContext** = `unknown`
+• **TOnMutateResult** = `unknown`
 
 ### Parameters
 
 #### options
 
-`WithRequired`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TContext`\>, `"mutationKey"`\>
+`WithRequired`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
 The mutation options.
 
 ### Returns
 
-`WithRequired`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TContext`\>, `"mutationKey"`\>
+`WithRequired`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
 Mutation options.
 
@@ -119,10 +119,10 @@ The mutation options.
 ## Call Signature
 
 ```ts
-function mutationOptions<TData, TError, TVariables, TContext>(
+function mutationOptions<TData, TError, TVariables, TOnMutateResult>(
   options,
 ): Omit<
-  CreateMutationOptions<TData, TError, TVariables, TContext>,
+  CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
   'mutationKey'
 >
 ```
@@ -168,19 +168,19 @@ class ComponentOrService {
 
 • **TVariables** = `void`
 
-• **TContext** = `unknown`
+• **TOnMutateResult** = `unknown`
 
 ### Parameters
 
 #### options
 
-`Omit`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TContext`\>, `"mutationKey"`\>
+`Omit`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
 The mutation options.
 
 ### Returns
 
-`Omit`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TContext`\>, `"mutationKey"`\>
+`Omit`\<[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
 Mutation options.