View on GitHub


tiny promise/A+ implementation

Download this project as a .zip file Download this project as a tar.gz file


D.js is a tiny implementation of promises/A+ made for nodejs and client-side browser (tested in ie7+, firefox and chrome) Build Status

If you want to know more about promises/A+ you can visit this page: Promises/A+ logo



npm install d.js


clone the repository or just copy the files D.js or D.min.js to your server and then include it in your pages with a classic <script src="D.js"></script> or using a javascript loader like l.js

Making an async method that return a promise:

example in node js wrapping the fs.readFile function to work with promise

var fs = require('fs')
    , D = require('d.js')

// define a method that will return a promise of a file read content
function readPromise(filename){
    var deferred = D();
    fs.readFile(filename, function (err, data) {
        if( err ){
        } else {
    return deferred.promise;
// use our readPromise method we don't pass in a callback, we will pass it to the then method
    .then( // the then method return a promise as well so we can chain then calls
        function(data){ console.log(data); }
        ,function(err){ console.log(err); }

Addition to the Promises/A+ specs

D.js offers a little more than the promises/A+ specification requirements. Here's the api:

Promises methods

In addition to the unique then method required by the specifications, D.js supports the following methods for each promise:

promise.isPending() // return false if the promise is fulfilled or rejected, true otherwise
promise.getStatus() // return -1 if rejected, 0 is pending and 1 if fulfilled
promise.success(onFulfilled); // same as promise.then(onFulfilled);
promise.error(onRejected);   // same as promise.then(undefined,onRejected);
promise.otherwise(onRejected);   // alias of promise.error();
promise.apply(onFulfilled,onRejected); // same as then but when received an array as promise resolution value will pass each array entry as single parameter of the onFulfill callback
promise.spread(onFulfilled,onRejected); // alias of apply
promise.ensure(onRejected);   // cleanup method which will be always executed regardless fulfillment or rejection
promise.nodify(nodeStyleCallback); // take a single callback which wait for an error as first parameter. other resolution values are passed as with the apply/spread method
promise.rethrow(onRejected) // helper for onRejected method that rethrow the reason of the rejection
promise.rethrow() // see below for more info on rethrow behaviour

promise.apply / promise.spread:

The apply method is a minor variation of the then method especially useful for promises of Array. Instead of passing an Array as the first parameter of onFulfulled, it will pass each element of the Array as a different parameter. Here is an example:

var arrayPromise = D.resolved([1,2,3]); // we'll talk about resolved later
arrayPromise.then(function(a){ /* a will contains the whole array */ })
arrayPromise.apply(function(a,b,c){ /* a will be 1, b is 2 and c is 3 */ }


The ensure method will return the same promise untouched. It is used for cleanup tasks and the given callback will be called regardless of the promise fulfillment or rejection. It won't receive any parameter and the returned value won't serve to fulfill a new promise.


The nodify method is the counterpart of the D.nodeCapsule method. it take a single node style callback as parameter which wait for an Error as first parameter if any. If the promise is fulfilled then the first parameter will be undefined and other promises values will be applied as with the promise.apply method. If the promise is rejected then the first parameter will be the reason of the rejection and other parameters will be ommited.

promise.nodify(function(err, arg1, arg2, arg3){
        // promise is rejected treat the error or rethrow it
    } else {
        // promise is fulfilled do some work with other arguments


The rethrow method serves two different purposes

var onRejectedResolve = function(reason){
    return 'resolvedvalue';

// first example the error is resolved
        /* a now contains 'resolvedvalue' */

// second example we want the same errorHandler but we don't want to resolve
        throw reason;
        /* this success will never get called */

// third example using the same errorHandler and rethrow.
// This does exactly the same thing as second example
        /* this success will never get called */
        throw "there's no good reason";
        throw reason;
        even throwing again the reason won't make the reason visible outside the promise library
        the error will go to the next error handler or simply be ignored if no error handler exists
    // rethrow call WITHOUT ANY PARAMATER will rejectet the reason in the outside world and you will see an uncaught error

D properties and methods

D() or D.defer()

return a deferred object with promise as a property and resolve, fulfill (alias of resolve), reject as methods

D.alwaysAsync = true

setting this to false will broke the compliance to the Promises/A+ specification but will try to resolve promise immediatly if the value is available instead of forcing an async resolution this is not a recommended behaviour but it may be useful in some cases

D.onlyFuncs = true

This setting passed to false will also break compliance with the Promises/A+ specification by allowing then, success, error, apply and rethrow to received values instead of callbacks for onFulfilled or onRejected and will resolve the promise with thoose values.

D.resolved(value), D.fulfilled(value)

return a resolved promise of value


return a rejected promise with given reason


return a promise that will resolve in time ms


return a promise for the return value of fn which will be resolved in delay ms (if fn is not a function it will be used as the resolved value)


internal method exposed that will return a resolved promised of value if value isn't a promise

D.all(listOfPromise), D.all(promise0,promise1,promise....)

take a list of promise as single Array or as list or parameters and return a promise that will resolved only when all given promised are resolved. the promise will received given promises values as parameters

D.resolveAll(listOfPromise), D.resolveAll(promise0,promise1,promise....)

take a list of promise as single Array or as list or parameters and return an always fulfilled promise of array list of promises/values regardless of their fulfilled or rejected resolution.

D.sequence(listOfFunction), D.sequence(fn0,fn1,fn....)

take a list of function to execute in order passing results of one to the other and return a promised of the last returned value. will be rejected if any of the function throw an error. as a convenience, it can also receive promises or direct values instead of functions in which case they will be considered as returned value

D.nodeCapsule(fn), D.nodeCapsule(subject,fn)

encapsulate typical node methods that wait for a callback(Err,param1,param2...) as last parameters and return the wrapped method which will return a promise of response usable with then, succes, ... ie:

var fs = require('fs')
    , D = require('d.js')
    , readFile = D.nodeCapsule(fs,fs.readFile)

    .success(function(data){ console.log(data); })