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 = ;
Or
var myextended = ;
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 = 123;var promiseArr = ; ; //OR ;
Chaining
When using promise-utils
as a monad with a promise you may chain methods together.
var arr = ; ;
forEach
Similar to Array#forEach
except that it resolves with the original array for chaining.
//as a monad ; pUtils;
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.
;
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.
;
In the above example only one item will be iterated one at a time.
map
Async version of Array#map
.
//as a monad ; pUtils;
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 ;
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.
;
In the above example only one item will be iterated at a time.
filter
Async version of Array#filter
.
//as a monad ; pUtils;
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 ;
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.
;
In the above example only one item will be iterated at a time.
every
Async version of Array#every
.
; pUtils;
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 ;
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.
;
In the above example only one item will be iterated at a time.
some
Async version of Array#every
.
; pUtils;
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 ;
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.
;
In the above example only one item will be iterated at a time.
sum
Sums the values of an array
pUtils; ;
avg
Finds the average of an array of numbers.
pUtils; ;
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
min
Finds the minimum value in an array based on a property, by natural ordering, or by a custom comparator.
pUtils; pUtils; ; ;
max
Finds the maximum value in an array based on a property, by natural ordering, or by a custom comparator.
pUtils; pUtils; ; ;
difference
Finds the difference between two arrays.
pUtils;pUtils; pUtils; pUtils; ; ;; ;;
unique
Removed duplicate values from an array
pUtils:; ; pUtils;
rotate
Rotates an array by the number of places for 1 position by default.
var arr = arr; //resolves with ["b", "c", "d", "a"]arr; //resolves with ["c", "d", "a", "b"]arr; //resolves with ["d", "a", "b", "c"]arr; //resolves with ["a", "b", "c", "d"]arr; //resolves with ["d", "a", "b", "c"]arr; //resolves with ["c", "d", "a", "b"]arr; //resolves with ["b", "c", "d", "a"]arr; //resolves with ["a", "b", "c", "d"] arr = ;pUtils; //resolves with ["b", "c", "d", "a"]pUtils; //resolves with ["c", "d", "a", "b"]pUtils; //resolves with ["d", "a", "b", "c"]pUtils; //resolves with ["a", "b", "c", "d"]pUtils //resolves with ["d", "a", "b", "c"]pUtils; //resolves with ["c", "d", "a", "b"]pUtils; //resolves with ["b", "c", "d", "a"]pUtils; //resolves with ["a", "b", "c", "d"]
permutations
Finds all permutations of an array.
; //resolves with [ // [ 1, 2, 3 ], // [ 1, 3, 2 ], // [ 2, 3, 1 ], // [ 2, 1, 3 ], // [ 3, 1, 2 ], // [ 3, 2, 1 ] //] ;// resolves with [ // [ 1, 2], // [ 1, 3], // [ 2, 3], // [ 2, 1], // [ 3, 1], // [ 3, 2] //] pUtils; // resolves with [ // [ 1, 2, 3 ], // [ 1, 3, 2 ], // [ 2, 3, 1 ], // [ 2, 1, 3 ], // [ 3, 1, 2 ], // [ 3, 2, 1 ] //] pUtils; //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.
;//resolves with [ // [ 1, 2, 3 ] //]; ; //resolves with [ // [ 1, 2, 3 ], // [2, null, null] //] ; //resolves with [ // [1, 4, 7], // [2, 5, 8], // [3, 6, 9] //] ; //resolves with [ // [1, 4, 7], // [2, 5, 8] //] ; //resolves with [ // [4, 1, 8], // [5, 2, null], // [6, null, null] //] pUtils; //resolves with [ // [ 1, 2, 3 ] //] pUtils; //resolves with [ // [ 1, 2, 3 ], // [2, null, null] //] pUtils; //resolves with [ // [1, 4, 7], // [2, 5, 8], // [3, 6, 9] //] pUtils; //resolves with [ // [1, 4, 7], // [2, 5, 8] //] pUtils; //resolves with [ // [4, 1, 8], // [5, 2, null], // [6, null, null] //]
transpose
Transpose a multi dimensional array.
; //resolves with [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]; //resolves with [ [ 1, 3, 5 ], [ 2, 4, 6 ] ]; //resolves with [ [1] ] pUtils; //resolves with [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]pUtils; //resolves with [ [ 1, 3, 5 ], [ 2, 4, 6 ] ]pUtils; //resolves with [ [1] ]
valuesAt
Gathers values at the specified indexes.
var arr = ;arr; //resolves with ["b", "c", "d"]arr; //resolves with ["b", "c", "d", null]arr; //resolves with ["a", "d"] arr = ;pUtils; //resolves with ["b", "c", "d"]pUtils; //resolves with ["b", "c", "d", null]pUtils; //resolves with ["a", "d"]
union
Finds the union of two arrays.
; //resolves with ["a", "b", "c", "d"]);; //resolves with ["a", "b", "c", "d"]); pUtils; //resolves with ["a", "b", "c", "d"]);pUtils; //resolves with ["a", "b", "c", "d"]);
intersect
Finds the intersection of arrays.
; //resolves with [2];; //resolves with [2, 3];; //resolves with [2, 3, 4];; //resolves with [1, 2, 3];; //resolves with [1, 2, 3]; pUtils; //resolves with [2]pUtils; //resolves with [2, 3]pUtils; //resolves with [2, 3, 4]pUtils; //resolves with [1, 2, 3]);pUtils; //resolves with [1, 2, 3]);
powerSet
Finds the powerset of a given array.
;pUtils;//Both resolve with//[// [],// [ 1 ],// [ 2 ],// [ 1, 2 ],// [ 3 ],// [ 1, 3 ],// [ 2, 3 ],// [ 1, 2, 3 ]//]
cartesian
Finds the cartesian product of arrays.
;pUtils;//Both resolve with//[// [1, 2],// [1, 3],// [2, 2],// [2, 3]//]
compact
Compacts the values of an array.
compact; //Resolves with [1, 2] compact; //Resolves with [1, 2] pUtilscompact; //Resolves with [1, 2]pUtilscompact; //Resolves with [1, 2]
multiply
Reproduces the values in an array the given number of times.
; //Resolves with[1, 2, 1, 2, 1, 2] pUtils; //Resolves with [1, 2, 3, 1, 2, 3]
flatten
Flatten multiple arrays into a single array.
; //Resolves with [1, 2, 3] pUtils; //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 = ; pUtils; //Resolves with ["Fred", "Bob", "Alice", "Johnny"]; //Resolves with [50, 40, 35, 56]
invoke
Invokes the specified method on each value in an array.
{ return { return ; } { age++; return ; } { return ; } ;}; var arr = ; pUtils; //Resolves with ["Bob", "Alice", "Fred", "Johnny"];; //Resolves with ["Bob", "Alice", "Fred", "Johnny"]; ; //Resolves with [41, 36, 51, 57];