promise-utils

promise-utils is a Javascript library that provides utilities for working with promises. promise-utils can be used as a monad library for promises or each function can be used standalone.

This library uses promise-extended internally but can be used with any promises A+ compliant library such as Q

promise-utils can be used standalone or incorporated into extended

var pUtils = require("promise-utils");

Or

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

Installation

npm install promise-utils

Or download the source (minified)

Usage

Arrays

promise-utils can be used with promises or normal arrays by using the async method.

NOTE The examples below uses a resolve method which represents turning an array into a promise resolved with the given array. This is used for brevity where you would typically be working with promises returned from an asynchronous method such as a database call.

var arr = [1,2,3];
var promiseArr = resolve(arr);

pUtils(arr).async().forEach(function(item){
    console.log(item);
}).then(function(){
    console.log("Done Looping");
});

//OR

pUtils(promiseArr).forEach(function(item){
    console.log(item);
}).then(function(){
    console.log("Done Looping");
});

Chaining

When using promise-utils as a monad with a promise you may chain methods together.

var arr = resolve([1, 2, 3, 4, 5]);
pUtils(arr)
    .map(function (num, i) {
        return num * (i + 1);
    })
    .filter(function (num) {
        return num % 2;
    })
    .avg()
    .then(function(res){
        //11.666666666666666
    });

forEach

Similar to Array#forEach except that it resolves with the original array for chaining.

//as a monad

pUtils(resolve([1, 2, 3])).forEach(function(item){
    console.log(item);
}).then(function(){
    console.log("Done Looping");
});

pUtils.forEach(resolve([1, 2, 3]), function(item){
    console.log(item);
}).then(function(){
    console.log("Done Looping");
});

You may also return a promise from the iterator function, which will prevent the returned promise from resolving until all the returned promises are done.

pUtils(resolve([1, 2, 3])).forEach(function(item){
     var ret = new Promise();
     setTimeout(function(){
        ret.callback(item);
     }, 200);
     return ret.promise();
}).then(function(){
    //all promises from iterator function are resolved.
    console.log("Done Looping");
});

You may also specify a limit which will specify the number of items to be looped at a time, if limit is not specified then all items will be iterated regardless of whether or not the previous item in the array is done.

pUtils(resolve([1, 2, 3])).forEach(function(item){
    var ret = new Promise();
    setTimeout(function(){
        ret.callback(item);
    }, 200);
    return ret.promise();
}, 1).then(function(){
    console.log("Done Looping");
});

In the above example only one item will be iterated one at a time.

map

Async version of Array#map.

//as a monad

pUtils(resolve([1, 2, 3])).map(function(item){
    return item * 2;
}).then(function(result){
    console.log(result); //[2, 4, 6];
});

pUtils.map(resolve([1, 2, 3]), function(item){
    return item * 2;
}).then(function(result){
    console.log(result); //[2, 4, 6];
});

You may also return a promise from the iterator function, which will prevent the returned promise from resolving until all the returned promises are done.

 //as a monad

pUtils(resolve([1, 2, 3])).map(function(item){
     var ret = new Promise();
     setTimeout(function(){
        ret.callback(item * 2);
     }, 200);
     return ret.promise();
}).then(function(result){
    console.log(result); //[2, 4, 6];
});

You may also specify a limit which will specify the number of items to be looped at a time, if limit is not specified then all items will be iterated regardless of whether or not the previous item in the array is done.

pUtils(resolve([1, 2, 3])).map(function(item){
    var ret = new Promise();
    setTimeout(function(){
        ret.callback(item * 2);
    }, 200);
    return ret.promise();
}, 1).then(function(){
    console.log(result); //[2, 4, 6];
});

In the above example only one item will be iterated at a time.

filter

Async version of Array#filter.

//as a monad

pUtils(resolve([1, 2, 3])).filter(function(item){
    return item % 2;
}).then(function(result){
    console.log(result); //[1, 3];
});

pUtils.filter(resolve([1, 2, 3]), function(item){
    return item % 2;
}).then(function(result){
    console.log(result); //[1, 3];
});

You may also return a promise from the iterator function, which will prevent the returned promise from resolving until all the returned promises are done.

 //as a monad

pUtils(resolve([1, 2, 3])).filter(function(item){
     var ret = new Promise();
     setTimeout(function(){
        ret.callback(item % 2);
     }, 200);
     return ret.promise();
}).then(function(result){
    console.log(result); //[1, 3];
});

You may also specify a limit which will specify the number of items to be looped at a time, if limit is not specified then all items will be iterated regardless of whether or not the previous item in the array is done.

