Update docs on serializability usage and dev check middleware (#630)

* Add more serializability usage info

* Update Docusaurus to alpha.58

* Remove unneeded pagination CSS

* Split API ref into subcategories

* Extract API ref docs for dev check middleware

* Update API types

* Assorted typo fixes and cleanup

Author: markerikson

docs/api/configureStore.md

@@ -19,7 +19,11 @@ type ConfigureEnhancersCallback = (
   defaultEnhancers: StoreEnhancer[]
 ) => StoreEnhancer[]
 
-interface ConfigureStoreOptions<S = any, A extends Action = AnyAction> {
+interface ConfigureStoreOptions<
+  S = any,
+  A extends Action = AnyAction,
+  M extends Middlewares<S> = Middlewares<S>
+> {
   /**
    * A single reducer function that will be used as the root reducer, or an
    * object of slice reducers that will be passed to `combineReducers()`.
@@ -30,7 +34,7 @@ interface ConfigureStoreOptions<S = any, A extends Action = AnyAction> {
    * An array of Redux middleware to install. If not supplied, defaults to
    * the set of middleware returned by `getDefaultMiddleware()`.
    */
-  middleware?: Middleware<{}, S>[]
+  middleware?: ((getDefaultMiddleware: CurriedGetDefaultMiddleware<S>) => M) | M
 
   /**
    * Whether to enable Redux DevTools integration. Defaults to `true`.
@@ -55,7 +59,7 @@ interface ConfigureStoreOptions<S = any, A extends Action = AnyAction> {
    * 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]`).
-   * If you only need to add middleware, use the `middleware` parameter instead.
+   * If you only need to add middleware, you can use the `middleware` parameter instead.
    */
   enhancers?: StoreEnhancer[] | ConfigureEnhancersCallback
 }
@@ -75,14 +79,18 @@ If it is an object of slice reducers, like `{users : usersReducer, posts : posts
 
 ### `middleware`
 
-An optional array of Redux middleware functions.
+An optional array of Redux middleware functions
 
 If this option is provided, it should contain all the middleware functions you
 want added to the store. `configureStore` will automatically pass those to `applyMiddleware`.
 
 If not provided, `configureStore` will call `getDefaultMiddleware` and use the
 array of middleware functions it returns.
 
+Alternately, you may pass a callback function that will receive `getDefaultMiddleware` as its argument,
+and should return a middleware array. This lets you skip importing `getDefaultMiddleware` separately. If using TypeScript, prefer using this syntax, as we provide a more strongly-typed version of `getDefaultMiddleware` that will correctly
+retain the types of the provided middleware when constructing the store.
+
 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.md).
 
@@ -181,5 +189,5 @@ const store = configureStore({
 // - The slice reducers were automatically passed to combineReducers()
 // - redux-thunk and redux-logger were added as middleware
 // - The Redux DevTools Extension is disabled for production
-// - The middleware, batch, and devtools enhancers were automatically composed together
+// - The middleware, batch, and devtools enhancers were composed together
 ```

docs/api/createReducer.md

@@ -86,7 +86,7 @@ const exampleReducer = createReducer(initialState, builder => {
 })
 ```
 
-See [the `builder callback` API](#the-builder-callback-api) below for details on defining reducers using this syntax.
+See the ["Builder Callback Notation"](#builder-callback-notation) section below for details on defining reducers using this syntax.
 
 > **Note**: If you are using TypeScript, we specifically recommend using the builder callback API to get proper inference of TS types for action objects. If you do not use the builder callback and are using TypeScript, you will need to use `actionCreator.type` or `actionCreator.toString()` as the key to force the TS compiler to accept the computed property. Please see [Usage With TypeScript](./../usage/usage-with-typescript.md#type-safety-with-extraReducers) for further details.
 
@@ -167,7 +167,7 @@ const todosReducer = createReducer([], {
 })
 ```
 
-## The "builder callback" API
+## Builder Callback Notation
 
 Instead of using a plain object as an argument to `createReducer`, you can also provide a "builder callback" function that receives an `ActionReducerMapBuilder` instance:
 
@@ -319,7 +319,7 @@ console.log(reducer(0, { type: 'increment' }))
 // - matcher ends with 't': 5 => 7
 ```
 
-## Debugging your state
+## Logging Draft State Values
 
 It's very common for a developer to call `console.log(state)` during the development process. However, browsers display Proxies in a format that is hard to read, which can make console logging of Immer-based state difficult.
 

docs/api/createSlice.md

@@ -154,7 +154,7 @@ createSlice({
 
 We recommend using this API if stricter type safety is necessary when defining reducer argument objects, as it will correctly infer the action type in the reducer based on the provided action creator. It's particularly useful for working with actions produced by `createAction` and `createAsyncThunk`.
 
-See [the "builder callback API" section of the `createReducer` reference](./createReducer.md#the-builder-callback-api) for details on how to use `builder.addCase`, `builder.addMatcher`, and `builder.addDefault`
+See [the "Builder Callback Notation" section of the `createReducer` reference](./createReducer.md#builder-callback-notation) for details on how to use `builder.addCase`, `builder.addMatcher`, and `builder.addDefault`
 
 ## Return Value
 

docs/api/getDefaultMiddleware.md

@@ -18,7 +18,7 @@ const store = configureStore({
   reducer: rootReducer
 })
 
-// Store has one or more middleware added, because the middleware list was not customized
+// Store has middleware added, because the middleware list was not customized
 ```
 
 If you want to customize the list of middleware, you can supply an array of middleware functions to `configureStore`:
@@ -47,7 +47,7 @@ const store = configureStore({
 // Store has all of the default middleware added, _plus_ the logger middleware
 ```
 
-## Usage without import (middleware callback notation)
+## Middleware Callback Notation for `configureStore`
 
 For convenience, the `middleware` property of `configureStore` can be used with a callback notation like this.
 
@@ -72,12 +72,12 @@ One of the goals of Redux Toolkit is to provide opinionated defaults and prevent
 `getDefaultMiddleware` includes some middleware that are added **in development builds of your app only** to
 provide runtime checks for two common issues:
 
-- [`immutable-state-invariant`](./otherExports.md#createimmutablestateinvariantmiddleware): deeply compares
+- [Immutability check middleware](./immutabilityMiddleware.md): deeply compares
   state values for mutations. It can detect mutations in reducers during a dispatch, and also mutations that occur between
   dispatches (such as in a component or a selector). When a mutation is detected, it will throw an error and indicate the key
   path for where the mutated value was detected in the state tree. (Forked from [`redux-immutable-state-invariant`](https://github.com/leoasis/redux-immutable-state-invariant).)
 
-- [`serializable-state-invariant-middleware`](./otherExports.md#createserializablestateinvariantmiddleware): a custom middleware created specifically for use in Redux Toolkit. Similar in
+- [Serializability check middleware](./serializabilityMiddleware.md): a custom middleware created specifically for use in Redux Toolkit. Similar in
   concept to `immutable-state-invariant`, but deeply checks your state tree and your actions for non-serializable values
   such as functions, Promises, Symbols, and other non-plain-JS-data values. When a non-serializable value is detected, a
   console error will be printed with the key path for where the non-serializable value was detected.
@@ -103,7 +103,7 @@ const middleware = [thunk]
 
 `getDefaultMiddleware` accepts an options object that allows customizing each middleware in two ways:
 
-- Each middleware can be excluded from inclusion in the array by passing `false` for its corresponding field
+- Each middleware can be excluded the result array by passing `false` for its corresponding field
 - Each middleware can have its options customized by passing the matching options object for its corresponding field
 
 This example shows excluding the serializable state check middleware, and passing a specific value for the thunk
@@ -126,46 +126,11 @@ interface ThunkOptions<E = any> {
 }
 
 interface ImmutableStateInvariantMiddlewareOptions {
-  isImmutable?: (value: any) => boolean
-  ignoredPaths?: string[]
-  warnAfter?: number
+  // See "Immutability Middleware" page for definition
 }
 
 interface SerializableStateInvariantMiddlewareOptions {
-  /**
-   * The function to check if a value is considered serializable. This
-   * function is applied recursively to every value contained in the
-   * state. Defaults to `isPlain()`.
-   */
-  isSerializable?: (value: any) => boolean
-  /**
-   * The function that will be used to retrieve entries from each
-   * value.  If unspecified, `Object.entries` will be used. Defaults
-   * to `undefined`.
-   */
-  getEntries?: (value: any) => [string, any][]
-
-  /**
-   * An array of action types to ignore when checking for serializability, Defaults to []
-   */
-  ignoredActions?: string[]
-
-  /**
-   * An array of dot-separated path strings to ignore when checking for serializability, Defaults to ['meta.arg']
-   * If you use this parameter, the default value 'meta.arg' will be removed, so we recommend re-adding it unless you
-   * specifically do not want to ignore it. Example: ['meta.arg', 'your.path', 'other.path', ...etc]
-   */
-  ignoredActionPaths?: string[]
-
-  /**
-   * An array of dot-separated path strings to ignore when checking for serializability, Defaults to []
-   */
-  ignoredPaths?: string[]
-
-  /**
-   * Execution time warning threshold. If the middleware takes longer than `warnAfter` ms, a warning will be displayed in the console. Defaults to 32
-   */
-  warnAfter?: number
+  // See "Serializability Middleware" page for definition
 }
 
 interface GetDefaultMiddlewareOptions {

docs/api/immutabilityMiddleware.md

@@ -0,0 +1,93 @@
+---
+id: immutabilityMiddleware
+title: Immutability Middleware
+sidebar_label: Immutability Middleware
+hide_title: true
+---
+
+# Immutability Middleware
+
+A port of the [`redux-immutable-state-invariant`](https://github.com/leoasis/redux-immutable-state-invariant) middleware, customized for use with Redux Toolkit. Any detected mutations will be thrown as errors.
+
+This middleware is added to the store by default by [`configureStore`](./configureStore.md) and [`getDefaultMiddleware`](./getDefaultMiddleware.md).
+
+You can customize the behavior of this middleware by passing any of the supported options as the `immutableCheck` value for `getDefaultMiddleware`.
+
+## Options
+
+```ts
+type IsImmutableFunc = (value: any) => boolean
+
+interface ImmutableStateInvariantMiddlewareOptions {
+  /**
+    Callback function to check if a value is considered to be immutable.
+    This function is applied recursively to every value contained in the state.
+    The default implementation will return true for primitive types 
+    (like numbers, strings, booleans, null and undefined).
+   */
+  isImmutable?: IsImmutableFunc
+  /** 
+    An array of dot-separated path strings that match named nodes from 
+    the root state to ignore when checking for immutability.
+    Defaults to undefined
+   */
+  ignoredPaths?: string[]
+  /** Print a warning if checks take longer than N ms. Default: 32ms */
+  warnAfter?: number
+  // @deprecated. Use ignoredPaths
+  ignore?: string[]
+}
+```
+
+## Exports
+
+### `createImmutableStateInvariantMiddleware`
+
+Creates an instance of the immutability check middleware, with the given options.
+
+You will most likely not need to call this yourself, as `getDefaultMiddleware` already does so.
+
+Example:
+
+```js
+import {
+  createSlice,
+  configureStore,
+  createImmutableStateInvariantMiddleware
+} from '@reduxjs/toolkit'
+
+const exampleSlice = createSlice({
+  name: 'example',
+  initialState: {
+    user: 'will track changes',
+    ignoredPath: 'single level',
+    ignoredNested: {
+      one: 'one',
+      two: 'two'
+    }
+  },
+  reducers: {}
+})
+
+const immutableInvariantMiddleware = createImmutableStateInvariantMiddleware({
+  ignoredPaths: ['ignoredPath', 'ignoredNested.one', 'ignoredNested.two']
+})
+
+const store = configureStore({
+  reducer: exampleSlice.reducer,
+  // Note that this will replace all default middleware
+  middleware: [immutableInvariantMiddleware]
+})
+```
+
+### `isImmutableDefault`
+
+Default implementation of the "is this value immutable?" check. Currently implemented as:
+
+```js
+return (
+  typeof value !== 'object' || value === null || typeof value === 'undefined'
+)
+```
+
+This will return true for primitive types (like numbers, strings, booleans, null and undefined)