promise-extended

promise-extended is a Javascript library that can be used standalone or incorporated into extended

var promise = require("promise-extended");

Or

var myextended = require("extended")
	.register(require("promise-extended"));

Installation

npm install promise-extended

Or download the source (minified)

Usage

Promise

The promise constructor used by promise and defer

Promise#callback

Resolve a promise with the given value.

Promise#errback

Reject a promise with the given value.

Promise#callback

Resolve a promise with the given value.

Promise#then(callback[, errback)

Allows the chaining of promises.

function myAsyncAction(num){
    var p = new promise.Promise();
    setTimeout(funciton(){
        p.callback(num);
    }, 50);
    return p.promise();
}

myAsyncAction(1)
    .then(function(num){
        return myAsyncAction(num+1);
    })
    .then(function(num){
        return myAsyncAction(num+1);
    })
    .then(function(num){
        console.log(num); //3
    });

Errors are propagated the the nearest error handler, this allows the bubbling of errors up a chain of promises.

function myAsyncAction(num){
    var p = new promise.Promise();
    setTimeout(funciton(){
        p.callback(num);
    }, 50);
    return p.promise();
}

myAsyncAction(1)
    .then(function(num){
        throw new Error("oops an error occured");
    })
    .then(function(num){
        return myAsyncAction(num+1);
    })
    .then(
        function(num){
            console.log(num); //3
        },
        function(err){
            console.log(err); //oops an error occured.
        }
    );

Of you return a promise from an error handler that resolved successfully then the next promise is the chain will be resolved successfully.

function myAsyncAction(num){
    var p = new promise.Promise();
    setTimeout(funciton(){
        p.callback(num);
    }, 50);
    return p.promise();
}

myAsyncAction(1)
    .then(function(num){
        throw new Error("oops an error occured");
    })
    .then(function(num){
        return myAsyncAction(num+1);
    })
    .then(
        function(num){
            console.log(num); //3
        },
        function(err){
            console.log(err); //oops an error occured.
            return asyncAction(10);
        }
    )
    .then(function(num){
        console.log(num); //10
    });

Promise#both

Allows the execution of a function regardless of whether or not a promises is successful.

new promise.Promise().errback("error").both(function(){
    //do some more work
}).then(function(){

});

Promise#resolve

The resolve method provides a mechanism to work with node style callbacks and promises.

var fs = require("fs");

var myPromise = new promise.Promise();
fs.readFile(__dirname + "/myFile.txt", "utf8", myPromise.resolve);

myPromise.then(function(txt){
    console.log(txt);
});

Promise#classic

Accepts a callback in the typical node style.

new promise.Promise()
    .callback("hello")
    .classic(function(err, res){
        console.log(res); //"hello"
    });

isPromiseLike

Determines if an object is like a promise (contains a .then function).

promise.isPromiseLike({then : function(){}}); //true
promise({then : function(){}}).isPromiseLike(); //true

promise

Creates a new promise.

function myAsyncAction(){
    var p = promise.promise();
    setTimeout(funciton(){
        p.callback("hello");
    }, 50);
    return p.promise();
}

myAsyncAction().then(function(hello){
    console.log(hello);
});

promiseList

Creates a new promise.

function myAsyncAction(){
    var p = promise.promise();
    setTimeout(funciton(){
        p.callback("hello");
    }, 50);
    return p.promise();
}

promise.promiseList([myAsyncAction(), myAsyncAction()]).then(function(hello){
    console.log(hello); //["hello", "hello"]
});

defer

Creates a new promise.

function myAsyncAction(){
    var p = promise.defer();
    setTimeout(funciton(){
        p.callback("hello");
    }, 50);
    return p.promise();
}

myAsyncAction.then(function(hello){
    console.log(hello);
});

deferredList

Creates a new promise.

function myAsyncAction(){
    var p = promise.defer();
    setTimeout(funciton(){
        p.callback("hello");
    }, 50);
    return p.promise();
}

promise.deferredList([myAsyncAction(), myAsyncAction()]).then(function(hello){
    console.log(hello); //["hello", "hello"]
});

resolve

Creates a promise that is resolved with the provided value.

promise.resolve("hello")
    .then(function(hello){
        console.log(hello); //hello
    });

reject

Creates a promise that is errored with the provided value.

promise.reject(new Error("an error occured"))
    .then(function(){
        //not called
    }, function(err){
       console.log(err.stack);
    });

wrap

Wraps traditional node style functions with a promise.

var fs = require("fs");
var readFile = promise.wrap(fs.readFile, fs);
readFile(__dirname + "/test.json").then(
    function(buffer){
        console.log(contents);
    },
    function(err){
       console.error(err);
    }
);

serial

Executes a list of items in a serial manner.

If the list contains promises then each promise will be executed in a serial manner.

If the list contains non async items then the next item in the list is called.

Note This will not propogate values from one action to another, instead results are passed as an array to the eventual promise.

function asyncAction(item, timeout){
    return function(){
        var p = promise.promise();
        setTimeout(function(){
            return p.callback(item);
        }, timeout);
        return p.promise();
    }
};

promise.serial([
    asyncAction(1, 1000),
    asyncAction(2, 900),
    asyncAction(3, 800),
    asyncAction(4, 700),
    asyncAction(5, 600),
    asyncAction(6, 500),
    asyncAction(7, 400),
    asyncAction(8, 300),
    asyncAction(9, 200),
]).then(function(results){
    console.log(results); // [1,2,3,4,5,6,7,8, 9];
});

chain

Allows you to propogate results from one function to another.

This is different than .serial in that it propogates results from one promise to the next, where .serial does not.

function asyncAction(add, timeout) {

     return function (num) {
         num = num || 0;
         var p = promise.promise();
         setTimeout(function () {
              p.callback(num + add);
         }, timeout);
         return p.promise();;
     }
}

promise.chain([
     asyncAction(1, 100),
     asyncAction(2, 100),
     asyncAction(3, 100),
     asyncAction(4, 100),
     asyncAction(5, 100),
]).then(function(results){
     console.log(results); //15
});

wait

Ensures that a promise is resolved before a the function can be run.

For example suppose you have to ensure that you are connected to a database before you execute a function.

var findUser = promise.wait(connect(), function findUser(id){
     //this wont execute until we are connected
     return User.findById(id);
});

promise.when(findUser(1), findUser(2)).then(function(users){
    var user1 = users[0], user2 = users[1];
 });