Merge remote-tracking branch 'origin/master' into yarn-workspaces

Author: phryneas

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [phryneas]

.github/workflows/tests.yml

@@ -89,7 +89,7 @@ jobs:
       fail-fast: false
       matrix:
         node: ['14.x']
-        ts: ['3.9', '4.0', '4.1', '4.2', 'next']
+        ts: ['3.9', '4.0', '4.1', '4.2', '4.3', 'next']
     steps:
       - name: Checkout repo
         uses: actions/checkout@v2
@@ -125,6 +125,10 @@ jobs:
         if: ${{ matrix.ts < 4.1 }}
         run: sed -i -e 's/@pre41-ts-ignore/@ts-ignore/' -e  '/pre41-remove-start/,/pre41-remove-end/d' ./src/tests/*.* ./src/query/tests/*.ts*
 
+      - name: 'disable strictOptionalProperties'
+        if: ${{ matrix.ts == 'next' }}
+        run: sed -i -e 's|//\(.*strictOptionalProperties.*\)$|\1|' tsconfig.base.json
+
       - name: Test types
         run: |
           yarn tsc --version

docs/api/createEntityAdapter.mdx

@@ -208,6 +208,7 @@ The primary content of an entity adapter is a set of generated reducer functions
 - `setAll`: accepts an array of entities or an object in the shape of `Record<EntityId, T>`, and replaces the existing entity contents with the values in the array.
 - `removeOne`: accepts a single entity ID value, and removes the entity with that ID if it exists.
 - `removeMany`: accepts an array of entity ID values, and removes each entity with those IDs if they exist.
+- `removeAll`: removes all entities from the entity state object.
 - `updateOne`: accepts an "update object" containing an entity ID and an object containing one or more new field values to update inside a `changes` field, and performs a shallow update on the corresponding entity.
 - `updateMany`: accepts an array of update objects, and performs shallow updates on all corresponding entities.
 - `upsertOne`: accepts a single entity. If an entity with that ID exists, it will perform a shallow update and the specified fields will be merged into the existing entity, with any matching fields overwriting the existing values. If the entity does not exist, it will be added.

docs/api/otherExports.mdx

@@ -22,6 +22,32 @@ console.log(nanoid())
 // 'dgPXxUz_6fWIQBD8XmiSy'
 ```
 
+### `miniSerializeError`
+
+The default error serialization function used by `createAsyncThunk`, based on https://github.com/sindresorhus/serialize-error. If its argument is an object (such as an `Error` instance), it returns a plain JS `SerializedError` object that copies over any of the listed fields. Otherwise, it returns a stringified form of the value: `{ message: String(value) }`.
+
+```ts no-transpile
+export interface SerializedError {
+  name?: string
+  message?: string
+  stack?: string
+  code?: string
+}
+
+export function miniSerializeError(value: any): SerializedError {}
+```
+
+### `copyWithStructuralSharing`
+
+A utility that will recursively merge two similar objects together, preserving existing references if the values appear to be the same. This is used internally to help ensure that re-fetched data keeps using the same references unless the new data has actually changed, to avoid unnecessary re-renders. Otherwise, every re-fetch would likely cause the entire dataset to be replaced and all consuming components to always re-render.
+
+If either of the inputs are not plain JS objects or arrays, the new value is returned.
+
+```ts no-transpile
+export function copyWithStructuralSharing<T>(oldObj: any, newObj: T): T
+export function copyWithStructuralSharing(oldObj: any, newObj: any): any {}
+```
+
 ## Exports from Other Libraries
 
 ### `createNextState`

docs/api/serializabilityMiddleware.mdx

@@ -55,6 +55,11 @@ interface SerializableStateInvariantMiddlewareOptions {
    * Defaults to 32ms.
    */
   warnAfter?: number
+
+  /**
+   * Opt out of checking state, but continue checking actions
+   */
+  ignoreState?: boolean
 }
 ```
 

docs/introduction/getting-started.md

@@ -20,7 +20,7 @@ The **Redux Toolkit** package is intended to be the standard way to write [Redux
 - "I have to add a lot of packages to get Redux to do anything useful"
 - "Redux requires too much boilerplate code"
 
-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.
+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://www.apollographql.com/blog/announcement/frontend/zero-config-graphql-state-management/), 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"](#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.
 
@@ -49,7 +49,11 @@ Redux Toolkit is available as a package on NPM for use with a module bundler or
 ```bash
 # NPM
 npm install @reduxjs/toolkit
