@netflix/nerror/lib/verror.js

Rich errors

'use strict';

/*
 * verror.js: richer JavaScript errors
 */
const util = require('util');

const _ = require('lodash');
const assert = require('assert-plus');
const { sprintf } = require('extsprintf');

/*
 * Public interface
 */

/* So you can 'var VError = require('@netflix/nerror')' */
module.exports = VError;
/* For compatibility */
VError.VError = VError;
/* Other exported classes */
VError.PError = PError;
VError.SError = SError;
VError.WError = WError;
VError.MultiError = MultiError;

/**
 * Normalized forms, producing an object with the following properties.
 * @private
 * @typedef {Object} ParsedOptions parsed Options
 * @param {Object} options e- quivalent to "options" in third form. This will
 *              never
 *    			be a direct reference to what the caller passed in
 *    			(i.e., it may be a shallow copy), so it can be freely
 *    			modified.
 * @param {String} shortmessage - result of sprintf(sprintf_args), taking
 *              `options.strict` into account as described in README.md.
 */

/**
 * Common function used to parse constructor arguments for VError, WError, and
 * SError.  Named arguments to this function:
 *
 *     strict		force strict interpretation of sprintf arguments, even
 *     			if the options in "argv" don't say so
 *
 *     argv		error's constructor arguments, which are to be
 *     			interpreted as described in README.md.  For quick
 *     			reference, "argv" has one of the following forms:
 *
 *          [ sprintf_args... ]           (argv[0] is a string)
 *          [ cause, sprintf_args... ]    (argv[0] is an Error)
 *          [ options, sprintf_args... ]  (argv[0] is an object)
 *

 * @private
 * @param {Array} args - arguments
 * @returns {ParsedOptions} parsed options
 */
function parseConstructorArguments(args) {
    let options, sprintf_args, shortmessage, k;

    assert.object(args, 'args');
    assert.bool(args.strict, 'args.strict');
    assert.array(args.argv, 'args.argv');
    assert.optionalBool(args.skipPrintf, 'args.skipPrintf');
    const argv = args.argv;

    /*
     * First, figure out which form of invocation we've been given.
     */
    if (argv.length === 0) {
        options = {};
        sprintf_args = [];
    } else if (_.isError(argv[0])) {
        options = { cause: argv[0] };
        sprintf_args = argv.slice(1);
    } else if (typeof argv[0] === 'object') {
        options = {};
        // eslint-disable-next-line guard-for-in
        for (k in argv[0]) {
            options[k] = argv[0][k];
        }
        sprintf_args = argv.slice(1);
    } else {
        assert.string(
            argv[0],
            'first argument to VError, PError, SError, or WError ' +
                'constructor must be a string, object, or Error'
        );
        options = {};
        sprintf_args = argv;
    }

    // Preserve options
    if (args.skipPrintf) {
        options.skipPrintf = args.skipPrintf;
    }
    if (args.strict) {
        options.strict = args.strict;
    }

    /*
     * Now construct the error's message.
     *
     * extsprintf (which we invoke here with our caller's arguments in order
     * to construct this Error's message) is strict in its interpretation of
     * values to be processed by the "%s" specifier.  The value passed to
     * extsprintf must actually be a string or something convertible to a
     * String using .toString().  Passing other values (notably "null" and
     * "undefined") is considered a programmer error.  The assumption is
     * that if you actually want to print the string "null" or "undefined",
     * then that's easy to do that when you're calling extsprintf; on the
     * other hand, if you did NOT want that (i.e., there's actually a bug
     * where the program assumes some variable is non-null and tries to
     * print it, which might happen when constructing a packet or file in
     * some specific format), then it's better to stop immediately than
     * produce bogus output.
     *
     * However, sometimes the bug is only in the code calling VError, and a
     * programmer might prefer to have the error message contain "null" or
     * "undefined" rather than have the bug in the error path crash the
     * program (making the first bug harder to identify).  For that reason,
     * by default VError converts "null" or "undefined" arguments to their
     * string representations and passes those to extsprintf.  Programmers
     * desiring the strict behavior can use the SError class or pass the
     * "strict" option to the VError constructor.
     */
    assert.object(options);
    if (!options.skipPrintf && !options.strict && !args.strict) {
        sprintf_args = sprintf_args.map(function(a) {
            return a === null ? 'null' : a === undefined ? 'undefined' : a;
        });
    }

    if (sprintf_args.length === 0) {
        shortmessage = '';
    } else if (
        options.skipPrintf ||
        (sprintf_args.length === 1 && typeof sprintf_args[0] === 'string')
    ) {
        assert.equal(
            sprintf_args.length,
            1,
            'only one argument is allowed with options.skipPrintf'
        );
        shortmessage = sprintf_args[0];
    } else {
        shortmessage = sprintf.apply(null, sprintf_args);
    }

    return {
        options: options,
        shortmessage: shortmessage
    };
}

