promise-resolver
Provide flexible methods that accept callbacks and return promises without requiring a Promise implementation exist
Install
$ npm install --save promise-resolver
Usage
var promiseResolver = require('promise-resolver');
function sayMyName(name, cb) {
var deferred = promiseResolver.defer(cb);
deferred.cb(null, 'My name is ' + name + '!');
return deferred.promise;
sayMyName
can now be used in one of two ways:
Provide a callback
sayMyName('James', function (error, message) {
console.log(message);
});
Use the returned promise
sayMyName('Susan').then(function (message) {
console.log(message);
});
If you do not provide a callback, then you should catch
errors on the promise. Most promise implementations emit
unhandledRejection
events.
If a callback is provided,
unhandledRejection
events are be suppressed (it is assumed the callback handles any errors).
Safe Callbacks
promise-resolver
protects against callback misuse in the following ways:
function doStuff (cb) {
var deferred = promiseResolver(cb);
deferred.cb()
deferred.cb()
deferred.cb()
}
Missing Promise Implementation
promise-resolver
allows you to create API's that provide the convenience of Promises,
without demanding a bulky Promise polyfill on systems that do not already have an implementation.
It looks first for bluebird
and then a native Promise
implementation.
If the user does not supply a callback and no promise implementation is found, an
error will be thrown explaining how to resolve the problem:
No Promise Implementation: You must use a callback function, upgrade to Node >= 0.11.13, or install bluebird
If it does not find a promise implementation, but a callback is found then it will still return a deferred
, but
deferred.promise
will be undefined
.
Finally, promiseResolver.defer(cb, Promise)
does allow you to specify an alternate Promise implementation as the second argument.
API
promiseResolver.defer(passThrough, Promise)
passThrough
- a "pass through" node style callback as described abovePromise
- an alternate Promise constructor (will use bluebird
or native Promise
implementation by default).
The return value is a standard defer
object with an additional cb
property
that is a node style resolver callback.
var deferred = promiseResolver(passThroughCallback);
deferred.cb(new Error('...'));
deferred. cb(null, 'result');
return deferred.promise;
deferred.cb
will resolve/reject the promise and call passThroughCallback
- Ensures that
passThroughCallback
is only called once. - If
passThroughCallback
is provided, it is assumed to handle any errors, and so unhandledRejection
errors on
the promise will be suppressed. This avoids potentially confusing console warnings if users are handling errors
via a callback and ignoring the returned promise. deferred.resolve
and deferred.reject
are also available, and behave as expected.deferred.promise
will be undefined
if no Promise implementation is found (in that case passThroughCallback
is required).
promiseResolver(resolve, reject, passThrough)
All arguments should be functions, null, or undefined.
resolve
- promise resolve functionreject
- promise reject functionpassThrough
- a "pass through" node style (error first) callback.
Returns a node style callback: cb(err, result...)
Calling the callback will resolve or reject the promise (depending on the err
argument).
If it exists, the passThrough
callback will be called with the same arguments.
var promiseResolver = require('promise-resolver');
return new Promise(function (resolve, reject) {
var cb = promiseResolver(resolve, reject, passThroughCallback);
cb(new Error('...'));
cb(null, 'result');
});
This behaves similar to the defer
method, with the only exception being that unhandledRejection
errors are not
automatically suppressed when passThroughCallback
is supplied. It also requires you find and invoke the Promise implementation.
License
MIT © James Talmage