redux-saga is a library that aims to make side effects (i.e. asynchronous things like data fetching and impure things like accessing the browser cache) in React/Redux applications easier and better.

The mental model is that a saga is like a separate thread in your application that's solely responsible for side effects. redux-saga is a redux middleware, which means this thread can be started, paused and cancelled from the main application with normal redux actions, it has access to the full redux application state and it can dispatch redux actions as well.

Source: https://redux-saga.github.io/redux-saga/index.html

Introduction

In short, redux-saga is about creating listeners for events (redux action).

Three parts of Sagas:

1. Worker saga
2. Watcher saga
3. Root saga

Worker saga example, do work and trigger state update

import axios from 'axios';
import { call, put } from 'redux-saga';
export function* createLessonAsync(action) {
    try {
        // call api
        const response = yield call(axios.get, '...');
        // dispatch action to store (handled by reducer)
        yield put({type: 'lessons/CREATED', response: response.data})
    } catch (e) {
        // handle exception
        yield put({type: 'lessons/CREATE_FAILED', message: e})
    }
}

Watcher saga example, spawn a new task on each action

import { takeEvery } from 'redux-saga';
export function* watchCreateLesson() {
   // listen to 'lessons/CREATE' action and call createLessonAsync worker
    yield takeEvery('lessons/CREATE', createLessonAsync);
}

take / takeEvery effects is to wait for specific actions in the store.

Root saga example, single entry point of starting all sagas

export default function* rootSaga() {
    yield [
        watchCreateLesson()
    ]
}

What happens is that the middleware examines the type of each yielded Effect then decides how to fulfill that Effect. If the Effect type is a PUT then it will dispatch an action to the Store. If the Effect is a CALL then it'll call the given function.

import { delay } from 'redux-saga'
import { put, call, takeEvery } from 'redux-saga/effects'
...
put({type: 'INCREMENT'}) // => { PUT: {type: 'INCREMENT'} }
call(delay, 1000)        // => { CALL: {fn: delay, args: [1000]}}

import { select, take } from 'redux-saga/effects'
function* watchAndLog() {
  while (true) {
    const action = yield take('*')
    const state = yield select()

    console.log('action', action)
    console.log('state after', state)
  }
}

Redux-Saga introduction

Fork effect

When we fork a task, the task is started in the background and the caller can continue its flow without waiting for the forked task to terminate.

Before

function* loginFlow() {
  while (true) {
    // ...
    try {
      const token = yield call(authorize, user, password)
      // ...
    }
    // ...
  }
}

After

function* loginFlow() {
  while (true) {
    ...
    try {
      // non-blocking call, what's the returned value here ?
      const ?? = yield fork(authorize, user, password)
      ...
    }
    ...
  }
}

When using fork effect and to prevent concurrent tasks evolving in parallel, we can use a dedicated effect cancel.

function* loginFlow() {
  while (true) {
    const {user, password} = yield take('LOGIN_REQUEST')
    // fork return a Task object
    const task = yield fork(authorize, user, password)
    const action = yield take(['LOGOUT', 'LOGIN_ERROR'])
    if (action.type === 'LOGOUT')
      yield cancel(task)
    yield call(Api.clearItem, 'token')
  }
}

Suppose that when we receive a LOGIN_REQUEST action, our reducer sets some isLoginPending flag to true so it can display some message or spinner in the UI. If we get a LOGOUT in the middle of an API call and abort the task by simply killing it (i.e. the task is stopped right away), then we may end up again with an inconsistent state. We'll still have isLoginPending set to true and our reducer will be waiting for an outcome action (LOGIN_SUCCESS or LOGIN_ERROR).

Fortunately, the cancel Effect won't brutally kill our authorize task, it'll instead give it a chance to perform its cleanup logic. The cancelled task can handle any cancellation logic (as well as any other type of completion) in its finally block. Since a finally block execute on any type of completion (normal return, error, or forced cancellation), there is an Effect cancelled which you can use if you want handle cancellation in a special way:

function* authorize(user, password) {
  try {
    const token = yield call(Api.authorize, user, password)
    yield put({type: 'LOGIN_SUCCESS', token})
    yield call(Api.storeItem, {token})
    return token
  } catch(error) {
    yield put({type: 'LOGIN_ERROR', error})
  } finally {
    if (yield cancelled()) {
      // ... put special cancellation handling code here
    }
  }
}

Source: https://redux-saga.github.io/redux-saga/docs/advanced/NonBlockingCalls.html

In redux-saga you can dynamically fork tasks that execute in the background using 2 Effects

• fork is used to create attached forks
• spawn is used to create detached forks

This a rule of thumb, you can't catch errors from forked tasks.

Attached forks (fork)

A failure in an attached fork will cause the forking parent to abort (Just like there is no way catch error inside a parallel Effect, only from outside by blocking on the parallel Effect).

Detached forks (spawn)

• own execution context
• parent doesn't wait for detached forks to terminate
• uncaught errors from spawned tasks are not bubbled up to the parent
• cancelling a parent doesn't automatically cancel detached forks

In short, detached forks behave like root Sagas started directly using the middleware.run API.

Running Tasks in Parallel

The yield statement is great for representing asynchronous control flow in a simple and linear style.

// wrong, effects will be executed in sequence
const users  = yield call(fetch, '/users'),
      repos = yield call(fetch, '/repos')

To run task in parallel,

// correct, effects will get executed in parallel
const [users, repos]  = yield [
  call(fetch, '/users'),
  call(fetch, '/repos')
]

Source: https://redux-saga.github.io/redux-saga/docs/advanced/RunningTasksInParallel.html

Race Effect

Sometimes we start multiple tasks in parallel but we don't want to wait for all of them, we just need to get the winner:

Example,

function* fetchPostsWithTimeout() {

  const {posts, timeout} = yield race({
    posts: call(fetchApi, '/posts'),
    timeout: call(delay, 1000)
  })

  if (posts)
    put({type: 'POSTS_RECEIVED', posts})
  else
    put({type: 'TIMEOUT_ERROR'})
}

Example 2,

function* watchStartBackgroundTask() {
  while (true) {
    yield take('START_BACKGROUND_TASK')
    yield race({
      task: call(backgroundTask),
      cancel: take('CANCEL_TASK')
    })
  }
}

In the case a CANCEL_TASK action is dispatched, the race Effect will automatically cancel backgroundTask by throwing a cancellation error inside it.

Source: https://redux-saga.github.io/redux-saga/docs/advanced/RacingEffects.html