Provide flexible methods that accept callbacks and return promises without requiring a Promise implementation exist
npm install promise-resolver> Provide flexible methods that accept callbacks and return promises without requiring a Promise implementation exist
``
$ npm install --save promise-resolver
`js
var promiseResolver = require('promise-resolver');
function sayMyName(name, cb) {
var deferred = promiseResolver.defer(cb);
// this resolves the promise and calls the callback (asynchronously).
deferred.cb(null, 'My name is ' + name + '!');
return deferred.promise;
`
sayMyName can now be used in one of two ways:
##### Provide a callback
`js`
sayMyName('James', function (error, message) {
console.log(message);
// => 'My name is James!'
});
##### Use the returned promise
`js`
sayMyName('Susan').then(function (message) {
console.log(message);
// => 'My name is Susan!'
});
If you do not provide a callback, then you should catch errors on the promise. Most promise implementations emitunhandledRejection
events.unhandledRejection
If a callback is provided,
events are be suppressed (it is assumed the callback handles any errors).
#### Safe Callbacks
promise-resolver protects against callback misuse in the following ways:
`js`
function doStuff (cb) {
var deferred = promiseResolver(cb);
// prevent these typical problems:
deferred.cb() // synchronous invocation
deferred.cb() // multiple invocations
deferred.cb() // undefined is not a function (deferred.cb is always defined, even if cb is not)
}
#### Missing Promise Implementation
promise-resolver allows you to create API's that provide the convenience of Promises,bluebird
without demanding a bulky Promise polyfill on systems that do not already have an implementation.
It looks first for 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.promiseResolver.defer(cb, Promise)
Finally, does allow you to specify an alternate Promise implementation as the second argument.
* 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.
js
var deferred = promiseResolver(passThroughCallback);
// rejects promise and calls passThroughCallback with same args
deferred.cb(new Error('...'));
// resolves promise and calls passThroughCallback with same args
deferred. cb(null, 'result');
return deferred.promise;
`
* deferred.cb will resolve/reject the promise and call passThroughCallback
* Ensures that is only called once.passThroughCallback
* If is provided, it is assumed to handle any errors, and so unhandledRejection errors on deferred.resolve
the promise will be suppressed. This avoids potentially confusing console warnings if users are handling errors
via a callback and ignoring the returned promise.
* 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).
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).passThrough
If it exists, the callback will be called with the same arguments.
`js
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 passThroughCallback` is supplied. It also requires you find and invoke the Promise implementation.
automatically suppressed when
MIT © James Talmage