promise-ring

Convenience methods for converting Node.js callbacks into native Promises.

Install

npm install promise-ring --save

Overview

promise-ring is small, simple library with no dependencies that eases the use of native JavaScript Promises in projects without a Promise library.

Important: promise-ring requires a native Promise implementation. If Promise is not defined, it throws immediately. Therefore, projects that need to support older environments (like Node.js 0.10.x) should look for similar functionality from Q, Bluebird, promise, etc..

For more about using Promise to write better code, see:

• Promise, Mozilla Developer Network
• JavaScript Promises, HTML5 Rocks
• Promises, Forbes Lindesay
• Promises/A+, specification

API / Examples

Each of the following snippets comes from the example directory in the repository and assumes the following requires:

var fs = require("fs");
 
var Database = require("./database.js");
var db = new Database("MockDB");
 
var pr = require("promise-ring");

call

call wraps a single invocation of a callback-based method and returns a Promise. If the first (i.e., "error") parameter of the callback is not null, the Promise is rejected. Otherwise, the Promise is resolved with the second parameter of the callback. If the callback received multiple parameters, the Promise is resolved with an Array of them.

pr.call(fs.readFile, "../package.json", { "encoding": "utf8" })
  .then(function(data) {
    console.log(JSON.parse(data).name);
  });

apply

apply is to call as Function.apply is to Function.call.

pr.apply(fs.readFile, [ "../package.json", { "encoding": "utf8" } ])
  .then(function(data) {
    console.log(JSON.parse(data).name);
  });

callBound

callBound is like call but allows the thisArg to be specified for scenarios that require it (like class instances).

pr.callBound(db, db.query, "promise-ring")
  .then(function(result) {
    console.log(result);
  });

applyBound

applyBound is to callBound as apply is to call.

pr.applyBound(db, db.query, [ "promise-ring" ])
  .then(function(result) {
    console.log(result);
  });

wrap

Instead of using call multiple times for the same function, wrap creates a wrapper function that can be used multiple times wherever it is needed.

var readFile = pr.wrap(fs.readFile);
 
readFile("../package.json", { "encoding": "utf8" })
  .then(function(data) {
    console.log(JSON.parse(data).name);
  });

wrapBound

wrapBound is to wrap as callBound is to call.

var dbquery = pr.wrapBound(db, db.query);
 
dbquery("promise-ring")
  .then(function(result) {
    console.log(result);
  });

wrapAll

As a convenience, wrapAll creates Promise wrappers for all functions on an object and binds thisArg to that object instance (similar to the *Bound functions above).

Note: wrapAll is not smart and may include functions that don't take a callback - it's up to the author to ensure only appropriate wrappers are used.

var fsw = pr.wrapAll(fs);
var dbw = pr.wrapAll(db);
 
fsw.readFile("../package.json", { "encoding": "utf8" })
  .then(function(data) {
    console.log(JSON.parse(data).name);
  });
 
dbw.query("promise-ring")
  .then(function(result) {
    console.log(result);
  });

History

• 0.1.0 - Initial release.