Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Collection of promise utilities
JavaScript Perl
Branch: master

v0.0.3

* Removed objet-extended dep
* Added dep to arguments-extended
latest commit dd82099d1e
@doug-martin authored
Failed to load latest commit information.
test v0.0.2
.gitignore Initial Commit
.jshintrc Initial Commit
.npmignore Initial Commit
.travis.yml Initial Commit
Gruntfile.js Initial Commit
LICENSE Initial Commit
README.md Initial Commit
index.js v0.0.3
package.json v0.0.3
promise-utils.min.js

README.md

Build Status

browser support

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];
Something went wrong with that request. Please try again.