wrap-promise

Like new Promise(), but prevents implicit rejection

Comparison

Using the native new Promise()

var fs = require('fs');

new Promise(function(resolve, reject) {
  // Node's fs.readFile throws a type error when the first argument is not a string.

  fs.readFile(123, function(err, buf) { // doesn't throw, but calls `onRejected` function
    if (err) {
      reject(err);
      return;
    }
    resolve(buf);
  });
}).catch(onRejected);

function onRejected() {
  console.log('This function should be called.');
}

Using wrap-promise

var fs = require('fs');
var wrapPromise = require('wrap-promise');

wrapPromise(function(resolve, reject) {
  fs.readFile(123, function(err, buf) { // doesn't call `onRejected` but throws immediately
    if (err) {
      reject(err);
      return;
    }
    resolve(buf);
  });
}).catch(onRejected);

function onRejected() {
  console.log('This function should not be called.');
}

According to the Promise specification, a promise will be rejected implicitly when an error is thrown in the constructor callback. The only (and the biggest) difference is that wrap-promise immediately throws an error in such a case.

Installation

Package managers

npm

npm install wrap-promise

Bower

bower install wrap-promise

Duo

var wrapPromise = require('shinnn/wrap-promise');

Standalone

Download the script file directly.

API

wrapPromise(fn)

fn: Function
Return: Object (Promise)

It can be used in the same way as new Promise() but new operator is not needed.

wrapPromise.Promise

Type: Function
Default: global Promise or require('es6-promise').Promise

The Promise constructor used in wrapPromise function.

On CommonJS-based environment (e.g. Node)

By default it uses the global Promise constructor if available, otherwise it requires es6-promise and use its Promise property.

If you don't need the fallback, use no-fallback.js instead. (Useful for Browserify)

var wrapPromise = require('wrap-promise/no-fallback');

On non-CommonJS environment

It uses the global Promise constructor without any fallbacks. Before using wrapPromise, you must load Promise polyfill if Promise doesn't exist by default.

License

Copyright (c) 2014 Shinnosuke Watanabe

Licensed under the MIT License.