redux-promise-middleware-actions

Create Redux actions with a type and payload in a standardized way. Inspired by redux-actions but simpler and with special support for asynchronous actions (promises).

Has no dependencies and is tiny (~680 bytes gzipped). First class TypeScript support.

Works with redux-promise-middleware to handle asynchronous actions by dispatching pending, fulfilled and rejected events based on the state of the input promise.

Goals of this library:

• Reference action creators directly - no need to maintain an action type enum/list
• Automatically generate actions for pending, fulfilled and rejected outcomes of a promise payload
• Have statically typed access to all action types - no need to manually add a type suffix like "_PENDING"
• TypeScript support so asynchronous actions can't be confused for normal synchronous actions

Note: If you are using TypeScript this library requires TypeScript 3. For TypeScript 2 use version 1 of this library.

Installation

You need to install this library as well as redux-promise-middleware.

npm install redux-promise-middleware-actions redux-promise-middleware

Include redux-promise-middleware when you create your store:

1import promiseMiddleware from 'redux-promise-middleware';
2
3composeStoreWithMiddleware = applyMiddleware(
4  promiseMiddleware,
5)(createStore);

NOTE: This library is not yet compatible with the promiseTypeSuffixes option of redux-promise-middleware

Usage

Synchronous action

Synchronous actions works exactly like redux-actions. You supply a function that returns whatever payload the action should have (if any).

1import { createAction } from 'redux-promise-middleware-actions';
2
3export const foo = createAction('FOO', (num) => num);
4
5dispatch(foo(5)); // { type: 'FOO', payload: 5 }

When handling the action in a reducer, you simply cast the action function to a string to return the type. This ensures type safety (no spelling errors) and you can use code navigation to find all uses of an action.

1const fooType = foo.toString(); // 'FOO'

Asynchronous action

When you create an asynchronous action you need to return a promise payload. If your action is called FOO the following events will be dispatched:

1. FOO_PENDING is dispatched immediately
2. FOO_FULFILLED is dispatched when the promise is resolved
   • ... or FOO_REJECTED is dispatched instead if the promise is rejected

1import { createAsyncAction } from 'redux-promise-middleware-actions';
2
3export const fetchData = createAsyncAction('FETCH_DATA', async () => {
4  const res = await fetch(...);
5  return res.json();
6});
7
8dispatch(fetchData()); // { type: 'FETCH_DATA_PENDING' }

An async action function has three properties to access the possible outcome actions: pending, fulfilled and rejected. You can dispatch them directly (in tests etc.):

1dispatch(fetchData.pending());          // { type: 'FETCH_DATA_PENDING' }
2dispacth(fetchData.fulfilled(payload)); // { type: 'FETCH_DATA_FULFILLED', payload: ... }
3dispacth(fetchData.rejected(err));      // { type: 'FETCH_DATA_REJECTED', payload: err, error: true }

But normally you only need them when you are writing reducers:

1case fetchData.pending.toString():   // 'FETCH_DATA_PENDING'
2case fetchData.fulfilled.toString(): // 'FETCH_DATA_FULFILLED'
3case fetchData.rejected.toString():  // 'FETCH_DATA_REJECTED'

Note that if you try and use the base function in a reducer, an error will be thrown to ensure you are not listening for an action that will never happen:

1case fetchData.toString(): // throws an error

Reducer

To create a type safe reducer, createReducer takes a list of handlers that accept one or more actions and returns the new state. You can use it with both synchronous and asynchronous action creators.

createReducer(defaultState, handlerMapsCreator)

1import { createAsyncAction, createReducer } from 'redux-promise-middleware-actions';
2
3const fetchData = createAsyncAction('GET', () => fetch(...));
4
5const defaultState = {};
6
7const reducer = createReducer(defaultState, (handleAction) => [
8  handleAction(fetchData.pending, (state) => ({ ...state, pending: true })),
9  handleAction(fetchData.fulfilled, (state, { payload }) => ({ ...state, pending: false, data: payload })),
10  handleAction(fetchData.rejected, (state, { payload }) => ({ ...state, pending: false, error: payload })),
11]);
12
13reducer(undefined, fetchData()); // { pending: true, data: ..., error: ... }

asyncReducer(asyncActionCreator)

It can get tedious writing the same reducer for every single async action so we've included a simple reducer that does the same as the example above:

1import { asyncReducer } from 'redux-promise-middleware-actions';
2
3const fetchData = createAsyncAction('GET', () => fetch(...));
4const fetchReducer = asyncReducer(fetchData);
5
6fetchReducer() // { data?: Payload, error?: Error, pending?: boolean }

You can also combine it with an existing reducer:

1export default (state, action) => {
2  const newState = fetchReducer(state, action);
3
4  switch (action.type) {
5    case 'SOME_OTHER_ACTION':
6      return { ... };
7    default:
8      return newState;
9  }
10};

Metadata

You can add metadata to any action by supplying an additional metadata creator function. The metadata creator will receive the same arguments as the payload creator:

createAction(type, payloadCreator, metadataCreator)

1const foo = createAction(
2  'FOO',
3  (num) => num,
4  (num) => num + num
5);
6
7dispatch(foo(5)); // { type: 'FOO', meta: 10, payload: 5 }

createAsyncAction(type, payloadCreator, metadataCreator)

1const fetchData = createAsyncAction(
2  'FETCH_DATA',
3  (n: number) => fetch(...),
4  (n: number) => ({ n })
5);
6
7dispatch(fetchData(42));
8// { type: 'FETCH_DATA_PENDING', meta: { n: 42 } }
9// { type: 'FETCH_DATA_FULFILLED', meta: { n: 42 }, payload: Promise<...> }
10// { type: 'FETCH_DATA_REJECTED', meta: { n: 42 }, payload: Error(...) }

Custome Type Delimiters

You can specify a different type delimiter for your async actions:

createAsyncAction(type, payloadCreator, metadataCreator, options)

1const foo = createAsyncAction(
2  'FETCH_DATA',
3  (n: number) => fetch(num),
4  undefined,
5  { promiseTypeDelimiter: '/' }
6);
7
8dispatch(foo());
9// { type: 'FETCH_DATA/PENDING' }
10// { type: 'FETCH_DATA/FULFILLED', payload: ... }
11// { type: 'FETCH_DATA/REJECTED', payload: ... }

Acknowledgements

Thanks to Deox for a lot of inspiration for the TypeScript types.