pUtils(resolve([1, 2, 3])).filter(function(item){
    var ret = new Promise();
    setTimeout(function(){
        ret.callback(item % 2);
    }, 200);
    return ret.promise();
}, 1).then(function(){
    console.log(result); //[1, 3];
});

In the above example only one item will be iterated at a time.

every

Async version of Array#every.

pUtils(resolve([1, 2, 3])).every(function(item){
    return isNumber(item);
}).then(function(result){
    console.log(result); //true;
});

pUtils.every(resolve([1, 2, 3]), function(item){
    return isNumber(item);
}).then(function(result){
    console.log(result); //true;
});

You may also return a promise from the iterator function, which will prevent the returned promise from resolving until all the returned promises are done.

 //as a monad

pUtils(resolve([1, 2, 3])).every(function(item){
     var ret = new Promise();
     setTimeout(function(){
        ret.callback(isNumber(item));
     }, 200);
     return ret.promise();
}).then(function(result){
    console.log(result); //[true];
});

You may also specify a limit which will specify the number of items to be looped at a time, if limit is not specified then all items will be iterated regardless of whether or not the previous item in the array is done.

pUtils(resolve([1, 2, 3])).every(function(item){
    var ret = new Promise();
    setTimeout(function(){
        ret.callback(isNumber(item));
    }, 200);
    return ret.promise();
}, 1).then(function(){
    console.log(result); //true;
});

In the above example only one item will be iterated at a time.

some

Async version of Array#every.

pUtils(resolve([1, 2, 3])).some(function(item){
    return item === 1;
}).then(function(result){
    console.log(result); //true;
});

pUtils.some(resolve([1, 2, 3]), function(item){
    return item === 1;
}).then(function(result){
    console.log(result); //true;
});

You may also return a promise from the iterator function, which will prevent the returned promise from resolving until all the returned promises are done.

 //as a monad

pUtils(resolve([1, 2, 3])).some(function(item){
     var ret = new Promise();
     setTimeout(function(){
        ret.callback(item === 1);
     }, 200);
     return ret.promise();
}).then(function(result){
    console.log(result); //[true];
});

You may also specify a limit which will specify the number of items to be looped at a time, if limit is not specified then all items will be iterated regardless of whether or not the previous item in the array is done.

pUtils(resolve([1, 2, 3])).some(function(item){
    var ret = new Promise();
    setTimeout(function(){
        ret.callback(item === 1);
    }, 200);
    return ret.promise();
}, 1).then(function(){
    console.log(result); //true;
});

In the above example only one item will be iterated at a time.

sum

Sums the values of an array

pUtils.sum(resolve([1,2,3])).then(function(sum){
   //6
});

pUtils(resolve([1,2,3])).sum().then(function(sum){
    //6
});

avg

Finds the average of an array of numbers.

pUtils.avg(resolve([1,2,3])).then(function(avg){
    //2
});

pUtils(resolve([1,2,3])).avg().then(function(avg){
    //2
});

sort

Sorts an array based on a property, by natural ordering, or by a custom comparator.

Note this does not change the original array.

pUtils.sort(resolve([{a: 1},{a: 2},{a: -2}]), "a").then(function(sorted){
    //[{a: -2},{a: 1},{a: 2}];
})

pUtils(resolve([{a: 1},{a: 2},{a: -2}])).sort("a").then(function(sorted){
    //[{a: -2},{a: 1},{a: 2}];
})

min

Finds the minimum value in an array based on a property, by natural ordering, or by a custom comparator.

pUtils.min(resolve([ 3, -3, -2, -1, 1, 2])).then(function(min){
    //-3
});

pUtils.min(resolve([{a: 1},{a: 2},{a: -2}]), "a").then(function(min){
    //{a : -2}
});

pUtils(resolve([ 3, -3, -2, -1, 1, 2])).min().then(function(min){
    //-3
});

pUtils(resolve([{a: 1},{a: 2},{a: -2}])).min("a").then(function(min){
    //{a : -2}
});

max

Finds the maximum value in an array based on a property, by natural ordering, or by a custom comparator.

pUtils.max(resolve([ 3, -3, -2, -1, 1, 2])).then(function(max){
     //2
});

pUtils.max(resolve([{a: 1},{a: 2},{a: -2}]), "a").then(function(max){
    //{a : 2}
});

pUtils(resolve([ 3, -3, -2, -1, 1, 2])).max().then(function(max){
    //2
});

pUtils(resolve([{a: 1},{a: 2},{a: -2}])).max("a").then(function(max){
    //{a : 2}
});

difference

Finds the difference between two arrays.

