redux-saga

Fixes resolving TS types for redux-saga/effects

This release is bringing improved TS typings - allowed by [email protected]. Thanks, @gilbsgilbs for working on this 👍

For more on this please read https://github.com/redux-saga/redux-saga/pull/1892#issue-297396449

Breaking changes:

• channel and actionChannel have default buffer of buffers.expanding()
• errors thrown during put execution are no longer caught and swallowed, you need to catch them manually
• signature of join & cancel, they both accept now a single task descriptor or an array of those (previously they have accepted variadic length of arguments)
• removed some deprecated APIs - takeEvery, takeLatest, throttle from the redux-saga entry point (they are and were importable from redux-saga/effects), takem, put.sync and executing array of effects, there is explicit API for this for already some time - all effect
• 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
• refactored shape of the effect objects to { [IO]: true, type, payload }
• removed asEffect, effect types are public, effect shapes are stable, so if for whatever reason you want to do some effect inspection you can just check them without us providing additional helpers for it
• removed logError, use only onError option (it's signature is onError(error, { sagaStack }))
• END will now finish the race effects
• task.done getter was changed to be task.toPromise method
• channels private getters (__takers__ and __closed__) got removed
• delay became an effect
• redux-saga/utils got removed, exports available exclusively there got moved to separate packages - @redux-saga/deferred, @redux-saga/delay-p, @redux-saga/is, @redux-saga/symbols & @redux-saga/testing-utils
• eventChannel does no longer accept matcher argument - it was a hacky way to support previous implementation of stdChannel
• {effects, utils} can't imported from 'redux-saga' anymore
• most runtime type checks got hidden behing development checks, inputs might not be validated in production (failed validation resulted in error being thrown anyway)
• detach helper returns a new effect instead of mutating the input one
• we have stopped interpreting effects returned from fork, this shouldn't affect any real-life code, affected patterns look like this fork(() => effectCreator()) and fork(takeEvery, 'type', fn)
• TS typings got revamped - they require TS@>3.1 now

New:

• babel-plugin-redux-saga - can be used to enhance stack traces of thrown errors
• multicastChannel - no buffering, notify all pending takers, multicastChannel#take(cb, matcher = matchers.wildard)
• 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.
• takeLeading effect - it takes "leading" action and ignores all incoming ones of the same type while the "leading" is still handled (useful for things debouncing)
• retry effect with the signature of retry(maxTries, delayLength, worker, ...args)
• debounce effect with the signature of debounce(delayLength, pattern, worker, ...args)
• new rootSagaStarted hook for saga monitor
• added dev warning about dispatching frozen actions, for scheduling purposes we are using Object.defineProperty on actions dispatched with put effect, so we have to be able to mutate the action object
• added dev warning about using async generators, they are not supported by redux-saga
• CommonJS entries are proxied now. This means that process.env.NODE_ENV is read only once and based on that value the appropriate bundle (development or production) is loaded conditionally with require. process.env is slow in node.js so this should improve performance a little bit.
• isRoot property on Task (you probably won't ever need to use it, it's internal)

Fixes:

• keeping single stdChannel in the internals allowed to fix 2 bugs with missed actions (see #707 and #1146)
• onError should get called now even if you throw non-Errors in your code.
• we suspend the scheduler before running a root saga, so it should behave the same as forked sagas in terms of scheduling
• small memory leak for closed actionChannels
• issue with joiner not ending in cancelled state when joining cancelled task

This is first (and very likely last 😉) release candidate version 🎉. We expect no more breaking changes before releasing stable v1 (truth to be told there were not many breaking changes during whole beta process - the API is mostly the same).

Added:

• isRoot property on Task (you probably won't ever need to use it, it's internal)
• dev warning for using delay effect incorrectly

Changed:

• sagaStack was refactored - onError call signature is now onError(error, { sagaStack })

Removed:

• removed logError, use only onError option
• removed redux-saga/utils entirely, move of those are moved to separate packages

Fixed:

• issue with joiner not ending in cancelled state when joining cancelled task

Improved:

• many docs improvements
• revamped TS typings (thanks to @aikoven)

Many thanks once more to @restrry and @shinima who made it possible with their contributions.

This is rather a smaller release, but some things have changed or got improved.

Added:

• new rootSagaStarted hook for saga monitor

Changed:

• we reverted changing effect types to Symbols, this previous change has caused some problems and we came to conclusion that strings are "good enough" for us
• detach helper returns a new effect instead of mutating the input one
• we suspend the scheduler before running a root saga, so it should behave the same as forked sagas in terms of scheduling

Removed:

• asEffect, it shouldn't be used, effect types are public, effect shapes are stable, so if for whatever reason you want to do some effect inspection you can just check them without us providing additional helpers for it

Fixed:

• we have stopped interpreting effects returned from fork, this shouldn't affect any real-life code, affected patterns look like this fork(() => effectCreator()) and fork(takeEvery, 'type', fn)
• small memory leak for closed actionChannels

Polished:

• added dev warning about dispatching frozen actions, for scheduling purposes we are using Object.defineProperty on actions dispatched with put effect, so we have to be able to mutate the action object
• added dev warning about using async generators, they are not supported by redux-saga
• we are reusing @babel/runtime helpers, this has helped us to remove some bytes from our bundles
• CommonJS entries are proxied now. This means that process.env.NODE_ENV is read only once and based on that value the appropriate bundle (development or production) is loaded conditionally with require. process.env is slow in node.js so this should improve performance a little bit.

This release is highly motivated by our 2 new core members @restrry & @shinima. They have put a lot of work into creating PRs & helping others with their issues.

We've recently extracted some modular packages, you can see @redux-saga/deferred, @redux-saga/delay-p, @redux-saga/is & @redux-saga/symbols. At the same time we've managed to shave off some bytes from the core build - according to some tests of our we've managed remove over 1kb, but your YMMV ofc.

Added:

• retry effect with the signature of retry(maxTries, delayLength, worker, ...args)
• debounce effect with the signature of debounce(delayLength, pattern, worker, ...args)

Changed:

• {effects, utils} aren't imported from 'redux-saga' anymore. import them from redux-saga/effects, redux-saga/utils
• is helper should be imported from @redux-saga/is.
• delay function (not effect!) should be imported from @redux-saga/delay-p
• signature of join & cancel, they both accept now a single task descriptor or an array of those (previously they have accepted variadic length of arguments)
• refactored shape of the effect objects to { [IO]: true, type, payload }, their structure should be treated as opaque anyway, so we hope this doesn't break anyone
• END will now finish the race effects

Error handling

Let's face it. Errors coming from redux-saga were unreadable and made finding a root cause of the problem really difficult. We really want to improve this situation and with this release (thanks to @restrry's amazing contribution) we start to log "saga stacks" along with original errors. This works similar to what React already does with its "component stacks". Just look at this one:

You can even enhance those stacks with file names and line numbers by using in development our new babel-plugin-redux-saga (also thanks to @restrry). Let us know if there are any issues with this or if we can make them even more useful!

Also onError should get called now even if you throw non-Errors in your code.

Beside that few things have changed, you can read more about them below.

Added:

• takeLeading effect - it takes "leading" action and ignores all incoming ones of the same type while the "leading" is still handled (useful for things debouncing)
• redux@4 got in supported range (this will let npm dedupe redux in node_modules, keep in mind though that we only depend on compose from that package)

Changed:

• delay became an effect, you still can import delay util from redux-saga/utils though

I must say that this release probably wouldn't be possible without community sponsors - both organizations and individual backers.

I'm not saying that money given by the community has helped, but it is a nice incentive to work and a token of appreciation. Somehow the fact alone that people are sending money towards us got me lately back on track, going, writing some code, pushing things forward towards v1 release.

Note that the money is not what you have most valuable to offer for OSS projects - your time is way more valuable. If you want some feature to get implemented, bug to be fixed or just want to help - please reach out to a project's maintainer, maybe ask for pointers about code internals so you can start working easier. OSS is done by regular people like you and most projects' code is not magic, everything can be figured out and you can get comfortable with it.

Maintaining a popular project (over 10k ⭐️⭐️⭐️!) is not an easy task to do. Truth to be told you do not even have to write code to get exhausted. Answering issues, replying to people's demands etc is time and energy consuming.

I'd want to think that at least in those areas I've maintained the package well - nearly every question gets answered and it gets answered within days. I've helped people fix their broken code, I've suggested how their apps can be structured, how to solve particular problems.

However GitHub is not really a place where (most of such) questions should be asked. Whenever you consider asking a question on any project's GitHub, please consider if it is the right place to ask. There are many places you can get help from the community, such as obviously StackOverflow. In terms of redux-saga additionally you can reach out to the community on our gitter channel and redux-saga reactiflux's channel.

New:

• multicastChannel - no buffering, notify all pending takers, multicastChannel#take(cb, matcher = matchers.wildard)
• 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

Breaking changes:

• channel and actionChannel have default buffer of buffers.expanding()
• errors thrown during put execution are no longer caught and swallowed, you need to catch them manually
• eventChannel does no longer accept matcher argument - it was a hacky way to support previous implementation of stdChannel
• exported util of arrayOfDeffered got renamed to the correct arrayOfDeferred
• internal util of sym tries to use Symbol if it's available, this mainly breaks effects' "shape" - types no longer are simple strings, although no code should make any assumptions about effects' shape anyway
• removed some deprecated APIs - takeEvery, takeLatest, throttle from the redux-saga entry point (they are and were importable from redux-saga/effects), takem, put.sync and executing array of effects, there is explicit API for this for already some time - all effect
• 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
• most runtime type checks got hidden behing development checks, inputs might not be validated in production (failed validation resulted in error being thrown anyway)
• task.done getter was changed to be task.toPromise method
• channels private getters (__takers__ and __closed__) got removed

Bug fixes:

• keeping single stdChannel in the internals allowed to fix 2 bugs with missed actions (see #707 and #1146), cc @gajus

Internals:

• We have started to use babel@7-beta, hopefully it won't break anything. I've investigated differences between outputs and everything seems to be ok, but you never know ;) This should result in a little bit smaller and a little bit more performant code.

• added detach helper - this is used internally now by spawn to mark fork effect as detached, got exported and might be used in userland, it's useful for creating i.e. detached takeEvery

import { detach } from 'redux-saga'
import { takeEvery } from 'redux-saga/effects'

// ...

yield detach(takeEvery(ACTION_A, mightThrowSaga))

• typings for detach got added thanks to @aikoven
• removed #__PURE__ annotations from the source code, adding them automatically with annotate-pure-calls babel's plugin
• made sagaStack property non-enumerable (this is attached sometimes by redux-saga to the thrown Errors)
• unified internally error logging
• removed annoying "saga has been cancelled" logs, didn't find a valid use case for them

TS Typings

• made take and put effects redeclarable (thanks to @Rokt33r)
• marked overloaded put.sync as deprecated

TS Typings

• optional cancel property on CpsCallback (thanks to @dannsam)
• support for non-strict effect combinators (thanks to @aikoven
• type definitions for util's cloneableGenerator function (thanks to @zyml)

• added pure functions annotations (for few deprecation warnings) so they can be better tree-shaken now. more can be read here, thanks to @iamakulov

• fixed middleware's context not being passed to the root sagas (thanks @VictorQueiroz)

• reverted using Symbols for some internal properties - this caused 2 redux-saga version to be incompatible, effects from one couldnt be interpreted by the other one

• fixed problem with yielding falsy values - normally all non-interpretable yields are just injected back to your saga (const two = yield 2), however yielding falsy values prevented yielding saga to continue

Things published already under recent patch versions, but without public release noted:

• got redux-saga/effects and redux-saga/utils working properly for webpack2 and rollup users (or any other bundle which recognizes jsnext:main/module entry). Thanks to @Ephys. How was it achieved can be seen here. Neat trick which I think is not publicly known and it was an issue for quite some time and also allowed me to help fixing this in some other libraries.
• fixed join(...tasks) implementation, its not accepting an array of tasks, but rather a variadic number of tasks as arguments
• implemented cancel(...tasks) in similar manner
• implemented possibility for self cancellation, this means you can now yield cancel() inside a task and handle both cancel(task) + self cancellation via cancel() within the same finally block
• fixed internal scheduler and its recursive nature, now its trampolining and cannot cause stack's overflow, thanks to @pbadenski and @wilsaj
• added getContext and setContext effects (thanks for the idea to @aikoven). It's not properly documented yet, but its a feature which allows sharing context properties across tasks without need to import them in each file or passing them explicitly through arguments. The feature is implemented as dynamic scoping which should sounds familiar for JS devs. In general you cannot share a context property from a child task to the parent, its only passed 'down'. You can read more in related issue and PR till its not documented.
• got rid of createSagaMiddleware({ onerror }) which got into library because of a typo and we have supported it for some time, please use onError instead

New in this release:

• refactored runSaga API, runSaga(iterator, storeInterface) got depreacted in favor of runSaga(storeInterface, saga, ...args). It allowed us to leverage the change internally so now sagaMiddleware.run became partially applied runSaga, they wont now go out of sync (in the past changes and bug fixes had to implemented in both of them).
• cloneableGenerator utils, which can ease ur unit testing when logic branching is needed, thanks to @nihaux
• call([obj, 'method']) - now you can pass a string as method's name which should be called on the passed context
• all effect - explicit effect for parallel effects, which is exactly what we had been supporting by accepting yielded arrays, so the latter is become deprecated now in favor of this explicitness which nicely maps to the Promise.all API. Please use this from now on
• improved TS typings, thanks to @aikoven for his continous support in this matter

Bug fixes:

• fixed issue with eventChannels not closing automatically upon emitting END, thanks to @baldwmic

In the meantime we have also:

• got us https://redux-saga.js.org/ domain, thanks to @baldwmic
• got us a rolluped UMD build, which is way smaller than the one which was produced by a webpack, thanks to the so called 'flat-bundling'
• got us a logo! Thanks to @thekarland

Fixes

• take effect supporting Symbol types again - thanks to @iMoses

This small update allows you to integrate better with some other redux libraries, like redux-actions and redux-act.

For the users of those it is now possible to omit maintaining action constants only for the sake's of redux-saga and they can use created actions as patterns for the take effect like this:

import { createAction } from 'redux-actions'

const increment = createAction('INCREMENT', amount => amount) // typeof increment === 'function'

// ...
yield take(increment)

It means that you can pass an action creator function with custom .toString() method on it and it can be checked by redux-saga against dispatched actions' types.

Special thanks for this goes to @thezanke

Also - finally the build for rollup should be fixed (public export of CHANNEL_END got fixed).

This small update allows you to integrate better with some other redux libraries, like redux-batched-actions.

From now on you can intercept what's being dispatched before it's emitted into the saga, which will allow for using take just like everybody else, instead of playing with the pattern argument.

The argument you need to pass to the middleware is a higher-order function which will first take out built-in emit function as the argument and return a 'middleware' function to process dispatched actions.

Example usage:

createSagaMiddleware({
 emitter: emit => action => {
   if (Array.isArray(action)) {
     action.forEach(emit);
     return
   }
   emit(action)
 }
});

More can be read in our docs

Great thanks to the @pbadenski for implementing the feature.

Just a small patch version with:

• join(...tasks) - this effect creator will accept array of tasks from now on, it's just a shorthand (more obvious one) for tasks.map(join)
• take(array) - array can be now of mixed types - strings and predicate functions so this is possible now yield take(['ACTION_A', ac => ac.payload])
• added TS typings for helpers' effect creators from the redux-saga/effects, that means takeEvery, takeLatest, throttle (thanks to @mcrawshaw)