promise-resolver v3.0.0

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);
  
  // 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

sayMyName('James', function (error, message) {
  console.log(message);
  // => 'My name is James!'
});

Use the returned promise

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 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);
  // 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, 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 above
• Promise - 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);

// 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 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 function
• reject - promise reject function
• passThrough - 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