arrayp v1.1.0

ifdef::env-github,env-browser:outfilesuffix: .adoc :rootdir: . :imagesdir: {rootdir}/images //:numbered: :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[] :toclevels: 1 :toc: :toc-placement!:

= arrayp

Functions for manipulating collections of JavaScript ((Promise)) objects.

toc::[]

== Usage Install with npm.

$ npm install arrayp --save

const arrayp = require('arrayp');

// Chain list of promises, passing result of one to the next.
arrayp.chain( [
  // Synchronously resolves to '1'
  1,

  // Argument: '1'. Asynchronously resolves to '2'
  ( x ) => new Promise( ( resolve ) =>
    setTimeout( () => resolve( x + 1 ), 250 ) ),

  // Argument: '2'. Asynchronously resolves to '6'
  ( x ) => x * 3,

  // Argument: '6'. Asynchronously resolves to '2'
  ( x ) => Promise.resolve( x - 4 ),

  // emit output
  console.log
] );

//output: 2

== About arrayp Iterables arrayp methods operate on JavaScript https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol:[iterables] which can contain literals, objects or functions. Before a collection item is used, it converted to a promise. arrayp wait asynchronously for an item's resolved value (or rejection error).

Collection items are converted to Promise objects in the following manner:

• Promise objects are used as-is.
• Non Promise objects are converted to a Promise that resolve to the object
• Functions are wrapped in a Promise. When used, the function is invoked and the Promise resolves with the value returned by the function, or is rejected with an error if the function throws an error.

== chain(iterable, initial) : Promise Evaluates each promise in the iterable in series and returns a Promise that resolves with the value from the last item in the iterable, or rejects with the reason from the first item in the iterable that rejects. The value from one item in the iterable is passed as an argument to the next item. An optional initial value to the chain method will be passed to the first promise of the iterable.

=== Parameters

• *array* An iterable object, such as an Array.
• *initial* _(*)_ Optional value passed to the first item.

=== Returns A pending https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise[Promise] that resolves with the value of the last item of the array, or rejects with reason of the first rejecting item in the iterable.

=== Description This method can be useful for chaining multiple promises.

==== Fulfilment

• If an empty iterable is passed, this method returns (synchronously) an already resolved promise.
• In all other cases, the promise returned by chain is fulfilled asynchronously.

==== Rejection If an iterable item rejects, chain asynchronously rejects with the rejection reason. Subsequent items in the iterable are not processed.

=== Examples

arrayp.chain( [1,2,3,4,5] ).then( console.log );

//output: 5

arrayp.chain( [
  1, //literal
  ( x ) => new Promise( ( resolve ) =>
    setTimeout( () => resolve( x + 1 ), 250 ) ),
  ( x ) => x * 3,
  ( x ) => Promise.resolve( x - 4 ),
  console.log
] );

//output: 2

This is equivalent to the following Promise chain:

Promise
    .resolve( 1 )
    .then( ( x ) => new Promise(
      ( resolve ) => setTimeout(
        () => resolve( x + 1 ), 250 ) ) )
    .then( ( x ) => x * 3 )
    .then( ( x ) => Promise.resolve( x - 4 ) )
    .then(console.log);

//output: 2

== series(iterable) : Promise Evaluates each promise in the iterable in series and returns a Promise that resolves with array containing all the resolved values of the iterable passed as argument. It rejects with the reason of the first promise that rejects.

=== Parameters

• *array* An iterable object, such as an Array.

=== Returns

• An already resolved Promise if the iterable passed is empty.
• In all other cases, a pending https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise[Promise] that resolves with array containing all the resolved values when all items in the given iterable have been resolved.

=== Description This method can be useful for chaining multiple promises.

==== Fulfilment

• If an empty iterable is passed, this method returns (synchronously) an already resolved promise.
• In all other cases, the promise returned by chain is fulfilled asynchronously.

==== Rejection If an iterable item rejects, chain asynchronously rejects with the rejection reason. Subsequent items in the iterable are not processed.

=== Examples

arrayp.series( [1,2,3,4,5] ).then( console.log );

//output: [1,2,3,4,5]

arrayp.series( [
  1,
  () => new Promise( ( resolve ) => setTimeout( () => resolve( 2 ), 250 ) ),
  () => 3,
  () => Promise.resolve( 4 ),
  Promise.resolve( 5 ),
  console.log
]);

//output: [1,2,3,4,5]

== parallel(array, limit) parallel evaluates up to limit items from the iterable in parallel and returns a single Promise that resolves when all of the promises in the iterable argument have resolved. It rejects with the reason of the first promise that rejects. If limit is not specified, all items will be evaluated in parallel (like Promise.all()).

=== Parameters

• *array* An iterable object, such as an Array.
• limit {Integer} a positive integer limiting the tasks to be evaluated in parallel.

=== Returns

• An already resolved Promise if the iterable passed is empty.
• In all other cases, a pending https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise[Promise] that resolves with array containing all the resolved values when all items in the given iterable have been resolved.

==== Fulfilment

• If an empty iterable is passed, this method returns (synchronously) an already resolved promise.
• In all other cases, the promise returned by parallel is fulfilled asynchronously.

==== Rejection If an iterable item rejects, parallel asynchronously rejects with the rejection reason. Subsequent items in the iterable are not processed.

=== Examples

==== No Limit (like Promise.all())

A helper function:

function _( delay, value ) {
  return function () {
    console.log( `${value}: start` );
    return new Promise( ( resolve ) => {
      setTimeout( () => {
        console.log( `${value}: done` );
        resolve( value )
      }, delay )
    } );
  };
}

const array = [
  _( 200, 1 ),
  _( 100, 2 ),
  _( 500, 3 ),
  _( 250, 4 ),
  _( 400, 5 ),
  _( 50, 6 )
];

parallel:

arrayp.parallel( array )
      .then( console.log );

Output:

1: start (200)
2: start (100)
3: start (500)
4: start (250)
5: start (400)
6: start (50)
6: done
2: done
1: done
4: done
5: done
3: done
[ 1, 2, 3, 4, 5, 6 ]

==== Limit Parallel Tasks to 3

parallel(iterable, 3):

arrayp.parallel( array, 3 )
      .then( console.log );

Output:

1: start (200)
2: start (100)
3: start (500)
2: done
4: start (250)
1: done
5: start (400)
4: done
6: start (50)
6: done
3: done
5: done
[ 1, 2, 3, 4, 5, 6 ]

== run(array, limit) Like parallel, but does not reject if array items reject. Returns a Promise which resolves with the values or reasons of the array items.