- restructure hook return values on query & mutation usage pages

Author: Shrugsy

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

@@ -325,10 +325,10 @@ type UseMutationResult<T> = {
   fulfilledTimestamp?: number // Timestamp for when the mutation was completed
 
   // Derived request status booleans
-  isError: boolean // Mutation is currently in an "error" state
+  isUninitialized: boolean // Mutation has not been fired yet
   isLoading: boolean // Mutation has been fired and is awaiting a response
   isSuccess: boolean // Mutation has data from a successful call
-  isUninitialized: boolean // Mutation has not been fired yet
+  isError: boolean // Mutation is currently in an "error" state
   startedTimeStamp?: number // Timestamp for when the latest mutation was initiated
 }
 ```

docs/usage/rtk-query/mutations.mdx

@@ -70,20 +70,32 @@ const api = createApi({
 Notice the `onQueryStarted` method? Be sure to check out how it can be used for [optimistic updates](./optimistic-updates)
 :::
 
-### Basic Mutation with React Hooks
-
-#### Mutation Hook Trigger Type
-
-```ts title="Mutation hook type" no-transpile
-type UseMutationTrigger<T> = (
-  arg: any
-) => Promise<{ data: T } | { error: BaseQueryError | SerializedError }> & {
-  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
-}
-```
+### Performing Mutations with React Hooks
+
+#### Frequently Used Mutation Hook Return Values
+
+The `useMutation` hook returns a tuple containing a `mutation trigger` function, as well as an object containing properties about the `mutation result`.
+
+The `mutation trigger` is a function that when called, will fire off the mutation request for that endpoint. Calling the `mutation trigger` returns a promise with an `unwrap` property, which can be called to unwrap the mutation call and provide the raw response/error. This can be useful if you wish to determine whether the mutation succeeds/fails inline at the call-site.
+
+The `mutation result` is an object containing properties such as the latest `data` for the mutation request, as well as status booleans for the current request lifecycle state.
+
+Below are some of the most frequently used properties on the `mutation result` object. Refer to [`useMutation`](../../api/rtk-query/created-api/hooks.mdx#usemutation) for an extensive list of all returned properties.
+
+- `data` - The returned result if present.
+- `error` - The error result if present.
+- `isUninitialized` - When true, indicates that the mutation has not been fired yet.
+- `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.
+
+:::note
+
+With RTK Query, a mutation does 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'.
+
+:::
+
+#### 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.
 
@@ -93,11 +105,12 @@ export const PostDetail = () => {
 
   const { data: post } = useGetPostQuery(id)
 
+  // highlight-start
   const [
-    // highlight-next-line
     updatePost, // This is the mutation trigger
-    { isLoading: isUpdating }, // You can use the `isLoading` flag, or do custom logic with `status`
+    { isLoading: isUpdating }, // This is the destructured mutation result
   ] = useUpdatePostMutation()
+  // highlight-end
 
   return (
     <Box p={4}>
@@ -115,7 +128,9 @@ export const PostDetail = () => {
             // highlight-end
           )
         }}
+        // highlight-start
         isLoading={isUpdating}
+        // highlight-end
       />
     </Box>
   )

docs/usage/rtk-query/queries.mdx

@@ -73,7 +73,7 @@ const api = createApi({
 })
 ```
 
-### Performing queries with React Hooks
+### Performing Queries with React Hooks
 
 If you're using React Hooks, RTK Query does a few additional things for you. The primary benefit is that you get a render-optimized hook that allows you to have 'background fetching' as well as [derived booleans](#query-hook-return-types) for convenience.
 
@@ -105,26 +105,20 @@ There are 5 query-related hooks:
 
 > All `refetch`-related options will override the defaults you may have set in [createApi](../../api/rtk-query/createApi)
 
-#### Query Hook Return Types
-
-```ts title="All returned elements" no-transpile
-// Base query state
-originalArgs?: unknown; // Arguments passed to the query
-data?: unknown; // Returned result if present
-error?: unknown; // Error result if present
-requestId?: string; // A string generated by RTK Query
-endpointName?: string; // The name of the given endpoint for the query
-startedTimeStamp?: number; // Timestamp for when the query was initiated
-fulfilledTimeStamp?: number; // Timestamp for when the query was completed
-
-isUninitialized: false; // Query has not started yet.
-isLoading: false; // Query is currently loading for the first time. No data yet.
-isFetching: false; // Query is currently fetching, but might have data from an earlier request.
-isSuccess: false; // Query has data from a successful load.
-isError: false; // Query is currently in "error" state.
-
-refetch: () => void; // A function to force refetch the query
-```
+#### Frequently Used Query Hook Return Values
+
+The query hook returns an object containing properties such as the latest `data` for the query request, as well as status booleans for the current request lifecycle state. Below are some of the most frequently used properties. Refer to [`useQuery`](../../api/rtk-query/created-api/hooks.mdx#usequery) for an extensive list of all returned properties.
+
+- `data` - The returned result if present.
+- `error` - The error result if present.
+- `isUninitialized` - When true, indicates that the query has not started yet.
+- `isLoading` - When true, indicates that the query is currently loading for the first time, and has no data yet. This will be `true` for the first request fired off, but _not_ for subsequent requests.
+- `isFetching` - When true, indicates that the query is currently fetching, but might have data from an earlier request. This will be `true` for both the first request fired off, as well as subsequent requests.
+- `isSuccess` - When true, indicates that the query has data from a successful request.
+- `isError` - When true, indicates that the query is in an `error` state.
+- `refetch` - A function to force refetch the query
+
+#### Example
 
 Here is an example of a `PostDetail` component: