promise-ring
v0.1.0
Published
Convenience methods for converting Node.js callbacks into native Promises.
Downloads
1,434
Readme
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 nativePromise
implementation. IfPromise
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 require
s:
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.