Rewrite docs for createReducer() (#74)

* Rewrite docs for createReducer()

This version tries to state more clearly the motivation behind
the function and how the immer-powered state mutation works.

* Add intro statement

Author: denisw

docs/api/createReducer.md

@@ -5,68 +5,116 @@ sidebar_label: createReducer
 hide_title: true
 ---
 
-# `createReducer`
+# `createReducer()`
 
-A utility function to create reducers that handle specific action types, similar to the example function in the ["Reducing Boilerplate" Redux docs page](https://redux.js.org/recipes/reducing-boilerplate#generating-reducers). Takes an initial state value and an object that maps action types to case reducer functions. Internally, it uses the [`immer` library](https://github.com/mweststrate/immer), so you can write code in your case reducers that mutates the existing `state` value, and it will correctly generate immutably-updated state values instead.
+A utility that simplifies creating Redux reducer functions, by defining them as lookup tables of functions to handle each action type.  It also allows you to drastically simplify immutable update logic, by writing "mutative" code inside your reducers.
 
-```ts
-function createReducer(
-  initialState: State,
-  actionsMap: Object<String, Function>
-) {}
-```
-
-Example usage:
+Redux [reducers](https://redux.js.org/basics/reducers) are often implemented using a `switch` statement, with one `case` for every handled action type.
 
 ```js
-import { createReducer } from 'redux-starter-kit'
+function counterReducer(state = 0, action) {
+  switch (action.type) {
+    case 'increment':
+      return state + action.payload
+    case 'decrement':
+      return state - action.payload
+    default:
+      return state
+  }
+}
+```
 
-function addTodo(state, action) {
-  const { newTodo } = action.payload
+This approach works well, but is a bit boilerplate-y and error-prone. For instance, it is easy to forget the `default` case or setting the initial state.
 
-  // Can safely call state.push() here
-  state.push({ ...newTodo, completed: false })
-}
+The `createReducer` helper streamlines the implementation of such reducers. It takes two arguments. The first one is the initial state. The second is an object mapping from action types to _case reducers_, each of which handles one specific action type.
 
-function toggleTodo(state, action) {
-  const { index } = action.payload
+```js
+const counterReducer = createReducr(0, {
+  increment: (state, action) => state + action.payload,
+  decrement: (state, action) => state - action.payload
+})
+```
 
-  const todo = state[index]
-  // Can directly modify the todo object
-  todo.completed = !todo.completed
-}
+If you created action creators using `createAction()`, you can use those directly as keys for the case reducers.
+
+```js
+const increment = createAction('increment')
+const decrement = createAction('decrement')
 
-const todosReducer = createReducer([], {
-  ADD_TODO: addTodo,
-  TOGGLE_TODO: toggleTodo
+const counterReducer = createReducr(0, {
+  [increment]: (state, action) => state + action.payload,
+  [decrement]: (state, action) => state - action.payload
 })
 ```
 
-This doesn't mean that you _have to_ write code in your case reducers that mutates the existing `state` value, you can still write code that updates the state immutably. You can think of `immer` as a safety net, if the code is written in a way that mutates the state directly, `immer` will make sure that such update happens immutably. On the other hand the following code is still valid:
+## Direct State Mutation
+
+Redux requires reducer functions to be pure and treat state values as immutable.  While this is essential for making state updates predictable and observable, it can sometimes make the implementation of such updates awkward. Consider the following example:
 
 ```js
-import { createReducer } from 'redux-starter-kit'
+const addTodo = createAction('todos/add')
+const toggleTodo = createAction('todos/toggle')
+
+const todosReducer = createReducr([], {
+  [addTodo]: (state, action) => {
+    const todo = action.payload
+    return [...state, todo]
+  },
+  [toggleTodo]: (state, action) => {
+    const index = action.payload
+    const todo = state[index]
+    return [
+      ...state.slice(0, index),
+      { ...todo, completed: !todo.completed }
+      ...state.slice(index + 1)
+    ]
+  }
+})
+```
 
-function addTodo(state, action) {
-  const { newTodo } = action.payload
+The  `addTodo` reducer is pretty easy to follow if you know the [ES6 spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax).  However, the code for  `toggleTodo` is much less straightforward, especially considering that it only sets a single flag.
 
-  // Updates the state immutably without relying on immer
-  return [...state, { ...newTodo, completed: false }]
-}
+To make things easier, `createReducer` uses [immer](https://github.com/mweststrate/immer) to let you write reducers as if they were mutating the state directly. In reality, the reducer receives a proxy state that translates all mutations into equivalent copy operations.
 
-function toggleTodo(state, action) {
-  const { index } = action.payload
+```js
+const addTodo = createAction('todos/add')
+const toggleTodo = createAction('todos/toggle')
+
+const todosReducer = createReducr([], {
+  [addTodo]: (state, action) => {
+    // This push() operation gets translated into the same
+    // extended-array creation as in the previous example.
+	  state.push(todo)
+  },
+  [toggleTodo]: (state, action) => {
+    // The "mutating" version of this case reducer is much
+    //  more direct than the explicitly pure one.
+    const index = action.payload
+	  const todo = state[index]
+	  todo.completed = !todo.completed
+  }
+})
+```
 
-  const todo = state[index]
-  // Updates the todo object immutably without relying on immer
-  return state.map((todo, i) => {
-    if (i !== index) return todo
-    return { ...todo, completed: !todo.completed }
-  })
-}
+If you choose to write reducers in this style, make sure to learn about  the [pitfalls mentioned in the immer docs](https://github.com/mweststrate/immer#pitfalls) . Most importantly, you need to ensure that you either mutate the `state` argument or return a new state, _but not both_. For example, the following reducer would throw an exception if a `toggleTodo` action is passed:
 
-const todosReducer = createReducer([], {
-  ADD_TODO: addTodo,
-  TOGGLE_TODO: toggleTodo
+```js
+const todosReducer = createReducr([], {
+  [toggleTodo]: (state, action) => {
+    const index = action.payload
+    const todo = state[index]
+
+    // This case reducer both mutates the passed-in state...
+    todo.completed = !todo.completed
+
+    // ... and returns a new value. This will throw an
+    // exception. In this example, the easiest fix is
+    // to remove the `return` statement.
+    return [
+      ...state.slice(0, index),
+      todo,
+      ...state.slice(index + 1)
+    ]
+  }
 })
 ```