*A tiny library for creating state machines in Redux apps.*

*A tiny library (12 lines) for creating state machines as swappable Redux reducers*

redux-machine enables you to create[reducers](http://redux.js.org/docs/basics/Reducers.html) that can transition between different "statuses." These are likes states in a[finite state machine](https://en.wikipedia.org/wiki/Finite-state_machine). The goal is for redux-machine to support complex workflows simply while keeping all state in the redux store. Keeping all state in the store is good because:

- redux-machine works with time-travel debugging. Time-travel debugging was the main[motivation for building redux itself](https://www.youtube.com/watch?v=xsSnOQynTHs).

- Debugging is easy because information is in one place (the store).

- Statuses such are queryable by the user interface. This is helpful if you want to show things to the user such as loading spinners to indicate status

redux-saga and redux-observable also make it easy to create workflows in redux apps. They are more beautiful and powerful than redux-machine, but can break the "all state is in the store" paradigm.

-**`createMachine(reducerObject)`** returns a machine, which is itself a reducer

`reducerObject` is an object where the keys are statuses and the values are sub-reducers. For example, this code creates a reducer that acts like`initReducer` when the status is`INIT` and acts like`inProgressReducer` when the status is`IN_PROGRESS`:

This is the entire API for redux-machine:

import {createMachine } =from'./index.js'

constfetchUsersReducer=createMachine({

'INIT': initReducer,

'IN_PROGRESS': inProgressReducer

})

`reducerObject` must have an`INIT` key. The value for the`INIT` key is the reducer for the starting status of the machine/reducer.

The reducer returned by`createMachine` adds a`STATUS` key to the store. That is, when the status is`INIT`, the value of`STATUS` is`INIT` and when the status is`IN_PROGRESS`, the value of`STATUS` is`IN_PROGRESS`. This is useful for debugging or for acting on the current status in the UI or in your API callers.

-**`become`** (symbol)

The reducers that are the values of`reducersObject` can use`become` to transition the machine/reducer to a different status. For example, the following code in`initReducer` transitions`fetchUsersReducer` to the`IN_PROGRESS` status when the`` action is dispatched. At that point,`fetchUsersReducer` will act like`inProgressReducer` and the value of`STATUS` changes to`IN_PROGRESS`:

import {become }from'redux-machine'

switch (action.type) {

case'FETCH_USERS':

returnObject.assign({}, state, {

error:null,

[become]:'IN_PROGRESS'

})

case default:

return state

}

Suppose you are making an API call to fetch users, and want only one instance of this API call to happen at a time. You also want to communicate to the user the status of the API call:`INIT` (initial status, no call in progress) and`IN_PROGRESS`.

You can use redux-machine to have the following status transitions in your reducer:


- When the status is`INIT` and the action type is`FETCH_USERS`, the machine transitions to`IN_PROGRESS` status.

- When the status is`IN_PROGRESS` and the action type is`FETCH_USERS_RESPONSE` or`FETCH_USERS_FAIL`, the machine transitions to the`INIT` (initial) status.

I'll walk through how to create the machine in this example. If you prefer to see all the code in one place, it's in`./test.js`.

import {createMachine,become }from'./index.js'

The reducer returned by`createMachine` will act like`initReducer` when its status is`INIT` and will act like`inProgressReducer` when the status is`IN_PROGRESS`. If the store's`state.status` is undefined, the reducer for`INIT` is used (so it's a good idea to provide a reducer for the`INIT` status).

Next, define a reducer for eachstatusin the machine ('INIT' and 'IN_PROGRESS'):

`initReducer` and`inProgressReducer` can dostatustransitions by setting`state.status`:

constinitReducer= (state= {error:null, users: []},action)=> {

switch (action.type) {

case'FETCH_USERS':

returnObject.assign({}, state, {

error:null,

[become]:'IN_PROGRESS'

status:'IN_PROGRESS'

})

default:

return state

}

}

constinProgressReducer= (state= {},action)=> {

switch (action.type) {

case'FETCH_USERS_RESPONSE':

returnObject.assign({}, state, {

error:null,

users:action.payload.users,

[become]:'INIT'

status:'INIT'

})

case'FETCH_USERS_FAIL':

returnObject.assign({}, state, {

error:'fail',

[become]:'INIT'

error:action.payload.error,

status:'INIT'

})

default:

return state

}

}

Here's how you can use the`createMachine` function to create a reducer from the`initReducer` and`inProgressReducer`:

constfetchUsersReducer=createMachine({

'INIT': initReducer,

'IN_PROGRESS': inProgressReducer

})

The example above defines the following state machine:

`initReducer` is the value for`INIT`, so`createMachine` knows to start off acting like`initReducer`.

In the object provided to`createMachine`, the names of the keys matter because they are used within reducers for transitioning the machine/reducer between statuses. For example, the following code in`initReducer` says that when the action is of type`FETCH_USERS`, transition the machine to the`IN_PROGRESS` status:

switch (action.type) {

case'FETCH_USERS':

returnObject.assign({}, state, {

error:null,

[become]:'IN_PROGRESS'

})

case default:

return state

}


In words:

- When the status is`INIT` and the action type is`FETCH_USERS`, the machine transitions to`IN_PROGRESS` status.

- When the status is`IN_PROGRESS` and the action type is`FETCH_USERS_RESPONSE` or`FETCH_USERS_FAIL`, the machine transitions to the`INIT` (initial) status.

redux-machine does only one thing: help you model explicit status transitions in reducers. It doesn't prescribe a way of handling asynchronous effects such as API calls. This leaves it open for you to use[no async effects library](http://stackoverflow.com/a/34599594/2482570),[redux-loop](https://github.com/redux-loop/redux-loop),[redux-thunk](https://github.com/gaearon/redux-thunk),[redux-saga](https://github.com/yelouafi/redux-saga), or anything else.

That said, redux-machine fits very naturally withredux-loop, since both enhancehow you can usereducers. Here's how you could use redux-machine with redux-loop:

That said, redux-machine fits very naturally withother tools which enhancethe expressiveness ofreducers, such as redux-loop and redux-side-effect. Here's how you could use redux-machine with redux-loop:

import {loop,Effects }from'redux-loop'