Document lazy state init option

Author: markerikson

docs/api/createReducer.mdx

@@ -121,6 +121,21 @@ so we recommend the "builder callback" notation in most cases.
 
 [params](docblock://createReducer.ts?token=createReducer&overload=1)
 
+### Returns
+
+The generated reducer function.
+
+The reducer will have a `getInitialState` function attached that will return the initial state when called. This may be useful for tests or usage with React's `useReducer` hook:
+
+```js
+const counterReducer = createReducer(0, {
+  increment: (state, action) => state + action.payload,
+  decrement: (state, action) => state - action.payload,
+})
+
+console.log(counterReducer.getInitialState()) // 0
+```
+
 ### Example Usage
 
 [examples](docblock://createReducer.ts?token=createReducer&overload=1)

docs/api/createSlice.mdx

@@ -71,6 +71,8 @@ function createSlice({
 
 The initial state value for this slice of state.
 
+This may also be a "lazy initializer" function, which should return an initial state value when called. This will be used whenever the reducer is called with `undefined` as its state value, and is primarily useful for cases like reading initial state from `localStorage`.
+
 ### `name`
 
 A string name for this slice of state. Generated action type constants will use this as a prefix.
@@ -196,7 +198,8 @@ We recommend using the `builder callback` API as the default, especially if you
     name : string,
     reducer : ReducerFunction,
     actions : Record<string, ActionCreator>,
-    caseReducers: Record<string, CaseReducer>
+    caseReducers: Record<string, CaseReducer>.
+    getInitialState: () => State
 }
 ```
 

packages/toolkit/src/createReducer.ts

@@ -94,8 +94,8 @@ export type ReducerWithInitialState<S extends NotFunction<any>> = Reducer<S> & {
  * That builder provides `addCase`, `addMatcher` and `addDefaultCase` functions that may be
  * called to define what actions this reducer will handle.
  *
- * @param initialState - The initial state that should be used when the reducer is called the first time.
- * @param builderCallback - A callback that receives a *builder* object to define
+ * @param initialState - `State | (() => State)`: The initial state that should be used when the reducer is called the first time. This may also be a "lazy initializer" function, which should return an initial state value when called. This will be used whenever the reducer is called with `undefined` as its state value, and is primarily useful for cases like reading initial state from `localStorage`.
+ * @param builderCallback - `(builder: Builder) => void` A callback that receives a *builder* object to define
  *   case reducers via calls to `builder.addCase(actionCreatorOrType, reducer)`.
  * @example
 ```ts
@@ -115,7 +115,7 @@ function isActionWithNumberPayload(
   return typeof action.payload === "number";
 }
 
-createReducer(
+const reducer = createReducer(
   {
     counter: 0,
     sumOfNumberPayloads: 0,
@@ -161,7 +161,7 @@ export function createReducer<S extends NotFunction<any>>(
  * This overload accepts an object where the keys are string action types, and the values
  * are case reducer functions to handle those action types.
  *
- * @param initialState - The initial state that should be used when the reducer is called the first time. This may optionally be a "lazy state initializer" that returns the intended initial state value when called.
+ * @param initialState - `State | (() => State)`: The initial state that should be used when the reducer is called the first time. This may also be a "lazy initializer" function, which should return an initial state value when called. This will be used whenever the reducer is called with `undefined` as its state value, and is primarily useful for cases like reading initial state from `localStorage`.
  * @param actionsMap - An object mapping from action types to _case reducers_, each of which handles one specific action type.
  * @param actionMatchers - An array of matcher definitions in the form `{matcher, reducer}`.
  *   All matching reducers will be executed in order, independently if a case reducer matched or not.
@@ -174,6 +174,14 @@ const counterReducer = createReducer(0, {
   increment: (state, action) => state + action.payload,
   decrement: (state, action) => state - action.payload
 })
+
+// Alternately, use a "lazy initializer" to provide the initial state
+// (works with either form of createReducer)
+const initialState = () => 0
+const counterReducer = createReducer(initialState, {
+  increment: (state, action) => state + action.payload,
+  decrement: (state, action) => state - action.payload
+})
 ```
  
  * Action creators that were generated using [`createAction`](./createAction) may be used directly as the keys here, using computed property syntax:

packages/toolkit/src/createSlice.ts

@@ -77,9 +77,7 @@ export interface CreateSliceOptions<
   name: Name
 
   /**
-   * The initial state to be returned by the slice reducer.
-   * This may optionally be a "lazy state initializer" that returns the
-   * intended initial state value when called.
+   * The initial state that should be used when the reducer is called the first time. This may also be a "lazy initializer" function, which should return an initial state value when called. This will be used whenever the reducer is called with `undefined` as its state value, and is primarily useful for cases like reading initial state from `localStorage`.
    */
   initialState: State | (() => State)