spex - npm Package Compare versions

Comparing version 0.0.29 to 0.0.30

API.md

@@ -10,9 +10,11 @@ ## Modules
 <dt><a href="#batch">batch(values, [cb])</a> ⇒ <code>Promise</code></dt>
-<dd><p>This method is a fusion of <code>promise.all</code> + <code>promise.settle</code> logic,
-to resolve with the same type of result as <code>promise.all</code>, while also
-settling all the promises, and providing a detailed summary in case
-any of the promises rejects.</p>
+<dd><p>Settles every <a href="https://github.com/vitaly-t/spex/wiki/Mixed-Values">mixed value</a> in the input array, and resolves with the array of
+results, if all values resolved, or rejects when one or more values rejected.</p>
+<p>This method is a fusion of <code>promise.all</code> + <code>promise.settle</code> logic, to resolve with
+the same type of result as the standard <code>promise.all</code>, while also settling all the promises,
+and providing a comprehensive rejection summary in case of any reject.</p>
 </dd>
-<dt><a href="#page">page(source, [dest], [limit])</a></dt>
-<dd></dd>
+<dt><a href="#page">page(source, [dest], [limit])</a> ⇒ <code>Promise</code></dt>
+<dd><p>Documentation is currently in the works...</p>
+</dd>
 <dt><a href="#sequence">sequence(source, [dest], [limit], [track])</a> ⇒ <code>Promise</code></dt>
@@ -44,7 +46,7 @@ <dd><p>Acquires <a href="https://github.com/vitaly-t/spex/wiki/Mixed-Values">mixed values</a> from the source function, one at a time, and resolves them,
 ## batch(values, [cb]) ⇒ <code>Promise</code>
-This method is a fusion of `promise.all` + `promise.settle` logic,
to resolve with the same type of result as `promise.all`, while also
settling all the promises, and providing a detailed summary in case
any of the promises rejects.
+Settles every <a href="https://github.com/vitaly-t/spex/wiki/Mixed-Values">mixed value</a> in the input array, and resolves with the array of
results, if all values resolved, or rejects when one or more values rejected.

This method is a fusion of `promise.all` + `promise.settle` logic, to resolve with
the same type of result as the standard `promise.all`, while also settling all the promises,
and providing a comprehensive rejection summary in case of any reject.
 
 **Kind**: global function  
-**Summary**: Attempts to resolve every value in the input array.  
-**Returns**: <code>Promise</code> - Result for the entire batch, which resolves when
every promise in the input array has been resolved, and rejects when one
or more promise objects in the array rejected:
- resolves with an array of individual resolved results, the same as `promise.all`;

  The array comes extended with read-only property `duration` - number of
  milliseconds taken to resolve all the data.

- rejects with an array of objects `{success, result}`:
  - `success`: `true/false`, indicates whether the corresponding value
    in the input array was resolved.
  - `result`: resolved data, if `success=true`, or else the rejection reason.

  The array comes extended with function `getErrors`, which returns the list
  of just errors, with support for nested batch results.
  Calling `getErrors()[0]`, for example, will get the same result as the
  rejection reason that `promise.all` would provide.

In both cases the output array is always the same size as the input one,
providing index mapping between input and output values.  
+**Summary**: Resolves a predefined array of <a href="https://github.com/vitaly-t/spex/wiki/Mixed-Values">mixed values</a>.  
+**Returns**: <code>Promise</code> - Result for the entire batch, which resolves when every value in the input array has been resolved,
and rejects when:
 - one or more values in the array rejected
 - one or more calls into the notification callback returned a rejected promise or threw an error

The method resolves with an array of individual resolved results, the same as `promise.all`.
In addition, the array is extended with read-only property `duration` - number of milliseconds
taken to resolve all the data.

When failed, the method rejects with an array of objects `{success, result}`:
 - `success`: `true/false`, indicates whether the corresponding value in the input array was resolved.
 - `result`: resolved data, if `success=true`, or else the rejection reason.

In addition, the array is extended with function `getErrors`, which returns the list of just errors,
with support for nested batch results. Calling `getErrors()[0]`, for example, will get the same
result as the rejection reason that `promise.all` would provide.

When a value in the array represents a failure that's the result of an unsuccessful call into the
notification callback, it will also have property `origin`. See documentation for parameter `cb`.

In both cases the output array is always the same size as the input one, providing index mapping
between input and output values.  
 <table>
@@ -58,16 +60,25 @@ <thead>
 <tr>
