continuation-local-storage support for bluebird promises
Patch bluebird for continuation-local-storage support.
Current Status
Version 2.x of cls-bluebird is a complete re-write aiming to make it 100% reliable and robust. Features comprehensive test coverage (over 100,000 tests) which cover pretty much all conceivable cases.
Compatible with bluebird v2.x and v3.x. Tests cover both versions.
Please use with latest version of bluebird in either v2.x or v3.x branches. Older versions are not guaranteed to work.
Usage
clsBluebird( ns [, Promise] )
var cls = require('continuation-local-storage');
var ns = cls.createNamespace('myNamespace');
var Promise = require('bluebird');
var clsBluebird = require('cls-bluebird');
clsBluebird( ns );
// Promise is now patched to maintain CLS context
The above patches the "global" instance of bluebird. So anywhere else in the same app that calls require('bluebird') will get the patched version (assuming npm resolves to the same file).
Patching a particular instance of Bluebird
So as not to alter the "global" instance of bluebird, it's recommended to first create a independent instance of the Bluebird constructor before patching, and pass it to cls-bluebird.
This is a more robust approach.
var Promise = require('bluebird').getNewLibraryCopy();
var clsBluebird = require('cls-bluebird');
clsBluebird( ns, Promise );
(see Promise.getNewLibraryCopy() docs on Bluebird website)
Nature of patching
Combining CLS and promises is a slightly tricky business. There are 3 different conventions one could use (see this issue for more detail).
cls-bluebird follows the convention of binding .then() callbacks to the context in which .then() is called.
var promise;
ns.run(function() {
ns.set('foo', 123);
promise = Promise.resolve();
});
ns.run(function() {
ns.set('foo', 456);
promise.then(print);
});
function print() {
console.log(ns.get('foo'));
}
// this outputs '456' (the value of `foo` at the time `.then()` was called)
Notes
Coroutines
The patch ensures that when execution in a coroutine continues after a yield statement, it always does so in the CLS context in which the coroutine started running.
var fn = Promise.coroutine(function* () {
console.log('Context 1:', ns.get('foo'));
yield Promise.resolve();
console.log('Context 2:', ns.get('foo'));
});
ns.run(function(ctx) {
ns.set('foo', 123);
fn();
});
outputs:
Context 1: 123
Context 2: 123
This means:
- If the
yield-ed expression loses CLS context, the original CLS context will be restored after the yield.
- Any code before the
yield which changes CLS context will only be effective until the next yield.
Global error handlers
Promise.onPossiblyUnhandledRejection() and Promise.onUnhandledRejectionHandled() allow you to attach global handlers to intercept unhandled rejections.
The CLS context in which callbacks are called is unknown. It's probably unwise to rely on the CLS context in the callback being that when the rejection occurred - use .catch() on the end of the promise chain that's created within namespace.run() instead.
Progression
Bluebird v2.x contains a deprecated API for handling progression (.progressed()) etc. These methods are patched and should work fine but they're not covered by the tests.
Tests
The tests cover every possible combination of input promises and callbacks that the Bluebird API allows. There's around 100,000 tests in total and the aim is to ensure cls-bluebird is as robust and reliable as possible.
Use npm test to run the tests. Use npm run cover to check coverage.
For more info on test tests, see tests/README.md
Changelog
See changelog.md
Issues/bugs
If you discover a bug, please raise an issue on Github. https://github.com/TimBeyer/cls-bluebird/issues
We are very keen to ensure cls-bluebird is completely bug-free and any bugs discovered will be fixed as soon as possible.
Contribution
Pull requests are very welcome. Please:
- ensure all tests pass before submitting PR
- add an entry to changelog
- add tests for new features
- document new functionality/API additions in README