pUtils.difference(resolve([1, 2, 3]), [2]).then(function(diff){
    //[1, 3]
});
pUtils.difference(resolve([true, false]), resolve([false])).then(function(diff){
    //[true]
});

pUtils.difference(resolve(["a", "b", 3]), resolve([3])).then(function(diff){
    //["a", "b"]
});

pUtils.difference(resolve([{a: 1}, {a: 2}, {a: 3}]), resolve([{a: 2}, {a: 3}])).then(function(diff){
    //[{a: 1}]
});

pUtils(resolve([true, false])).difference([false]).then(function(diff){
    // [true]
});

pUtils(resolve([1, 2, 3])).difference(resolve([2])).then(function(diff){
    // [1, 3]
});
pUtils(resolve([1, 2, 3])).difference([2], resolve([3])).then(function(diff){
     //[1]
});

pUtils(resolve(["a", "b", 3])).difference([3]).then(function(diff){
     //["a", "b"]
});
pUtils(resolve([{a: 1}, {a: 2}, {a: 3}])).difference(resolve([{a: 2}, {a: 3}])).then(function(diff){
    // [{a: 1}]
});

unique

Removed duplicate values from an array

pUtils.unique(resolve([1, 2, 2, 3, 3, 3, 4, 4, 4])).then(function(unique){
    //[1, 2, 3, 4]
}):
pUtils(resolve([1, 2, 2, 3, 3, 3, 4, 4, 4])).unique().then(function(unique){
    //[1, 2, 3, 4]
});

pUtils(resolve(["a", "b", "b"])).unique().then(function(unique){
    //["a", "b"]
});

pUtils.unique(resolve(["a", "b", "b"])).then(function(unique){
    //["a", "b"]
});

rotate

Rotates an array by the number of places for 1 position by default.

var arr = pUtils(resolve(["a", "b", "c", "d"]))
arr.rotate();   //resolves with ["b", "c", "d", "a"]
arr.rotate(2);  //resolves with ["c", "d", "a", "b"]
arr.rotate(3);  //resolves with ["d", "a", "b", "c"]
arr.rotate(4);  //resolves with ["a", "b", "c", "d"]
arr.rotate(-1); //resolves with ["d", "a", "b", "c"]
arr.rotate(-2); //resolves with ["c", "d", "a", "b"]
arr.rotate(-3); //resolves with ["b", "c", "d", "a"]
arr.rotate(-4); //resolves with ["a", "b", "c", "d"]

arr = resolve(["a", "b", "c", "d"]);
pUtils.rotate(arr);     //resolves with ["b", "c", "d", "a"]
pUtils.rotate(arr, 2);  //resolves with ["c", "d", "a", "b"]
pUtils.rotate(arr, 3);  //resolves with ["d", "a", "b", "c"]
pUtils.rotate(arr, 4);  //resolves with ["a", "b", "c", "d"]
pUtils.rotate(arr, -1)  //resolves with ["d", "a", "b", "c"]
pUtils.rotate(arr, -2); //resolves with ["c", "d", "a", "b"]
pUtils.rotate(arr, -3); //resolves with ["b", "c", "d", "a"]
pUtils.rotate(arr, -4); //resolves with ["a", "b", "c", "d"]

permutations

Finds all permutations of an array.

pUtils(resolve([1, 2, 3])).permutations(); //resolves with [
                                 //   [ 1, 2, 3 ],
                                 //   [ 1, 3, 2 ],
                                 //   [ 2, 3, 1 ],
                                 //   [ 2, 1, 3 ],
                                 //   [ 3, 1, 2 ],
                                 //   [ 3, 2, 1 ]
                                 //]

pUtils(resolve([1, 2, 3])).permutations(2);// resolves with [
                                           //   [ 1, 2],
                                           //   [ 1, 3],
                                           //   [ 2, 3],
                                           //   [ 2, 1],
                                           //   [ 3, 1],
                                           //   [ 3, 2]
                                           //]

pUtils.permutations(resolve([1, 2, 3]));   // resolves with [
                                 //   [ 1, 2, 3 ],
                                 //   [ 1, 3, 2 ],
                                 //   [ 2, 3, 1 ],
                                 //   [ 2, 1, 3 ],
                                 //   [ 3, 1, 2 ],
                                 //   [ 3, 2, 1 ]
                                 //]

pUtils.permutations(resolve([1, 2, 3]), 2); //resolves with [
                                    //   [ 1, 2],
                                    //   [ 1, 3],
                                    //   [ 2, 3],
                                    //   [ 2, 1],
                                    //   [ 3, 1],
                                    //   [ 3, 2]
                                    //]

zip

