redux-actions

Flux Standard Action utilities for Redux.

npm install --save redux-actions

import { createAction, handleAction, handleActions } from 'redux-actions';

createAction(type, payloadCreator = Identity, ?metaCreator)

Wraps an action creator so that its return value is the payload of a Flux Standard Action. If no payload creator is passed, or if it's not a function, the identity function is used.

Example:

let increment = createAction('INCREMENT', amount => amount);
// same as
increment = createAction('INCREMENT');

expect(increment(42)).to.deep.equal({
  type: 'INCREMENT',
  payload: 42
});

If the payload is an instance of an Error object, redux-actions will automatically set action.error to true.

Example:

const increment = createAction('INCREMENT');

const error = new TypeError('not a number');
expect(increment(error)).to.deep.equal({
  type: 'INCREMENT',
  payload: error,
  error: true
});

NOTE: The more correct name for this function is probably createActionCreator(), but that seems a bit redundant.

Use the identity form to create one-off actions:

createAction('ADD_TODO')('Use Redux');

metaCreator is an optional function that creates metadata for the payload. It receives the same arguments as the payload creator, but its result becomes the meta field of the resulting action. If metaCreator is undefined or not a function, the meta field is omitted.

handleAction(type, reducer | reducerMap)

Wraps a reducer so that only handles Flux Standard Actions of a certain type.

If a single reducer is passed, it is used to handle both normal actions and failed actions. (A failed action is analogous to a rejected promise.) You can use this form if you know a certain type of action will never fail, like the increment example above.

Otherwise, you can specify separate reducers for next() and throw(). This API is inspired by the ES6 generator interface.

handleAction('FETCH_DATA', {
  next(state, action) {...}
  throw(state, action) {...}
});

handleActions(reducerMap, ?defaultState)

Creates multiple reducers using handleAction() and combines them into a single reducer that handles multiple actions. Accepts a map where the keys are the passed as the first parameter to handleAction() (the action type), and the values are passed as the second parameter (either a reducer or reducer map).

The optional second parameter specifies a default or initial state, which is used when undefined is passed to the reducer.

(Internally, handleActions() works by applying multiple reducers in sequence using reduce-reducers.)

Example:

const reducer = handleActions({
  INCREMENT: (state, action) => ({
    counter: state.counter + action.payload
  }),

  DECREMENT: (state, action) => ({
    counter: state.counter - action.payload
  })
}, { counter: 0 });

Usage with middleware

redux-actions is handy all by itself, however, its real power comes when you combine it with middleware.

The identity form of createAction is a great way to create a single action creator that handles multiple payload types. For example, using redux-promise and redux-rx:

const addTodo = createAction('ADD_TODO');

// A single reducer...
handleAction('ADD_TODO', (state = { todos: [] }, action) => ({
  ...state,
  todos: [...state.todos, action.payload]
}));

// ...that works with all of these forms:
// (Don't forget to use `bindActionCreators()` or equivalent.
// I've left that bit out)
addTodo('Use Redux')
addTodo(Promise.resolve('Weep with joy'));
addTodo(Observable.of(
  'Learn about middleware',
  'Learn about higher-order stores'
)).subscribe();

See also

Use redux-actions in combination with FSA-compliant libraries.

• redux-promise - Promise middleware
• redux-rx - Includes observable middleware.