Merge branch 'master' into v2.0-integration

Author: markerikson

.github/FUNDING.yml

@@ -1 +1 @@
-github: [phryneas, markerikson]
+github: [phryneas, markerikson, EskiMojo14]

docs/api/configureStore.mdx

@@ -9,8 +9,28 @@ hide_title: true
 
 # `configureStore`
 
-A friendly abstraction over the standard Redux `createStore` function that adds good defaults
-to the store setup for a better development experience.
+The standard method for creating a Redux store. It uses the low-level Redux core `createStore` method internally, but wraps that to provide good defaults to the store setup for a better development experience.
+
+## Purpose and Behavior
+
+A standard Redux store setup typically requires multiple pieces of configuration:
+
+- Combining the slice reducers into the root reducer
+- Creating the middleware enhancer, usually with the thunk middleware or other side effects middleware, as well as middleware that might be used for development checks
+- Adding the Redux DevTools enhancer, and composing the enhancers together
+- Calling `createStore`
+
+Legacy Redux usage patterns typically required several dozen lines of copy-pasted boilerplate to achieve this.
+
+Redux Toolkit's `configureStore` simplifies that setup process, by doing all that work for you. One call to `configureStore` will:
+
+- Call `combineReducers` to combine your slices reducers into the root reducer function
+- Add the thunk middleware and called `applyMiddleware`
+- In development, automatically add more middleware to check for common mistakes like accidentally mutating the state
+- Automatically set up the Redux DevTools Extension connection
+- Call `createStore` to create a Redux store using that root reducer and those configuration options
+
+`configureStore` also offers an improved API and usage patterns compared to the original `createStore` by accepting named fields for `reducer`, `preloadedState`, `middleware`, `enhancers`, and `devtools`, as well as much better TS type inference.
 
 ## Parameters
 

docs/api/createSlice.mdx

@@ -15,7 +15,7 @@ and automatically generates action creators and action types that correspond to
 This API is the standard approach for writing Redux logic.
 
 Internally, it uses [`createAction`](./createAction.mdx) and [`createReducer`](./createReducer.mdx), so