Zips the values of multiple arrays into a single pUtils.

pUtils(resolve([1])).zip(resolve([2]), resolve([3]));//resolves with [
                                                     //  [ 1, 2, 3 ]
                                                     //];

pUtils(resolve([1, 2])).zip(resolve([2]), [3]);      //resolves with [
                                                     //  [ 1, 2, 3 ],
                                                     //  [2, null, null]
                                                     //]

pUtils(resolve([1, 2, 3])).zip([ 4, 5, 6 ], b);      //resolves with [
                                                     //  [1, 4, 7],
                                                     //  [2, 5, 8],
                                                     //  [3, 6, 9]
                                                     //]

pUtils(resolve([1, 2])).zip([ 4, 5, 6 ], resolve([7, 8, 9 ])); //resolves with [
                                                               //  [1, 4, 7],
                                                               //  [2, 5, 8]
                                                               //]

pUtils(resolve([ 4, 5, 6 ])).zip([1, 2], [8]);       //resolves with [
                                                     //  [4, 1, 8],
                                                     //  [5, 2, null],
                                                     //  [6, null, null]
                                                     //]


pUtils.zip(resolve([1]), [2], [3]);                  //resolves with [
                                                     //  [ 1, 2, 3 ]
                                                     //]

pUtils.zip(resolve([1, 2]), resolve([2]), [3]);      //resolves with [
                                                     //  [ 1, 2, 3 ],
                                                     //  [2, null, null]
                                                     //]

pUtils.zip(resolve([1, 2, 3]), [4,5,6],  resolve([7, 8, 9 ])); //resolves with [
                                                               //  [1, 4, 7],
                                                               //  [2, 5, 8],
                                                               //  [3, 6, 9]
                                                               //]

pUtils.zip(resolve([1, 2]), [4,5,6],  [7, 8, 9 ]);    //resolves with [
                                                      //  [1, 4, 7],
                                                      //  [2, 5, 8]
                                                      //]

pUtils.zip([ 4, 5, 6 ], [1, 2], resolve([8]));        //resolves with [
                                                      //  [4, 1, 8],
                                                      //  [5, 2, null],
                                                      //  [6, null, null]
                                                      //]

transpose

Transpose a multi dimensional array.

pUtils(resolve([[1, 2, 3],[4, 5, 6]])).transpose();   //resolves with [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
pUtils([[1, 2],[3, 4],[5, 6]]).async().transpose();   //resolves with [ [ 1, 3, 5 ], [ 2, 4, 6 ] ]
pUtils(resolve([[1],[3, 4],[5, 6]])).transpose();     //resolves with [ [1] ]


pUtils.transpose(resolve([[1, 2, 3],[4, 5, 6]]));     //resolves with [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
pUtils.transpose(resolve([[1, 2],[3, 4],[5, 6]]));    //resolves with [ [ 1, 3, 5 ], [ 2, 4, 6 ] ]
pUtils.transpose(resolve([[1],[3, 4],[5, 6]]));       //resolves with [ [1] ]

valuesAt

Gathers values at the specified indexes.

var arr = pUtils(resolve(["a", "b", "c", "d"]));
arr.valuesAt(1, 2, 3);      //resolves with ["b", "c", "d"]
arr.valuesAt(1, 2, 3, 4);   //resolves with ["b", "c", "d", null]
arr.valuesAt(0, 3);         //resolves with ["a", "d"]

arr = resolve(["a", "b", "c", "d"]);
pUtils.valuesAt(arr, 1, 2, 3);       //resolves with ["b", "c", "d"]
pUtils.valuesAt(arr, 1, 2, 3, 4);    //resolves with ["b", "c", "d", null]
pUtils.valuesAt(arr, 0, 3);          //resolves with ["a", "d"]

union

Finds the union of two arrays.

pUtils(resolve(["a", "b", "c"])).union(["b", "c", "d"]);           //resolves with ["a", "b", "c", "d"]);
pUtils(["a"]).async().union(["b"], ["c"], ["d"], resolve(["c"]));  //resolves with ["a", "b", "c", "d"]);

pUtils.union(resolve(["a", "b", "c"]), ["b", "c", "d"]);           //resolves with ["a", "b", "c", "d"]);
pUtils.union(resolve(["a"]), ["b"], resolve(["c"]), ["d"], ["c"]); //resolves with ["a", "b", "c", "d"]);

intersect

Finds the intersection of arrays.

