Update to NPM version

ProjectSourceCode/node_modules/spex/lib/errors/batch.js

@@ -0,0 +1,173 @@
+const npm = {
+    u: require('util'),
+    os: require('os'),
+    utils: require('../utils/static')
+};
+
+/**
+ * @class errors.BatchError
+ * @augments external:Error
+ * @description
+ * This type represents all errors rejected by method {@link batch}, except for {@link external:TypeError TypeError}
+ * when the method receives invalid input parameters.
+ *
+ * @property {string} name
+ * Standard {@link external:Error Error} property - error type name = `BatchError`.
+ *
+ * @property {string} message
+ * Standard {@link external:Error Error} property - the error message.
+ *
+ * It represents the message of the first error encountered in the batch, and is a safe
+ * version of using `first.message`.
+ *
+ * @property {string} stack
+ * Standard {@link external:Error Error} property - the stack trace.
+ *
+ * @property {array} data
+ * Array of objects `{success, result, [origin]}`:
+ * - `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.
+ * - `origin` - set only when failed as a result of an unsuccessful call into the notification callback
+ *    (parameter `cb` of method {@link batch})
+ *
+ * The array has the same size as the input one that was passed into method {@link batch}, providing direct mapping.
+ *
+ * @property {} stat
+ * Resolution Statistics.
+ *
+ * @property {number} stat.total
+ * Total number of elements in the batch.
+ *
+ * @property {number} stat.succeeded
+ * Number of resolved values in the batch.
+ *
+ * @property {number} stat.failed
+ * Number of rejected values in the batch.
+ *
+ * @property {number} stat.duration
+ * Time in milliseconds it took to settle all values.
+ *
+ * @property {} first
+ * The very first error within the batch, with support for nested batch results, it is also the same error
+ * as $[promise.all] would provide.
+ *
+ * @see {@link batch}
+ *
+ */
+class BatchError extends Error {
+
+    constructor(result, errors, duration) {
+
+        function getErrors() {
+            const err = new Array(errors.length);
+            for (let i = 0; i < errors.length; i++) {
+                err[i] = result[errors[i]].result;
+                if (err[i] instanceof BatchError) {
+                    err[i] = err[i].getErrors();
+                }
+            }
+            npm.utils.extend(err, '$isErrorList', true);
+            return err;
+        }
+
+        const e = getErrors();
+
+        let first = e[0];
+
+        while (first && first.$isErrorList) {
+            first = first[0];
+        }
+
+        let message;
+
+        if (first instanceof Error) {
+            message = first.message;
+        } else {
+            if (typeof first !== 'string') {
+                first = npm.u.inspect(first);
+            }
+            message = first;
+        }
+
+        super(message);
+        this.name = this.constructor.name;
+
+        this.data = result;
+
+        // we do not show it within the inspect, because when the error
+        // happens for a nested result, the output becomes a mess.
+        this.first = first;
+
+        this.stat = {
+            total: result.length,
+            succeeded: result.length - e.length,
+            failed: e.length,
+            duration: duration
+        };
+
+        this.getErrors = getErrors;
+
+        Error.captureStackTrace(this, this.constructor);
+    }
+
+    /**
+     * @method errors.BatchError.getErrors
+     * @description
+     * Returns the complete list of errors only.
+     *
+     * It supports nested batch results, presented as a sub-array.
+     *
+     * @returns {array}
+     */
+}
+
+/**
+ * @method errors.BatchError.toString
+ * @description
+ * Creates a well-formatted multi-line string that represents the error.
+ *
+ * It is called automatically when writing the object into the console.
+ *
+ * The output is an abbreviated version of the error, because the complete error
+ * is often too much for displaying or even logging, as a batch can be of any size.
+ * Therefore, only errors are rendered from the `data` property, alongside their indexes,
+ * and only up to the first 5, to avoid polluting the screen or the log file.
+ *
+ * @param {number} [level=0]
+ * Nested output level, to provide visual offset.
+ *
+ * @returns {string}
+ */
+BatchError.prototype.toString = function (level) {
+    level = level > 0 ? parseInt(level) : 0;
+    const gap0 = npm.utils.messageGap(level),
+        gap1 = npm.utils.messageGap(level + 1),
+        gap2 = npm.utils.messageGap(level + 2),
+        lines = [
+            'BatchError {',
+            gap1 + 'stat: { total: ' + this.stat.total + ', succeeded: ' + this.stat.succeeded +
+            ', failed: ' + this.stat.failed + ', duration: ' + this.stat.duration + ' }',
+            gap1 + 'errors: ['
+        ];
+
+    // In order to avoid polluting the error log or the console, 
+    // we limit the log output to the top 5 errors:
+    const maxErrors = 5;
+    let counter = 0;
+    this.data.forEach((d, index) => {
+        if (!d.success && counter < maxErrors) {
+            lines.push(gap2 + index + ': ' + npm.utils.formatError(d.result, level + 2));
+            counter++;
+        }
+    });
+    lines.push(gap1 + ']');
+    lines.push(gap0 + '}');
+    return lines.join(npm.os.EOL);
+};
+
+npm.utils.addInspection(BatchError, function () {
+    return this.toString();
+});
+
+module.exports = {BatchError};
+

