es6 Native Promise Defer that helps build promise/callback dual APIS
npm install deferentiales6 Native Promise Defer that helps build promise/callback dual APIS

This module is installed via npm:
`` bash`
$ npm install deferential
It is very easy to produce APIs that are equally consumable with node callbacks
as well as promises.
Various promise libraries such as
Q
and bluebird have methods
to either convert Promises or Deferred objects into forms that make it easy to
adapt existing node.js APIS to support these DUAL APIs.
However, as of ES6 (and node 0.12), Promises are native in Javascript, and thus
the need to have a heavy kitchen-sink API like Q or Bluebird is no longer
necessary as we get fast native-only implementations of Promises.
And we can easily polyfill these with great libries such as
native-promise-only.
Thus, we can create some small focused, modules to add these additional
features that should work with any native Promise implementation.
Say you have a regular function tht returns the contents of a file.
Here is the callback version:
` js
var fs = require('fs');
function getFile(fileName, cb) {
fs.readFile(fileName, 'utf8', cb);
}
getFile('myfile.text', function (err, data) {
if (err) return console.error(err);
console.log(data);
});
`
Here is the promise version:
` js
var Promise = require('native-promise-only'),
fs = require('fs');
function getFile(fileName, cb) {
var p = new Promise(function (resolve, reject) {
fs.readFile(fileName, 'utf8', function (err, data) {
if (err) return reject(err);
resolve(data);
});
});
return p;
}
getFile('myfile.txt')
.then(function (data) {
console.log(data);
})
.catch(function (err) {
console.error(err);
});
`
Here is a version that supports both!
` js
var Promise = require('native-promise-only'),
fs = require('fs'),
Deferred = require('deferential');
function getFile(fileName, cb) {
var d = Deferred();
fs.readFile(fileName, 'utf8', d.resolver());
return d.nodeify(cb);
}
// Use with callback
getFile('myfile.text', function (err, data) {
if (err) return console.error(err);
console.log(data);
});
// Use with promise
getFile('myfile.txt')
.then(function (data) {
console.log(data);
})
.catch(function (err) {
console.error(err);
});
`
The first line creats a new Deferred object:
` js`
var d = Deferred();
The d.resolver() returns a callback thunk which a standard node.jsresolve()
callback function can call, and then depending on the error state, it will or reject() the underlying promise (represented as d.promise).
The last line detects whether a cb callback arguments was passed in, and ifcb
it is, it will callback the supplied based on the success or failure of the
underlying promise:
` js`
return d.nodeify(cb);
If the cb argument is missing (ie. undefined) then d.nodeify() returns.then()
the underlying promise so that the function can be used as a regular promise
and chained with and .catch() calls.
So, in summary, if a cb parameter is passed in d.nodeify() will call the
callback as normal and all is good to use the function as a regular callback.
If the cb parameter is missing, then a promise is returned.
The Deferred object has resolve() and reject() methods on it to helpPromise
resolve/reject the state of the underlying . But there is also a helperDeferred#resolver()
method called which returns a thunk that can easilyif (err) return d.reject(err)
passed into the callback paramter of regular node.js functions to automate
the tedious logic.
Creates a new instance of a Deferred. It can be created with or without the
new operator.
Resolve the underlying Promise.
Reject the underlying Promise with an error.
Return the underlying Promise. NB: This is a Native Promise as the underlyingPromise
library uses native-promise-only
which will use the underlying Native implementation or a native
polyfill without all the guff.
Returns a node.js thunk (a function with the signature cb(err, results).
Pass this to a node.js style callback and then based on the result of the
callback, the undelrying Promise will be resolved/rejected.
Call the provided cb node.js callback function if the underlying promisePromise
is resolved/rejected. If not, return the underlying promise to allow for
regular thenable chaining.
* cb - node callback that will be called when the underlying Deferred#promiseopts
is resolved/rejected.
* :spread
* - (default: false). When true when multiple return arguments#resolver()
are provided by the , they will be mapped to additionalPromises
return arguments in the callback. This is because can onlycb(null, val1, val2)
return a single value, whereas node.js callbacks can return multiple
return values (eg. . If this is false` and
multiple return values are returned, then the multiple values will
be returned as a single array of the return values. See the tests for
more details.