/**
 * @public
 * @typedef {Object} VErrorOptions Options
 * @param {String} name - Name of the error.
 * @param {Error} [cause] -  Indicates that the new error was caused by `cause`.
 * @param {Boolean} [strict=false] - If true, then `null` and `undefined` values
 *  in `sprintf_args` are passed through to `sprintf()`
 * @param {Function} [constructorOpt] -If specified, then the stack trace for
 *  this error ends at function `constructorOpt`.
 * @param {Object} [info]- Specifies arbitrary informational properties.
 * @param {Boolean} [skipPrintf=false] - If true, then `sprintf()` is not called
 */

/**
 *
 * About Constructor:
 * All of these forms construct a new VError that behaves just like the built-in
 * JavaScript `Error` class, with some additional methods described below.
 *
 * About Properties:
 * For all of these classes except `PError`, the printf-style arguments passed to
 * the constructor are processed with `sprintf()` to form a message.
 * For `WError`, this becomes the complete `message` property.  For `SError` and
 * `VError`, this message is prepended to the message of the cause, if any
 * (with a suitable separator), and the result becomes the `message` property.
 *
 * The `stack` property is managed entirely by the underlying JavaScript
 * implementation.  It's generally implemented using a getter function because
 * constructing the human-readable stack trace is somewhat expensive.
 *
 * @public
 * @class VError
 * @param {...String|VErrorOptions|Error} [arg] - sprintf args, options or cause
 * @param {...String} [args] - sprintf args
 * @property {String} name - Programmatically-usable name of the error.
 * @property {String} message - Human-readable summary of the failure.
 * Programmatically-accessible details are provided through `VError.info(err)`
 * class method.
 * @property {String} stack - Human-readable stack trace where the Error was
 * constructed.
 * @example
 * // This is the most general form.  You can specify any supported options
 * // including "cause" and "info") this way.</caption>
 * new VError(options, sprintf_args...)
 * @example
 * // This is a useful shorthand when the only option you need is "cause".
 * new VError(cause, sprintf_args...)
 * @example
 * // This is a useful shorthand when you don't need any options at all.
 * new VError(sprintf_args...)
 */