-    <td>values</td><td><code>Array</code></td><td><p>array of values of the following types:</p>
+    <td>values</td><td><code>Array</code></td><td><p>Array of <a href="https://github.com/vitaly-t/spex/wiki/Mixed-Values">mixed values</a> to be resolved asynchronously, i.e. in no particular order.</p>
+<p>If the parameter is anything other than an array, an error is thrown:
+<code>Array of values is required to execute a batch.</code></p>
+</td>
+    </tr><tr>
+    <td>[cb]</td><td><code>function</code></td><td><p>Optional callback to receive a notification about the resolution result for each value.</p>
+<p>Parameters:</p>
 <ul>
-<li>a simple value or object, to resolve with by default;</li>
-<li>a promise object to be either resolved or rejected;</li>
-<li>a function, to be called with the task/transaction context,
-so it can return a value, an object or a promise.
-If it returns another function, the call will be repeated,
-until the returned type is a value, an object or a promise.</li>
+<li><code>index</code> - index of the value in the array</li>
+<li><code>success</code> - indicates whether the value was resolved (<code>true</code>), or rejected (<code>false</code>)</li>
+<li><code>data</code> - resolved data, if <code>success</code>=<code>true</code>, or else the rejection reason</li>
 </ul>
-<p>If the parameter is anything other than an array, an error will
-be thrown: <code>Array of values is required to execute a batch.</code></p>
+<p>The function is called with the same <code>this</code> context as the calling method.</p>
+<p>It can optionally return a promise object, to indicate that it handles notifications asynchronously.
+If the returned promise resolves, it signals a successful notification, while any resolved data is ignored.</p>
+<p>If the function returns a rejected promise or throws an error, the entire method rejects, while the
+rejected element is replaced with object <code>{success, result, origin}</code>:</p>
+<ul>
+<li><code>success</code> = <code>false</code></li>
+<li><code>result</code> - the rejection reason or the error thrown by the notification callback</li>
+<li><code>origin</code> - the original data passed into the callback, as object <code>{success, result}</code></li>
+</ul>
 </td>
-    </tr><tr>
-    <td>[cb]</td><td><code>function</code></td><td></td>
     </tr>  </tbody>
@@ -77,5 +88,7 @@ </table>
 <a name="page"></a>
-## page(source, [dest], [limit])
+## page(source, [dest], [limit]) ⇒ <code>Promise</code>
+Documentation is currently in the works...
+
 **Kind**: global function  
-**Summary**: Resolves dynamic arrays/pages of promises;  
+**Summary**: Resolves a dynamic sequence of arrays/pages with <a href="https://github.com/vitaly-t/spex/wiki/Mixed-Values">mixed values</a>.  
 <table>
@@ -103,3 +116,3 @@ <thead>
 **Summary**: Resolves a dynamic sequence of <a href="https://github.com/vitaly-t/spex/wiki/Mixed-Values">mixed values</a>.  
-**Returns**: <code>Promise</code> - When successful, the resolved data depends on parameter `track`. When `track` is `false`
(default), the method resolves with object `{total, duration}`:
 - `total` - total number of values resolved from the sequence
 - `duration` - number of milliseconds consumed by the method

When `track` is `true`, the method resolves with an array of all the data that has been resolved.
The array comes extended with read-only property `duration` - number of milliseconds consumed by the method.

If the method fails, it rejects with an object according to which of the two functions caused
the failure - `source` or `dest`. See the two parameters for the rejection details.  
+**Returns**: <code>Promise</code> - When successful, the resolved data depends on parameter `track`. When `track` is `false`
(default), the method resolves with object `{total, duration}`:
 - `total` - total number of values resolved from the sequence
 - `duration` - number of milliseconds consumed by the method

When `track` is `true`, the method resolves with an array of all the data that has been resolved,
the same way that the standard `promise.all` resolves. In addition, the array comes extended with
read-only property `duration` - number of milliseconds consumed by the method.

If the method fails, it rejects with an object according to which function caused
the failure - `source` or `dest`. See the two parameters for the rejection details.  
 <table>
@@ -150,7 +163,7 @@ <thead>
 </ul>
-<p>Passing in anything other than a function will throw <code>Invalid sequence destination.</code></p>
+<p>Passing in a non-empty value other than a function will throw <code>Invalid sequence destination.</code></p>
 </td>
     </tr><tr>
     <td>[limit]</td><td><code>Integer</code></td><td><code>0</code></td><td><p>Limits the maximum size of the sequence. If the value is an integer greater than 0,
