Repository files navigation

Sensible promise handling and middleware for redux

redux-pack is a library that introduces promise-based middleware that allows async actions based on the lifecycle of a promise to be declarative.

Async actions in redux are often done usingredux-thunk or other middlewares. The problem with this approach is that it makes it too easy to usedispatch sequentially, and dispatch multiple "actions" as the result of the same interaction/event, where they probably should have just been a single action dispatch.

This can be problematic because we are treating several dispatches as all part of a single transaction, but in reality, each dispatch causes a separate rerender of the entire component tree, where we not only pay a huge performance penalty, but also risk the redux store being in an inconsistent state.

redux-pack helps prevent us from making these mistakes, as it doesn't give us the power of adispatch function, but allows us to do all of the things we were doing before.

To give you some more context into the changes, here are some examples/information about the old way and new way of doing things below:

Ready to use it? Jump straight to theHow-To and API doc

Before this change, you would create individual action constants for each lifecycle of the promise, and useredux-thunk to dispatch before the promise, and when it resolves/rejects.

// types.jsexportconstLOAD_FOO_STARTED='LOAD_FOO_STARTED';exportconstLOAD_FOO_SUCCESS='LOAD_FOO_SUCCESS';exportconstLOAD_FOO_FAILED='LOAD_FOO_FAILED';

// actions.jsexportfunctionloadFoo(id){returndispatch=>{dispatch({type:LOAD_FOO_STARTED,payload:id});returnApi.getFoo(id).then(foo=>{dispatch({type:LOAD_FOO_SUCCESS,payload:foo});}).catch(error=>{dispatch({type:LOAD_FOO_FAILED,error:true,payload:error});});};}

In the reducer, you would handle each action individually in your reducer:

// reducer.jsexportfunctionfooReducer(state=initialState,action){const{ type, payload}=action;switch(type){caseLOAD_FOO_STARTED:return{        ...state,isLoading:true,fooError:null};caseLOAD_FOO_SUCCESS:return{        ...state,isLoading:false,foo:payload};caseLOAD_FOO_FAILED:return{        ...state,isLoading:false,fooError:payload};default:returnstate;}}

Note: The example uses{ ...state } syntax that is calledObject rest spread properties. If you'd prefer the API ofImmutable.js, you could write code like the following:

switch(type){caseLOAD_FOO_STARTED:returnstate.set('isLoading',true).set('fooError',null);caseLOAD_FOO_SUCCESS:// ...}

With redux-pack, we only need to define a single action constant for the entire promise lifecycle, and then return the promise directly with apromise namespace specified:

// types.jsexportconstLOAD_FOO='LOAD_FOO';

// actions.jsexportfunctionloadFoo(id){return{type:LOAD_FOO,promise:Api.getFoo(id),};}

In the reducer, you handle the action with redux-pack'shandle function, where you can specify several smaller "reducer" functions for each lifecycle.finish is called for both resolving/rejecting,start is called at the beginning,success is called on resolve,failure is called on reject, andalways is called for all of them.

// reducer.jsimport{handle}from'redux-pack';exportfunctionfooReducer(state=initialState,action){const{ type, payload}=action;switch(type){caseLOAD_FOO:returnhandle(state,action,{start:prevState=>({          ...prevState,isLoading:true,fooError:null}),finish:prevState=>({ ...prevState,isLoading:false}),failure:prevState=>({ ...prevState,fooError:payload}),success:prevState=>({ ...prevState,foo:payload}),});default:returnstate;}}

Often times we want to log whether an action succeeded or not etc. We are able to handle this now using theonSuccess oronFailure meta options:

Before:

// actions.jsexportfunctionloadFoo(id){returndispatch=>{dispatch(loadFooStart());Api.getFoo(id).then(response=>{dispatch(loadFooSucceeded(response);logSuccess(response);}).catch(error=>dispatch(loadFooFailed(error)));};}

After:

// actions.jsexportfunctionloadFoo(id){return{type:LOAD_FOO,promise:Api.getFoo(id),meta:{onSuccess:(response)=>logSuccess(response)},};}

The first step is to addredux-pack in your project

npm install -S redux-pack# oryarn add redux-pack

Theredux-pack middleware is the heart ofredux-pack. As the following example shows, it installs like most middlewares:

import{createStore,applyMiddleware}from'redux'import{middlewareasreduxPackMiddleware}from'redux-pack'importthunkfrom'redux-thunk'importcreateLoggerfrom'redux-logger'importrootReducerfrom'./reducer'constlogger=createLogger()conststore=createStore(rootReducer,applyMiddleware(thunk,reduxPackMiddleware,logger))

Note that it should probably be one of the first middleware to run, here it would run just afterthunk and beforelogger.

Let's start with the function signature:handle(state, action, handlers) → newState

As you can see, it takes 3 arguments:

1. state: the current state in your reducer
2. action: the action that should be handled
3. handlers: a object mapping the promise lifecycle steps to reducer functions

• the steps names are:start,finish,failure,success andalways
• every handler function should be of the form:state => state

Here is a minimalist example:

import{handle}from'redux-pack';import{getFoo}from'../api/foo';constLOAD_FOO='LOAD_FOO';constinitialState={isLoading:false,error:null,foo:null,};exportfunctionfooReducer(state=initialState,action){const{ type, payload}=action;switch(type){caseLOAD_FOO:returnhandle(state,action,{start:prevState=>({ ...prevState,isLoading:true,error:null,foo:null}),finish:prevState=>({ ...prevState,isLoading:false}),failure:prevState=>({ ...prevState,error:payload}),success:prevState=>({ ...prevState,foo:payload}),always:prevState=>prevState,// unnecessary, for the sake of example});default:returnstate;}}exportfunctionloadFoo(){return{type:LOAD_FOO,promise:getFoo(),}}

Note: The example uses{ ...state } syntax that is calledObject rest spread properties.

You might want to add side effects (like sending analytics events or navigate to different views) based on promise results.

redux-pack lets you do that through event hooks functions. These are functions attached to themeta attribute of the original action. They are called with two parameters:

1. the matching step payload (varies based on the step, details below)
2. thegetState function

Here are the available hooks and their associated payload:

• onStart, called with the initial actionpayload value
• onFinish, called withtrue if the promise resolved,false otherwise
• onSuccess, called with the promise resolution value
• onFailure, called with the promise error

Here is an example usage to send analytics event when the userdoesFoo:

import{sendAnalytics}from'../analytics';import{doFoo}from'../api/foo';exportfunctionuserDoesFoo(){return{type:DO_FOO,promise:doFoo(),meta:{onSuccess:(result,getState)=>{constuserId=getState().currentUser.id;constfooId=result.id;sendAnalytics('USER_DID_FOO',{          userId,          fooId,});}}}}

At the moment, testing reducers and action creators withredux-pack doesrequire understanding a little bit about its implementation. Thehandlemethod uses a specialKEY.LIFECYCLE property on themeta object on theaction that denotes the lifecycle of the promise being handled.

Right now it is suggested to make a simple helper method to make testingeasier. Simple test code might look something like this:

import{LIFECYCLE,KEY}from'redux-pack';importFooReducerfrom'../path/to/FooReducer';// this utility method will make an action that redux pack understandsfunctionmakePackAction(lifecycle,{ type, payload, meta={}}){return{    type,    payload,meta:{      ...meta,[KEY.LIFECYCLE]:lifecycle,},}}// your test code would then look something like...constinitialState={ ...};constexpectedEndState={ ...};constaction=makePackAction(LIFECYCLE.START,{type:'FOO',payload:{ ...}});constendState=FooReducer(initialState,action);assertDeepEqual(endState,expectedEndState);