README.md

denodeify

Tool to turn functions with Node-style callback APIs into functions that return Promises.

Inspired by and adapted from Q's Q.denodeify/Q.nfcall function.

Warning: This micro-library doesn't force you to use any particular Promise implementation by using whatever Promise has been defined as globally. This is so that you may use any ES6 standard Promise compliant library - or, of course, native ES6 Promises.

If you're running the code on a browser or node version that doesn't include native promises you will need to include a polyfill. The following polyfills are tested as part of this module's test suite:-

• Jake Archibald's ES6 Promise library (which is actually adapted from Stefan Penner's RSVP.js). - require('es6-promise').polyfill();
• Getify's Native Promise Only library - require('native-promise-only');
• ES6 Shim - require('es6-shim');
• Calvin Metcalf's Lie - global.Promise = global.Promise || require('lie');

Note: as of v1.2.0 you can use denodeify in the front end. Pull it in via CommonJS, AMD or simply add to your webpage and it'll be available on window.denodeify.

Installation

npm install denodeify --save

Or:-

bower install denodeify --save

Examples

Simple example with readFile:-

require('es6-promise').polyfill();

var denodeify = require('denodeify');
var readFile = denodeify(require('fs').readFile);

readFile('my-file.txt', { encoding: 'UTF-8' })
  .then(function(text) {
    console.log("My file's contents is: " + text);
  });

(Note: you will need to also install es6-promise with npm install es6-promise for this code sample to work within node versions that don't have Promise natively available)

More complex example with exec:-

Advanced usage

You can also pass in a function as a second argument of denodeify that allows you to manipulate the data returned by the wrapped function before it gets passed to the Promise's reject or resolve functions, for example:-

require('es6-promise').polyfill();

var denodeify = require('denodeify');
var exec = denodeify(require('child_process').exec, function(err, stdout, stderr) {

  // Throw away stderr data
  return [err, stdout];
});

exec('hostname')
  .then(function(host) {
    console.log("My hostname is: " + host.replace('\n', ''));
  });

Or,

require('es6-promise').polyfill();

var denodeify = require('denodeify');
var exec = denodeify(require('child_process').exec, function(err, stdout, stderr) {
  return [err, [stdout, stderr]];
});

exec('my-command')
  .then(function(results) {
    console.log("stdout is: " + results[0]);
    console.log("stderr is: " + results[1]);
  });

Useful for functions that return multiple arguments, for example child_process#exec.

Troubleshooting

Note that if you have a method that uses the Node.js callback pattern, as opposed to just a function, you will need to bind its this value before passing it to denodeify, like so:

var Thing = mongoose.model("Thing");
var brokenFind = denodeify( Thing.find ); // the find method won't have the right 'this' defined
var findThings = denodeify( Thing.find.bind(Thing) );

Credits and collaboration

The lead developer of denodeify is Matt Andrews at FT Labs with much help and support from Kornel Lesiński. All open source code released by FT Labs is licenced under the MIT licence. We welcome comments, feedback and suggestions. Please feel free to raise an issue or pull request.