Merge branch 'v2.0-integration' into entity-record

Author: EskiMojo14

docs/api/actionCreatorMiddleware.mdx

@@ -47,6 +47,7 @@ export default function (state = {}, action: any) {
 import {
   configureStore,
   createActionCreatorInvariantMiddleware,
+  Tuple,
 } from '@reduxjs/toolkit'
 import reducer from './reducer'
 
@@ -62,6 +63,6 @@ const actionCreatorMiddleware = createActionCreatorInvariantMiddleware({
 
 const store = configureStore({
   reducer,
-  middleware: [actionCreatorMiddleware],
+  middleware: new Tuple(actionCreatorMiddleware),
 })
 ```

docs/api/autoBatchEnhancer.mdx

@@ -51,9 +51,9 @@ const { incrementBatched, decrementUnbatched } = counterSlice.actions
 const store = configureStore({
   reducer: counterSlice.reducer,
   // highlight-start
-  enhancers: (existingEnhancers) => {
+  enhancers: (getDefaultEnhancers) => {
     // Add the autobatch enhancer to the store setup
-    return existingEnhancers.concat(autoBatchEnhancer())
+    return getDefaultEnhancers().concat(autoBatchEnhancer())
   },
   // highlight-end
 })

docs/api/configureStore.mdx

@@ -17,14 +17,12 @@ to the store setup for a better development experience.
 `configureStore` accepts a single configuration object parameter, with the following options:
 
 ```ts no-transpile
-type ConfigureEnhancersCallback = (
-  defaultEnhancers: EnhancerArray<[StoreEnhancer]>
-) => StoreEnhancer[]
 
 interface ConfigureStoreOptions<
   S = any,
   A extends Action = AnyAction,
   M extends Middlewares<S> = Middlewares<S>
+  E extends Enhancers = Enhancers
 > {
   /**
    * A single reducer function that will be used as the root reducer, or an
@@ -59,11 +57,11 @@ interface ConfigureStoreOptions<
    * The store enhancers to apply. See Redux's `createStore()`.
    * All enhancers will be included before the DevTools Extension enhancer.
    * If you need to customize the order of enhancers, supply a callback
-   * function that will receive the original array (ie, `[applyMiddleware]`),
-   * and should return a new array (such as `[applyMiddleware, offline]`).
+   * function that will receive the getDefaultEnhancers,
+   * and should return a new array (such as `getDefaultEnhancers().concat(offline)`).
    * If you only need to add middleware, you can use the `middleware` parameter instead.
    */
-  enhancers?: StoreEnhancer[] | ConfigureEnhancersCallback
+  enhancers?: (getDefaultEnhancers: GetDefaultEnhancers<M>) => E | E
 }
 
 function configureStore<S = any, A extends Action = AnyAction>(
@@ -96,6 +94,22 @@ and should return a middleware array.
 For more details on how the `middleware` parameter works and the list of middleware that are added by default, see the
 [`getDefaultMiddleware` docs page](./getDefaultMiddleware.mdx).
 
+:::note Tuple
+Typescript users are required to use a `Tuple` instance (if not using a `getDefaultMiddleware` result, which is already a `Tuple`), for better inference.
+
+```ts no-transpile
+import { configureStore, Tuple } from '@reduxjs/toolkit'
+
+configureStore({
+  reducer: rootReducer,
+  middleware: new Tuple(additionalMiddleware, logger),
+})
+```
+
+Javascript-only users are free to use a plain array if preferred.
+
+:::
+
 ### `devTools`
 
 If this is a boolean, it will be used to indicate whether `configureStore` should automatically enable support for [the Redux DevTools browser extension](https://github.com/reduxjs/redux-devtools).
@@ -124,7 +138,7 @@ If defined as an array, these will be passed to [the Redux `compose` function](h
 
 This should _not_ include `applyMiddleware()` or the Redux DevTools Extension `composeWithDevTools`, as those are already handled by `configureStore`.
 
-Example: `enhancers: [offline]` will result in a final setup of `[applyMiddleware, offline, devToolsExtension]`.
+Example: `enhancers: new Tuple(offline)` will result in a final setup of `[applyMiddleware, offline, devToolsExtension]`.
 
 If defined as a callback function, it will be called with the existing array of enhancers _without_ the DevTools Extension (currently `[applyMiddleware]`),
 and should return a new array of enhancers. This is primarily useful for cases where a store enhancer needs to be added
@@ -133,6 +147,22 @@ in front of `applyMiddleware`, such as `redux-first-router` or `redux-offline`.
 Example: `enhancers: (defaultEnhancers) => defaultEnhancers.prepend(offline)` will result in a final setup
 of `[offline, applyMiddleware, devToolsExtension]`.
 
+:::note Tuple
+Typescript users are required to use a `Tuple` instance (if not using a `getDefaultEnhancer` result, which is already a `Tuple`), for better inference.
+
+```ts no-transpile
+import { configureStore, Tuple } from '@reduxjs/toolkit'
+
+configureStore({
+  reducer: rootReducer,
+  enhancers: new Tuple(offline),
+})
+```
+
+Javascript-only users are free to use a plain array if preferred.
+
+:::
+
 ## Usage
 
 ### Basic Example
@@ -203,7 +233,10 @@ const store = configureStore({
   middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(logger),
   devTools: process.env.NODE_ENV !== 'production',
   preloadedState,
-  enhancers: [batchedSubscribe(debounceNotify)],
+  enhancers: (getDefaultEnhancers) =>
+    getDefaultEnhancers({
+      autoBatch: false,
+    }).concat(batchedSubscribe(debounceNotify)),
 })
 
 // The store has been created with these options:

docs/api/createAction.mdx

@@ -31,7 +31,7 @@ const action = increment(3)
 // { type: 'counter/increment', payload: 3 }
 ```
 
-The `createAction` helper combines these two declarations into one. It takes an action type and returns an action creator for that type. The action creator can be called either without arguments or with a `payload` to be attached to the action. Also, the action creator overrides [toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) so that the action type becomes its string representation.
+The `createAction` helper combines these two declarations into one. It takes an action type and returns an action creator for that type. The action creator can be called either without arguments or with a `payload` to be attached to the action.
 
 ```ts
 import { createAction } from '@reduxjs/toolkit'
@@ -44,10 +44,7 @@ let action = increment()
 action = increment(3)
 // returns { type: 'counter/increment', payload: 3 }
 
-console.log(increment.toString())
-// 'counter/increment'
-
-console.log(`The action type is: ${increment}`)
+console.log(`The action type is: ${increment.type}`)
 // 'The action type is: counter/increment'
 ```
 
@@ -89,7 +86,7 @@ If provided, all arguments from the action creator will be passed to the prepare
 
 ## Usage with createReducer()
 
-Because of their `toString()` override, action creators returned by `createAction()` can be used directly as keys for the case reducers passed to [createReducer()](createReducer.mdx).
+Action creators can be passed directly to `addCase` in a [createReducer()](createReducer.mdx) build callback.
 
 ```ts
 import { createAction, createReducer } from '@reduxjs/toolkit'
@@ -103,21 +100,23 @@ const counterReducer = createReducer(0, (builder) => {
 })
 ```
 
+<!-- TODO: how do we handle this? -->
+
 ## Non-String Action Types
 
 In principle, Redux lets you use any kind of value as an action type. Instead of strings, you could theoretically use numbers, [symbols](https://developer.mozilla.org/en-US/docs/Glossary/Symbol), or anything else ([although it's recommended that the value should at least be serializable](https://redux.js.org/faq/actions#why-should-type-be-a-string-or-at-least-serializable-why-should-my-action-types-be-constants)).
 
-However, Redux Toolkit rests on the assumption that you use string action types. Specifically, some of its features rely on the fact that with strings, the `toString()` method of an `createAction()` action creator returns the matching action type. This is not the case for non-string action types because `toString()` will return the string-converted type value rather than the type itself.
+However, Redux Toolkit rests on the assumption that you use string action types.
 
 ```js
 const INCREMENT = Symbol('increment')
 const increment = createAction(INCREMENT)
 
-increment.toString()
+increment.type.toString()
 // returns the string 'Symbol(increment)',
 // not the INCREMENT symbol itself
 
-increment.toString() === INCREMENT
+increment.type.toString() === INCREMENT
 // false
 ```
 

docs/api/createDynamicMiddleware.mdx

@@ -0,0 +1,181 @@
+---
+id: createDynamicMiddleware
+title: createDynamicMiddleware
+sidebar_label: createDynamicMiddleware
+hide_title: true
+---
+
+ 
+
+# `createDynamicMiddleware`
+
+## Overview
+
+A "meta-middleware" that allows adding middleware to the dispatch chain after store initialisation.
+
+## Instance Creation
+
+```ts no-transpile
+import { createDynamicMiddleware, configureStore } from '@reduxjs/toolkit'
+
+const dynamicMiddleware = createDynamicMiddleware()
+
+const store = configureStore({
+  reducer: {
+    todos: todosReducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().prepend(dynamicMiddleware.middleware),
+})
+```
+
+:::tip
+
+It's possible to pass two type parameters to `createDynamicMiddleware`, `State` and `Dispatch`.
+
+These are used by methods that receive middleware to ensure that the provided middleware are compatible with the types provided.
+
+```ts no-transpile
+const dynamicMiddleware = createDynamicMiddleware<State, Dispatch>()
+```
+
+However, if these values are derived from the store (as they should be), a circular type dependency is formed.
+
+As a result, it's better to use the `withTypes` helper attached to `addMiddleware`, `withMiddleware` and `createDispatchWithMiddlewareHook`.
+
+```ts no-transpile
+import { createDynamicMiddleware } from '@reduxjs/toolkit/react'
+import type { RootState, AppDispatch } from './store'
+
+const dynamicMiddleware = createDynamicMiddleware()
+
+const {
+  middleware,
+  addMiddleware,
+  withMiddleware,
+  createDispatchWithMiddlewareHook,
+} = dynamicMiddleware
+
+interface MiddlewareApiConfig {
+  state: RootState
+  dispatch: AppDispatch
+}
+
+export const addAppMiddleware = addMiddleware.withTypes<MiddlewareApiConfig>()
+
+export const withAppMiddleware = withMiddleware.withTypes<MiddlewareApiConfig>()
+
+export const createAppDispatchWithMiddlewareHook =
+  createDispatchWithMiddlewareHook.withTypes<MiddlewareApiConfig>()
+
+export default middleware
+```
+
+:::
+
+## Dynamic Middleware Instance
+
+The "dynamic middleware instance" returned from `createDynamicMiddleware` is an object similar to the object generated by `createListenerMiddleware`. The instance object is _not_ the actual Redux middleware itself. Rather, it contains the middleware and some instance methods used to add middleware to the chain.
+
+```ts no-transpile
+export type DynamicMiddlewareInstance<
+  State = unknown,
+  Dispatch extends ReduxDispatch<AnyAction> = ReduxDispatch<AnyAction>
+> = {
+  middleware: DynamicMiddleware<State, Dispatch>
+  addMiddleware: AddMiddleware<State, Dispatch>
+  withMiddleware: WithMiddleware<State, Dispatch>
+}
+```
+
+### `middleware`
+
+The wrapper middleware instance, to add to the Redux store.
+
+You can place this anywhere in the middleware chain, but note that all the middleware you inject into this instance will be contained within this position.
+
+### `addMiddleware`
+
+Injects a set of middleware into the instance.
+
+```ts no-transpile
+addMiddleware(logger, listenerMiddleware.instance)
+```
+
+:::note
+
+- Middleware are compared by function reference, and each is only added to the chain once.
+
+- Middleware are stored in an ES6 map, and are thus called in insertion order during dispatch.
+
+:::
+
+### `withMiddleware`
+
+Accepts a set of middleware, and creates an action. When dispatched, it injects the middleware and returns a version of `dispatch` typed to be aware of any extensions added.
+
+```ts no-transpile
+const listenerDispatch = store.dispatch(
+  withMiddleware(listenerMiddleware.middleware)
+)
+
+const unsubscribe = listenerDispatch(addListener({ type, effect }))
+```
+
+## React Integration
+
+When imported from the React-specific entry point (`@reduxjs/toolkit/react`), the result of calling `createDynamicMiddleware` will have extra methods attached.
+
+_These depend on having `react-redux` installed._
+
+```ts no-transpile
+interface ReactDynamicMiddlewareInstance<
+  State = any,
+  Dispatch extends ReduxDispatch<AnyAction> = ReduxDispatch<AnyAction>
+> extends DynamicMiddlewareInstance<State, Dispatch> {
+  createDispatchWithMiddlewareHook: CreateDispatchWithMiddlewareHook<
+    State,
+    Dispatch
+  >
+  createDispatchWithMiddlewareHookFactory: (
+    context?: Context<
+      ReactReduxContextValue<State, ActionFromDispatch<Dispatch>>
+    >
+  ) => CreateDispatchWithMiddlewareHook<State, Dispatch>
+}
+```
+
+### `createDispatchWithMiddlewareHook`
+
+Accepts a set of middleware, and returns a [`useDispatch`](https://react-redux.js.org/api/hooks#usedispatch) hook returning a `dispatch` typed to include extensions from provided middleware.
+
+```ts no-transpile
+const useListenerDispatch = createDispatchWithMiddlewareHook(
+  listenerMiddleware.instance
+)
+
+const Component = () => {
+  const listenerDispatch = useListenerDispatch()
+  useEffect(() => {
+    const unsubscribe = listenerDispatch(addListener({ type, effect }))
+    return () => unsubscribe()
+  }, [dispatch])
+}
+```
+
+:::caution
+
+Middleware is injected when `createDispatchWithMiddlewareHook` is called, not when the `useDispatch` hook is used.
+
+:::
+
+### `createDispatchWithMiddlewareHookFactory`
+
+Accepts a React context instance, and returns a `createDispatchWithMiddlewareHook` built to use that context.
+
+```ts no-transpile
+const createDispatchWithMiddlewareHook =
+  createDispatchWithMiddlewareHookFactory(context)
+```
+
+Useful if you're using a [custom context](https://react-redux.js.org/using-react-redux/accessing-store#providing-custom-context) for React Redux.