Merge pull request reduxjs#1259 from Shrugsy/docs/show-unwrap-property-usage

📝 Document .unwrap() usage for createAsyncThunk

Author: markerikson

docs/api/createAsyncThunk.mdx

@@ -246,25 +246,78 @@ const onClick = () => {
 
 The thunks generated by `createAsyncThunk` **will always return a resolved promise** with either the `fulfilled` action object or `rejected` action object inside, as appropriate.
 
-The calling logic may wish to treat these actions as if they were the original promise contents. Redux Toolkit exports an `unwrapResult` function that can be used to extract the `payload` of a `fulfilled` action or to throw either the `error` or, if available, `payload` created by `rejectWithValue` from a `rejected` action:
+The calling logic may wish to treat these actions as if they were the original promise contents. The promise returned by the dispatched thunk has an `unwrap` property which can be called to extract the `payload` of a `fulfilled` action or to throw either the `error` or, if available, `payload` created by `rejectWithValue` from a `rejected` action:
 
-```js
+```ts no-transpile
+// in the component
+
+const onClick = () => {
+  dispatch(fetchUserById(userId))
+    .unwrap()
+    .then((originalPromiseResult) => {
+      // handle result here
+    })
+    .catch((rejectedValueOrSerializedError) => {
+      // handle error here
+    })
+}
+```
+
+Or with async/await syntax:
+
+```ts no-transpile
+// in the component
+
+const onClick = async () => {
+  try {
+    const originalPromiseResult = await dispatch(fetchUserById(userId)).unwrap()
+    // handle result here
+  } catch (rejectedValueOrSerializedError) {
+    // handle error here
+  }
+}
+```
+
+Using the attached `.unwrap()` property is preferred in most cases, however Redux Toolkit also exports an `unwrapResult` function that can be used for a similar purpose:
+
+```ts no-transpile
 import { unwrapResult } from '@reduxjs/toolkit'
 
 // in the component
 const onClick = () => {
   dispatch(fetchUserById(userId))
     .then(unwrapResult)
-    .then((originalPromiseResult) => {})
-    .catch((rejectedValueOrSerializedError) => {})
+    .then((originalPromiseResult) => {
+      // handle result here
+    })
+    .catch((rejectedValueOrSerializedError) => {
+      // handle result here
+    })
+}
+```
+
+Or with async/await syntax:
+
+```ts no-transpile
+import { unwrapResult } from '@reduxjs/toolkit'
+
+// in the component
+const onClick = async () => {
+  try {
+    const resultAction = await dispatch(fetchUserById(userId))
+    const originalPromiseResult = unwrapResult(resultAction)
+    // handle result here
+  } catch (rejectedValueOrSerializedError) {
+    // handle error here
+  }
 }
 ```
 
 ### Checking Errors After Dispatching
 
 Note that this means **a failed request or error in a thunk will _never_ return a _rejected_ promise**. We assume that any failure is more of a handled error than an unhandled exception at this point. This is due to the fact that we want to prevent uncaught promise rejections for those who do not use the result of `dispatch`.
 
-If your component needs to know if the request failed, use `unwrapResult` and handle the re-thrown error accordingly.
+If your component needs to know if the request failed, use `.unwrap` or `unwrapResult` and handle the re-thrown error accordingly.
 
 ## Handling Thunk Errors
 
@@ -449,7 +502,7 @@ const fetchUserById = createAsyncThunk(
 - Requesting a user by ID, with loading state, and only one request at a time:
 
 ```js
-import { createAsyncThunk, createSlice, unwrapResult } from '@reduxjs/toolkit'
+import { createAsyncThunk, createSlice } from '@reduxjs/toolkit'
 import { userAPI } from './userAPI'
 
 const fetchUserById = createAsyncThunk(
@@ -512,8 +565,7 @@ const UsersComponent = () => {
 
   const fetchOneUser = async (userId) => {
     try {
-      const resultAction = await dispatch(fetchUserById(userId))
-      const user = unwrapResult(resultAction)
+      const user = await dispatch(fetchUserById(userId)).unwrap()
       showToast('success', `Fetched ${user.name}`)
     } catch (err) {
       showToast('error', `Fetch failed: ${err.message}`)
@@ -545,7 +597,7 @@ export declare const userAPI: {
 }
 
 // file: user/slice.ts
-import { createAsyncThunk, createSlice, unwrapResult } from '@reduxjs/toolkit'
+import { createAsyncThunk, createSlice } from '@reduxjs/toolkit'
 import { userAPI } from './userAPI'
 import { AxiosError } from 'axios'