feat(query-core): add context to mutationfn

Co-Authored-By: travikk <[email protected]>

Author: joshuaellis

docs/framework/angular/guides/mutations.md

@@ -90,20 +90,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 scope containing data to use when for example rolling back
     return { id: 1 }
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, scope) => {
     // An error happened!
-    console.log(`rolling back optimistic update with id ${context.id}`)
+    console.log(`rolling back optimistic update with id ${scope.id}`)
   },
-  onSuccess: (data, variables, context) => {
+  onSuccess: (data, variables, scope) => {
     // Boom baby!
   },
-  onSettled: (data, error, variables, context) => {
+  onSettled: (data, error, variables, scope) => {
     // Error or success... doesn't matter!
   },
 }))
@@ -130,25 +130,25 @@ mutation = injectMutation(() => ({
 ```ts
 mutation = injectMutation(() => ({
   mutationFn: addTodo,
-  onSuccess: (data, variables, context) => {
+  onSuccess: (data, variables, scope) => {
     // I will fire first
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, scope) => {
     // I will fire first
   },
-  onSettled: (data, error, variables, context) => {
+  onSettled: (data, error, variables, scope) => {
     // I will fire first
   },
 }))
 
 mutation.mutate(todo, {
-  onSuccess: (data, variables, context) => {
+  onSuccess: (data, variables, scope) => {
     // I will fire second!
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, scope) => {
     // I will fire second!
   },
-  onSettled: (data, error, variables, context) => {
+  onSettled: (data, error, variables, scope) => {
     // I will fire second!
   },
 })
@@ -161,15 +161,15 @@ mutation.mutate(todo, {
 export class Example {
   mutation = injectMutation(() => ({
     mutationFn: addTodo,
-    onSuccess: (data, variables, context) => {
+    onSuccess: (data, variables, scope) => {
       // 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, scope) => {
           // Will execute only once, for the last mutation (Todo 3),
           // regardless which mutation resolves first
         },
@@ -214,31 +214,29 @@ 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 { optimisticTodo }
+    // Return scope with the optimistic todo
+    return { optimisticTodo, client: context.client }
   },
-  onSuccess: (result, variables, context) => {
+  onSuccess: (result, variables, scope) => {
     // Replace optimistic todo in the todos list with the result
-    queryClient.setQueryData(['todos'], (old) =>
-      old.map((todo) =>
-        todo.id === context.optimisticTodo.id ? result : todo,
-      ),
+    scope.client.setQueryData(['todos'], (old) =>
+      old.map((todo) => (todo.id === scope.optimisticTodo.id ? result : todo)),
     )
   },
-  onError: (error, variables, context) => {
+  onError: (error, variables, scope) => {
     // Remove optimistic todo from the todos list
-    queryClient.setQueryData(['todos'], (old) =>
-      old.filter((todo) => todo.id !== context.optimisticTodo.id),
+    scope.client.setQueryData(['todos'], (old) =>
+      old.filter((todo) => todo.id !== scope.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 { previousTodos }
+    // Return a scope object with the snapshotted value
+    return { previousTodos, client: context.client }
   },
   // If the mutation fails,
-  // use the context returned from onMutate to roll back
-  onError: (err, newTodo, context) => {
-    client.setQueryData(['todos'], context.previousTodos)
+  // use the scope returned from onMutate to roll back
+  onError: (err, newTodo, scope) => {
+    scope.client.setQueryData(['todos'], scope.previousTodos)
   },
   // Always refetch after error or success:
-  onSettled: () => {
-    this.queryClient.invalidateQueries({ queryKey: ['todos'] })
+  onSettled: (data, error, variables, scope) => {
+    scope.client.invalidateQueries({ queryKey: ['todos'] })
   },
 }))
 ```
@@ -122,30 +122,27 @@ 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 { previousTodo, newTodo }
+    // Return a scope with the previous and new todo
+    return { previousTodo, newTodo, client: context.client }
   },
-  // 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 scope we returned above
+  onError: (err, newTodo, scope) => {
+    scope.client.setQueryData(['todos', scope.newTodo.id], scope.previousTodo)
   },
   // Always refetch after error or success:
-  onSettled: (newTodo) => {
-    this.queryClient.invalidateQueries({ queryKey: ['todos', newTodo.id] })
+  onSettled: (newTodo, error, variables, scope) => {
+    scope.client.invalidateQueries({ queryKey: ['todos', newTodo.id] })
   },
 }))
 ```
@@ -157,7 +154,7 @@ updateTodo = injectMutation(() => ({
 injectMutation({
   mutationFn: updateTodo,
   // ...
-  onSettled: (newTodo, error, variables, context) => {
+  onSettled: (newTodo, error, variables, scope) => {
     if (error) {
       // do something
     }

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

@@ -6,10 +6,10 @@ title: injectMutation
 # Function: injectMutation()
 
 ```ts