-the method will successfully resolve once the specified size limit has been reached.
+the method will successfully resolve once the specified limit has been reached.
 By default, the sequence is unlimited, and will continue till either <code>source</code> function
@@ -160,3 +173,4 @@ returns <code>undefined</code> or an error/reject occurs.</p>
     </tr><tr>
-    <td>[track]</td><td><code>Boolean</code></td><td><code>false</code></td><td><p>The value of this parameter changes the type of data to be resolved by this method.
+    <td>[track]</td><td><code>Boolean</code></td><td><code>false</code></td><td><p>This parameter changes the type of data to be resolved by this method.
+By default, it is <code>false</code> (see the return result).
 When set to be <code>true</code>, it instructs the method to track/collect all resolved data into
@@ -163,0 +177,0 @@ an array internally, so it can be resolved with once the method has finished successfully.</p>

lib/ext/batch.js

@@ -5,42 +5,59 @@ 'use strict';
  * @method batch
- * @summary Attempts to resolve every value in the input array.
+ * @summary Resolves a predefined array of $[mixed values].
  * @description
- * This method is a fusion of `promise.all` + `promise.settle` logic,
- * to resolve with the same type of result as `promise.all`, while also
- * settling all the promises, and providing a detailed summary in case
- * any of the promises rejects.
+ * Settles every $[mixed value] in the input array, and resolves with the array of
+ * results, if all values resolved, or rejects when one or more values rejected.
  *
- * @param {Array} values - array of values of the following types:
- * - a simple value or object, to resolve with by default;
- * - a promise object to be either resolved or rejected;
- * - a function, to be called with the task/transaction context,
- *   so it can return a value, an object or a promise.
- *   If it returns another function, the call will be repeated,
- *   until the returned type is a value, an object or a promise.
+ * This method is a fusion of `promise.all` + `promise.settle` logic, to resolve with
+ * the same type of result as the standard `promise.all`, while also settling all the promises,
+ * and providing a comprehensive rejection summary in case of any reject.
  *
- * If the parameter is anything other than an array, an error will
- * be thrown: `Array of values is required to execute a batch.`
+ * @param {Array} values
+ * Array of $[mixed values] to be resolved asynchronously, i.e. in no particular order.
  *
+ * If the parameter is anything other than an array, an error is thrown:
+ * `Array of values is required to execute a batch.`
+ *
  * @param {Function} [cb]
+ * Optional callback to receive a notification about the resolution result for each value.
  *
- * @returns {Promise} Result for the entire batch, which resolves when
- * every promise in the input array has been resolved, and rejects when one
- * or more promise objects in the array rejected:
- * - resolves with an array of individual resolved results, the same as `promise.all`;
+ * Parameters:
+ *  - `index` - index of the value in the array
+ *  - `success` - indicates whether the value was resolved (`true`), or rejected (`false`)
+ *  - `data` - resolved data, if `success`=`true`, or else the rejection reason
  *
- *   The array comes extended with read-only property `duration` - number of
- *   milliseconds taken to resolve all the data.
+ * The function is called with the same `this` context as the calling method.
  *
- * - rejects with an array of objects `{success, result}`:
- *   - `success`: `true/false`, indicates whether the corresponding value
- *     in the input array was resolved.
- *   - `result`: resolved data, if `success=true`, or else the rejection reason.
+ * It can optionally return a promise object, to indicate that it handles notifications asynchronously.
+ * If the returned promise resolves, it signals a successful notification, while any resolved data is ignored.
  *
- *   The array comes extended with function `getErrors`, which returns the list
- *   of just errors, with support for nested batch results.
- *   Calling `getErrors()[0]`, for example, will get the same result as the
- *   rejection reason that `promise.all` would provide.
+ * If the function returns a rejected promise or throws an error, the entire method rejects, while the
+ * rejected element is replaced with object `{success, result, origin}`:
+ *  - `success` = `false`
+ *  - `result` - the rejection reason or the error thrown by the notification callback
+ *  - `origin` - the original data passed into the callback, as object `{success, result}`
  *