function VError(...args) {
    let obj, ctor, message, k;

    /*
     * This is a regrettable pattern, but JavaScript's built-in Error class
     * is defined to work this way, so we allow the constructor to be called
     * without "new".
     */
    if (!(this instanceof VError)) {
        obj = Object.create(VError.prototype);
        VError.apply(obj, arguments);
        return obj;
    }

    /*
     * For convenience and backwards compatibility, we support several
     * different calling forms.  Normalize them here.
     */
    const parsed = parseConstructorArguments({
        argv: args,
        strict: false
    });

    /*
     * If we've been given a name, apply it now.
     */
    if (parsed.options.name) {
        assert.string(parsed.options.name, 'error\'s "name" must be a string');
        this.name = parsed.options.name;
    }

    /*
     * For debugging, we keep track of the original short message (attached
     * this Error particularly) separately from the complete message (which
     * includes the messages of our cause chain).
     */
    this.jse_shortmsg = parsed.shortmessage;
    message = parsed.shortmessage;

    /*
     * If we've been given a cause, record a reference to it and update our
     * message appropriately.
     */
    const cause = parsed.options.cause;
    if (cause) {
        VError._assertError(cause, '"cause" must be an Error');
        this.jse_cause = cause;

        if (!parsed.options.skipCauseMessage) {
            message += ': ' + cause.message;
        }
    }

    /*
     * If we've been given an object with properties, shallow-copy that
     * here.  We don't want to use a deep copy in case there are non-plain
     * objects here, but we don't want to use the original object in case
     * the caller modifies it later.
     */
    this.jse_info = {};
    if (parsed.options.info) {
        // eslint-disable-next-line guard-for-in
        for (k in parsed.options.info) {
            this.jse_info[k] = parsed.options.info[k];
        }
    }

    this.message = message;
    Error.call(this, message);

    if (Error.captureStackTrace) {
        ctor = parsed.options.constructorOpt || this.constructor;
        Error.captureStackTrace(this, ctor);
    }

    return this;
}

util.inherits(VError, Error);
VError.prototype.name = 'VError';

/**
 * Appends any keys/fields to the existing jse_info. this can stomp over any
 * existing fields.
 * @public
 * @memberof VError.prototype
 * @param {Object} obj source obj to assign fields from
 * @return {Object} new info object
 */
VError.prototype.assignInfo = function ve_assignInfo(obj) {
    assert.optionalObject(obj, 'obj');
    return Object.assign(this.jse_info, obj);
};

/**
 * Instance level convenience method vs using the static methods on VError.
 * @public
 * @memberof VError.prototype
 * @return {Object} info object
 */
VError.prototype.info = function ve_info() {
    return VError.info(this);
};

/**
 * A string representing the VError.
 * @public
 * @memberof VError.prototype
 * @return {String} string representation
 */
VError.prototype.toString = function ve_toString() {
    let str =
        (this.hasOwnProperty('name') && this.name) ||
        this.constructor.name ||
        this.constructor.prototype.name;
    if (this.message) {
        str += ': ' + this.message;
    }

    return str;
};

/**
 * This method is provided for compatibility.  New callers should use
 * VError.cause() instead.  That method also uses the saner `null` return value
 * when there is no cause.
 * @public
 * @memberof VError.prototype
 * @return {undefined|Error} Error cause if any
 */
VError.prototype.cause = function ve_cause() {
    const cause = VError.cause(this);
    return cause === null ? undefined : cause;
};

/*
 * Static methods
 *
 * These class-level methods are provided so that callers can use them on
 * instances of Errors that are not VErrors.  New interfaces should be provided
 * only using static methods to eliminate the class of programming mistake where
 * people fail to check whether the Error object has the corresponding methods.
 */

/**
 * @private
 * @static
 * @memberof VError
 * @param {Error} err - error to assert
 * @param {String} [msg] - optional message
 * @returns {undefined} no return value
 * @throws AssertationError - when input is not an error
 */
VError._assertError = function _assertError(err, msg) {
    assert.optionalString(msg, 'msg');
    const _msg = (msg || 'err must be an Error') + ` but got ${String(err)}`;
    assert.ok(_.isError(err), _msg);
};

/**
 * Checks if an error is a VError or VError sub-class.
 *
 * @public
 * @static
 * @memberof VError
 * @param {Error} err - error
 * @return {Boolean} is a VError or VError sub-class
 */
VError.isVError = function assignInfo(err) {
    // We are checking on internals here instead of using
    // `err instanceof VError` to being compatible with the original VError lib.
    return err && err.hasOwnProperty('jse_info');
};

