Make async actions easy.
Redux-Observable is the great library based on Rxjs and helps you to handle side-effects of Redux managable application.
To reduce the boilerplate of handling async actions, I've created the redux-async-epic. It includes async-epic itself and gives you some handy helpers to manage outgoing actions.
To install the stable version:
npm install --save redux-async-epic
This assumes you are using npm as your package manager.
The library depends only on rxjs but also has 2 peer dependencies:
- redux-observable
- redux
Usually async actions includes 3 major steps:
- request (turn on pending status)
- wait for response
- response (turn of pending status)
That's why you have to keep minimum three actions:
{type: "fetch"}{type: "success"}{type: "failure"}
if you want to abort the process you will need a fourth action
{type: "abort"}
So, each time when you working with it using redux-observable you have to make something like this:
// epic.js
import { types, fullfill, failure } from "./actions";
const epic = (action$) => (
action$.pipe(
ofType(types.fetch),
mergeMap(action =>
ajax(action.payload).pipe(
map(success),
takeUntil(action$.pipe(
ofType(types.abort)
))
catchError(failure)
)
)
)
)A boilerplate action creators.
// actions.js
export const types = {
fetch: "fetch",
success: "success",
failure: "failure",
abort: "abort"
};
export const fetch = payload => ({
type: types.fetch,
payload
});
export const success = payload => ({
type: types.success,
payload
});
export const failure = error => ({
type: types.failure,
error
});
export const abort = () => ({
type: types.abort
});And finally the reducer:
// reducer.js
import { types } from "./actions";
const initialState = { uiStatus: "idle", items: [], error: null };
export default (state = initialState, action) => {
switch (action.type) {
case types.fetch: {
return {
...state,
uiStatus: "pending"
};
}
case types.success: {
return {
...state,
uiStatus: "success",
items: action.payload
};
}
case types.failure: {
return {
...state,
uiStatus: "failure",
error: action.error
};
}
case types.abort: {
return {
...state,
uiStatus: "idle"
};
}
default: {
return state;
}
}
};There is lot of boilerplate code, isn't it?
It's time to redux-async-epic to shine! To use it, you need to combine async epic to your root epic.
// root-epic.js
import { combineEpics } from "redux-observable";
import { asyncEpic } from "redux-async-epic";
export const rootEpit = combineEpics(asyncEpic); // more of your epicsNow you should define your async action as flux-standard-action:
// actions.js
import { async, getAbortType } from "redux-async-epic";
export const types = {
fetch: "fetch"
};
export const fetch = payload => ({
type: types.fetch,
payload,
meta: {
[async]: true,
method: ({ payload }) => ajax(payload)
}
});
export const abort = () => ({
type: getAbortType(types.fetch) // generates: fetch/abort
});That's it!
- You don't need to create more actions to handle response or pending status
- You don't need to create epic that handles the fetch action
And finally the reducer:
// reducer.js
import { getSuccessType, getFailureType, getAbortType } from "redux-async-epic";
// you can reduce a boilerpalte even more by using "redux-actions"
import { handleActions } from "redux-actions";
import { types } from "./actions";
const initialState = { uiStatus: "idle", items: [], error: null };
export default handleActions({
[types.fetch]: state => {
return {
...state,
uiStatus: "pending"
};
},
[getSuccessType(types.fetch)]: (state, action) => {
return {
...state,
uiStatus: "success",
items: action.payload
};
},
[getFailureType(types.fetch)]: (state, action) => {
return {
...state,
uiStatus: "failure",
error: action.payload
};
},
[getAbortType]: state => {
return {
...state,
uiStatus: "idle"
};
}
});When epic gets an async action it generates three more actions:
{type: "fetch"}{type: "fetch/pending", payload: true}{type: "fetch/success"}or{type: "fetch/failure"}{type: "fetch/pending", payload: false}
When async action is pending it also is listening the {type: "fetch/abort"} action, to break the execution.
As you can see, each time when async action fires it follows by 2 pending actions. That's why you can listen for it and make a global UI spinner.
When async action is failed redux-async-epic generates a special failure action which looks like that:
{
type: "async-action/failure",
error: "something went wront",
meta: [
[failure]: true,
originalPayload: {
user: "admin"
}
]
}Where failure is a special unique symbol. Here the example how you can make a global error handler:
// global failure epic
import { isFailureAction } from "redux-async-epic";
import { filter, tap, ignoreElements } from "rxjs/operators";
// just for example
import { clearCredentials } from "./session/lib";
import { logUnauthorizedAccess } from "./analytics";
import { redirectToErrorPage } from "./router";
export default action$ =>
action.pipe(
filter(isFailureAction),
filter(({ error }) => error.status === 403),
tap(action => {
clearCredentials();
logUnauthorizedAccess(action);
redirectToErrorPage();
}),
ignoreElements()
);In this example we are requiring first 10 comments, and when request is fulfilled we fire another request to get next page of comments.
// helper
const commentRequest = ({ payload }) =>
ajax({
url: "https://comments.server.com",
method: "post",
body: payload
});
// primary action
const fetchComments = (
payload = {
offset: 0,
limit: 10
}
) => ({
type: "fetch",
payload,
meta: {
[async]: true,
method: commentRequest,
onSuccess: () => prefetchNextPage(payload)
}
});
// on-success action
const prefetchNextPage = payload => {
const config = {
...payload,
offset: payload.offset + payload.limit
};
return {
type: "prefetch",
payload: config,
meta: {
[async]: true,
method: commentRequest
}
};
};You can fire even more actions by passing an array of them:
onSuccess: () => [first(), second(), third()];