Add context as callback to useMutation mutate function (#12959)

Author: jerelmiller

.api-reports/api-report-react.api.md

@@ -639,7 +639,9 @@ export namespace useMutation {
     }
     ]) => Promise<ApolloClient.MutateResult<MaybeMasked<TData>>>;
     // (undocumented)
-    export type MutationFunctionOptions<TData = unknown, TVariables extends OperationVariables = OperationVariables, TCache extends ApolloCache = ApolloCache> = Options<TData, TVariables, TCache>;
+    export type MutationFunctionOptions<TData = unknown, TVariables extends OperationVariables = OperationVariables, TCache extends ApolloCache = ApolloCache> = Options<TData, TVariables, TCache> & {
+        context?: DefaultContext | ((hookContext: DefaultContext | undefined) => DefaultContext);
+    };
     // (undocumented)
     export interface Options<TData = unknown, TVariables extends OperationVariables = OperationVariables, TCache extends ApolloCache = ApolloCache, TConfiguredVariables extends Partial<TVariables> = Partial<TVariables>> {
         awaitRefetchQueries?: boolean;

.changeset/big-flowers-move.md

@@ -0,0 +1,23 @@
+---
+"@apollo/client": minor
+---
+
+You can now provide a callback function as the `context` option on the `mutate` function returned by `useMutation`. The callback function is called with the value of the `context` option provided to the `useMutation` hook. This is useful if you'd like to merge the context object provided to the `useMutation` hook with a value provided to the `mutate` function.
+
+
+```ts
+function MyComponent() {
+  const [mutate, result] = useMutation(MUTATION, {
+    context: { foo: true }
+  });
+
+  async function runMutation() {
+    await mutate({
+      // sends context as { foo: true, bar: true }
+      context: (hookContext) => ({ ...hookContext, bar: true })
+    });
+  }
+
+  // ...
+}
+```

docs/source/data/mutations.mdx

@@ -156,6 +156,31 @@ When using TypeScript, you might see an error related to a missing variable when
 
 </Note>
 
+<MinVersion version="4.1">
+
+##### Merging `context` from the hook and `mutate` function
+
+</MinVersion>
+
+Due to option precedence, `context` provided to the `mutate` function overrides `context` provided to the `useMutation` hook. In some cases, you might want to merge the `context` value provided to the hook with a value available at the time you execute the `mutate` function.
+
+You accomplish this by using a callback function for the `context` option provided to the `mutate` function. The callback function is called with the `context` value provided to the hook, allowing you to merge them together.
+
+```ts
+addTodo({
+  context: (hookContext) => ({
+    ...hookContext,
+    myCustomValue: true,
+  }),
+});
+```
+
+<Note>
+
+Your callback function is not required to merge the context values together. The `context` value sent to the link chain is the value returned from the function which makes it possible to change the `context` value in any way you wish, such as omitting a property from the hook context.
+
+</Note>
+
 ### Tracking mutation status
 
 In addition to a mutate function, the `useMutation` hook returns an object that represents the current state of the mutation's execution. The fields of this object include booleans that indicate whether the mutate function has been `called` and whether the mutation's result is currently `loading`.