No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
ashaffer Merge pull request #9 from cutepig/upstream-cherry-pick
Resolve issue with promise propagation
Latest commit aa26312 May 10, 2016
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Call promisify for each step in promise chain. May 10, 2016
test Make default reject handler always rethrow Apr 16, 2016
.babelrc fix babelrc (closes #7) Jan 5, 2016
.gitignore use es6 again Aug 25, 2015
.npmignore add npmignore Aug 25, 2015
Makefile added a test Aug 23, 2015
Readme.md Update Readme.md Oct 14, 2015
package.json Add babel-cli as dependency and update other dependencies Apr 16, 2016

Readme.md

redux-effects

Virtual DOM for effects and impurities. You write pure functions, redux-effects handles the rest.

Installation

npm install redux-effects

Benefits

  • Trivial universality. If your effect middleware is universal, your app is universal.
  • Powerful meta-programming facilities (e.g. request caching)
  • More testable code
  • Better insights into what is happening in your application (e.g. logging effects)
  • Better ability to serialize state

Usage

Add redux-effects anywhere in your redux middleware stack*:

import effects from 'redux-effects'
import fetch from 'redux-effects-fetch'
import cookie from 'redux-effects-cookie'
import location from 'redux-effects-location'

applyMiddleware(effects, fetch, cookie, location)

* It used to need to come first, but that is no longer the case

In action creators

All effectful action creators should return a declarative object describing the effect to be done, even if their operation is normally synchronous*. In order to operate on the values returned by these actions, you need to specify your handlers in .meta.steps in the action object. This library comes with a composition utility bind, but you are free to write your own such as declarative-promise.

*E.g. Math.random or accessing cookies. These values are also impure, even though they are synchronous, because they are non-deterministic with respect to your function's parameters.

import {bind} from 'redux-effects'
import {cookie} from 'redux-effects-cookie'
import {createAction} from 'redux-actions'

function checkAuth () {
  return bind(cookie('authToken'), setAuthToken)
}

const setAuthToken = createAction('SET_AUTH_TOKEN')

The values returned by your actions will be passed to the handlers specified on your action object. Then, what your handlers return will be dispatched back into redux to either trigger other effects or be preserved in state. If your functions do not return a value, they do not do anything. Their only ability to effect the world is by ultimately dispatching actions that trigger state reducers, or by triggering effects that cause state to be preserved elsewhere (e.g. a POST request to an API server).

Effect composition

Effects compose by placing steps in .meta.steps on the action object. E.g.

{
  type: 'EFFECT_COMPOSE',
  payload: {
    type: 'FETCH'
    payload: {url: '/some/thing', method: 'GET'}
  },
  meta: {
    steps: [
      [success, failure]
    ]
  }
}

Since this is cumbersome to write out, there are libraries / action creators to help with it:

But it is important to understand that ultimately these libraries just produce plain JS objects, and you are totally free to create your own composition interfaces that behave exactly the way you want if you don't like these. There is nothing magical going on.

Writing effectful middleware

Effects middleware look essentially just like regular redux middleware, except that it must return a promise. If it does not return a promise, it won't compose with other effects, and so won't be very useful to anyone.

As a general rule, your effect middleware should be as dumb as possible. There are two reasons for this:

  • Effect middleware is inherently impure, and therefore difficult to test and reason about
  • Keeping complexity out of the effect middleware ensures it is as generally useful as possible, and as open as possible to abstraction and metaprogramming.

Example - Simple cookie middleware

import cookie from 'component-cookie'

export default function ({dispatch, getState}) {
  return next => action => {
    if (action.type !== 'COOKIE') {
      return next(action)
    }

    switch (action.verb) {
      case 'set':
        return Promise.resolve(cookie(action.name, action.value))
      case 'get':
        return Promise.resolve(cookie(action.name))
    }
  }
}

Example - Universal cookie middleware

import _cookie from 'component-cookie'

export default function (cookieMap) {
  return ({dispatch, getState}) => next => action => {
    if (action.type !== 'COOKIE') {
      return next(action)
    }

    switch (action.verb) {
      case 'set':
        return Promise.resolve(cookie(action.name, action.value))
      case 'get':
        return Promise.resolve(cookie(action.name))
    }
  }

  function cookie (name, value) {
    if (arguments.length === 2) {
      if (cookieMap) cookieMap[name] = value
      else _cookie(name, value)
    }

    return cookieMap ? cookieMap[name] : _cookie(name)
  }
}

With this form, you can simply initialize your cookie middleware with a map of cookies. E.g.

function (req, res, next) {
  req.store = applyMiddleware(effects(cookie(req.cookies)))(createStore)
}

Metaprogramming

Where this approach gets really interesting is when you start applying transformations to your effects. Normally these things are implemented in disparate and often hacky ways. But when you have declarative descriptions of all of your effects, you can unify your transformations into your redux middleware stack, and they can be completely orthogonal to the actual implementations of the effects themselves. Here are some examples:

Request caching

function httpCache () {
  const {get, set, check} = cache()

  return next => action =>
   !isGetRequest(action)
      ? next(action)
      : check(action.payload.url)
        ? Promise.resolve(get(action.payload.url))
        : next(action).then(set(action.payload.url))
}

Response normalization

function normalize () {
  return next => action =>
    isGetRequest(action)
      ? next(action).then(normalizr)
      : next(action)
}

Note that while these examples both transform http requests, they are completely orthogonal to the actual implementation of those requests, and completely orthogonal to the action creator interface you choose to use to generate your descriptors. That means you can:

  • Swap out your http request implementation
  • Change your action creator interface
  • Use a different effect composition strategy
  • ...And most importantly, compose other transformations

And not have to change your transform middleware at all.

Ecosystem

Effect drivers

Plugins that enable various effects:

Alternate composition middleware

Composition helpers