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 Effects middleware (aka Asynchronous Actions) 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. If you're not familiar with them you may find some useful links here

Unlike Thunks which get invoked on every action by Action Creators. Sagas are fired only once at the start of the application (but startup Sagas may fire other Sagas dynamically). They can be seen as Processes running in the background. Sagas watch the actions dispatched to the Store, then decide what to do based on dispatched actions : Either making an asynchronous call (like an AJAX request), dispatching other actions to the Store or even starting other Sagas dynamically.

In redux-saga all the above tasks are achieved by yielding Effects. Effects are simply JavaScript Objects containing instructions to be executed by the Saga middleware (As an analogy, you can see Redux actions as Objects containing instructions to be executed by the Store). redux-saga provides Effect creators for various tasks like calling an asynchronous function, dispatching an action to the Store, starting a background task or waiting for a future action that satisfies a certain condition.

Using Generators, redux-saga allows you to write your asynchronous code in a simple synchronous style. Just like you can do with async/await functions. But Generators allows some things that aren't possible with async functions.

The fact that Sagas yield plain Objects make it easy to test all the logic inside your Generator by simply iterating over the yielded Objects and doing simple equality tests.

Furthermore, tasks started in redux-saga can be cancelled at any moment either manually or automatically by putting them in a race with other Effects.

Getting started

Install

npm install --save redux-saga

Alternatively, you may use the provided UMD builds directly in the <script> tag of an HTML page. See this section

Usage Example

Suppose we have an UI to fetch some user data from a remote server when a button is clicked (For brevity, we'll just show the action triggering code).

class UserComponent extends React.Component {
  ...
  onSomeButtonClicked() {
    const { userId, dispatch } = this.props
    dispatch({type: 'USER_FETCH_REQUESTED', payload: {userId}})
  }
  ...
}

The Component dispatches a plain Object action to the Store. We'll create a Saga that watches for all USER_FETCH_REQUESTED actions and triggers an API call to fetch the user data

sagas.js

import { takeEvery, takeLatest } from 'redux-saga'
import { call, put } from 'redux-saga/effects'
import Api from '...'

// worker Saga : will be fired on USER_FETCH_REQUESTED 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});
   }
}

/*
  starts fetchUser on each dispatched `USER_FETCH_REQUESTED` action
  Allow concurrent fetches of user
*/
function* mySaga() {
  yield* takeEvery("USER_FETCH_REQUESTED", fetchUser);
}

/*
  Alternatively you may use takeLatest

  Do not allow concurrent fetches of user, If "USER_FETCH_REQUESTED" gets
  dispatched while a fetch is already pending, that pending fetch is cancelled
  and only the latest one will be run
*/
function* mySaga() {
  yield* takeLatest("USER_FETCH_REQUESTED", fetchUser);
}

To run our Saga, we'll have to connect it to the Redux Store using the redux-saga middleware

main.js

import { createStore, applyMiddleware } from 'redux'
import createSagaMiddleware from `redux-saga`

import reducer from './reducers'
import mySaga from './sagas'

const sagaMiddleware = createSagaMiddleware(mySaga)
const store = createStore(
  reducer,
  applyMiddleware(sagaMiddleware)
)

// render the application

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 examples

There are 3 counter examples

counter-vanilla

Demo using vanilla JavaScript and UMD builds. All source is inlined in index.html

To launch the example, just open index.html in your browser

Important Your browser must support Generators. Latest versions of Chrome/Firefox/Edge are suitable.

counter

Demo using webpack and high level API takeEvery

npm run counter

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

cancellable-counter

Demo using low level API. Demonstrate task cancellation

npm run cancellable-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)

npm run real-world

//sorry, no tests yet