Package detail

@redux-saga/deferred

redux-saga3.8mMIT1.2.1

Helper for creating "exposed" promise object (with resolve & reject methods).

promise, resolve, reject, defer

readme

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, easy to test, and better at handling failures.

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.

It uses an ES6 feature called Generators to make those asynchronous flows easy to read, write and test. (if you're not familiar with them here are some introductory links) By doing so, these asynchronous flows look like your standard synchronous JavaScript code. (kind of like async/await, but generators have a few more awesome features we need)

You might've used redux-thunk before to handle your data fetching. Contrary to redux thunk, you don't end up in callback hell, you can test your asynchronous flows easily and your actions stay pure.

Getting started

Install

$ npm install redux-saga

$ yarn add 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 a 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 { call, put, takeEvery, takeLatest } 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.
  Allows concurrent fetches of user.
*/
function* mySaga() {
  yield takeEvery('USER_FETCH_REQUESTED', fetchUser)
}

/*
  Alternatively you may use takeLatest.

  Does 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)
}

export default mySaga

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'

// create the saga middleware
const sagaMiddleware = createSagaMiddleware()
// mount it on the Store
const store = createStore(reducer, applyMiddleware(sagaMiddleware))

// then run the saga
sagaMiddleware.run(mySaga)

// render the application

Documentation

Translation

Using umd build in the browser

There is also a 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. This enables you to create Saga middleware without using ES6 import syntax like this:

var sagaMiddleware = ReduxSaga.default()

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

The following builds are available:

Important! If the browser you are targeting doesn't support ES2015 generators, you must transpile them (i.e. with babel plugin) and provide a valid runtime, such as the one here. The runtime must be imported before redux-saga:

import 'regenerator-runtime/runtime'
// then
import sagaMiddleware from 'redux-saga'

Building examples from sources

$ git clone https://github.com/redux-saga/redux-saga.git
$ cd redux-saga
$ yarn
$ npm test

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

Counter examples

There are three counter examples.

counter-vanilla

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

To launch the example, 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 to 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

# test sample for the generators
$ npm run test-async

real-world example (with webpack hot reloading)

$ npm run real-world

# sorry, no tests yet

TypeScript

Redux-Saga with TypeScript requires DOM.Iterable or ES2015.Iterable. If your target is ES6, you are likely already set, however, for ES5, you will need to add it yourself. Check your tsconfig.json file, and the official compiler options documentation.

Logo

You can find the official Redux-Saga logo with different flavors in the logo directory.

Redux Saga chooses generators over `async/await`

A few issues have been raised asking whether Redux saga plans to use async/await syntax instead of generators.

We will continue to use generators. The primary mechanism of async/await is Promises and it is very difficult to retain the scheduling simplicity and semantics of existing Saga concepts using Promises. async/await simply don't allow for certain things - like i.e. cancellation. With generators we have full power over how & when effects are executed.

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

License

Licensed under The MIT License (MIT).

changelog

Changes from v0.16.0 to v1.0.0

During work on v1, we made several breaking changes

Breaking changes

errors thrown during put execution are no longer caught and swallowed, you need to catch them manually
errors thrown during cancellation process are no longer swallowed, you need to keep finally block fail-safe
removed some deprecated APIs - takeEvery, takeLatest, throttle from the redux-saga entry point (they are and were importable from redux-saga/effects). put.sync and takem were removed.
removing execution of an array of effects yield [...]. use all effect instead.
delay became an effect, old delay function (not effect!) can be imported from @redux-saga/delay-p
put.resolve was changed to putResolve
take.maybe was changed to takeMaybe
changed API of runSaga - it no longer accepts subscribe option, you should create a channel (preferably stdChannel), pass it as channel argument to the runSaga API and communicate with through it with take and put methods
task.done getter was changed to be task.toPromise method
onError doesn't extend error with additional field sagaStack, but pass it as a property of second argument. before: onError: (e: Error), after: onError(e: Error, { sagaStack })
Effect shape, yielded to redux-saga middleware, is stabilized and declared now as a plain JavaScript object
channels private getters (takers and closed) got removed
{effects, utils} aren't imported from 'redux-saga' anymore. imports them from redux-saga/effects, redux-saga/utils
is helper should be imported from @redux-saga/is.
createMockTask, cloneableGenerator should be imported from @redux-saga/testing-utils
now race should be finished if any of effects resolved with END (by analogy with all)
cancel and join cannot receive variadic arguments anymore. so you have to rewrite cancel(...[tasks]) and join(...[tasks]) to cancel([tasks]) and join([tasks]) respectively. also calling cancel(...) returns a cancel-effect (before it may return an all effect), and calling join(...) returns a join-effect.
refactor effect structure from {[IO]: true, [type]: payload } to { [IO]: true, type, payload } to get rid of dynamic type property. Could affect you if implement custom monitor for saga effects.
channel and actionChannel have default buffer of buffers.expanding()
eventChannel does no longer accept matcher argument.
exported util of arrayOfDeffered got renamed to the correct arrayOfDeferred

New functionality

multicastChannel - no buffering, notify all pending takers, multicastChannel#take(cb, matcher = matchers.wildcard)
support for yield take(multicastChannel, pattern)
internal stdChannel got reworked to be a singleton object (it is wrapped multicastChannel's instance'), also it is an exported API to support new runSaga's signature - this should also result in being a small perf boost
effectMiddlewares - useful especially for testing, you can intercept/hijack any effect and resolve it on your own - passing it very redux-style to the next middleware (last being redux-saga itself). How it might be used can be checked here. Many thanks to @eloytoro for this feature
takeLeading helper. It takes "leading" action and ignores all incoming ones of the same type while the "leading" is still handled (useful for things debouncing)
retry helper. Receives a function and executes it (with blocking call). In case of failure will try to make another call after delayLength milliseconds, if a number of attempts < maxTries parameter
add debounce helper. Spawns a saga on an action dispatched to the Store that matches pattern. Saga will be called after it stops taking pattern actions for ms milliseconds. Purpose of this is to prevent calling saga until the actions are settled off.