Merge pull request #1631 from Shrugsy/docs/update-mutation-documentation

Author: markerikson

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<
@@ -323,12 +325,12 @@ type UseMutationTrigger<T> = (arg: any) => Promise<
   requestId: string // A string generated by RTK Query
   abort: () => void // A method to cancel the mutation promise
   unwrap: () => Promise<T> // A method to unwrap the mutation call and provide the raw response/error
-  unsubscribe: () => void // A method to manually unsubscribe from the mutation call
+  reset: () => void // A method to manually unsubscribe from the mutation call and reset the result to the uninitialized state
 }
 
 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
@@ -340,6 +342,8 @@ type UseMutationResult<T> = {
   isSuccess: boolean // Mutation has data from a successful call
   isError: boolean // Mutation is currently in an "error" state
   startedTimeStamp?: number // Timestamp for when the latest mutation was initiated
+
+  reset: () => void // A method to manually unsubscribe from the mutation call and reset the result to the uninitialized state
 }
 ```
 
@@ -357,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/error-handling.mdx

@@ -94,7 +94,7 @@ import { toast } from 'your-cool-library'
 export const rtkQueryErrorLogger: Middleware = (api: MiddlewareAPI) => (
   next
 ) => (action) => {
-  // RTK Query uses `createAsyncThunk` from redux-toolkit under the hood, so we're able to utilize these use matchers!
+  // RTK Query uses `createAsyncThunk` from redux-toolkit under the hood, so we're able to utilize these matchers!
   if (isRejectedWithValue(action)) {
     console.warn('We got a rejected action!')
     toast.warn({ title: 'Async error!', message: action.error.data.message })

docs/rtk-query/usage/mutations.mdx

@@ -109,16 +109,71 @@ Below are some of the most frequently used properties on the "mutation result" o
 - `isLoading` - When true, indicates that the mutation has been fired and is awaiting a response.
 - `isSuccess` - When true, indicates that the last mutation fired has data from a successful request.
 - `isError` - When true, indicates that the last mutation fired resulted in an error state.
+- `reset` - A method to reset the hook back to it's original state and remove the current result from the cache
 
 :::note
 
 With RTK Query, a mutation does not contain a semantic distinction between 'loading' and 'fetching' in the way that a [query does](./queries.mdx#frequently-used-query-hook-return-values). For a mutation, subsequent calls are not assumed to be necessarily related, so a mutation is either 'loading' or 'not loading', with no concept of 're-fetching'.
 
 :::
 
+### 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 = () => {