ProjectSourceCode/node_modules/spex/lib/errors/index.js

@@ -0,0 +1,36 @@
+const {BatchError} = require('./batch');
+const {PageError} = require('./page');
+const {SequenceError} = require('./sequence');
+
+
+/**
+ * @namespace errors
+ * @description
+ * Namespace for all custom error types supported by the library.
+ *
+ * In addition to the custom error type used by each method (regular error), they can also reject with
+ * {@link external:TypeError TypeError} when receiving invalid input parameters.
+ *
+ * @property {function} BatchError
+ * {@link errors.BatchError BatchError} class.
+ *
+ * Represents regular errors that can be reported by method {@link batch}.
+ *
+ * @property {function} PageError
+ * {@link errors.PageError PageError} class.
+ *
+ * Represents regular errors that can be reported by method {@link page}.
+ *
+ * @property {function} SequenceError
+ * {@link errors.SequenceError SequenceError} class.
+ *
+ * Represents regular errors that can be reported by method {@link sequence}.
+ *
+ */
+module.exports = {
+    BatchError,
+    PageError,
+    SequenceError
+};
+
+Object.freeze(module.exports);

ProjectSourceCode/node_modules/spex/lib/errors/page.js

@@ -0,0 +1,135 @@
+const npm = {
+    u: require('util'),
+    os: require('os'),
+    utils: require('../utils/static')
+};
+
+const errorReasons = {
+    0: 'Page with index %d rejected.',
+    1: 'Source %s returned a rejection at index %d.',
+    2: 'Source %s threw an error at index %d.',
+    3: 'Destination %s returned a rejection at index %d.',
+    4: 'Destination %s threw an error at index %d.',
+    5: 'Source %s returned a non-array value at index %d.'
+};
+
+/**
+ * @class errors.PageError
+ * @augments external:Error
+ * @description
+ * This type represents all errors rejected by method {@link page}, except for {@link external:TypeError TypeError}
+ * when the method receives invalid input parameters.
+ *
+ * @property {string} name
+ * Standard {@link external:Error Error} property - error type name = `PageError`.
+ *
+ * @property {string} message
+ * Standard {@link external:Error Error} property - the error message.
+ *
+ * @property {string} stack
+ * Standard {@link external:Error Error} property - the stack trace.
+ *
+ * @property {} error
+ * The error that was thrown, or the rejection reason.
+ *
+ * @property {number} index
+ * Index of the element in the sequence for which the error/rejection occurred.
+ *
+ * @property {number} duration
+ * Duration (in milliseconds) of processing until the error/rejection occurred.
+ *
+ * @property {string} reason
+ * Textual explanation of why the method failed.
+ *
+ * @property {} source
+ * Resolved `data` parameter that was passed into the `source` function.
+ *
+ * It is only set when the error/rejection occurred inside the `source` function.
+ *
+ * @property {} dest
+ * Resolved `data` parameter that was passed into the `dest` function.
+ *
+ * It is only set when the error/rejection occurred inside the `dest` function.
+ *
+ * @see
+ * {@link page},
+ * {@link batch}
+ *
+ */
+class PageError extends Error {
+
+    constructor(e, code, cbName, duration) {
+
+        let message;
+        if (e.error instanceof Error) {
+            message = e.error.message;
+        } else {
+            message = e.error;
+            if (typeof message !== 'string') {
+                message = npm.u.inspect(message);
+            }
+        }
+        super(message);
+        this.name = this.constructor.name;
+
+        this.index = e.index;
+        this.duration = duration;
+        this.error = e.error;
+
+        if ('source' in e) {
+            this.source = e.source;
+        }
+
+        if ('dest' in e) {
+            this.dest = e.dest;
+        }
+
+        if (code) {
+            cbName = cbName ? ('\'' + cbName + '\'') : '<anonymous>';
+            this.reason = npm.u.format(errorReasons[code], cbName, e.index);
+        } else {
+            this.reason = npm.u.format(errorReasons[code], e.index);
+        }
+
+        Error.captureStackTrace(this, this.constructor);
+    }
+
+}
+
+/**
+ * @method errors.PageError.toString
+ * @description
+ * Creates a well-formatted multi-line string that represents the error.
+ *
+ * It is called automatically when writing the object into the console.
+ *
+ * @param {number} [level=0]
+ * Nested output level, to provide visual offset.
+ *
+ * @returns {string}
+ */
+PageError.prototype.toString = function (level) {
+
+    level = level > 0 ? parseInt(level) : 0;
+
+    const gap0 = npm.utils.messageGap(level),
+        gap1 = npm.utils.messageGap(level + 1),
+        lines = [
+            'PageError {',
+            gap1 + 'message: ' + JSON.stringify(this.message),
+            gap1 + 'reason: ' + this.reason,
+            gap1 + 'index: ' + this.index,
+            gap1 + 'duration: ' + this.duration
+        ];
+
+    lines.push(gap1 + 'error: ' + npm.utils.formatError(this.error, level + 1));
+    lines.push(gap0 + '}');
+    return lines.join(npm.os.EOL);
+};
+
+npm.utils.addInspection(PageError, function () {
+    return this.toString();
+});
+
+module.exports = {PageError};
+

