redux-saga

What is redux-saga?

redux-saga is a library that aims to make application side effects (i.e., asynchronous things like data fetching and impure things like accessing the browser cache) easier to manage, more efficient to execute, and better at handling failures. It uses an ES6 feature called Generators to make those asynchronous flows easy to read, write, and test.

What are redux-saga's main functionalities?

Handling Asynchronous Actions

This feature allows you to handle asynchronous actions in a more readable and maintainable way. The code sample demonstrates how to fetch user data asynchronously using the `call` effect to call the API and `put` effect to dispatch actions.

function* fetchUser(action) {
  try {
    const user = yield call(Api.fetchUser, action.payload.userId);
    yield put({type: 'USER_FETCH_SUCCEEDED', user: user});
  } catch (e) {
    yield put({type: 'USER_FETCH_FAILED', message: e.message});
  }
}

function* mySaga() {
  yield takeEvery('USER_FETCH_REQUESTED', fetchUser);
}

Managing Side Effects

redux-saga helps manage side effects like delays, API calls, and more. The code sample shows how to delay an increment action by 1 second using the `delay` effect.

import { delay } from 'redux-saga/effects';

function* incrementAsync() {
  yield delay(1000);
  yield put({ type: 'INCREMENT' });
}

function* watchIncrementAsync() {
  yield takeEvery('INCREMENT_ASYNC', incrementAsync);
}

Handling Concurrency

redux-saga provides tools to handle concurrency, ensuring that only the latest action is processed. The code sample demonstrates using `takeLatest` to handle only the most recent fetch request.

import { takeLatest } from 'redux-saga/effects';

function* fetchData(action) {
  try {
    const data = yield call(Api.fetchData, action.payload);
    yield put({ type: 'FETCH_SUCCEEDED', data });
  } catch (error) {
    yield put({ type: 'FETCH_FAILED', error });
  }
}

function* mySaga() {
  yield takeLatest('FETCH_REQUESTED', fetchData);
}

Other packages similar to redux-saga

redux-thunk

redux-thunk is a middleware that allows you to write action creators that return a function instead of an action. It is simpler and more lightweight compared to redux-saga, but it doesn't offer the same level of control over complex asynchronous flows.

redux-observable

redux-observable is an RxJS-based middleware for Redux that allows you to work with async actions using Observables. It is more powerful and flexible than redux-saga for handling complex async logic, but it has a steeper learning curve due to its reliance on RxJS.

rematch

rematch is a Redux framework that abstracts away much of the boilerplate associated with Redux. It includes built-in support for side effects and async actions, making it easier to use than redux-saga, but it may not offer the same level of customization and control.

README

redux-saga

An alternative Side Effect model for Redux applications. Instead of dispatching thunks which get handled by the redux-thunk middleware, you create Sagas to gather all your Side Effects logic in a central place.

This means the logic of the application lives in 2 places:

• Reducers are responsible for handling state transitions between actions

• Sagas are responsible for orchestrating complex/asynchronous operations.

Sagas are created using Generator functions.

As you'll see in the docs, Generators, while seemingly more low-level than ES7 async functions, allow some features like declarative effects and cancellation which are harder—if not impossible—to implement with simple async functions.

What this middleware proposes is:

• A composable abstraction Effect: waiting for an action, triggering state updates (by dispatching actions to the store), and calling a remote service are all different forms of Effects. A Saga composes those Effects using familiar control flow constructs (if, while, for, try/catch).

• The Saga is itself an Effect. It can be combined with other Effects using combinators. It can also be called from inside other Sagas, providing the full power of Subroutines and Structured Programming

• Effects may be yielded declaratively. You yield a description of the Effect which will be executed by the middleware. This makes your operational logic inside Generators fully testable.

• You can implement complex operations with logic that spans across multiple actions (e.g. User onboarding, wizard dialogs, complex Game rules, etc.), which are non-trivial to express using other effects middlewares.

Install

npm install redux-saga

Documentation

• Introduction
• Basic Concepts
• Advanced Concepts
• Recipes
• External Resources
• Troubleshooting
• Glossary
• API Reference

Using umd build in the browser

There's also an umd build of redux-saga available in the dist/ folder. When using the umd build redux-saga is available as ReduxSaga in the window object.

The umd version is useful if you don't use Webpack or Browserify. You can access it directly from npmcdn.

The following builds are available:

• https://npmcdn.com/redux-saga/dist/redux-saga.js
• https://npmcdn.com/redux-saga/dist/redux-saga.min.js

Important! If the browser you are targeting doesn't support es2015 generators you must provide a valid polyfill, for example the one provided by babel: browser-polyfill.min.js. The polyfill must be imported before redux-saga.

import 'babel-polyfill'
// then
import sagaMiddleware from 'redux-saga'

Building examples from sources

git clone https://github.com/yelouafi/redux-saga.git
cd redux-saga
npm install
npm test

Below are the examples ported (so far) from the Redux repos

Counter example

npm run counter

// test sample for the generator
npm run test-counter

Shopping Cart example

npm run shop

// test sample for the generator
npm run test-shop

async example

npm run async

//sorry, no tests yet

real-world example (with webpack hot reloading)

cd examples/real-world
npm install
npm start