diff --git a/README.md b/README.md index a3c9e4f..9b5063c 100644 --- a/README.md +++ b/README.md @@ -166,19 +166,32 @@ const res = await P.series( [ ### Collection methods -#### `all( arr )` +#### `all( promises [, options] )` -Identical to native `Promise.all( arr )`. +Identical to native `Promise.all( promises )`, except adds `await` option. -#### `allAwait( arr )` +If `options.await` is `true` and a promise rejects, all it waits for all other promises to settle (resolve or reject) before rejecting. -Like `Promise.all()`, but if a promise rejects, all it waits for all other promises to settle (resolve or reject) before rejecting. +If no promise rejects, resolves to array of resolution values of the input promises (just like `Promise.all()`). If any input promise rejects, rejects with rejection reason of the *first* promise to reject. -If no promise rejects, resolves to array of resolution values of the input promises. +```js +const promise1 = Promise.reject( new Error('Oops!') ); +const promise2 = new Promise( + resolve => setTimeout( () => console.log('Resolved!'), 1000 ) +); -If any input promise rejects, rejects with rejection reason of the first promise to reject. +await P.all( [ promise1, promise2 ]); +// 'Resolved!' not logged yet + +await P.all( [ promise1, promise2 ], { await: true } ); +// 'Resolved!' logged before promise rejects +``` -#### `props( obj )` +#### `allAwait( promises )` + +Shortcut for `all( promises, { await: true } )`. + +#### `props( obj [, options] )` Like `Promise.all()` for objects. @@ -195,7 +208,9 @@ const files = await P.props( { // files = { f1: 'file contents 1', f2: 'file contents 2', f3: 'file contents 3' } ``` -#### `propsOwn( obj )` +`await` option can be provided (see `all()` above). + +#### `propsOwn( obj [, options] )` Same as `props()` but only with object's *own* enumerable properties (i.e. properties on the object prototype are ignored). diff --git a/lib/all.js b/lib/all.js index 4945acb..9398619 100644 --- a/lib/all.js +++ b/lib/all.js @@ -5,13 +5,19 @@ 'use strict'; +// Imports +const allAwait = require('./allAwait'); + // Exports /** - * Same as `Promise.all()` - * @param {Array} arr - Array of promises + * Same as `Promise.all()` except adds `await` option. + * @param {Array} promises - Array of promises + * @param {Object} [options] - Options + * @param {boolean} [options.await=false] - `true` to await all promises if a promise rejects * @returns {Promise} - Promise of array of fulfilled values */ -module.exports = function all(arr) { - return Promise.all(arr); +module.exports = function all(promises, options) { + if (options && options.await) return allAwait(promises); + return Promise.all(promises); }; diff --git a/lib/props.js b/lib/props.js index d5abc72..5d07658 100644 --- a/lib/props.js +++ b/lib/props.js @@ -5,14 +5,19 @@ 'use strict'; +// Imports +const all = require('./all'); + // Exports /** * Resolve object of promises. * @param {Object} obj - Object + * @param {Object} [options] - Options + * @param {boolean} [options.await=false] - `true` to await all promises if a promise rejects * @returns {Promise} - Promise of object of fulfilled values */ -module.exports = function props(obj) { +module.exports = function props(obj, options) { const keys = [], values = []; for (const key in obj) { @@ -20,7 +25,7 @@ module.exports = function props(obj) { values.push(obj[key]); } - return Promise.all(values).then((resolvedValues) => { + return all(values, options).then((resolvedValues) => { const out = {}; for (let i = 0; i < keys.length; i++) { out[keys[i]] = resolvedValues[i]; diff --git a/lib/propsOwn.js b/lib/propsOwn.js index d33d51c..33dc815 100644 --- a/lib/propsOwn.js +++ b/lib/propsOwn.js @@ -5,18 +5,23 @@ 'use strict'; +// Imports +const all = require('./all'); + // Exports /** * Resolve object of promises (own properties only). * @param {Object} obj - Object + * @param {Object} [options] - Options + * @param {boolean} [options.await=false] - `true` to await all promises if a promise rejects * @returns {Promise} - Promise of object of fulfilled values */ -module.exports = function propsOwn(obj) { +module.exports = function propsOwn(obj, options) { const keys = Object.keys(obj), values = keys.map(key => obj[key]); - return Promise.all(values).then((resolvedValues) => { + return all(values, options).then((resolvedValues) => { const out = {}; for (let i = 0; i < keys.length; i++) { out[keys[i]] = resolvedValues[i];