/**
 * Appends any keys/fields to the `jse_info`. This can stomp over any existing
 * fields.
 *
 * Note: This method is static because in this way we don't need to check on
 * VError versions to be sure `assignInfo` method is supported.
 *
 * @public
 * @static
 * @memberof VError
 * @param {Error} err - error
 * @param {Object} obj - source obj to assign fields from
 * @return {Object} new info object
 */
VError.assignInfo = function assignInfo(err, obj) {
    VError._assertError(err);
    assert.optionalObject(obj, 'obj');

    if (!VError.isVError(err)) {
        throw new TypeError('err must be an instance of VError');
    }

    return Object.assign(err.jse_info, obj);
};

/**
 * Returns the next Error in the cause chain for `err`, or `null` if there is no
 * next error.  See the `cause` argument to the constructor.
 * Errors can have arbitrarily long cause chains.  You can walk the `cause`
 * chain by invoking `VError.cause(err)` on each subsequent return value.
 * If `err` is not a `VError`, the cause is `null`.
 *
 * @public
 * @static
 * @memberof VError
 * @param {VError} err - error
 * @return {undefined|Error} Error cause if any
 */
VError.cause = function cause(err) {
    VError._assertError(err);
    return _.isError(err.jse_cause) ? err.jse_cause : null;
};

/**
 * Returns an object with all of the extra error information that's been
 * associated with this Error and all of its causes. These are the properties
 * passed in using the `info` option to the constructor. Properties not
 * specified in the constructor for this Error are implicitly inherited from
 * this error's cause.
 *
 * These properties are intended to provide programmatically-accessible metadata
 * about the error.  For an error that indicates a failure to resolve a DNS
 * name, informational properties might include the DNS name to be resolved, or
 * even the list of resolvers used to resolve it.  The values of these
 * properties should generally be plain objects (i.e., consisting only of null,
 * undefined, numbers, booleans, strings, and objects and arrays containing only
 * other plain objects).
 *
 * @public
 * @static
 * @memberof VError
 * @param {VError} err - error
 * @return {Object} info object
 */
VError.info = function info(err) {
    let rv, k;

    VError._assertError(err);
    const cause = VError.cause(err);
    if (cause !== null) {
        rv = VError.info(cause);
    } else {
        rv = {};
    }

    if (typeof err.jse_info === 'object' && err.jse_info !== null) {
        // eslint-disable-next-line guard-for-in
        for (k in err.jse_info) {
            rv[k] = err.jse_info[k];
        }
    }

    return rv;
};

/**
 * The `findCauseByName()` function traverses the cause chain for `err`, looking
 * for an error whose `name` property matches the passed in `name` value. If no
 * match is found, `null` is returned.
 *
 * If all you want is to know _whether_ there's a cause (and you don't care what
 * it is), you can use `VError.hasCauseWithName(err, name)`.
 *
 * If a vanilla error or a non-VError error is passed in, then there is no cause
 * chain to traverse. In this scenario, the function will check the `name`
 * property of only `err`.
 *
 * @public
 * @static
 * @memberof VError
 * @param {VError} err - error
 * @param {String} name - name of cause Error
 * @return {null|Error} cause if any
 */
VError.findCauseByName = function findCauseByName(err, name) {
    let cause;

    VError._assertError(err);
    assert.string(name, 'name');
    assert.ok(name.length > 0, 'name cannot be empty');

    for (cause = err; cause !== null; cause = VError.cause(cause)) {
        assert.ok(_.isError(cause));
        if (cause.name === name) {
            return cause;
        }
    }

    return null;
};

/**
 * Returns true if and only if `VError.findCauseByName(err, name)` would return
 * a non-null value.  This essentially determines whether `err` has any cause in
 * its cause chain that has name `name`.
 *
 * @public
 * @static
 * @memberof VError
 * @param {VError} err - error
 * @param {String} name - name of cause Error
 * @return {Boolean} has cause
 */
