Skip to content

Commit 8bab783

Browse files
iamakulovgaearon
authored andcommitted
Clarify dispatch() usage inside subscribe() listener (reduxjs#1630)
1 parent 2e394e2 commit 8bab783

File tree

1 file changed

+4
-2
lines changed

1 file changed

+4
-2
lines changed

docs/api/Store.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,9 +84,11 @@ Adds a change listener. It will be called any time an action is dispatched, and
8484

8585
You may call [`dispatch()`](#dispatch) from a change listener, with the following caveats:
8686

87-
1. The subscriptions are snapshotted just before every [`dispatch()`](#dispatch) call. If you subscribe or unsubscribe while the listeners are being invoked, this will not have any effect on the [`dispatch()`](#dispatch) that is currently in progress. However, the next [`dispatch()`](#dispatch) call, whether nested or not, will use a more recent snapshot of the subscription list.
87+
1. The listener should only call [`dispatch()`](#dispatch) either in responce to user actions or under specific conditions (e. g. dispatching an action when the store has a specific field). Calling [`dispatch()`](#dispatch) without any conditions is technically possible, however it leads to infinite loop as every [`dispatch()`](#dispatch) call usually triggers the listener again.
8888

89-
2. The listener should not expect to see all state changes, as the state might have been updated multiple times during a nested [`dispatch()`](#dispatch) before the listener is called. It is, however, guaranteed that all subscribers registered before the [`dispatch()`](#dispatch) started will be called with the latest state by the time it exits.
89+
2. The subscriptions are snapshotted just before every [`dispatch()`](#dispatch) call. If you subscribe or unsubscribe while the listeners are being invoked, this will not have any effect on the [`dispatch()`](#dispatch) that is currently in progress. However, the next [`dispatch()`](#dispatch) call, whether nested or not, will use a more recent snapshot of the subscription list.
90+
91+
3. The listener should not expect to see all state changes, as the state might have been updated multiple times during a nested [`dispatch()`](#dispatch) before the listener is called. It is, however, guaranteed that all subscribers registered before the [`dispatch()`](#dispatch) started will be called with the latest state by the time it exits.
9092

9193
It is a low-level API. Most likely, instead of using it directly, you’ll use React (or other) bindings. If you feel that the callback needs to be invoked with the current state, you might want to [convert the store to an Observable or write a custom `observeStore` utility instead](https://github.com/reactjs/redux/issues/303#issuecomment-125184409).
9294

0 commit comments

Comments
 (0)