- * In both cases the output array is always the same size as the input one,
- * providing index mapping between input and output values.
+ * @returns {Promise}
+ * Result for the entire batch, which resolves when every value in the input array has been resolved,
+ * and rejects when:
+ *  - one or more values in the array rejected
+ *  - one or more calls into the notification callback returned a rejected promise or threw an error
+ *
+ * The method resolves with an array of individual resolved results, the same as `promise.all`.
+ * In addition, the array is extended with read-only property `duration` - number of milliseconds
+ * taken to resolve all the data.
+ *
+ * When failed, the method rejects with an array of objects `{success, result}`:
+ *  - `success`: `true/false`, indicates whether the corresponding value in the input array was resolved.
+ *  - `result`: resolved data, if `success=true`, or else the rejection reason.
+ *
+ * In addition, the array is extended with function `getErrors`, which returns the list of just errors,
+ * with support for nested batch results. Calling `getErrors()[0]`, for example, will get the same
+ * result as the rejection reason that `promise.all` would provide.
+ *
+ * When a value in the array represents a failure that's the result of an unsuccessful call into the
+ * notification callback, it will also have property `origin`. See documentation for parameter `cb`.
+ *
+ * In both cases the output array is always the same size as the input one, providing index mapping
+ * between input and output values.
  */
@@ -47,0 +64,0 @@

lib/ext/page.js

 'use strict';
 
-// This method is identical to `sequence`, except it does paging.
-
-// RESOLVES:
-// {duration, pages, total}, when `undefined` or `[]` returned from the source function;
-
-// REJECTS:
-// 1. {index, error} - source returned invalid value, error="Invalid value!"
-// 2. {index, error, source} - source rejected or returned an error;
-// 3. {index, data} - data page rejected;
-// 4. {index, error, dest} - destination function rejected or threw an error;
-
-// Source format: (index, data);
-// Destination format: (index, data);
-// + THIS context;
-
 /**
  * @method page
- * @summary Resolves dynamic arrays/pages of promises;
+ * @summary Resolves a dynamic sequence of arrays/pages with $[mixed values].
+ * @description
+ * Documentation is currently in the works...
  * @param {function} source
  * @param {function} [dest]
  * @param {function} [limit=0]
+ * @returns {Promise}
  */
@@ -135,1 +123,16 @@ function page(source, dest, limit) {
 };
+
+// This method is identical to `sequence`, except it does paging.
+
+// RESOLVES:
+// {duration, pages, total}, when `undefined` or `[]` returned from the source function;
+
+// REJECTS:
+// 1. {index, error} - source returned invalid value, error="Invalid value!"
+// 2. {index, error, source} - source rejected or returned an error;
+// 3. {index, data} - data page rejected;
+// 4. {index, error, dest} - destination function rejected or threw an error;
+
+// Source format: (index, data);
+// Destination format: (index, data);
+// + THIS context;

lib/ext/sequence.js

@@ -48,7 +48,7 @@ 'use strict';
  *
- * Passing in anything other than a function will throw `Invalid sequence destination.`
+ * Passing in a non-empty value other than a function will throw `Invalid sequence destination.`
  *
  * @param {Integer} [limit=0]
  * Limits the maximum size of the sequence. If the value is an integer greater than 0,
- * the method will successfully resolve once the specified size limit has been reached.
+ * the method will successfully resolve once the specified limit has been reached.
  * By default, the sequence is unlimited, and will continue till either `source` function
@@ -58,3 +58,4 @@ * returns `undefined` or an error/reject occurs.
  * @param {Boolean} [track=false]
- * The value of this parameter changes the type of data to be resolved by this method.
+ * This parameter changes the type of data to be resolved by this method.
+ * By default, it is `false` (see the return result).
  * When set to be `true`, it instructs the method to track/collect all resolved data into
@@ -72,6 +73,7 @@ * an array internally, so it can be resolved with once the method has finished successfully.
  *
- * When `track` is `true`, the method resolves with an array of all the data that has been resolved.
- * The array comes extended with read-only property `duration` - number of milliseconds consumed by the method.
+ * When `track` is `true`, the method resolves with an array of all the data that has been resolved,
+ * the same way that the standard `promise.all` resolves. In addition, the array comes extended with
+ * read-only property `duration` - number of milliseconds consumed by the method.
  *
- * If the method fails, it rejects with an object according to which of the two functions caused
+ * If the method fails, it rejects with an object according to which function caused
  * the failure - `source` or `dest`. See the two parameters for the rejection details.
@@ -78,0 +80,0 @@ */

package.json

 {
   "name": "spex",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "description": "Specialized Promise Extensions",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

40096

increased by9.71%

Lines of code

696

increased by3.26%

No dependency changes