📝 Add 'shared mutation results' documentation

Author: Shrugsy

docs/rtk-query/api/created-api/hooks.mdx

@@ -315,6 +315,8 @@ type UseMutation = (
 type UseMutationStateOptions = {
   // A method to determine the contents of `UseMutationResult`
   selectFromResult?: (result: UseMutationStateDefaultResult) => any
+  // A string used to enable shared results across hook instances which have the same key
+  fixedCacheKey?: string
 }
 
 type UseMutationTrigger<T> = (arg: any) => Promise<
@@ -328,7 +330,7 @@ type UseMutationTrigger<T> = (arg: any) => Promise<
 
 type UseMutationResult<T> = {
   // Base query state
-  originalArgs?: unknown // Arguments passed to the latest mutation call
+  originalArgs?: unknown // Arguments passed to the latest mutation call. Not available if using the `fixedCacheKey` option
   data?: T // Returned result if present
   error?: unknown // Error result if present
   endpointName?: string // The name of the given endpoint for the mutation
@@ -359,7 +361,9 @@ selectFromResult: () => ({})
 
 - **Parameters**
 
-  - `options`: A set of options that control the subscription behavior of the hook
+  - `options`: A set of options that control the subscription behavior of the hook:
+    - `selectFromResult`: A callback that can be used to customize the mutation result returned as the second item in the tuple
+    - `fixedCacheKey`: An optional string used to enable shared results across hook instances
 
 - **Returns**: A tuple containing:
   - `trigger`: A function that triggers an update to the data based on the provided argument. The trigger function returns a promise with the properties shown above that may be used to handle the behavior of the promise

docs/rtk-query/usage/mutations.mdx

@@ -117,9 +117,63 @@ With RTK Query, a mutation does not contain a semantic distinction between 'load
 
 :::
 
+### Shared Mutation Results
+
+By default, separate instances of a `useMutation` hook are not inherently related to each other.
+Triggering one instance will not affect the result for a separate instance. This applies regardless
+of whether the hooks are called within the same component, or different components.
+
+```tsx no-transpile
+export const ComponentOne = () => {
+  // Triggering `updatePostOne` will affect the result in this component,
+  // but not the result in `ComponentTwo`, and vice-versa
+  const [updatePost, result] = useUpdatePostMutation()
+
+  return <div>...</div>
+}
+
+export const ComponentTwo = () => {
+  const [updatePost, result] = useUpdatePostMutation()
+
+  return <div>...</div>
+}
+```
+
+RTK Query provides an option to share results across mutation hook instances using the
+`fixedCacheKey` option.
+Any `useMutation` hooks with the same `fixedCacheKey` string will share results between each other
+when any of the trigger functions are called. This should be a unique string shared between each
+mutation hook instance you wish to share results.
+
+```tsx no-transpile
+export const ComponentOne = () => {
+  // Triggering `updatePostOne` will affect the result in both this component,
+  // but as well as the result in `ComponentTwo`, and vice-versa
+  const [updatePost, result] = useUpdatePostMutation({
+    fixedCacheKey: 'shared-update-post',
+  })
+
+  return <div>...</div>
+}
+
+export const ComponentTwo = () => {
+  const [updatePost, result] = useUpdatePostMutation({
+    fixedCacheKey: 'shared-update-post',
+  })
+
+  return <div>...</div>
+}
+```
+
+:::note
+
+When using `fixedCacheKey`, the `originalArgs` property is not able to be shared and will always be `undefined`.
+
+:::
+
 ### Standard Mutation Example
 
-This is a modified version of the complete example you can see at the bottom of the page to highlight the `updatePost` mutation. In this scenario, a post is fetched with `useQuery`, and then a `EditablePostName` component is rendered that allows us to edit the name of the post.
+This is a modified version of the complete example you can see at the bottom of the page to highlight the `updatePost` mutation. In this scenario, a post is fetched with `useQuery`, and then an `EditablePostName` component is rendered that allows us to edit the name of the post.
 
 ```tsx title="src/features/posts/PostDetail.tsx"
 export const PostDetail = () => {