+```
+
+or
 
+```bash
 # Yarn
 yarn add @reduxjs/toolkit
 ```
@@ -71,9 +75,9 @@ Redux Toolkit includes these APIs:
 
 ## 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**](../rtk-query/overview.md) 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 built on top of the Redux Toolkit core for its implementation, using [Redux](https://redux.js.org/) internally for its 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:
 
@@ -89,11 +93,13 @@ import { createApi } from '@reduxjs/toolkit/query/react'
 
 RTK Query includes these APIs:
 
-- [`createApi()`](../rtk-query/api/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()`](../rtk-query/api/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.
+- [`createApi()`](../rtk-query/api/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. In most cases, you should use this once per app, with "one API slice per base URL" as a rule of thumb.
+- [`fetchBaseQuery()`](../rtk-query/api/fetchBaseQuery.mdx): A small wrapper around [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) that aims to simplify requests. Intended as the recommended `baseQuery` to be used in `createApi` for the majority of users.
 - [`<ApiProvider />`](../rtk-query/api/ApiProvider.mdx): Can be used as a `Provider` if you **do not already have a Redux store**.
 - [`setupListeners()`](../rtk-query/api/setupListeners.mdx): A utility used to enable `refetchOnMount` and `refetchOnReconnect` behaviors.
 
+See the [**RTK Query Overview**](../rtk-query/overview.md) page for more details on what RTK Query is, what problems it solves, and how to use it.
+
 ## Learn Redux
 
 We have a variety of resources available to help you learn Redux.

docs/rtk-query/api/ApiProvider.mdx

@@ -20,7 +20,7 @@ Using this together with an existing Redux store will cause them to conflict wit
 ### Example
 
 <iframe
-  src="https://codesandbox.io/embed/github/reduxjs/redux-toolkit/tree/feature/v1.6-integration/examples/query/react/with-apiprovider?fontsize=12&hidenavigation=1&module=%2Fsrc%2FApp.tsx&theme=dark"
+  src="https://codesandbox.io/embed/github/reduxjs/redux-toolkit/tree/master/examples/query/react/with-apiprovider?fontsize=12&runonclick=1&hidenavigation=1&module=%2Fsrc%2FApp.tsx&theme=dark"
   style={{
     width: '100%',
     height: '800px',

docs/rtk-query/api/createApi.mdx

@@ -11,6 +11,14 @@ hide_title: true
 
 `createApi` is 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. It generates [an "API slice" structure](./created-api/overview.mdx) that contains Redux logic (and optionally React hooks) that encapsulate the data fetching and caching process for you.
 
+:::tip
+
+Typically, you should only have one API slice per base URL that your application needs to communicate with. For example, if your site fetches data from both `/api/posts` and `/api/users`, you would have a single API slice with `/api/` as the base URL, and separate endpoint definitions for `posts` and `users`. This allows you to effectively take advantage of [automated re-fetching](../usage/automated-refetching.mdx) by defining [tag](../usage/automated-refetching.mdx#tags) relationships across endpoints.
+
+For maintainability purposes, you may wish to split up endpoint definitions across multiple files, while still maintaining a single API slice which includes all of these endpoints. See [code splitting](../usage/code-splitting.mdx) for how you can use the `injectEndpoints` property to inject API endpoints from other files into a single API slice definition.
+
+:::
+
 ```ts title="Example: src/services/pokemon.ts"
 // file: src/services/types.ts noEmit
 export type Pokemon = {}
@@ -484,6 +492,46 @@ async function onQueryStarted(
 ): Promise<void>
 ```
 
+```ts title="onQueryStarted query lifecycle example"
+// file: notificationsSlice.ts noEmit
+export const messageCreated = (msg: string) => ({
+  type: 'notifications/messageCreated',
+  payload: msg,
+})
+
+// file: api.ts
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
+import { messageCreated } from './notificationsSlice'
+
+export interface Post {
+  id: number
+  name: string
+}
+
+const api = createApi({
+  baseQuery: fetchBaseQuery({
+    baseUrl: '/',
+  }),
+  endpoints: (build) => ({
+    getPost: build.query<Post, number>({
+      query: (id) => `post/${id}`,
+      async onQueryStarted(id, { dispatch, queryFulfilled }) {
+        // `onStart` side-effect
+        dispatch(messageCreated('Fetching post...'))
+        try {
+          const { data } = await queryFulfilled
+          // `onSuccess` side-effect
+          dispatch(messageCreated('Post received!'))
+        } catch (err) {
+          // `onError` side-effect
+          dispatch(messageCreated('Error fetching post!'))
+        }
+      },
+    }),
+  }),
+})
+```
+
 ### `onCacheEntryAdded`
 
 _(optional)_

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

@@ -17,7 +17,9 @@ This section documents the contents of that API structure, with the different fi
 
 :::tip
 
-Typically, you should only have one API slice per base URL that your application needs to communicate with. For example, if your site fetches data from both `/api/posts` and `/api/users`, you would have a single API slice with `/api/` as the base URL, and separate endpoint definitions for `posts` and `users`.
+Typically, you should only have one API slice per base URL that your application needs to communicate with. For example, if your site fetches data from both `/api/posts` and `/api/users`, you would have a single API slice with `/api/` as the base URL, and separate endpoint definitions for `posts` and `users`. This allows you to effectively take advantage of [automated re-fetching](../../usage/automated-refetching.mdx) by defining [tag](../../usage/automated-refetching.mdx#tags) relationships across endpoints.
+
+For maintainability purposes, you may wish to split up endpoint definitions across multiple files, while still maintaining a single API slice which includes all of these endpoints. See [code splitting](../../usage/code-splitting.mdx) for how you can use the `injectEndpoints` property to inject API endpoints from other files into a single API slice definition.
 
 :::
 

docs/rtk-query/comparison.md

@@ -27,12 +27,12 @@ In general, the main reasons to use RTK Query are:
 RTK Query has some unique API design aspects and capabilities that are worth considering.
 
 - With React Query and SWR, you usually define your hooks yourself, and you can do that all over the place and on the fly. With RTK Query, you do so in one central place by defining an "API slice" with multiple endpoints ahead of time. This allows for a more tightly integrated model of mutations automatically invalidating/refetching queries on trigger.
-- With the endpoint [matcher functionality](./api/created-api/endpoints#matchers): Every request is automatically is visible to your Redux reducers and can easily update the global application state if necessary ([see example](https://github.com/reduxjs/redux-toolkit/issues/958#issuecomment-809570419)).
+- Because RTK Query dispatches normal Redux actions as requests are processed, all actions are visible in the Redux DevTools. Additionally, every request is automatically is visible to your Redux reducers and can easily update the global application state if necessary ([see example](https://github.com/reduxjs/redux-toolkit/issues/958#issuecomment-809570419)). You can use the endpoint [matcher functionality](./api/created-api/endpoints#matchers) to do additional processing of cache-related actions in your own reducers.
+- Like Redux itself, the main RTK Query functionality is UI-agnostic and can be used with any UI layer
 - You can easily invalidate entities or patch existing query data (via `util.updateQueryData`) from middleware.
 - RTK Query enables [streaming cache updates](./usage/streaming-updates.mdx), such as updating the initial fetched data as messages are received over a websocket, and has built in support for [optimistic updates](./usage/optimistic-updates.mdx) as well.
-- Like Redux itself, the main RTK Query functionality is UI-agnostic and can be used with any UI layer
 - RTK Query ships a very tiny and flexible fetch wrapper: [`fetchBaseQuery`](./api/fetchBaseQuery.mdx). It's also very easy to [swap our client with your own](./usage/customizing-queries.mdx), such as using `axios`, `redaxios`, or something custom.
-- RTK Query has [a (currently experimental) code-gen tool](https://github.com/rtk-incubator/rtk-query-codegen) that will take an OpenAPI spec and give you a typed API client, as well as provide methods for enhancing the generated client after the fact.
+- RTK Query has [a (currently experimental) code-gen tool](https://github.com/rtk-incubator/rtk-query-codegen) that will take an OpenAPI spec or GraphQL schema and give you a typed API client, as well as provide methods for enhancing the generated client after the fact.
 
 ## Tradeoffs
 
@@ -45,6 +45,19 @@ RTK Query deliberately **does _not_ implement a cache that would deduplicate ide
 - In many cases, simply refetching data when it's invalidated works well and is easier to understand
 - At a minimum, RTKQ can help solve the general use case of "fetch some data", which is a big pain point for a lot of people
 
+### Bundle Size
+
+RTK Query adds a fixed one-time amount to your app's bundle size. Since RTK Query builds on top of Redux Toolkit and React-Redux, the added size varies depending on whether you are already using those in your app. The estimated min+gzip bundle sizes are:
+
+- If you are using RTK already: ~9kb for RTK Query and ~2kb for the hooks.
+- If you are not using RTK already:
+  - Without React: 17 kB for RTK+dependencies+RTK Query
+  - With React: 19kB + React-Redux, which is a peer dependency
+
+Adding additional endpoint definitions should only increase size based on the actual code inside the `endpoints` definitions, which will typically be just a few bytes.
+
+The functionality included in RTK Query quickly pays for the added bundle size, and the elimination of hand-written data fetching logic should be a net improvement in size for most meaningful applications.
+
 ## Comparing Feature Sets
 
 It's worth comparing the feature sets of all these tools to get a sense of their similarities and differences.