-function injectMutation<TData, TError, TVariables, TContext>(
+function injectMutation<TData, TError, TVariables, TScope>(
   injectMutationFn,
   options?,
-): CreateMutationResult<TData, TError, TVariables, TContext>
+): CreateMutationResult<TData, TError, TVariables, TScope>
 ```
 
 Injects a mutation: an imperative function that can be invoked which typically performs server side effects.
@@ -24,13 +24,13 @@ Unlike queries, mutations are not run automatically.
 
 • **TVariables** = `void`
 
-• **TContext** = `unknown`
+• **TScope** = `unknown`
 
 ## Parameters
 
 ### injectMutationFn
 
-() => [`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TContext`\>
+() => [`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TScope`\>
 
 A function that returns mutation options.
 
@@ -42,7 +42,7 @@ Additional configuration
 
 ## Returns
 
-[`CreateMutationResult`](../../type-aliases/createmutationresult.md)\<`TData`, `TError`, `TVariables`, `TContext`\>
+[`CreateMutationResult`](../../type-aliases/createmutationresult.md)\<`TData`, `TError`, `TVariables`, `TScope`\>
 
 The mutation.
 

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

@@ -6,9 +6,9 @@ title: mutationOptions
 # Function: mutationOptions()
 
 ```ts
-function mutationOptions<TData, TError, TVariables, TContext>(
+function mutationOptions<TData, TError, TVariables, TScope>(
   options,
-): CreateMutationOptions<TData, TError, TVariables, TContext>
+): CreateMutationOptions<TData, TError, TVariables, TScope>
 ```
 
 Allows to share and re-use mutation options in a type-safe way.
@@ -46,19 +46,19 @@ mutation.mutate({ title: 'New Title' })
 
 • **TVariables** = `void`
 
-• **TContext** = `unknown`
+• **TScope** = `unknown`
 
 ## Parameters
 
 ### options
 
-`MutationObserverOptions`\<`TData`, `TError`, `TVariables`, `TContext`\>
+`MutationObserverOptions`\<`TData`, `TError`, `TVariables`, `TScope`\>
 
 The mutation options.
 
 ## Returns
 
-[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TContext`\>
+[`CreateMutationOptions`](../../interfaces/createmutationoptions.md)\<`TData`, `TError`, `TVariables`, `TScope`\>
 
 Mutation options.
 

docs/framework/angular/reference/interfaces/basemutationnarrowing.md

@@ -3,7 +3,7 @@ id: BaseMutationNarrowing
 title: BaseMutationNarrowing
 ---
 
-# Interface: BaseMutationNarrowing\<TData, TError, TVariables, TContext\>
+# Interface: BaseMutationNarrowing\<TData, TError, TVariables, TScope\>
 
 ## Type Parameters
 
@@ -13,7 +13,7 @@ title: BaseMutationNarrowing
 
 • **TVariables** = `unknown`
 
-• **TContext** = `unknown`
+• **TScope** = `unknown`
 
 ## Properties
 
@@ -25,17 +25,12 @@ isError: SignalFunction<
     TData,
     TError,
     TVariables,
-    TContext,
+    TScope,
     Override<
-      MutationObserverErrorResult<TData, TError, TVariables, TContext>,
-      { mutate: CreateMutateFunction<TData, TError, TVariables, TContext> }
+      MutationObserverErrorResult<TData, TError, TVariables, TScope>,
+      { mutate: CreateMutateFunction<TData, TError, TVariables, TScope> }
     > & {
-      mutateAsync: CreateMutateAsyncFunction<
-        TData,
-        TError,
-        TVariables,
-        TContext
-      >
+      mutateAsync: CreateMutateAsyncFunction<TData, TError, TVariables, TScope>
     }
   >
 >
@@ -55,17 +50,12 @@ isIdle: SignalFunction<
     TData,
     TError,
     TVariables,
-    TContext,
+    TScope,
     Override<
-      MutationObserverIdleResult<TData, TError, TVariables, TContext>,
-      { mutate: CreateMutateFunction<TData, TError, TVariables, TContext> }
+      MutationObserverIdleResult<TData, TError, TVariables, TScope>,
+      { mutate: CreateMutateFunction<TData, TError, TVariables, TScope> }
     > & {
-      mutateAsync: CreateMutateAsyncFunction<
-        TData,
-        TError,
-        TVariables,
-        TContext
-      >
+      mutateAsync: CreateMutateAsyncFunction<TData, TError, TVariables, TScope>
     }
   >
 >
@@ -85,17 +75,12 @@ isPending: SignalFunction<
     TData,
     TError,
     TVariables,
-    TContext,
+    TScope,
     Override<
-      MutationObserverLoadingResult<TData, TError, TVariables, TContext>,
-      { mutate: CreateMutateFunction<TData, TError, TVariables, TContext> }
+      MutationObserverLoadingResult<TData, TError, TVariables, TScope>,
+      { mutate: CreateMutateFunction<TData, TError, TVariables, TScope> }
     > & {
-      mutateAsync: CreateMutateAsyncFunction<
-        TData,
-        TError,
-        TVariables,
-        TContext
-      >
+      mutateAsync: CreateMutateAsyncFunction<TData, TError, TVariables, TScope>
     }
   >
 >
@@ -115,17 +100,12 @@ isSuccess: SignalFunction<
     TData,
     TError,
     TVariables,
-    TContext,
+    TScope,
     Override<
-      MutationObserverSuccessResult<TData, TError, TVariables, TContext>,
-      { mutate: CreateMutateFunction<TData, TError, TVariables, TContext> }
+      MutationObserverSuccessResult<TData, TError, TVariables, TScope>,
+      { mutate: CreateMutateFunction<TData, TError, TVariables, TScope> }
     > & {
-      mutateAsync: CreateMutateAsyncFunction<
-        TData,
-        TError,
-        TVariables,
-        TContext
-      >
+      mutateAsync: CreateMutateAsyncFunction<TData, TError, TVariables, TScope>
     }
   >
 >