-you may also use [Immer](https://immerjs.github.io/immer/) to write "mutating" immutable updates:
+you may also use [Immer](../usage/immer-reducers.md) to write "mutating" immutable updates:
 
 ```ts
 import { createSlice } from '@reduxjs/toolkit'
@@ -321,16 +321,17 @@ reducers: (create) => {
 
 ### `extraReducers`
 
-One of the key concepts of Redux is that each slice reducer "owns" its slice of state, and that many slice reducers
-can independently respond to the same action type. `extraReducers` allows `createSlice` to respond to other action types
-besides the types it has generated.
+Conceptually, each slice reducer "owns" its slice of state. There's also a natural correspondance between the update logic defined inside `reducers`, and the action types that are generated based on those.
 
-As case reducers specified with `extraReducers` are meant to reference "external" actions, they will not have actions generated in `slice.actions`.
+However, there are many times that a Redux slice may also need to update its own state in response to action types that were defined elsewhere in the application (such as clearing many different kinds of data when a "user logged out" action is dispatched). This can include action types defined by another `createSlice` call, actions generated by a `createAsyncThunk`, RTK Query endpoint matchers, or any other action. In addition, one of the key concepts of Redux is that many slice reducers can independently respond to the same action type.
 
-As with `reducers`, these case reducers will also be passed to `createReducer` and may "mutate" their state safely.
+**`extraReducers` allows `createSlice` to respond and update its own state in response to other action types besides the types it has generated.**
 
-If two fields from `reducers` and `extraReducers` happen to end up with the same action type string,
-the function from `reducers` will be used to handle that action type.
+As with the `reducers` field, each case reducer in `extraReducers` is [wrapped in Immer and may use "mutating" syntax to safely update the state inside](../usage/immer-reducers.md).
+
+However, unlike the `reducers` field, each individual case reducer inside of `extraReducers` will _not_ generate a new action type or action creator.
+
+If two fields from `reducers` and `extraReducers` happen to end up with the same action type string, the function from `reducers` will be used to handle that action type.
 
 #### The `extraReducers` "builder callback" notation
 
@@ -372,6 +373,7 @@ const counterSlice = createSlice({
 })
 ```
 
+<<<<<<< HEAD
 This cycle can be fixed by providing an explicit return type for the selector:
 
 ```ts no-transpile
@@ -417,6 +419,10 @@ const counterSlice = createSlice({
 
 :::
 
+=======
+
+> > > > > > > master
+
 ## Return Value
 
 `createSlice` will return an object that looks like:

docs/api/matching-utilities.mdx

@@ -42,9 +42,9 @@ As of Redux 5.0, action types are _required_ to be a string.
 A higher-order function that accepts one or more of:
 
 - `redux-toolkit` action creator functions such as the ones produced by:
-  - [`createAction`](./createAction)
-  - [`createSlice`](./createSlice#return-value)
-  - [`createAsyncThunk`](./createAsyncThunk#promise-lifecycle-actions)
+  - [`createAction`](./createAction.mdx)
+  - [`createSlice`](./createSlice.mdx#return-value)
+  - [`createAsyncThunk`](./createAsyncThunk.mdx#promise-lifecycle-actions)
 - type guard functions
 - custom action creator functions that have a `.match` property that is a type guard
 
@@ -56,7 +56,7 @@ Accepts the same inputs as `isAllOf` and will return a type guard function that
 
 ## `isAsyncThunkAction`
 
-A higher-order function that returns a type guard function that may be used to check whether an action was created by [`createAsyncThunk`](./createAsyncThunk).
+A higher-order function that returns a type guard function that may be used to check whether an action was created by [`createAsyncThunk`](./createAsyncThunk.mdx).
 
 ```ts title="isAsyncThunkAction usage"
 import { isAsyncThunkAction } from '@reduxjs/toolkit'
@@ -128,7 +128,7 @@ function handleRejectedAction(action: UnknownAction) {
 
 ## `isRejectedWithValue`
 
-A higher-order function that returns a type guard function that may be used to check whether an action is a 'rejected' action creator from the `createAsyncThunk` promise lifecycle that was created by [`rejectWithValue`](./createAsyncThunk#handling-thunk-errors).
+A higher-order function that returns a type guard function that may be used to check whether an action is a 'rejected' action creator from the `createAsyncThunk` promise lifecycle that was created by [`rejectWithValue`](./createAsyncThunk.mdx#handling-thunk-errors).
 
 ```ts title="isRejectedWithValue usage"
 import { isRejectedWithValue } from '@reduxjs/toolkit'

docs/rtk-query/api/createApi.mdx

@@ -508,7 +508,7 @@ See also [Invalidating cache data](../usage/automated-refetching.mdx#invalidatin
 
 _(optional, only for query endpoints)_
 
-Overrides the api-wide definition of `keepUnusedDataFor` for this endpoint only.a
+Overrides the api-wide definition of `keepUnusedDataFor` for this endpoint only.
 
 [summary](docblock://query/createApi.ts?token=CreateApiOptions.keepUnusedDataFor)
 

docs/rtk-query/api/created-api/api-slice-utils.mdx

@@ -29,8 +29,9 @@ Some of the TS types on this page are pseudocode to illustrate intent, as the ac
 const updateQueryData = (
   endpointName: string,
   args: any,
-  updateRecipe: (draft: Draft<CachedState>) => void
-) => ThunkAction<PatchCollection, PartialState, any, UnknownAction>;
+  updateRecipe: (draft: Draft<CachedState>) => void,
+  updateProvided?: boolean
+) => ThunkAction<PatchCollection, PartialState, any, AnyAction>;
 
 interface PatchCollection {
   patches: Patch[];
@@ -43,6 +44,7 @@ interface PatchCollection {
   - `endpointName`: a string matching an existing endpoint name
   - `args`: an argument matching that used for a previous query call, used to determine which cached dataset needs to be updated
   - `updateRecipe`: an Immer `produce` callback that can apply changes to the cached state
+  - `updateProvided`: a boolean indicating whether the endpoint's provided tags should be re-calculated based on the updated cache. Defaults to `false`.
 
 #### Description
 
@@ -155,14 +157,16 @@ await dispatch(
 const patchQueryData = (
   endpointName: string,
   args: any
-  patches: Patch[]
+  patches: Patch[],
+  updateProvided?: boolean
 ) => ThunkAction<void, PartialState, any, UnknownAction>;
 ```
 
 - **Parameters**
   - `endpointName`: a string matching an existing endpoint name
   - `args`: a cache key, used to determine which cached dataset needs to be updated
   - `patches`: an array of patches (or inverse patches) to apply to cached state. These would typically be obtained from the result of dispatching [`updateQueryData`](#updatequerydata)
+  - `updateProvided`: a boolean indicating whether the endpoint's provided tags should be re-calculated based on the updated cache. Defaults to `false`.
 
 #### Description
 
@@ -255,11 +259,21 @@ function selectInvalidatedBy(
 A function that can select query parameters to be invalidated.
 
 The function accepts two arguments
+<<<<<<< HEAD
+
+=======
+
+> > > > > > > master
 
 - the root state and
 - the cache tags to be invalidated.
 
 It returns an array that contains
+<<<<<<< HEAD
+
+=======
+
+> > > > > > > master
 
 - the endpoint name,
 - the original args and

docs/rtk-query/overview.md

@@ -67,7 +67,7 @@ import { createApi } from '@reduxjs/toolkit/query/react'
 
 RTK Query includes these APIs:
 
-- [`createApi()`](./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.
+- [`createApi()`](./api/createApi.mdx): The core of RTK Query's functionality. It allows you to define a set of "endpoints" that describe how to retrieve data from backend APIs and other async sources, including the 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()`](./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 />`](./api/ApiProvider.mdx): Can be used as a `Provider` if you **do not already have a Redux store**.
 - [`setupListeners()`](./api/setupListeners.mdx): A utility used to enable `refetchOnMount` and `refetchOnReconnect` behaviors.

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

@@ -26,6 +26,30 @@ See also [`baseQuery API Reference`](../api/createApi.mdx#basequery).
 
 RTK Query expects a `baseQuery` function to be called with three arguments: `args`, `api`, and `extraOptions`. It is expected to return an object with either a `data` or `error` property, or a promise that resolves to return such an object.
 
+:::tip
+
+Base query and query functions must _always_ catch errors themselves, and return it in an object!
+
+```ts no-transpile
+function brokenCustomBaseQuery() {
+  // ❌ Don't let this throw by itself
+  const data = await fetchSomeData()
+  return { data }
+}
+
+function correctCustomBaseQuery() {
+  // ✅ Catch errors and _return_ them so the RTKQ logic can track it
+  try {
+    const data = await fetchSomeData()
+    return { data }
+  } catch (error) {
+    return { error }
+  }
+}
+```
+
+:::
+
 #### baseQuery function arguments
 
 ```ts title="baseQuery example arguments" no-transpile
@@ -232,13 +256,17 @@ transformErrorResponse: (response: Posts, meta, arg) => {
 
 ## Customizing queries with `queryFn`
 
-Individual endpoints on [`createApi`](../api/createApi.mdx) accept a [`queryFn`](../api/createApi.mdx#queryfn) property which allows a given endpoint to ignore `baseQuery` for that endpoint by providing an inline function determining how that query resolves.
+RTK Query comes with `fetchBaseQuery` out of the box, which makes it straightforward to define endpoints that talk to HTTP URLs (such as a typical REST API). We also have integrations with GraphQL as well. However, at its core, RTK Query is really about tracking loading state and cached values for _any_ async request/response sequence, not just HTTP requests.
 
-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:
+RTK Query supports defining endpoints that run arbitrary async logic and return a result. Individual endpoints on [`createApi`](../api/createApi.mdx) accept a [`queryFn`](../api/createApi.mdx#queryfn) property, which let you write your own async function with whatever logic you want inside.
+
+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, including:
 
 - One-off queries that use a different base URL
 - One-off queries that use different request handling, such as automatic re-tries
 - One-off queries that use different error handling behaviour
+- Queries that make requests using a third-party library SDK, such as Firebase or Supabase
+- Queries that perform async tasks that are not a typical request/response
 - Performing multiple requests with a single query ([example](#performing-multiple-requests-with-a-single-query))
 - Leveraging invalidation behaviour with no relevant query ([example](#using-a-no-op-queryfn))
 - Using [Streaming Updates](./streaming-updates) with no relevant initial request ([example](#streaming-data-with-no-initial-request))
@@ -247,7 +275,39 @@ See also [`queryFn API Reference`](../api/createApi.mdx#queryfn) for the type si
 
 ### Implementing a `queryFn`
 
-In order to use `queryFn`, it can be treated as an inline `baseQuery`. It will be called with the same arguments as `baseQuery`, as well as the provided `baseQuery` function itself (`arg`, `api`, `extraOptions`, and `baseQuery`). Similarly to `baseQuery`, it is expected to return an object with either a `data` or `error` property, or a promise that resolves to return such an object.
+A `queryFn` can be thought of as an inline `baseQuery`. It will be called with the same arguments as `baseQuery`, as well as the provided `baseQuery` function itself (`arg`, `api`, `extraOptions`, and `baseQuery`). Similarly to `baseQuery`, it is expected to return an object with either a `data` or `error` property, or a promise that resolves to return such an object.
+
+#### Basic `queryFn` Example
+
+```ts title="Basic queryFn example" no-transpile
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
+import { userAPI, User } from './userAPI'
+
+const api = createApi({
+  baseQuery: fetchBaseQuery({ url: '/' }),
+  endpoints: (build) => ({
+    // normal HTTP endpoint using fetchBaseQuery
+    getPosts: build.query<PostsResponse, void>({
+      query: () => ({ url: 'posts' }),
+    }),
+    // highlight-start
+    // endpoint with a custom `queryFn` and separate async logic
+    getUser: build.query<User, string>({
+      queryFn: async (userId: string) => {
+        try {
+          const user = await userApi.getUserById(userId)
+          // Return the result in an object with a `data` field
+          return { data: user }
+        } catch (error) {
+          // Catch any errors and return them as an object with an `error` field
+          return { error }
+        }
+      },
+    }),
+    // highlight-end
+  }),
+})
+```
 
 #### queryFn function arguments
 
@@ -878,6 +938,34 @@ export const { useGetPostsQuery } = api
 
 ## Examples - `queryFn`
 
+### Using a Third-Party SDK
+
+Many services like Firebase and Supabase provide their own SDK to make requests. You can use those SDK methods in a `queryFn`:
+
+```ts title="Basic Third-Party SDK" no-transpile
+import { createApi, fakeBaseQuery } from '@reduxjs/toolkit/query/react'
+import { supabase } from './supabaseApi'
+
+export const supabaseApi = createApi({
+  reducerPath: 'supabaseApi',
+  baseQuery: fakeBaseQuery(),
+  endpoints: (builder) => ({
+    getBlogs: builder.query({
+      queryFn: async () => {
+        // Supabase conveniently already has `data` and `error` fields
+        const { data, error } = await supabase.from('blogs').select()
+        if (error) {
+          return { error }
+        }
+        return { data }
+      },
+    }),
+  }),
+})
+```
+
+You could also try creating a custom base query that uses the SDK, and define endpoints that pass method names or args into that base query.
+
 ### Using a no-op queryFn
 
 In certain scenarios, you may wish to have a `query` or `mutation` where sending a request or returning data is not relevant for the situation. Such a scenario would be to leverage the `invalidatesTags` property to force re-fetch specific `tags` that have been provided to the cache.