VError.hasCauseWithName = function hasCauseWithName(err, name) {
    return VError.findCauseByName(err, name) !== null;
};

/**
 * Returns a string containing the full stack trace, with all nested errors
 * recursively reported as `'caused by:' + err.stack`.
 *
 * @public
 * @static
 * @memberof VError
 * @param {VError} err - error
 * @return {String} full stack trace
 */
VError.fullStack = function fullStack(err) {
    VError._assertError(err);

    const cause = VError.cause(err);

    if (cause) {
        return err.stack + '\ncaused by: ' + VError.fullStack(cause);
    }

    return err.stack;
};

/**
 * Given an array of Error objects (possibly empty), return a single error
 * representing the whole collection of errors. If the list has:
 *
 * * 0 elements, returns `null`
 * * 1 element, returns the sole error
 * * more than 1 element, returns a MultiError referencing the whole list
 *
 * This is useful for cases where an operation may produce any number of errors,
 * and you ultimately want to implement the usual `callback(err)` pattern.
 * You can accumulate the errors in an array and then invoke
 * `callback(VError.errorFromList(errors))` when the operation is complete.
 *
 * @public
 * @static
 * @memberof VError
 * @param {Array<Error>} errors - errors
 * @return {null|Error|MultiError} single or multi error if any
 */
VError.errorFromList = function errorFromList(errors) {
    assert.arrayOfObject(errors, 'errors');

    if (errors.length === 0) {
        return null;
    }

    errors.forEach(function(e) {
        assert.ok(_.isError(e), 'all errors must be an Error');
    });

    if (errors.length === 1) {
        return errors[0];
    }

    return new MultiError(errors);
};

/**
 * Convenience function for iterating an error that may itself be a MultiError.
 *
 * In all cases, `err` must be an Error.  If `err` is a MultiError, then `func`
 * is invoked as `func(errorN)` for each of the underlying errors of the
 * MultiError.
 * If `err` is any other kind of error, `func` is invoked once as `func(err)`.
 * In all cases, `func` is invoked synchronously.
 *
 * This is useful for cases where an operation may produce any number of
 * warnings that may be encapsulated with a MultiError -- but may not be.
 *
 * This function does not iterate an error's cause chain.
 *
 * @public
 * @static
 * @memberof VError
 * @param {Error} err - error
 * @param {Function} func - iterator
 * @return {undefined} no return value
 */
VError.errorForEach = function errorForEach(err, func) {
    VError._assertError(err);
    assert.func(func, 'func');

    if (err.name === 'MultiError') {
        err.errors().forEach(function iterError(e) {
            func(e);
        });
    } else {
        func(err);
    }
};

/**
 * PError is like VError, but the message is not run through printf-style
 * templating.
 *
 * @public
 * @class PError
 * @extends VError
 * @param {...String|VErrorOptions|Error} [arg] - sprintf args, options or cause
 * @param {...String} [args] - sprintf args
 */
function PError(...args) {
    let obj;

    if (!(this instanceof PError)) {
        obj = Object.create(PError.prototype);
        PError.apply(obj, args);
        return obj;
    }

    const parsed = parseConstructorArguments({
        argv: args,
        strict: false,
        skipPrintf: true
    });

    VError.call(this, parsed.options, parsed.shortmessage);

    return this;
}

util.inherits(PError, VError);
PError.prototype.name = 'PError';

/**
 * SError is like VError, but stricter about types. You cannot pass "null" or
 * "undefined" as string arguments to the formatter.
 *
 * @public
 * @class SError
 * @extends VError
 * @param {...String|VErrorOptions|Error} [arg] - sprintf args, options or cause
 * @param {...String} [args] - sprintf args
 */
