Merge branch 'feature/v1.6-integration' of github.com:reduxjs/redux-toolkit into feature/v1.6-integration

Author: markerikson

docs/api/rtk-query/createApi.mdx

@@ -267,11 +267,12 @@ type UseQueryResult<T> = {
   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 an "error" state.
+  // Derived request status booleans
+  isUninitialized: boolean // Query has not started yet.
+  isLoading: boolean // Query is currently loading for the first time. No data yet.
+  isFetching: boolean // Query is currently fetching, but might have data from an earlier request.
+  isSuccess: boolean // Query has data from a successful load.
+  isError: boolean // Query is currently in an "error" state.
 
   refetch: () => void // A function to force refetch the query
 }
@@ -316,15 +317,18 @@ type UseMutationTrigger<T> = (
 }
 
 type UseMutationResult<T> = {
+  // Base query state
+  originalArgs?: unknown // Arguments passed to the latest mutation call
   data?: T // Returned result if present
-  endpointName?: string // The name of the given endpoint for the mutation
   error?: unknown // Error result if present
+  endpointName?: string // The name of the given endpoint for the mutation
   fulfilledTimestamp?: number // Timestamp for when the mutation was completed
-  isError: boolean // Mutation is currently in an "error" state
+
+  // Derived request status booleans
+  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
-  originalArgs?: unknown // Arguments passed to the latest mutation call
+  isError: boolean // Mutation is currently in an "error" state
   startedTimeStamp?: number // Timestamp for when the latest mutation was initiated
 }
 ```

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

@@ -8,7 +8,7 @@ hide_table_of_contents: false
 
 # `fetchBaseQuery`
 
-This is a very small wrapper around `fetch` that aims to simplify requests. It is not a full-blown replacement for `axios`, `superagent`, or any other more heavy-weight library, but it will cover the large majority of your needs.
+This is a very small wrapper around [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) that aims to simplify requests. It is not a full-blown replacement for `axios`, `superagent`, or any other more heavy-weight library, but it will cover the large majority of your needs.
 
 It takes all standard options from fetch's [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) interface, as well as `baseUrl`, a `prepareHeaders` function, and an optional `fetch` function.
 

docs/api/rtk-query/fetchBaseQuery.mdx

@@ -17,7 +17,7 @@ The **Redux Toolkit** package is intended to be the standard way to write [Redux
 
 We can't solve every use case, but in the spirit of [`create-react-app`](https://github.com/facebook/create-react-app) and [`apollo-boost`](https://dev-blog.apollodata.com/zero-config-graphql-state-management-27b1f1b3c2c3), we can try to provide some tools that abstract over the setup process and handle the most common use cases, as well as include some useful utilities that will let the user simplify their application code.
 
-Redux Toolkit also includes a powerful data fetching and caching capability that we've dubbed "RTK Query". It's included in the package as a separate set of entry points. It's optional, but can eliminate the need to hand-write data fetching logic yourself.
+Redux Toolkit also includes a powerful data fetching and caching capability that we've dubbed ["RTK Query"](#rtk-query). It's included in the package as a separate set of entry points. It's optional, but can eliminate the need to hand-write data fetching logic yourself.
 
 **These tools should be beneficial to all Redux users**. Whether you're a brand new Redux user setting up your
 first project, or an experienced user who wants to simplify an existing application, **Redux Toolkit** can help
@@ -66,6 +66,31 @@ Redux Toolkit includes these APIs:
 - [`createEntityAdapter`](../api/createEntityAdapter.mdx): generates a set of reusable reducers and selectors to manage normalized data in the store
 - The [`createSelector` utility](../api/createSelector.mdx) from the [Reselect](https://github.com/reduxjs/reselect) library, re-exported for ease of use.
 
+## RTK Query
+
+**RTK Query** is provided as an optional addon within the `@reduxjs/toolkit` package. It is purpose-built to solve the use case of data fetching and caching, supplying a compact, but powerful toolset to define an API interface layer for your app. It is intended to simplify common cases for loading data in a web application, eliminating the need to hand-write data fetching & caching logic yourself.
+
+RTK Query is built on top of the Redux Toolkit core for it's implementation, using [Redux](https://redux.js.org/) internally for it's architecture. Although knowledge of Redux and RTK are not required to use RTK Query, you should explore all of the additional global store management capabilities they provide, as well as installing the [Redux DevTools browser extension](https://github.com/reduxjs/redux-devtools), which works flawlessly with RTK Query to traverse and replay a timeline of your request & cache behavior.
+
+RTK Query is included within the installation of the core Redux Toolkit package. It is available via either of the two entry points below:
+
+```ts no-transpile
+import { createApi } from '@reduxjs/toolkit/query'
+
+/* React-specific entry point that automatically generates
+   hooks corresponding to the defined endpoints */
+import { createApi } from '@reduxjs/toolkit/query/react'
+```
+
+### What's included
+
+RTK Query includes these APIs:
+
+- [`createApi()`](../api/rtk-query/createApi.mdx): The core of RTK Query's functionality. It allows you to define a set of endpoints describe how to retrieve data from a series of endpoints, including configuration of how to fetch and transform that data.
+- [`fetchBaseQuery()`](../api/rtk-query/fetchBaseQuery.mdx): A small wrapper around [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) that aims to simply requests. Intended as the recommended `baseQuery` to be used in `createApi` for the majority of users.
+- [`<ApiProvider />`](../api/rtk-query/ApiProvider.mdx): Can be used as a `Provider` if you **do not already have a Redux store**.
+- [`setupListeners()`](../api/rtk-query/setupListeners.mdx): A utility used to enable `refetchOnMount` and `refetchOnReconnect` behaviors.
+
 ## Help and Discussion
 
 The **[#redux channel](https://discord.gg/0ZcbPKXt5bZ6au5t)** of the **[Reactiflux Discord community](http://www.reactiflux.com)** is our official resource for all questions related to learning and using Redux. Reactiflux is a great place to hang out, ask questions, and learn - come join us!

docs/introduction/getting-started.md

@@ -15,7 +15,7 @@ RTK Query provides a number of concepts and tools to manipulate the cache behavi
 
 ### Tags
 
-_see also: [tagTypes](../../api/rtk-query/createApi#tagtypes)_
+_see also: [tagTypes API reference](../../api/rtk-query/createApi.mdx#tagtypes)_
 
 For RTK Query, _tags_ are just a name that you can give to a specific collection of data to control caching and invalidation behavior for refetching purposes. It can be considered as a 'label' attached to cached data that is read after a `mutation`, to decide whether the data should be affected by the mutation.
 
@@ -25,15 +25,15 @@ An individual `tag` has a `type`, represented as a `string` name, and an optiona
 
 ### Providing tags
 
-_see also: [Anatomy of an endpoint](../../api/rtk-query/createApi#anatomy-of-an-endpoint)_
+_see also: [providesTags API reference](../../api/rtk-query/createApi.mdx#providestags)_
 
 A _query_ can have it's cached data _provide_ tags. Doing so determines which 'tag' is attached to the cached data returned by the query.
 
 The `providesTags` argument can either be an array of `string` (such as `['Post']`), `{type: string, id?: string|number}` (such as `[{type: 'Post', id: 1}]`), or a callback that returns such an array. That function will be passed the result as the first argument, the response error as the second argument, and the argument originally passed into the `query` method as the third argument. Note that either the result or error arguments may be undefined based on whether the query was successful or not.
 
 ### Invalidating tags
 
-_see also: [Anatomy of an endpoint](../../api/rtk-query/createApi#anatomy-of-an-endpoint)_
+_see also: [invalidatesTags API reference](../../api/rtk-query/createApi.mdx#invalidatesTags)_
 
 A _mutation_ can _invalidate_ specific cached data based on the tags. Doing so determines which cached data will be either refetched or removed from the cache.
 

docs/usage/rtk-query/cached-data.mdx

@@ -13,6 +13,10 @@ If you want to prevent a query from automatically running, you can use the `skip
 
 [remarks](docblock://query/react/buildHooks.ts?token=UseQuerySubscriptionOptions.skip)
 
+:::tip
+Typescript users may wish to use [`skipToken`](../../api/rtk-query/created-api/hooks.mdx#skiptoken) as an alternative to the `skip` option in order to skip running a query, while still keeping types for the endpoint accurate.
+:::
+
 ### Example
 
 <iframe

docs/usage/rtk-query/conditional-fetching.mdx

@@ -286,7 +286,7 @@ export const { useGetPostsQuery, useGetPostQuery } = api
 
 ### Excluding baseQuery with queryFn
 
-Individual endpoints on [`createApi`](../../api/rtk-query/createApi) accept a [`queryFn`](../../api/rtk-query/createApi#anatomy-of-an-endpoint) property which allows a given endpoint to ignore `baseQuery` for that endpoint by providing an inline function determining how that query resolves.
+Individual endpoints on [`createApi`](../../api/rtk-query/createApi) accept a [`queryFn`](../../api/rtk-query/createApi#queryfn) property which allows a given endpoint to ignore `baseQuery` for that endpoint by providing an inline function determining how that query resolves.
 
 This can be useful for scenarios where you want to have particularly different behaviour for a single endpoint, or where the query itself is not relevant. Such situations may include:
 

docs/usage/rtk-query/customizing-queries.mdx

@@ -11,6 +11,8 @@ Unlike `useQuery`, `useMutation` returns a tuple. The first item in the tuple is
 
 Unlike the `useQuery` hook, the `useMutation` hook doesn't execute automatically. To run a mutation you have to call the trigger function returned as the first tuple value from the hook.
 
+See [`useMutation`](../../api/rtk-query/created-api/hooks.mdx#usemutation) for the hook signature and additional details.
+
 ```ts title="Example of all mutation endpoint options"
 // file: types.ts noEmit
 export interface Post {
@@ -68,47 +70,32 @@ const api = createApi({
 Notice the `onQueryStarted` method? Be sure to check out how it can be used for [optimistic updates](./optimistic-updates)
 :::
 
-### Type interfaces
-
-```ts title="Mutation endpoint definition" no-transpile
-export type MutationDefinition<
-  QueryArg,
-  BaseQuery extends BaseQueryFn,
-  TagTypes extends string,
-  ResultType,
-  ReducerPath extends string = string,
-  Context = Record<string, any>
-> = BaseEndpointDefinition<QueryArg, BaseQuery, ResultType> & {
-  type: DefinitionType.mutation
-  invalidatesTags?: ResultDescription<TagTypes, ResultType, QueryArg>
-  providesTags?: never
-  onQueryStarted?(
-    arg: QueryArg,
-    {
-      dispatch,
-      getState,
-      queryFulfilled,
-      requestId,
-      extra,
-      getCacheEntry,
-    }: MutationLifecycleApi
-  ): Promise<void>
-  onCacheEntryAdded?(
-    arg: QueryArg,
-    {
-      dispatch,
-      getState,
-      extra,
-      requestId,
-      cacheEntryRemoved,
-      cacheDataLoaded,
-      getCacheEntry,
-    }: MutationCacheLifecycleApi
-  ): Promise<void>
-}
-```
+### 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'.
+
+:::
 
-### Basic 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.
 
@@ -118,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}>
@@ -140,7 +128,9 @@ export const PostDetail = () => {
             // highlight-end
           )
         }}
+        // highlight-start
         isLoading={isUpdating}
+        // highlight-end
       />
     </Box>
   )