Merge branch 'v2.0-integration' into unknown-action

Author: ben.durrant

docs/api/actionCreatorMiddleware.mdx

@@ -0,0 +1,67 @@
+---
+id: actionCreatorMiddleware
+title: Action Creator Middleware
+sidebar_label: Action Creator Middleware
+hide_title: true
+---
+
+ 
+
+# Action Creator Middleware
+
+A custom middleware that detects if an action creator has been mistakenly dispatched, instead of being called before dispatching.
+
+A common mistake is to call `dispatch(actionCreator)` instead of `dispatch(actionCreator())`.
+This tends to "work" as the action creator has the static `type` property, but can lead to unexpected behaviour.
+
+## Options
+
+```ts no-transpile
+export interface ActionCreatorInvariantMiddlewareOptions {
+  /**
+   * The function to identify whether a value is an action creator.
+   * The default checks for a function with a static type property and match method.
+   */
+  isActionCreator?: (action: unknown) => action is Function & { type?: unknown }
+}
+```
+
+## Exports
+
+### `createActionCreatorInvariantMiddleware`
+
+Creates an instance of the action creator check middleware, with the given options.
+
+You will most likely not need to call this yourself, as `getDefaultMiddleware` already does so.
+Example:
+
+```ts
+// file: reducer.ts noEmit
+
+export default function (state = {}, action: any) {
+  return state
+}
+
+// file: store.ts
+
+import {
+  configureStore,
+  createActionCreatorInvariantMiddleware,
+} from '@reduxjs/toolkit'
+import reducer from './reducer'
+
+// Augment middleware to consider all functions with a static type property to be action creators
+const isActionCreator = (
+  action: unknown
+): action is Function & { type: unknown } =>
+  typeof action === 'function' && 'type' in action
+
+const actionCreatorMiddleware = createActionCreatorInvariantMiddleware({
+  isActionCreator,
+})
+
+const store = configureStore({
+  reducer,
+  middleware: [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
 })
@@ -84,9 +84,9 @@ Any action that is tagged with `action.meta[SHOULD_AUTOBATCH] = true` will be tr
 `autoBatchEnhancer` accepts options to configure how the notification callback is queued:
 
 - `{type: 'raf'}`: queues using `requestAnimationFrame` (default)
-- `{type: 'tick'}: queues using `queueMicrotask`
+- `{type: 'tick'}`: queues using `queueMicrotask`
 - `{type: 'timer, timeout: number}`: queues using `setTimeout`
-- `{type: 'callback', queueNotification: (notify: () => void) => void}: lets you provide your own callback, such as a debounced or throttled function
+- `{type: 'callback', queueNotification: (notify: () => void) => void}`: lets you provide your own callback, such as a debounced or throttled function
 
 The default behavior is to queue the notifications using `requestAnimationFrame`.
 

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 = UnknownAction,
   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 = UnknownAction>(
@@ -203,7 +201,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.