ProjectSourceCode/node_modules/spex/lib/errors/sequence.js

@@ -0,0 +1,125 @@
+const npm = {
+    u: require('util'),
+    os: require('os'),
+    utils: require('../utils/static')
+};
+
+const errorReasons = {
+    0: 'Source %s returned a rejection at index %d.',
+    1: 'Source %s threw an error at index %d.',
+    2: 'Destination %s returned a rejection at index %d.',
+    3: 'Destination %s threw an error at index %d.'
+};
+
+/**
+ * @class errors.SequenceError
+ * @augments external:Error
+ * @description
+ * This type represents all errors rejected by method {@link sequence}, except for {@link external:TypeError TypeError}
+ * when the method receives invalid input parameters.
+ *
+ * @property {string} name
+ * Standard {@link external:Error Error} property - error type name = `SequenceError`.
+ *
+ * @property {string} message
+ * Standard {@link external:Error Error} property - the error message.
+ *
+ * @property {string} stack
+ * Standard {@link external:Error Error} property - the stack trace.
+ *
+ * @property {} error
+ * The error that was thrown or the rejection reason.
+ *
+ * @property {number} index
+ * Index of the element in the sequence for which the error/rejection occurred.
+ *
+ * @property {number} duration
+ * Duration (in milliseconds) of processing until the error/rejection occurred.
+ *
+ * @property {string} reason
+ * Textual explanation of why the method failed.
+ *
+ * @property {} source
+ * Resolved `data` parameter that was passed into the `source` function.
+ *
+ * It is only set when the error/rejection occurred inside the `source` function.
+ *
+ * @property {} dest
+ * Resolved `data` parameter that was passed into the `dest` function.
+ *
+ * It is only set when the error/rejection occurred inside the `dest` function.
+ *
+ * @see {@link sequence}
+ *
+ */
+class SequenceError extends Error {
+
+    constructor(e, code, cbName, duration) {
+
+        let message;
+        if (e.error instanceof Error) {
+            message = e.error.message;
+        } else {
+            message = e.error;
+            if (typeof message !== 'string') {
+                message = npm.u.inspect(message);
+            }
+        }
+
+        super(message);
+        this.name = this.constructor.name;
+
+        this.index = e.index;
+        this.duration = duration;
+        this.error = e.error;
+
+        if ('source' in e) {
+            this.source = e.source;
+        } else {
+            this.dest = e.dest;
+        }
+
+        cbName = cbName ? ('\'' + cbName + '\'') : '<anonymous>';
+        this.reason = npm.u.format(errorReasons[code], cbName, e.index);
+
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+/**
+ * @method errors.SequenceError.toString
+ * @description
+ * Creates a well-formatted multi-line string that represents the error.
+ *
+ * It is called automatically when writing the object into the console.
+ *
+ * @param {number} [level=0]
+ * Nested output level, to provide visual offset.
+ *
+ * @returns {string}
+ */
+SequenceError.prototype.toString = function (level) {
+
+    level = level > 0 ? parseInt(level) : 0;
+
+    const gap0 = npm.utils.messageGap(level),
+        gap1 = npm.utils.messageGap(level + 1),
+        lines = [
+            'SequenceError {',
+            gap1 + 'message: ' + JSON.stringify(this.message),
+            gap1 + 'reason: ' + this.reason,
+            gap1 + 'index: ' + this.index,
+            gap1 + 'duration: ' + this.duration
+        ];
+
+    lines.push(gap1 + 'error: ' + npm.utils.formatError(this.error, level + 1));
+    lines.push(gap0 + '}');
+    return lines.join(npm.os.EOL);
+};
+
+npm.utils.addInspection(SequenceError, function () {
+    return this.toString();
+});
+
+module.exports = {SequenceError};
+