source: trip-planner-front/node_modules/verror/lib/verror.js@ 188ee53

/*
 * verror.js: richer JavaScript errors
 */

var mod_assertplus = require('assert-plus');
var mod_util = require('util');

var mod_extsprintf = require('extsprintf');
var mod_isError = require('core-util-is').isError;
var sprintf = mod_extsprintf.sprintf;

/*
 * Public interface
 */

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

/*
 * 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)
 *
 * This function normalizes these forms, producing an object with the following
 * properties:
 *
 *    options           equivalent 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.
 *
 *    shortmessage      result of sprintf(sprintf_args), taking options.strict
 *                      into account as described in README.md.
 */
function parseConstructorArguments(args)
{
        var argv, options, sprintf_args, shortmessage, k;

        mod_assertplus.object(args, 'args');
        mod_assertplus.bool(args.strict, 'args.strict');
        mod_assertplus.array(args.argv, 'args.argv');
        argv = args.argv;

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

        /*
         * 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.
         */
        mod_assertplus.object(options);
        if (!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 {
                shortmessage = sprintf.apply(null, sprintf_args);
        }

        return ({
            'options': options,
            'shortmessage': shortmessage
        });
}

/*
 * See README.md for reference documentation.
 */
function VError()
{
        var args, obj, parsed, cause, ctor, message, k;

        args = Array.prototype.slice.call(arguments, 0);

        /*
         * 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.
         */
        parsed = parseConstructorArguments({
            'argv': args,
            'strict': false
        });

        /*
         * If we've been given a name, apply it now.
         */
        if (parsed.options.name) {
                mod_assertplus.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.
         */
        cause = parsed.options.cause;
        if (cause) {
                mod_assertplus.ok(mod_isError(cause), 'cause is not 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) {
                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);
}

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

VError.prototype.toString = function ve_toString()
{
        var 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.
 */
VError.prototype.cause = function ve_cause()
{
        var 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.
 */

VError.cause = function (err)
{
        mod_assertplus.ok(mod_isError(err), 'err must be an Error');
        return (mod_isError(err.jse_cause) ? err.jse_cause : null);
};

VError.info = function (err)
{
        var rv, cause, k;

        mod_assertplus.ok(mod_isError(err), 'err must be an Error');
        cause = VError.cause(err);
        if (cause !== null) {
                rv = VError.info(cause);
        } else {
                rv = {};
        }

        if (typeof (err.jse_info) == 'object' && err.jse_info !== null) {
                for (k in err.jse_info) {
                        rv[k] = err.jse_info[k];
                }
        }

        return (rv);
};

VError.findCauseByName = function (err, name)
{
        var cause;

        mod_assertplus.ok(mod_isError(err), 'err must be an Error');
        mod_assertplus.string(name, 'name');
        mod_assertplus.ok(name.length > 0, 'name cannot be empty');

        for (cause = err; cause !== null; cause = VError.cause(cause)) {
                mod_assertplus.ok(mod_isError(cause));
                if (cause.name == name) {
                        return (cause);
                }
        }

        return (null);
};

VError.hasCauseWithName = function (err, name)
{
        return (VError.findCauseByName(err, name) !== null);
};

VError.fullStack = function (err)
{
        mod_assertplus.ok(mod_isError(err), 'err must be an Error');

        var cause = VError.cause(err);

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

        return (err.stack);
};

VError.errorFromList = function (errors)
{
        mod_assertplus.arrayOfObject(errors, 'errors');

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

        errors.forEach(function (e) {
                mod_assertplus.ok(mod_isError(e));
        });

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

        return (new MultiError(errors));
};

VError.errorForEach = function (err, func)
{
        mod_assertplus.ok(mod_isError(err), 'err must be an Error');
        mod_assertplus.func(func, 'func');

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


/*
 * SError is like VError, but stricter about types.  You cannot pass "null" or
 * "undefined" as string arguments to the formatter.
 */
function SError()
{
        var args, obj, parsed, options;

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

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

        options = parsed.options;
        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.
 */
mod_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.
 */
function MultiError(errors)
{
        mod_assertplus.array(errors, 'list of errors');
        mod_assertplus.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');
}

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

MultiError.prototype.errors = function me_errors()
{
        return (this.ase_errors.slice(0));
};


/*
 * See README.md for reference details.
 */
function WError()
{
        var args, obj, parsed, options;

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

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

        options = parsed.options;
        options['skipCauseMessage'] = true;
        VError.call(this, options, '%s', parsed.shortmessage);

        return (this);
}

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

WError.prototype.toString = function we_toString()
{
        var 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.
 */
WError.prototype.cause = function we_cause(c)
{
        if (mod_isError(c))
                this.jse_cause = c;

        return (this.jse_cause);
};