adjust the hooks docs with more details about useSelector and add some more examples (#1267)

* adjust the hooks docs with more details about the inner workings of useSelector and add some more examples

* update hooks docs for removal of `useSelector` deps; add examples for usage with memoizing selectors; removed code example for custom `useActions` hook to not second-guess our own API design decision; some other minor docs tweaks

* in the hooks doc code examples change nr to num or number

* Update useSelector equality info and add hooks recipes

Author: MrWolfZ

docs/api/batch.md

@@ -16,19 +16,19 @@ React's `unstable_batchedUpdate()` API allows any React updates in an event loop
 Since React-Redux needs to work in both ReactDOM and React Native environments, we've taken care of importing this API from the correct renderer at build time for our own use. We also now re-export this function publicly ourselves, renamed to `batch()`. You can use it to ensure that multiple actions dispatched outside of React only result in a single render update, like this:
 
 ```js
-import { batch } from "react-redux";
+import { batch } from 'react-redux'
 
 function myThunk() {
-    return (dispatch, getState) => {
-        // should only result in one combined re-render, not two
-        batch(() => {
-            dispatch(increment());
-            dispatch(increment());
-        })
-    }
+  return (dispatch, getState) => {
+    // should only result in one combined re-render, not two
+    batch(() => {
+      dispatch(increment())
+      dispatch(increment())
+    })
+  }
 }
 ```
 
 ## References
 
-- [`unstable_batchedUpdate()` API from React](https://github.com/facebook/react/commit/b41883fc708cd24d77dcaa767cde814b50b457fe)
+- [`unstable_batchedUpdate()` API from React](https://github.com/facebook/react/commit/b41883fc708cd24d77dcaa767cde814b50b457fe)

docs/api/hooks.md

@@ -15,7 +15,7 @@ React Redux now offers a set of hook APIs as an alternative to the existing `con
 
 These hooks were first added in v7.1.0.
 
-This page reflects the latest alpha, which is currently **v7.1.0-alpha.4**.
+This page reflects the latest alpha, which is currently **v7.1.0-alpha.5**.
 
 ## Using Hooks in a React Redux App
 
@@ -37,25 +37,56 @@ From there, you may import any of the listed React Redux hooks APIs and use them
 ## `useSelector()`
 
 ```js
-const result : any = useSelector(selector : Function, deps : any[])
+const result : any = useSelector(selector : Function, equalityFn? : Function)
 ```
 
 Allows you to extract data from the Redux store state, using a selector function.
 
+> **Note**: The selector function should be [pure](https://en.wikipedia.org/wiki/Pure_function) since it is potentially executed multiple times and at arbitrary points in time.
+
 The selector is approximately equivalent to the [`mapStateToProps` argument to `connect`](../using-react-redux/connect-extracting-data-with-mapStateToProps.md) conceptually. The selector will be called with the entire Redux store state as its only argument. The selector will be run whenever the function component renders. `useSelector()` will also subscribe to the Redux store, and run your selector whenever an action is dispatched.
 
 However, there are some differences between the selectors passed to `useSelector()` and a `mapState` function:
 
 - The selector may return any value as a result, not just an object. The return value of the selector will be used as the return value of the `useSelector()` hook.
-- The selector function used will be based on the `deps` array. If no deps array is provided, the latest passed-in selector function will be used when the component renders, and also when any actions are dispatched before the next render. If a deps array is provided, the last saved selector will be used, and that selector will be overwritten whenever the deps array contents have changed.
 - When an action is dispatched, `useSelector()` will do a shallow comparison of the previous selector result value and the current result value. If they are different, the component will be forced to re-render. If they are the same, they component will not re-render.
-- The selector function does _not_ receive an `ownProps` argument. If you wish to use props within the selector function to determine what values to extract, you should call the React [`useMemo()`](https://reactjs.org/docs/hooks-reference.html#usememo) or [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) hooks yourself to create a version of the selector that will be re-created whenever the props it depends on change.
+- The selector function does _not_ receive an `ownProps` argument. However, props can be used through closure (see the examples below) or by using a curried selector.
+- Extra care must be taken when using memoizing selectors (see examples below for more details).
+- `useSelector()` uses strict `===` reference equality checks by default, not shallow equality (see the following section for more details).
 
 > **Note**: There are potential edge cases with using props in selectors that may cause errors. See the [Usage Warnings](#usage-warnings) section of this page for further details.
 
 You may call `useSelector()` multiple times within a single function component. Each call to `useSelector()` creates an individual subscription to the Redux store. Because of the React update batching behavior used in React Redux v7, a dispatched action that causes multiple `useSelector()`s in the same component to return new values _should_ only result in a single re-render.
 
-#### Examples
+### Equality Comparisons and Updates
+
+When the function component renders, the provided selector function will be called and its result will be returned
+from the `useSelector()` hook. (A cached result may be returned if the selector has been run and hasn't changed.)
+
+However, when an action is dispatched to the Redux store, `useSelector()` only forces a re-render if the selector result
+appears to be different than the last result. As of v7.1.0-alpha.5, the default comparison is a strict `===` reference
+comparison. This is different than `connect()`, which uses shallow equality checks on the results of `mapState` calls
+to determine if re-rendering is needed. This has several implications on how you should use `useSelector()`.
+
+With `mapState`, all individual fields were returned in a combined object. It didn't matter if the return object was
+a new reference or not - `connect()` just compared the individual fields. With `useSelector()`, returning a new object
+every time will _always_ force a re-render by default. If you want to retrieve multiple values from the store, you can:
+
+- Call `useSelector()` multiple times, with each call returning a single field value
+- Use Reselect or a similar library to create a memoized selector that returns multiple values in one object, but
+  only returns a new object when one of the values has changed.
+- Use the `shallowEqual` function from React-Redux as the `equalityFn` argument to `useSelector()`, like:
+
+```js
+import { shallowEqual, useSelector } from 'react-redux'
+
+// later
+const selectedData = useSelector(selectorReturningObject, shallowEqual)
+```
+
+The optional comparison function also enables using something like Lodash's `_.isEqual()` or Immutable.js's comparison capabilities.
+
+### `useSelector` Examples
 
 Basic usage:
 
@@ -69,19 +100,119 @@ export const CounterComponent = () => {
 }
 ```
 
-Using props to determine what to extract:
+Using props via closure to determine what to extract:
 
 ```jsx
 import React from 'react'
 import { useSelector } from 'react-redux'
 
 export const TodoListItem = props => {
-  const todo = useSelector(state => state.todos[props.id], [props.id])
-
+  const todo = useSelector(state => state.todos[props.id])
   return <div>{todo.text}</div>
 }
 ```
 
+#### Using memoizing selectors
+
+When using `useSelector` with an inline selector as shown above, a new instance of the selector is created whenever the component is rendered. This works as long as the selector does not maintain any state. However, memoizing selectors (e.g. created via `createSelector` from `reselect`) do have internal state, and therefore care must be taken when using them. Below you can find typical usage scenarios for memoizing selectors.
+
+When the selector does only depend on the state, simply ensure that it is declared outside of the component so that the same selector instance is used for each render:
+
+```jsx
+import React from 'react'
+import { useSelector } from 'react-redux'
+import { createSelector } from 'reselect'
+
+const selectNumOfDoneTodos = createSelector(
+  state => state.todos,
+  todos => todos.filter(todo => todo.isDone).length
+)
+
+export const DoneTodosCounter = () => {
+  const NumOfDoneTodos = useSelector(selectNumOfDoneTodos)
+  return <div>{NumOfDoneTodos}</div>
+}
+
+export const App = () => {
+  return (
+    <>
+      <span>Number of done todos:</span>
+      <DoneTodosCounter />
+    </>
+  )
+}
+```
+
+The same is true if the selector depends on the component's props, but will only ever be used in a single instance of a single component:
+
+```jsx
+import React from 'react'
+import { useSelector } from 'react-redux'
+import { createSelector } from 'reselect'
+
+const selectNumOfTodosWithIsDoneValue = createSelector(
+  state => state.todos,
+  (_, isDone) => isDone,
+  (todos, isDone) => todos.filter(todo => todo.isDone === isDone).length
+)
+
+export const TodoCounterForIsDoneValue = ({ isDone }) => {
+  const NumOfTodosWithIsDoneValue = useSelector(state =>
+    selectNumOfTodosWithIsDoneValue(state, isDone)
+  )
+
+  return <div>{NumOfTodosWithIsDoneValue}</div>
+}
+
+export const App = () => {
+  return (
+    <>
+      <span>Number of done todos:</span>
+      <TodoCounterForIsDoneValue isDone={true} />
+    </>
+  )
+}
+```
+
+However, when the selector is used in multiple component instances and depends on the component's props, you need to ensure that each component instance gets its own selector instance (see [here](https://github.com/reduxjs/reselect#accessing-react-props-in-selectors) for a more thourough explanation of why this is necessary):
+
+```jsx
+import React, { useMemo } from 'react'
+import { useSelector } from 'react-redux'
+import { createSelector } from 'reselect'
+
+const makeNumOfTodosWithIsDoneSelector = () =>
+  createSelector(
+    state => state.todos,
+    (_, isDone) => isDone,
+    (todos, isDone) => todos.filter(todo => todo.isDone === isDone).length
+  )
+
+export const TodoCounterForIsDoneValue = ({ isDone }) => {
+  const selectNumOfTodosWithIsDone = useMemo(
+    makeNumOfTodosWithIsDoneSelector,
+    []
+  )
+
+  const NumOfTodosWithIsDoneValue = useSelector(state =>
+    selectNumOfTodosWithIsDoneValue(state, isDone)
+  )
+
+  return <div>{NumOfTodosWithIsDoneValue}</div>
+}
+
+export const App = () => {
+  return (
+    <>
+      <span>Number of done todos:</span>
+      <TodoCounterForIsDoneValue isDone={true} />
+      <span>Number of unfinished todos:</span>
+      <TodoCounterForIsDoneValue isDone={false} />
+    </>
+  )
+}
+```
+
 ## Removed: `useActions()`
 
 This hook was removed in `v7.1.0-alpha.4`, based on [Dan Abramov's suggestion](https://github.com/reduxjs/react-redux/issues/1252#issuecomment-488160930).
@@ -93,25 +224,6 @@ and manually call `dispatch(someActionCreator())` in callbacks and effects as ne
 [`bindActionCreators`](https://redux.js.org/api/bindactioncreators) function in your own code to bind action creators,
 or "manually" bind them like `const boundAddTodo = (text) => dispatch(addTodo(text))`.
 
-If you still wish to use the `useActions()` hook, you may copy and paste this implementation into your own app:
-
-```js
-import { bindActionCreators } from 'redux'
-import { useDispatch } from 'react-redux'
-import { useMemo } from 'react'
-
-export function useActions(actions, deps) {
-  const dispatch = useDispatch()
-  return useMemo(() => {
-    if (Array.isArray(actions)) {
-      return actions.map(a => bindActionCreators(a, dispatch))
-    }
-
-    return bindActionCreators(actions, dispatch)
-  }, deps)
-}
-```
-
 ## Removed: `useRedux()`
 
 This hook was removed in `v7.1.0-alpha.3`, on the grounds that it didn't provide any real benefit.
@@ -128,24 +240,48 @@ This hook returns a reference to the `dispatch` function from the Redux store. Y
 
 #### Examples
 
+```jsx
+import React from 'react'
+import { useDispatch } from 'react-redux'
+
+export const CounterComponent = ({ value }) => {
+  const dispatch = useDispatch()
+
+  return (
+    <div>
+      <span>{value}</span>
+      <button onClick={() => dispatch({ type: 'increment-counter' })}>
+        Increment counter
+      </button>
+    </div>
+  )
+}
+```
+
+When passing a callback using `dispatch` to a child component, it is recommended to memoize it with `useCallback`, since otherwise child components may render unnecessarily due to the changed reference.
+
 ```jsx
 import React, { useCallback } from 'react'
 import { useDispatch } from 'react-redux'
 
 export const CounterComponent = ({ value }) => {
   const dispatch = useDispatch()
-  const increaseCounter = useCallback(
-    () => dispatch({ type: 'increase-counter' }),
+  const incrementCounter = useCallback(
+    () => dispatch({ type: 'increment-counter' }),
     []
   )
 
   return (
     <div>
       <span>{value}</span>
-      <button onClick={increaseCounter}>Increase counter</button>
+      <MyIncrementButton onIncrement={incrementCounter} />
     </div>
   )
 }
+
+export const MyIncrementButton = React.memo(({ onIncrement }) => (
+  <button onClick={onIncrement}>Increment counter</button>
+))
 ```
 
 ## `useStore()`
@@ -198,11 +334,13 @@ Depending on what props were used and what the current store state is, this _may
 - The parent component _would_ stop rendering that child as a result
 - However, because the child subscribed first, its subscription runs before the parent stops rendering it. When it reads a value from the store based on props, that data no longer exists, and if the extraction logic is not careful, this may result in an error being thrown.
 
-Some possible options for avoiding these problems with `useSelector()`:
+`useSelector()` tries to deal with this by catching all errors that are thrown when the selector is executed due to a store update (but not when it is executed during rendering). When an error occurs, the component will be forced to render, at which point the selector is executed again. This works as long as the selector is a pure function and you do not depend on the selector throwing errors.
+
+If you prefer to deal with this issue yourself, here are some possible options for avoiding these problems altogether with `useSelector()`:
 
 - Don't rely on props in your selector function for extracting data
 - In cases where you do rely on props in your selector function _and_ those props may change over time, _or_ the data you're extracting may be based on items that can be deleted, try writing the selector functions defensively. Don't just reach straight into `state.todos[props.id].name` - read `state.todos[props.id]` first, and verify that it exists before trying to read `todo.name`.
-- Because connected components add the necessary `Subscription` to the context provider, putting a connected component in the tree just above the components with potential data issues may keep those issues from occurring.
+- Because `connect` adds the necessary `Subscription` to the context provider, wrapping the component with `connect` (without any arguments, i.e. `connect()(MyComponent)` will keep those issues from occurring.
 
 > **Note**: For a longer description of this issue, see [this chat log that describes the problems in more detail](https://gist.github.com/markerikson/faac6ae4aca7b82a058e13216a7888ec), as well as [issue #1179](https://github.com/reduxjs/react-redux/issues/1179).
 
@@ -242,3 +380,37 @@ export const CounterComponent = props => {
   return renderedChildren
 }
 ```
+
+## Hooks Recipes
+
+We've pared down our hooks API from the original alpha release, focusing on a more minimal set of API primitives.
+However, you may still wish to use some of the approaches we tried in your own apps. These examples should be ready
+to copy and paste into your own codebase.
+
+### Recipe: `useActions()`
+
+```js
+import { bindActionCreators } from 'redux'
+import { useDispatch } from 'react-redux'
+import { useMemo } from 'react'
+
+export function useActions(actions, deps) {
+  const dispatch = useDispatch()
+  return useMemo(() => {
+    if (Array.isArray(actions)) {
+      return actions.map(a => bindActionCreators(a, dispatch))
+    }
+    return bindActionCreators(actions, dispatch)
+  }, deps)
+}
+```
+
+### Recipe: `useShallowEqualSelector()`
+
+```js
+import { shallowEqual } from 'react-redux'
+
+export function useShallowEqualSelector(selector) {
+  return useSelector(selector, shallowEqual)
+}
+```