Skip to content

Add documentation on transaction behavior #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add documentation on transaction behavior #28

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1eb7268
Add documentation on transaction behavior
CGamesPlay Apr 30, 2017
5d3852d
Remove implementation details from explanation
CGamesPlay Oct 17, 2017
1114433
Merge branch 'master' into patch-1
CGamesPlay Oct 17, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 28 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?
Expand All @@ -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`.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not necessarily, this is true for the first BEGIN, but then for the 2nd BEGIN, the beforeState doesn't change

- 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';
Expand All @@ -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?
Expand All @@ -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*.
Expand Down Expand Up @@ -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
Expand Down