pUtils(resolve([1, 2])).intersect([2, 3], [2, 3, 5]);                            //resolves with [2];
pUtils(resolve([1, 2, 3])).intersect([2, 3, 4, 5], [2, 3, 5]);                   //resolves with [2, 3];
pUtils(resolve([1, 2, 3, 4])).intersect([2, 3, 4, 5], [2, 3, 4, 5]);             //resolves with [2, 3, 4];
pUtils(resolve([1, 2, 3, 4, 5])).intersect([1, 2, 3, 4, 5], [1, 2, 3]);          //resolves with [1, 2, 3];
pUtils(resolve([[1, 2, 3, 4, 5],[1, 2, 3, 4, 5],[1, 2, 3]])).intersect();        //resolves with [1, 2, 3];

pUtils.intersect(resolve([1, 2]), [2, 3], [2, 3, 5]);                             //resolves with [2]
pUtils.intersect(resolve([1, 2, 3]), [2, 3, 4, 5], [2, 3, 5]);                    //resolves with [2, 3]
pUtils.intersect(resolve([1, 2, 3, 4]), [2, 3, 4, 5], resolve([2, 3, 4, 5]));     //resolves with [2, 3, 4]
pUtils.intersect(resolve([1, 2, 3, 4, 5]), [1, 2, 3, 4, 5], [1, 2, 3]);           //resolves with [1, 2, 3]);
pUtils.intersect(resolve([[1, 2, 3, 4, 5],[1, 2, 3, 4, 5], [1, 2, 3]]));          //resolves with [1, 2, 3]);

powerSet

Finds the powerset of a given array.

pUtils(resolve([1, 2, 3])).powerSet();
pUtils.powerSet(resolve([1, 2, 3]));
//Both resolve with
//[
//  [],
//  [ 1 ],
//  [ 2 ],
//  [ 1, 2 ],
//  [ 3 ],
//  [ 1, 3 ],
//  [ 2, 3 ],
//  [ 1, 2, 3 ]
//]

cartesian

Finds the cartesian product of arrays.

pUtils(resolve([1, 2])).cartesian(resolve([2, 3]));
pUtils.cartesian(resolve([1, 2]), [2, 3]);
//Both resolve with
//[
//  [1, 2],
//  [1, 3],
//  [2, 2],
//  [2, 3]
//]

compact

Compacts the values of an array.

pUtils(resolve([1, null, null, x, 2])).compact(); //Resolves with [1, 2]

pUtils([1, 2]).async().compact();  //Resolves with [1, 2]


pUtils.compact(resolve([1, null, null, x, 2])); //Resolves with [1, 2]
pUtils.compact(resolve([1, 2])); //Resolves with [1, 2]

multiply

Reproduces the values in an array the given number of times.

pUtils(resolve([1, 2])).multiply(2); //Resolves with[1, 2, 1, 2, 1, 2]

pUtils.multiply(resolve([1, 2, 3]), 2); //Resolves with [1, 2, 3, 1, 2, 3]

flatten

Flatten multiple arrays into a single array.

pUtils(resolve([ [1], [2], [3] ])).flatten(); //Resolves with [1, 2, 3]

pUtils.flatten(resolve([1, 2]), [2, 3], resolve([3, 4])); //Resolves with [1, 2, 2, 3, 3, 4]

pluck

Pluck properties from values in an array.

NOTE Plucked properties may also be promises. pluck will return the resolved value of the promise

var arr = resolve([
    {name: {first: "Fred", last: "Jones"}, age: 50, roles: ["a", "b", "c"]},
    {name: {first: resolve("Bob"), last: "Yukon"}, age: resolve(40), roles: resolve(["b", "c"])},
    {name: {first: "Alice", last: "Palace"}, age: 35, roles: ["c"]},
    {name: {first: resolve("Johnny"), last: "P."}, age: 56, roles: resolve([])}
]);

pUtils.pluck(arr, "name.first"); //Resolves with ["Fred", "Bob", "Alice", "Johnny"]
pUtils(arr).pluck("age"); //Resolves with [50, 40, 35, 56]

invoke

Invokes the specified method on each value in an array.

function person(name, age) {
    return {
        getName: function () {
            return resolve(name);
        },

        getOlder: function () {
            age++;
            return resolve(this);
        },

        getAge: function () {
            return resolve(age);
        }
    };
};

var arr = resolve([person("Bob", 40), person("Alice", 35), person("Fred", 50), person("Johnny", 56)]);

pUtils.invoke(arr, "getName"); //Resolves with ["Bob", "Alice", "Fred", "Johnny"];
pUtils(arr).invoke("getName"); //Resolves with ["Bob", "Alice", "Fred", "Johnny"];

pUtils(arr).invoke("getOlder").invoke("getAge"); //Resolves with [41, 36, 51, 57];