chore: rename to onMutateResult

Author: joshuaellis

docs/framework/angular/guides/mutations.md

@@ -93,17 +93,17 @@ mutation = injectMutation(() => ({
   onMutate: (variables, context) => {
     // A mutation is about to happen!
 
-    // Optionally return a scope 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, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // An error happened!
     console.log(`rolling back optimistic update with id ${scope.id}`)
   },
-  onSuccess: (data, variables, scope, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // Boom baby!
   },
-  onSettled: (data, error, variables, scope, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // Error or success... doesn't matter!
   },
 }))
@@ -130,25 +130,25 @@ mutation = injectMutation(() => ({
 ```ts
 mutation = injectMutation(() => ({
   mutationFn: addTodo,
-  onSuccess: (data, variables, scope, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // I will fire first
   },
-  onError: (error, variables, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // I will fire first
   },
-  onSettled: (data, error, variables, scope, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // I will fire first
   },
 }))
 
 mutation.mutate(todo, {
-  onSuccess: (data, variables, scope, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // I will fire second!
   },
-  onError: (error, variables, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // I will fire second!
   },
-  onSettled: (data, error, variables, scope, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // I will fire second!
   },
 })
@@ -161,15 +161,15 @@ mutation.mutate(todo, {
 export class Example {
   mutation = injectMutation(() => ({
     mutationFn: addTodo,
-    onSuccess: (data, variables, scope, 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, scope, context) => {
+        onSuccess: (data, variables, onMutateResult, context) => {
           // Will execute only once, for the last mutation (Todo 3),
           // regardless which mutation resolves first
         },
@@ -227,16 +227,18 @@ queryClient.setMutationDefaults(['addTodo'], {
     // Return scope with the optimistic todo
     return { optimisticTodo }
   },
-  onSuccess: (result, variables, scope, context) => {
+  onSuccess: (result, variables, onMutateResult, context) => {
     // Replace optimistic todo in the todos list with the result
     context.client.setQueryData(['todos'], (old) =>
-      old.map((todo) => (todo.id === scope.optimisticTodo.id ? result : todo)),
+      old.map((todo) =>
+        todo.id === onMutateResult.optimisticTodo.id ? result : todo,
+      ),
     )
   },
-  onError: (error, variables, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // Remove optimistic todo from the todos list
     context.client.setQueryData(['todos'], (old) =>
-      old.filter((todo) => todo.id !== scope.optimisticTodo.id),
+      old.filter((todo) => todo.id !== onMutateResult.optimisticTodo.id),
     )
   },
   retry: 3,

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

@@ -98,16 +98,16 @@ updateTodo = injectMutation(() => ({
     // Optimistically update to the new value
     context.client.setQueryData(['todos'], (old) => [...old, newTodo])
 
-    // Return a scope object with the snapshotted value
+    // Return a result object with the snapshotted value
     return { previousTodos }
   },
   // If the mutation fails,
-  // use the scope returned from onMutate to roll back
-  onError: (err, newTodo, scope, context) => {
-    context.client.setQueryData(['todos'], scope.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: (data, error, variables, scope, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     context.client.invalidateQueries({ queryKey: ['todos'] })
   },
 }))
@@ -133,15 +133,18 @@ updateTodo = injectMutation(() => ({
     // Optimistically update to the new value
     context.client.setQueryData(['todos', newTodo.id], newTodo)
 
-    // Return a scope with the previous and new todo
+    // Return a result with the previous and new todo
     return { previousTodo, newTodo }
   },
-  // If the mutation fails, use the scope we returned above
-  onError: (err, newTodo, scope, context) => {
-    context.client.setQueryData(['todos', scope.newTodo.id], scope.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, error, variables, scope, context) => {
+  onSettled: (newTodo, error, variables, onMutateResult, context) => {
     context.client.invalidateQueries({ queryKey: ['todos', newTodo.id] })
   },
 }))
@@ -154,7 +157,7 @@ updateTodo = injectMutation(() => ({
 injectMutation({
   mutationFn: updateTodo,
   // ...
-  onSettled: (newTodo, error, variables, scope) => {
+  onSettled: (newTodo, error, variables, onMutateResult, context) => {
     if (error) {
       // do something
     }

docs/framework/react/guides/mutations.md

@@ -149,14 +149,14 @@ useMutation({
     // Optionally return a scope containing data to use when for example rolling back
     return { id: 1 }
   },
-  onError: (error, variables, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // An error happened!
-    console.log(`rolling back optimistic update with id ${scope.id}`)
+    console.log(`rolling back optimistic update with id ${onMutateResult.id}`)
   },
-  onSuccess: (data, variables, scope, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // Boom baby!
   },
-  onSettled: (data, error, variables, scope, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // Error or success... doesn't matter!
   },
 })
@@ -189,25 +189,25 @@ You might find that you want to **trigger additional callbacks** beyond the ones
 ```tsx
 useMutation({
   mutationFn: addTodo,
-  onSuccess: (data, variables, scope, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // I will fire first
   },
-  onError: (error, variables, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // I will fire first
   },
-  onSettled: (data, error, variables, scope, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // I will fire first
   },
 })
 
 mutate(todo, {
-  onSuccess: (data, variables, scope, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // I will fire second!
   },
-  onError: (error, variables, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // I will fire second!
   },
-  onSettled: (data, error, variables, scope, context) => {
+  onSettled: (data, error, variables, onMutateResult, context) => {
     // I will fire second!
   },
 })
@@ -226,15 +226,15 @@ There is a slight difference in handling `onSuccess`, `onError` and `onSettled`
 ```tsx
 useMutation({
   mutationFn: addTodo,
-  onSuccess: (data, variables, scope, context) => {
+  onSuccess: (data, variables, onMutateResult, context) => {
     // Will be called 3 times
   },
 })
 
 const todos = ['Todo 1', 'Todo 2', 'Todo 3']
 todos.forEach((todo) => {
   mutate(todo, {
-    onSuccess: (data, variables, scope, context) => {
+    onSuccess: (data, variables, onMutateResult, context) => {
       // Will execute only once, for the last mutation (Todo 3),
       // regardless which mutation resolves first
     },
@@ -304,19 +304,21 @@ queryClient.setMutationDefaults(['addTodo'], {
     // Add optimistic todo to todos list
     context.client.setQueryData(['todos'], (old) => [...old, optimisticTodo])
 
-    // Return scope with the optimistic todo
+    // Return onMutateResult with the optimistic todo
     return { optimisticTodo }
   },
-  onSuccess: (result, variables, scope, context) => {
+  onSuccess: (result, variables, onMutateResult, context) => {
     // Replace optimistic todo in the todos list with the result
     context.client.setQueryData(['todos'], (old) =>
-      old.map((todo) => (todo.id === scope.optimisticTodo.id ? result : todo)),
+      old.map((todo) =>
+        todo.id === onMutateResult.optimisticTodo.id ? result : todo,
+      ),
     )
   },
-  onError: (error, variables, scope, context) => {
+  onError: (error, variables, onMutateResult, context) => {
     // Remove optimistic todo from the todos list
     context.client.setQueryData(['todos'], (old) =>
-      old.filter((todo) => todo.id !== scope.optimisticTodo.id),
+      old.filter((todo) => todo.id !== onMutateResult.optimisticTodo.id),
     )
   },
   retry: 3,

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

@@ -110,16 +110,16 @@ useMutation({
     // Optimistically update to the new value
     context.client.setQueryData(['todos'], (old) => [...old, newTodo])
 
-    // Return a scope object with the snapshotted value
+    // Return a result with the snapshotted value
     return { previousTodos }
   },
   // If the mutation fails,
-  // use the scope returned from onMutate to roll back
-  onError: (err, newTodo, scope, context) => {
-    context.client.setQueryData(['todos'], scope.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: (data, error, variables, scope, context) =>
+  onSettled: (data, error, variables, onMutateResult, context) =>
     context.client.invalidateQueries({ queryKey: ['todos'] }),
 })
 ```
@@ -145,15 +145,18 @@ useMutation({
     // Optimistically update to the new value
     context.client.setQueryData(['todos', newTodo.id], newTodo)
 
-    // Return a scope with the previous and new todo
+    // Return a result with the previous and new todo
     return { previousTodo, newTodo }
   },
-  // If the mutation fails, use the scope we returned above
-  onError: (err, newTodo, scope, context) => {
-    context.client.setQueryData(['todos', scope.newTodo.id], scope.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, error, variables, scope, context) =>
+  onSettled: (newTodo, error, variables, onMutateResult, context) =>
     context.client.invalidateQueries({ queryKey: ['todos', newTodo.id] }),
 })
 ```
@@ -168,7 +171,7 @@ You can also use the `onSettled` function in place of the separate `onError` and
 useMutation({
   mutationFn: updateTodo,
   // ...
-  onSettled: async (newTodo, error, variables, scope) => {
+  onSettled: async (newTodo, error, variables, onMutateResult, context) => {
     if (error) {
       // do something
     }

docs/framework/react/reference/useMutation.md

@@ -69,15 +69,15 @@ mutate(variables, {
   - This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
   - Useful to perform optimistic updates to a resource in hopes that the mutation succeeds
   - The value returned from this function will be passed to both the `onError` and `onSettled` functions in the event of a mutation failure and can be useful for rolling back optimistic updates.
-- `onSuccess: (data: TData, variables: TVariables, scope: TScope | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown`
+- `onSuccess: (data: TData, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown`
   - Optional
   - This function will fire when the mutation is successful and will be passed the mutation's result.
   - If a promise is returned, it will be awaited and resolved before proceeding
-- `onError: (err: TError, variables: TVariables, scope: TScope | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown`
+- `onError: (err: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown`
   - Optional
   - This function will fire if the mutation encounters an error and will be passed the error.
   - If a promise is returned, it will be awaited and resolved before proceeding
-- `onSettled: (data: TData, error: TError, variables: TVariables, scope: TScope | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown`
+- `onSettled: (data: TData, error: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown`
   - Optional
   - This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
   - If a promise is returned, it will be awaited and resolved before proceeding
@@ -114,15 +114,15 @@ mutate(variables, {
   - `variables: TVariables`
     - Optional
     - The variables object to pass to the `mutationFn`.
-  - `onSuccess: (data: TData, variables: TVariables, scope: TScope | undefined, context: MutationFunctionContext) => void`
+  - `onSuccess: (data: TData, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void`
     - Optional
     - This function will fire when the mutation is successful and will be passed the mutation's result.
     - Void function, the returned value will be ignored
-  - `onError: (err: TError, variables: TVariables, scope: TScope | undefined, context: MutationFunctionContext) => void`
+  - `onError: (err: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void`
     - Optional
     - This function will fire if the mutation encounters an error and will be passed the error.
     - Void function, the returned value will be ignored
-  - `onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, scope: TScope | undefined, context: MutationFunctionContext) => void`
+  - `onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void`
     - Optional
     - This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
     - Void function, the returned value will be ignored

examples/react/optimistic-updates-cache/src/pages/index.tsx

@@ -71,14 +71,17 @@ function Example() {
       return { previousTodos }
     },
     // If the mutation fails,
-    // use the scope returned from onMutate to roll back
-    onError: (err, variables, scope, context) => {
-      if (scope?.previousTodos) {
-        context.client.setQueryData<Todos>(['todos'], scope.previousTodos)
+    // use the result returned from onMutate to roll back
+    onError: (err, variables, onMutateResult, context) => {
+      if (onMutateResult?.previousTodos) {
+        context.client.setQueryData<Todos>(
+          ['todos'],
+          onMutateResult.previousTodos,
+        )
       }
     },
     // Always refetch after error or success:
-    onSettled: (data, error, variables, scope, context) =>
+    onSettled: (data, error, variables, onMutateResult, context) =>
       context.client.invalidateQueries({ queryKey: ['todos'] }),
   })
 

packages/angular-query-experimental/src/__tests__/mutation-options.test-d.ts

@@ -64,10 +64,12 @@ describe('mutationOptions', () => {
       mutationFn: () => Promise.resolve(5),
       mutationKey: ['key'],
       onMutate: () => {
-        return { name: 'scope' }
+        return { name: 'onMutateResult' }
       },
-      onSuccess: (_data, _variables, scope) => {
-        expectTypeOf(scope).toEqualTypeOf<{ name: string } | undefined>()
+      onSuccess: (_data, _variables, onMutateResult) => {
+        expectTypeOf(onMutateResult).toEqualTypeOf<
+          { name: string } | undefined
+        >()
       },
     })
   })
@@ -82,13 +84,13 @@ describe('mutationOptions', () => {
       onMutate: (_variables, context) => {
         expectTypeOf(context).toEqualTypeOf<MutationFunctionContext>()
       },
-      onSuccess: (_data, _variables, _scope, context) => {
+      onSuccess: (_data, _variables, _onMutateResult, context) => {
         expectTypeOf(context).toEqualTypeOf<MutationFunctionContext>()
       },
-      onError: (_error, _variables, _scope, context) => {
+      onError: (_error, _variables, _onMutateResult, context) => {
         expectTypeOf(context).toEqualTypeOf<MutationFunctionContext>()
       },
-      onSettled: (_data, _error, _variables, _scope, context) => {
+      onSettled: (_data, _error, _variables, _onMutateResult, context) => {
         expectTypeOf(context).toEqualTypeOf<MutationFunctionContext>()
       },
     })