id | title |
---|---|
new-in-bluebird-3 |
New in bluebird 3.0 |
##Cancellation overhaul
Cancellation has been redesigned for bluebird 3.0. Any code that relies on 2.x cancellation semantics won't work in 3.0 or later. See Cancellation for more information.
##Promisification API changes
Both promisification (Promise.promisify and Promise.promisifyAll) methods and Promise.fromCallback now by default ignore multiple arguments passed to the callback adapter and instead only the first argument is used to resolve the promise. The behavior in 2.x is to construct an array of the arguments and resolve the promise with it when more than one argument is passed to the callback adapter. The problems with this approach and reasons for the change are discussed in #307.
Promise.promisify's second argument is now an options object, so any code using the second argument needs to change:
// 2.x
Promise.promisify(fn, ctx);
// 3.0
Promise.promisify(fn, {context: ctx});
Both promisification (Promise.promisify and Promise.promisifyAll) methods and Promise.fromCallback all take a new boolean option multiArgs
which defaults to false
. Enabling this option will make the adapter callback always construct an array of the passed arguments regardless of amount of arguments. This can be used to reliably get access to all arguments rather than just the first one.
##Collection method changes
All collection methods now support objects that implement ES6's iterable protocol along with regular arrays.
Promise.props and .props now support ES6 Map
objects along with normal objects. Actual Map
objects are only considered for their entries in the map instead of both entries and properties.
##Warnings
Warnings have been added to report usages which are very likely to be programmer errors. See Promise.config for how to enable warnings. See Warning Explanations for list of the warnings and their explanations.
##Feature additions
- .catch() now supports an object predicate as a filter:
.catch({code: 'ENOENT'}, e => ...)
. - Added .suppressUnhandledRejections().
- Added .catchThrow().
- Added .catchReturn().
- Added Promise.mapSeries() and .mapSeries()
##Deprecations
Promise.settle
has been deprecated. Use .reflect instead.Promise.spawn
has been deprecated. Use Promise.coroutine instead.- Promise.try's
ctx
andarg
arguments have been deprecated. .nodeify
is now better known as .asCallback.fromNode
is now better known as Promise.fromCallback
##Summary of breaking changes
- Promisifier APIs.
- Cancellation redesign.
- Promise progression has been completely removed.
- .spread's second argument has been removed.
- .done causes an irrecoverable fatal error in Node.js environments now. See #471 for rationale.
- Errors created with Promise.reject or
reject
callback of new Promise are no longer marked as OperationalErrors.
##3.0.1 update
Note that the 3.0.1 update is strictly speaking backward-incompatible with 3.0.0. Version 3.0.0 changed the previous behavior of the .each
method and made it work the same as the new .mapSeries
- 3.0.1 unrolls this change by reverting to the .tap
-like behavior found in 2.x However, this would only affect users who updated to 3.0.0 during the short time that it wasn't deprecated and started relying on the new .each
behavior. This seems unlikely, and therefore the major version was not changed.