Redux Butterfly

Side effects middleware for Redux.

npm install redux-butterfly

or

yarn add redux-butterfly

Attention

If you use Butterfly in CommonJS environment, don’t forget to add .default to your import

const butterfly = require('redux-butterfly').default

What this does?

This library acts similary to redux-thunk

Its a middleware which alows you to use action creators which return a function. This function recieves set of enhancments. Those enhancments are then available on action creator. More on that below. Additionaly, if you return promise as a key named payload in your action. Butterfly will automaticaly dispatch start, success, and error actions for you.

Why this silly name? Because butterflies

Usage

import { applyMiddleware, createStore } from 'redux'
import butterfly from 'redux-butterfly'

import rootReducer from './reducers'

const config = {
  enhancers: {
    statics, // default: {}
    dynamics, // default: {}
  },
  enums: {
    start: START, // default: "START"
    success: SUCCESS, // default: "SUCCESS"
    error: ERROR, // default: "ERROR"
  },
}

const store = createStore(
  reducers,
  devToolsEnhancer(),
  applyMiddleware(butterfly(config), ...othermidlewares)
)

You may notice two config keys.

enhancers - this is where your enhancers will go

enums - define enum values for actions. MW will dispatch ACTION_TYPE_{value} for you automaticaly.

Enhancers

Enhancers are functions which are provided to the function returned by the action creator. There are two types: statics and dynamics

statics looks like this:

someValue => console.log(someValue)

dynamics:

(store) => store.someValue
(store) => (value) => `${store.someValue}_${value}`

As you can see - dynamic enhancment gets a redux store as an input parameter, then its up to you what you want to do with it. For example you can have function which makes an API calls and always takes user token from the redux store. This function is then available in action creator.

Action creator

const api = store => url =>
  fetch(url, {
    headers: {
      Authorization: store.session.token,
    },
  })

Then pass it to mw as a dynamic enhancer and use it in action creator

export const logIn = (username, password) => ({ api }) => ({
  type: LOG_IN,
  payload: api('http://example.com'),
})

If you dont pass payload (or you do, but its not a promise), or your action creator doesnt return a function, butterfly simply passes the action into next middleware.

And since you can pass promise to payload, you can use async action as a value of a payload and await complex api calls there, to avoid thunk promise chain hell.

Typescript

import { ButterflyAction, ButterflyProps, ButterflyResult } from './types'

interface Store {
  auth: { token: string}
}

interface User {
  name: string
  age: number
  token?: string
}

enum ActionTypes {
  GET_USER = 'GET_USER',
  GET_USER_SUCCESS = 'GET_USER_SUCCESS'
}

interface UserActionMeta {
  token: string
}


const getUser = (id: string) => ({ getState, logger }: ButterflyProps<Store>): ButterflyAction => {
  const { auth: { token } } = getState()
  return {
    type: 'GET_USER',
    payload: fetch('some_url', { headers: { authorization: token }}).then(res => res.json()),
    onSuccess: (data: User) => logger(data),
    token,
  }
}

const reducer = (state: Store, action: ButterflyResult<ActionTypes, User, UserActionMeta>) => {
  switch (action.type) {
    case ActionTypes.GET_USER_SUCCESS:
      return {
        ...action.payload,
        token: action.rest.token
      }

    default:
      return state
  }
}