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:
Sagas are created using Generator functions.
As you'll see in the rest of this README, 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.
-
Getting started
-
Waiting for future actions
-
Dispatching actions to the store
-
A common abstraction: Effect
-
Declarative Effects
-
Error handling
-
Effect Combinators
-
Sequencing Sagas via yield*
-
Composing Sagas
-
Non blocking calls with fork/join
-
Task cancellation
-
Dynamically starting Sagas with runSaga
-
Building examples from sources
-
Using umd build in the browser
#Getting started
Install
npm install redux-saga
Create the Saga (using the counter example from Redux)
import { take, put } from 'redux-saga'
function* incrementAsync() {
while(true) {
const nextAction = yield take(INCREMENT_ASYNC)
yield delay(1000)
yield put( increment() )
}
}
export default [incrementAsync]
Plug redux-saga in the middleware pipeline
import sagaMiddleware from 'redux-saga'
import sagas from '../sagas'
const createStoreWithSaga = applyMiddleware(
sagaMiddleware(...sagas)
)(createStore)
export default function configureStore(initialState) {
return createStoreWithSaga(reducer, initialState)
}
#Waiting for future actions
In the previous example we created an incrementAsync
Saga. The call yield take(INCREMENT_ASYNC)
is an
illustration of how Sagas typically work.
Typically, actual middlewares handle some Effect form triggered by an Action Creator. For example,
redux-thunk handles thunks by calling them with (getState, dispatch)
as arguments,
redux-promise handles Promises by dispatching their resolved values, and redux-gen handles generators by
dispatching all yielded actions to the store. The common thing that all those middlewares share is the
same 'call on each action' pattern. They will be called again and again each time an action happens,
i.e. they are scoped by the root action that triggered them.
Sagas work differently, they are not fired from within Action Creators but are started with your
application and choose what user actions to watch. They are like daemon tasks that run in
the background and choose their own logic of progression. In the example above, incrementAsync
pulls
the INCREMENT_ASYNC
action using yield take(...)
. This is a blocking call, which means the Saga
will not progress until it receives a matching action.
Above, we used the form take(INCREMENT_ASYNC)
, which means we're waiting for an action whose type
is INCREMENT_ASYNC
.
take
support some more patterns to constrain future actions matching. A call of yield take(PATTERN)
will be
handled using the following rules
-
If PATTERN is undefined or '*'
all incoming actions are matched (e.g. take()
will match all actions)
-
If PATTERN is a function, the action is matched if PATTERN(action) is true (e.g. take(action => action.entities)
will match all actions having a (truthy) entities
field.)
-
If PATTERN is a string, the action is matched if action.type === PATTERN
(as used above take(INCREMENT_ASYNC)
-
If PATTERN is an array, action.type is matched against all items in the array (e.g. take([INCREMENT, DECREMENT])
will
match either actions of type INCREMENT
or DECREMENT
).
#Dispatching actions to the store
After receiving the queried action, the Saga triggers a call to delay(1000)
, which in our example
returns a Promise that will resolve after 1 second. This is a blocking call, so the Saga
will wait for 1 second before continuing on.
After the delay, the Saga dispatches an INCREMENT_COUNTER
action using the put(action)
function. Here also, the Saga will wait for the dispatch result. If the dispatch call returns
a normal value, the Saga resumes immediately (ASAP), but if the result value is a Promise then the
Saga will wait until the Promise is resolved (or rejected).
#A common abstraction: Effect
To generalize: waiting for a future action, waiting for the future result of a function call like
yield delay(1000)
, or waiting for the result of a dispatch all are the same concept. In all cases,
we are yielding some form of Effects.
What a Saga does is actually compose all those effects together to implement the desired control flow.
The simplest is to sequence yielded Effects by just putting the yields one after another. You can also use the
familiar control flow operators (if
, while
, for
) to implement more sophisticated control flows. Or you
you can use the provided Effects combinators to express concurrency (yield race) and parallelism (yield [...]).
You can even yield calls to other Sagas, allowing the powerful routine/subroutine pattern.
For example, incrementAsync
uses an infinite loop while(true)
which means it will stay alive
for the entirety of the application's lifetime.
You can also create Sagas that last a limited amount of time. For example, the following Saga
waits for the first 3 INCREMENT_COUNTER
actions, triggers a showCongratulation()
action and then finishes.
function* onBoarding() {
for(let i = 0; i < 3; i++)
yield take(INCREMENT_COUNTER)
yield put( showCongratulation() )
}
#Declarative Effects
Sagas Generators can yield Effects in multiple forms. The simplest way is to yield a Promise.
function* fetchSaga() {
const products = yield fetch('/products')
yield put( receiveProducts(products) )
}
In the example above, fetch('/products')
returns a Promise that will resolve with the GET response,
so the 'fetch effect' will be executed immediately. Simple and idiomatic but...
Suppose we want to test generator above:
const iterator = fetchSaga()
assert.deepEqual( iterator.next().value, ?? )
We want to check the result of the first value yielded by the generator, which is in our case the result of running
fetch('/products')
. Executing the real service during tests is neither a viable nor practical approach, so we have to
mock the fetch service, i.e. we'll have to replace the real fetch
method with a fake one which doesn't actually
run the GET request but only checks that we've called fetch
with the right arguments ('/products'
in our case).
Mocks make testing more difficult and less reliable. On the other hand, functions that simply return values are
easier to test, since we can use a simple equal()
to check the result. This is the way to write the most reliable tests.
Not convinced? I encourage you to read this [Eric Elliott' article]
(https://medium.com/javascript-scene/what-every-unit-test-needs-f6cd34d9836d#.4ttnnzpgc)
(...)equal()
, by nature answers the two most important questions every unit test must answer, but most don’t:
- What is the actual output?
- What is the expected output?
If you finish a test without answering those two questions, you don’t have a real unit test. You have a sloppy, half-baked test.
What we actually need is just to make sure the fetchSaga
yields a call with the right function and the right
arguments. For this reason, the library provides some declarative ways to yield Side Effects while still making it
easy to test the Saga logic
import { call } from 'redux-saga'
function* fetchSaga() {
const products = yield call( fetch, '/products' )
}
We're using now the call(fn, ...args)
function. The difference from the preceeding example is that now we're not
executing the fetch call immediately, instead, call
creates a description of the effect. Just as in
Redux you use action creators to create a plain object describing the action that will get executed by the Store,
call
creates a plain object describing the function call. The redux-saga middleware takes care of executing
the function call and resuming the generator with the resolved response.
This allows us to easily test the Generator outside the Redux environment.
import { call } from 'redux-saga'
const iterator = fetchSaga()
assert.deepEqual(iterator.next().value, call(fetch, '/products'))
Now we don't need to mock anything, and a simple equality test will suffice.
The advantage of declarative effects is that we can test all the logic inside a Saga/Generator
by simply iterating over the resulting iterator and doing a simple equality tests on the values
yielded successively. This is a real benefit, as your complex asynchronous operations are no longer
black boxes, and you can test in detail their operational logic no matter how complex it is.
To invoke methods of some object (i.e. created with new
), you can provide a this
context to the
invoked functions using the following form:
yield call([obj, obj.method], arg1, arg2, ...)
apply
is an alias for the method invocation form
yield apply(obj, obj.method, [arg1, arg2, ...])
call
and apply
are well suited for functions that return Promise results. Another function
cps
can be used to handle Node style functions (e.g. fn(...args, callback)
where callback
is of the form (error, result) => ()
). For example:
import { cps } from 'redux-saga'
const content = yield cps(readFile, '/path/to/file')
and of course you can test it just like you test call:
import { cps } from 'redux-saga'
const iterator = fetchSaga()
assert.deepEqual(iterator.next().value, cps(readFile, '/path/to/file') )
cps
supports also the same method invocation form as call
.
#Error handling
You can catch errors inside the Generator using the simple try/catch syntax. In the following example,
the Saga catch errors from the api.buyProducts
call (i.e. a rejected Promise)
function* checkout(getState) {
while( yield take(types.CHECKOUT_REQUEST) ) {
try {
const cart = getState().cart
yield call(api.buyProducts, cart)
yield put(actions.checkoutSuccess(cart))
} catch(error) {
yield put(actions.checkoutFailure(error))
}
}
}
Of course you're not forced to handle you API errors inside try
/catch
blocks, you can also make
your API service return a normal value with some error flag on it.
function buyProducts(cart) {
return doPost(...)
.then(result => {result})
.catch(error => {error})
}
function* checkout(getState) {
while( yield take(types.CHECKOUT_REQUEST) ) {
const cart = getState().cart
const {result, error} = yield call(api.buyProducts, cart)
if(!error)
yield put(actions.checkoutSuccess(result))
else
yield put(actions.checkoutFailure(error))
}
}
#Effect Combinators
The yield
statement is great for representing asynchronous control flow in a simple and linear
style, but we also need to do things in parallel. We can't simply write:
const users = yield call(fetch, '/users'),
repose = yield call(fetch, '/repose')
Because the 2nd effect will not get executed until the first call resolves. Instead we have to write:
import { call } from 'redux-saga'
const [users, repose] = yield [
call(fetch, '/users'),
call(fetch, '/repose')
]
When we yield an array of effects, the generator is blocked until all the effects are resolved (or as soon as
one is rejected, just like how Promise.all
behaves).
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: the first one that resolves (or rejects). The race
function offers a way of
triggering a race between multiple effects.
The following sample shows a Saga that triggers a remote fetch request, and constrain the response with a
1 second timeout.
import { race, take, put } from 'redux-saga'
function* fetchPostsWithTimeout() {
while( yield take(FETCH_POSTS) ) {
const {posts, timeout} = yield race({
posts : call(fetchApi, '/posts'),
timeout : call(delay, 1000)
})
if(posts)
put( actions.receivePosts(posts) )
else
put( actions.timeoutError() )
}
}
#Sequencing Sagas via yield*
You can use the builtin yield*
operator to compose multiple sagas in a sequential way.
This allows you to sequence your macro-tasks in a simple procedural style.
function* playLevelOne(getState) { ... }
function* playLevelTwo(getState) { ... }
function* playLevelThree(getState) { ... }
function* game(getState) {
const score1 = yield* playLevelOne(getState)
put(showScore(score1))
const score2 = yield* playLevelTwo(getState)
put(showScore(score2))
const score3 = yield* playLevelThree(getState)
put(showScore(score3))
}
Note that using yield*
will cause the JavaScript runtime to spread the whole sequence.
The resulting iterator (from game()
) will yield all values from the nested
iterators. A more powerful alternative is to use the more generic middleware composition mechanism.
#Composing Sagas
While using yield*
provides an idiomatic way of composing Sagas, this approach has some limitations:
-
You'll likely want to test nested generators separately. This leads to some duplication in the test
code as well as the overhead of the duplicated execution. We don't want to execute a nested generator
but only make sure the call to it was issued with the right argument.
-
More importantly, yield*
allows only for sequential composition of tasks, so you can only
yield* to one generator at a time.
You can simply use yield
to start one or more subtasks in parallel. When yielding a call to a
generator, the Saga will wait for the generator to terminate before progressing, then resume
with the returned value (or throws if an error propagates from the subtask).
function* fetchPosts() {
yield put( actions.requestPosts() )
const products = yield call(fetchApi, '/products')
yield put( actions.receivePosts(products) )
}
function* watchFetch() {
while ( yield take(FETCH_POSTS) ) {
yield call(fetchPosts)
}
}
Yielding to an array of nested generators will start all the sub-generators in parallel and wait
for them to finish. Then resume with all the results
function* mainSaga(getState) {
const results = yield [ call(task1), call(task2), ...]
yield put( showResults(results) )
}
In fact, yielding Sagas is no different than yielding other effects (future actions, timeouts, etc).
This means you can combine those Sagas with all the other types using the effect combinators.
For example you may want the user to finish some game in a limited amount of time:
function* game(getState) {
let finished
while(!finished) {
const {score, timeout} = yield race({
score : call( play, getState),
timeout : call(delay, 60000)
})
if(!timeout) {
finished = true
yield put( showScore(score) )
}
}
}
#Non blocking calls with fork/join
the yield
statement causes the generator to pause until the yielded effect resolves or rejects.
If you look closely at this example:
function* watchFetch() {
while ( yield take(FETCH_POSTS) ) {
yield put( actions.requestPosts() )
const posts = yield call(fetchApi, '/posts')
yield put( actions.receivePosts(posts) )
}
}
the watchFetch
generator will wait until yield call(fetchApi, '/posts')
terminates. Imagine that the
FETCH_POSTS
action is fired from a Refresh
button. If our application disables the button between
each fetch (no concurrent fetches) then there is no issue, because we know that no FETCH_POSTS
action
will occur until we get the response from the fetchApi
call.
But what happens if the application allows the user to click on Refresh
without waiting for the
current request to terminate?
The following example illustrates a possible sequence of the events
UI watchFetch
--------------------------------------------------------
FETCH_POSTS.....................call fetchApi........... waiting to resolve
........................................................
........................................................
FETCH_POSTS............................................. missed
........................................................
FETCH_POSTS............................................. missed
................................fetchApi returned.......
........................................................
When watchFetch
is blocked on the fetchApi
call, all FETCH_POSTS
occurring in between the
call and the response are missed.
To express non-blocking calls, we can use the fork
function. A possible rewrite of the previous example
with fork
can be:
import { fork, call, take, put } from 'redux-saga'
function* fetchPosts() {
yield put( actions.requestPosts() )
const posts = yield call(fetchApi, '/posts')
yield put( actions.receivePosts(posts) )
}
function* watchFetch() {
while ( yield take(FETCH_POSTS) ) {
yield fork(fetchPosts)
}
}
fork
, just like call
, accepts function/generator calls.
yield fork(func, ...args)
yield fork(generator, ...args)
The result of yield fork(api)
is a Task descriptor. To get the result of a forked Task
in a later time, we use the join
function
import { fork, join } from 'redux-saga'
function* child() { ... }
function *parent() {
const task = yield fork(subtask, ...args)
const result = yield join(task)
}
the task object exposes some useful methods
method | return value |
---|
task.isRunning() | true if the task hasn't yet returned or throwed an error |
task.result() | task return value. `undefined` if task is still running |
task.error() | task thrown error. `undefined` if task is still running |
task.done |
a Promise which is either
- resolved with task's return value
- rejected with task's thrown error
|
#Task cancellation
Once a task is forked, you can abort its execution using yield cancel(task)
. Cancelling
a running task will throw a SagaCancellationException
inside it.
To see how it works, let's consider a simple example. A background sync which can be
started/stopped by some UI commands. Upon receiving a START_BACKGROUND_SYNC
action,
we fork a background task that will periodically sync some data from a remote server.
The task will execute continually until a STOP_BACKGROUND_SYNC
action is triggered.
Then we cancel the background task and wait again for the next START_BACKGROUND_SYNC
action.
import { take, put, call, fork, cancel, SagaCancellationException } from 'redux-saga'
import actions from 'somewhere'
import { someApi, delay } from 'somewhere'
function* bgSync() {
try {
while(true) {
yield put(actions.requestStart())
const result = yield call(someApi)
yield put(actions.requestSuccess(result))
yield call(delay, 5000)
}
} catch(error) {
if(error instanceof SagaCancellationException)
yield put(actions.requestFailure('Sync cancelled!'))
}
}
function* main() {
while( yield take(START_BACKGROUND_SYNC) ) {
const bgSyncTask = yield fork(bgSync)
yield take(STOP_BACKGROUND_SYNC)
yield cancel(bgSyncTask)
}
}
yield cancel(bgSyncTask)
will throw a SagaCancellationException
inside the currently running task. In the above example, the exception is caught by
bgSync
. Note that uncaught SagaCancellationException are not bubbled upward. In the
above example, if bgSync
doesn't catch the cancellation error, the error will not propagate
to main
(because main
has already moved on).
Cancelling a running task will also cancel the current effect where the task is blocked
at the moment of cancellation.
For example, suppose that at a certain point in an application's lifetime, we had this pending call chain:
function* main() {
const task = yield fork(subtask)
...
yield cancel(task)
}
function* subtask() {
...
yield call(subtask2)
...
}
function* subtask2() {
...
yield call(someApi)
...
}
yield cancel(task)
will trigger a cancellation on subtask
, which in turn will trigger
a cancellation on subtask2
. A SagaCancellationException
will be thrown inside subtask2
,
then another SagaCancellationException
will be thrown inside subtask
. If subtask
omits to handle the cancellation exception, a warning message is printed to the console to
warn the developer (the message is only printed if there is a process.env.NODE_ENV
variable
set and it's set to 'development'
).
The main purpose of the cancellation exception is to allow cancelled tasks to perform any
cleanup logic, so we wont leave the application in an inconsistent state. In the above example
of background sync, by catching the cancellation exception, bgSync
is able to dispatch a
requestFailure
action to the store. Otherwise, the store could be left in a inconsistent
state (e.g. waiting for the result of a pending request).
It's important to remember that yield cancel(task)
doesn't wait for the cancelled task
to finish (i.e. to perform its catch block). The cancel effect behave like fork. It returns
as soon as the cancel was initiated.
Once cancelled, a task should normally return as soon as it finishes its cleanup logic.
In some cases, the cleanup logic could involve some async operations, but the cancelled
task lives now as a separate process, and there is no way for it to rejoin the main
control flow (except dispatching actions for other tasks via the Redux store. However
this will lead to complicated control flows that are hard to reason about. It's always preferable
to terminate a cancelled task ASAP).
##Automatic cancellation
Besides manual cancellation there are cases where cancellation is triggered automatically
1- In a race
effect. All race competitors, except the winner, are automatically cancelled.
2- In a parallel effect (yield [...]
). The parallel effect is rejected as soon as one of the
sub-effects is rejected (as implied by Promise.all
). In this case, all the other sub-effects
are automatically cancelled.
#Dynamically starting Sagas with runSaga
The runSaga
function allows starting sagas outside the Redux middleware environment. It also
allows you to hook up to external input/output, other than store actions.
For example, you can start a Saga on the server using:
import serverSaga from 'somewhere'
import {runSaga, storeIO} from 'redux-saga'
import configureStore from 'somewhere'
import rootReducer from 'somewhere'
const store = configureStore(rootReducer)
runSaga(
serverSaga(store.getState),
storeIO(store)
).done.then(...)
runSaga
returns a task object. Just like the one returned from a fork
effect.
Besides taking and dispatching actions to the store runSaga
can also be connected to
other input/output sources. This allows you to exploit all the features of sagas to implement
control flows outside Redux.
The method has the following signature
runSaga(iterator, {subscribe, dispatch}, [monitor])
Arguments
-
iterator: {next, throw}
: an iterator object, Typically created by invoking a Generator function
-
subscribe(callback) => unsubscribe
: i.e. a function which accepts a callback and returns an unsubscribe function
-
callback(action)
: callback (provided by runSaga) used to subscribe to input events. subscribe
must
support registering multiple subscriptions
-
unsubscribe()
: used by runSaga
to unsubscribe from the input source once it
has completed (either by normal return or a thrown exception)
-
dispatch(action) => result
: used to fulfill put
effects. Each time a yield put(action)
is issued, dispatch
is invoked with action
. The return value of dispatch
is used to fulfill the put
effect. Promise results
are automatically resolved/rejected.
-
monitor(sagaAction)
(optional): a callback which is used to dispatch all Saga related events. In the middleware
version, all actions are dispatched to the Redux store. See the [sagaMonitor example]
(https://github.com/yelouafi/redux-saga/blob/master/examples/sagaMonitor.js) for usage.
The subscribe
argument is used to fulfill take(action)
effects. Each time subscribe
emits an action
to its callbacks, all sagas that are blocked on take(PATTERN)
, and whose take pattern matches the currently incoming action,
are resumed with that action.
#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
#Using umd build in the browser
There's 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:
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.