function SError(...args) {
    let obj;

    if (!(this instanceof SError)) {
        obj = Object.create(SError.prototype);
        SError.apply(obj, arguments);
        return obj;
    }

    const parsed = parseConstructorArguments({
        argv: args,
        strict: true
    });

    const options = parsed.options;
    options.skipPrintf = false;
    VError.call(this, options, '%s', parsed.shortmessage);

    return this;
}

/*
 * We don't bother setting SError.prototype.name because once constructed,
 * SErrors are just like VErrors.
 */
util.inherits(SError, VError);

/**
 * Represents a collection of errors for the purpose of consumers that generally
 * only deal with one error.  Callers can extract the individual errors
 * contained in this object, but may also just treat it as a normal single
 * error, in which case a summary message will be printed.
 *
 * @public
 * @class MultiError
 * @extends VError
 * @param {Array<Error>} errors - errors
 * @example
 * // `error_list` is an array of at least one `Error` object.
 * new MultiError(error_list)
 *
 * // The cause of the MultiError is the first error provided.  None of the
 * // other `VError` options are supported.  The `message` for a MultiError
 * // consists the `message` from the first error, prepended with a message
 * // indicating that there were other errors.
 *
 * //For example:
 * err = new MultiError([
 *     new Error('failed to resolve DNS name "abc.example.com"'),
 *     new Error('failed to resolve DNS name "def.example.com"'),
 * ]);
 * console.error(err.message);
 *
 * // outputs:
 * //   first of 2 errors: failed to resolve DNS name "abc.example.com"
 */
function MultiError(errors) {
    assert.array(errors, 'list of errors');
    assert.ok(errors.length > 0, 'must be at least one error');
    this.ase_errors = errors;

    VError.call(
        this,
        {
            cause: errors[0]
        },
        'first of %d error%s',
        errors.length,
        errors.length === 1 ? '' : 's'
    );
}

util.inherits(MultiError, VError);
MultiError.prototype.name = 'MultiError';

/**
 * Returns an array of the errors used to construct this MultiError.
 *
 * @public
 * @memberof MultiError.prototype
 * @returns {Array<Error>} errors
 */
MultiError.prototype.errors = function me_errors() {
    return this.ase_errors.slice(0);
};

/**
 * WError for wrapping errors while hiding the lower-level messages from the
 * top-level error.  This is useful for API endpoints where you don't want to
 * expose internal error messages, but you still want to preserve the error
 * chain for logging and debugging
 *
 * @public
 * @class WError
 * @extends VError
 * @param {...String|VErrorOptions|Error} [arg] - sprintf args, options or cause
 * @param {...String} [args] - sprintf args
 */
function WError(...args) {
    let obj;

    if (!(this instanceof WError)) {
        obj = Object.create(WError.prototype);
        WError.apply(obj, args);
        return obj;
    }

    const parsed = parseConstructorArguments({
        argv: args,
        strict: false
    });

    const options = parsed.options;
    options.skipCauseMessage = true;
    options.skipPrintf = false;
    VError.call(this, options, '%s', parsed.shortmessage);

    return this;
}

util.inherits(WError, VError);
WError.prototype.name = 'WError';

/**
 * A string representing the WError.
 * @public
 * @memberof WError.prototype
 * @return {String} string representation
 */
WError.prototype.toString = function we_toString() {
    let str =
        (this.hasOwnProperty('name') && this.name) ||
        this.constructor.name ||
        this.constructor.prototype.name;
    if (this.message) {
        str += ': ' + this.message;
    }
    if (this.jse_cause && this.jse_cause.message) {
        str += '; caused by ' + this.jse_cause.toString();
    }

    return str;
};

/**
 * For purely historical reasons, WError's cause() function allows you to set
 * the cause.
 * @public
 * @memberof WError.prototype
 * @param {Error} c - cause
 * @return {undefined|Error} Error cause
 */
WError.prototype.cause = function we_cause(c) {
    if (_.isError(c)) {
        this.jse_cause = c;
    }

    return this.jse_cause;
};