From 1eb7268b3e1f242cefbc69df415dae131fb1b1bf Mon Sep 17 00:00:00 2001 From: Ryan Patterson Date: Sun, 30 Apr 2017 10:33:12 -0700 Subject: [PATCH 1/2] Add documentation on transaction behavior This was pretty confusing for me as a first-time user and I had to read the source code and do several experiments to figure this out. I'm submitting this change to the README that adds a section on the specific behavior of `BEGIN`, `COMMIT`, and `REVERT` and also includes a recommendation on how to use them effectively. I also cleaned up the formatting. FYI GIthub doesn't recognize headings unless there's a space following the `###` --- README.md | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e36cca0..a8a1cbf 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # redux-optimistic-ui a reducer enhancer to enable type-agnostic optimistic updates -##Installation +## Installation `npm i -S redux-optimistic-ui` ## A what-now? @@ -24,9 +24,31 @@ This makes your app feel super fast, regardless of server location or internet c | uses immutable.js behind the scenes | uses native JS objects behind the scenes | | FSA compliant | not FSA compliant | | must wrap your state calls in `ensureState` | no change necessary to get your state | -##Usage -###Feed it your reducer +## How do optimistic actions work? + +- When you dispatch a `BEGIN` action + - Your current state is recorded as the `beforeState`. + - The action is dispatched normally. + - All future actions are dispatched normally and additionally stored in the `history`. +- When you dispatch a `COMMIT` action + - The action is dispatched normally. + - The `history` is cleared to save memory and future actions are no longer stored (unless there is another uncommitted `BEGIN`). +- When you dispatch a `REVERT` action + - The state is reverted to the `beforeState`. + - The initial `BEGIN` action is skipped but all other actions in the `history` are re-dispatched immediately. + - The `REVERT` action is dispatched normally. + - The `history` is cleared to save memory and future actions are no longer stored (unless there is another uncommitted `BEGIN`). + - This effectively makes your state appear as though the intial `BEGIN` action was never dispatched in the first place (leaving a "dangling" `REVERT` action). + +To take advantage of this: +- Your `BEGIN` action should update your state with the expected outcome of the optimistic action and can optionally indicate that the change is "pending" (e.g. not fully loaded). +- Your `COMMIT` action should clear the "pending" flag, if you used it. +- Your `REVERT` action doesn't need to modify the state except to display an error message to the user. + +## Usage + +### Feed it your reducer ```js import {optimistic} from 'redux-optimistic-ui'; @@ -48,7 +70,7 @@ If the client is not waiting for a response from the server, the following are g If you don't need to know if there is an outstanding fetch, you'll never need to use these. -###Update your references to `state` +### Update your references to `state` Since your state is now wrapped, you need `state.get('current')`. But that sucks. What if you don't enhance the state until the user hits a certain route? @@ -64,7 +86,7 @@ import {ensureState} from 'redux-optimistic-ui' ensureState(getState()).counter ``` -###Write some middleware +### Write some middleware Now comes the fun! Not all of your actions should be optimistic. Just the ones that fetch something from a server *and have a high probability of success*. @@ -110,7 +132,7 @@ export default store => next => action => { }; ``` -##Pro tips +## Pro tips Not using an optimistic-ui until a certain route? Using something like `redux-undo` in other parts? Write a little something like this and call it on your asychronous route: ```js From 5d3852de797f6d372a828526d17ad86108585bc3 Mon Sep 17 00:00:00 2001 From: Ryan Patterson Date: Tue, 17 Oct 2017 10:33:38 -0700 Subject: [PATCH 2/2] Remove implementation details from explanation --- README.md | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index a8a1cbf..4028808 100644 --- a/README.md +++ b/README.md @@ -27,24 +27,17 @@ This makes your app feel super fast, regardless of server location or internet c ## How do optimistic actions work? -- When you dispatch a `BEGIN` action - - Your current state is recorded as the `beforeState`. +- When you dispatch a `BEGIN` action: - The action is dispatched normally. - - All future actions are dispatched normally and additionally stored in the `history`. -- When you dispatch a `COMMIT` action + - Your reducer should update your state with the expected outcome of the optimistic action and can optionally indicate that the change is "pending" (e.g. not fully loaded). +- When you dispatch a `COMMIT` action: - The action is dispatched normally. - - The `history` is cleared to save memory and future actions are no longer stored (unless there is another uncommitted `BEGIN`). -- When you dispatch a `REVERT` action - - The state is reverted to the `beforeState`. - - The initial `BEGIN` action is skipped but all other actions in the `history` are re-dispatched immediately. + - Your reducer should clear the "pending" flag, if you used it. +- When you dispatch a `REVERT` action: + - The state is reverted to its value before the `BEGIN` action. + - All actions after the `BEGIN` that have been previously dispatched are re-dispatched immediately (this makes it look as though the initial `BEGIN` action never happened). - The `REVERT` action is dispatched normally. - - The `history` is cleared to save memory and future actions are no longer stored (unless there is another uncommitted `BEGIN`). - - This effectively makes your state appear as though the intial `BEGIN` action was never dispatched in the first place (leaving a "dangling" `REVERT` action). - -To take advantage of this: -- Your `BEGIN` action should update your state with the expected outcome of the optimistic action and can optionally indicate that the change is "pending" (e.g. not fully loaded). -- Your `COMMIT` action should clear the "pending" flag, if you used it. -- Your `REVERT` action doesn't need to modify the state except to display an error message to the user. + - Your reducer should update the state to indicate the error message to the user and clear the "pending" flag, if you used it. ## Usage