arekinath

bahamat

chudley

dbuell

kusor

melloc

michael.hicks

tchameroy

todd.whiteman

wyatt

trentm

jclulow

kellymclaughlin

verror

* #47 could use VError.hasCauseWithName()

* #39 captureStackTrace lost when inheriting from WError

* #10 better support for extra properties on Errors

* #11 make it easy to find causes of a particular kind

* #29 No documentation on how to Install this package

* #36 elide development-only files from npm package

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

var mod_extsprintf = require('extsprintf');

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

/* So you can 'var VError = require('verror')' */

 * 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

 *    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

 *    shortmessage      result of sprintf(sprintf_args), taking options.strict

 *    			into account as described in README.md.

	var argv, options, sprintf_args, shortmessage, k;

	mod_assertplus.bool(args.strict, 'args.strict');

	mod_assertplus.array(args.argv, 'args.argv');

	 * First, figure out which form of invocation we've been given.

	} else if (typeof (argv[0]) === 'object') {

		    'first argument to VError, SError, or WError ' +

		    'constructor must be a string, object, or Error');

	 * 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

	 * However, sometimes the bug is only in the code calling VError, and a

	mod_assertplus.ok(mod_isError(err), 'err must be an Error');

	mod_assertplus.ok(name.length > 0, 'name cannot be empty');

	for (cause = err; cause !== null; cause = VError.cause(cause)) {

VError.hasCauseWithName = function (err, name)

	return (VError.findCauseByName(err, name) !== null);

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

 * SError is like VError, but stricter about types.  You cannot pass "null" or

 * "undefined" as string arguments to the formatter.

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

	VError.call(this, options, '%s', parsed.shortmessage);

 * We don't bother setting SError.prototype.name because once constructed,

 * 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.

	mod_assertplus.array(errors, 'list of errors');

	mod_assertplus.ok(errors.length > 0, 'must be at least one error');

	}, 'first of %d error%s', errors.length, errors.length == 1 ? '' : 's');

MultiError.prototype.name = 'MultiError';

MultiError.prototype.errors = function me_errors()

	"description": "richer JavaScript errors",

		"url": "git://github.com/davepacheco/node-verror.git"

This module provides several classes in support of Joyent's [Best Practices for

Error Handling in Node.js](http://www.joyent.com/developers/node/design/errors).

If you find any of the behavior here confusing or surprising, check out that

* properties to provide extra information about the error

* creating your own subclasses that support all of these

* **VError**, for chaining errors while preserving each one's error message.

  This is useful in servers and command-line utilities when you want to

  propagate an error up a call stack, but allow various levels to add their own

* **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

* **SError**, which is just like VError but interprets printf-style arguments

* **MultiError**, which is just an Error that encapsulates one or more other

  errors.  (This is used for parallel operations that return several errors.)

If nothing else, you can use VError as a drop-in replacement for the built-in

JavaScript Error class, with the addition of printf-style messages:

var err = new VError('missing file: "%s"', '/etc/passwd');

You can also pass a `cause` argument, which is any other Error object:

	var err2 = new VError(err1, 'stat "%s"', filename);

    stat "/nonexistent": ENOENT, stat '/nonexistent'

which resembles how Unix programs typically report errors:

    sort: open failed: /nonexistent: No such file or directory

To match the Unixy feel, when you print out the error, just prepend the

program's name to the VError's `message`.  Or just call

[node-cmdutil.fail(your_verror)](https://github.com/joyent/node-cmdutil), which

You can get the next-level Error using `err.cause()`:

Of course, you can chain these as many times as you want, and it works with any

var err1 = new Error('No such file or directory');

var err2 = new VError(err1, 'failed to stat "%s"', '/junk');

var err3 = new VError(err2, 'request failed');

    request failed: failed to stat "/junk": No such file or directory

The idea is that each layer in the stack annotates the error with a description

of what it was doing.  The end result is a message that explains what happened

  rather than checking the `name` field directly.

* If the caller logs this error, the logs can be analyzed to aggregate 

  errors by cause, by RPC method name, by user, or whatever.  Or the

  error can be correlated with other events for the same rpcMsgid.

* It wasn't very hard for any part of the code to contribute to this Error.

  Each part of the stack has just a few lines to provide exactly what it knows,

It's not expected that you'd use these complex forms all the time.  Despite

supporting the complex case above, you can still just do:

   new VError("my service isn't working");

VError, WError, and SError are convenient drop-in replacements for `Error` that

support printf-style arguments, first-class causes, informational properties,

The VError constructor has several forms:

 * This is the most general form.  You can specify any supported options

 * (including "cause" and "info") this way.

 * This is a useful shorthand when the only option you need is "cause".

 * This is a useful shorthand when you don't need any options at all.

All of these forms construct a new VError that behaves just like the built-in

JavaScript `Error` class, with some additional methods described below.

In the first form, `options` is a plain object with any of the following

Option name      | Type             | Meaning

---------------- | ---------------- | -------

`name`           | string           | Describes what kind of error this is.  This is intended for programmatic use to distinguish between different kinds of errors.  Note that in modern versions of Node.js, this name is ignored in the `stack` property value, but callers can still use the `name` property to get at it.

`cause`          | any Error object | Indicates that the new error was caused by `cause`.  See `cause()` below.  If unspecified, the cause will be `null`.

`strict`         | boolean          | If true, then `null` and `undefined` values in `sprintf_args` are passed through to `sprintf()`.  Otherwise, these are replaced with the strings `'null'`, and '`undefined`', respectively.

`constructorOpt` | function         | If specified, then the stack trace for this error ends at function `constructorOpt`.  Functions called by `constructorOpt` will not show up in the stack.  This is useful when this class is subclassed.

`info`           | object           | Specifies arbitrary informational properties that are available through the `VError.info(err)` static class method.  See that method for details.

The second form is equivalent to using the first form with the specified `cause`

as the error's cause.  This form is distinguished from the first form because

The third form is equivalent to using the first form with all default option

values.  This form is distinguished from the other forms because the first

The `WError` constructor is used exactly the same way as the `VError`

constructor.  The `SError` constructor is also used the same way as the

`VError` constructor except that in all cases, the `strict` property is

`VError`, `WError`, and `SError` all provide the same public properties as

`name`        | string | Programmatically-usable name of the error.

`message`     | string | Human-readable summary of the failure.  Programmatically-accessible details are provided through `VError.info(err)` class method.

`stack`       | string | Human-readable stack trace where the Error was constructed.

For all of these classes, 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.

The following methods are defined on the `VError` class and as exported

functions on the `verror` module.  They're defined this way rather than using

methods on VError instances so that they can be used on Errors not created with

The `findCauseByName()` function traverses the cause chain for `err`, looking

for an error whose `name` property matches the passed in `name` value. If no

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`

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

The "Demo" section above covers several basic cases.  Here's a more advanced

var err1 = new VError('something bad happened');

}, 'failed to connect to "%s:%d"', '127.0.0.1', 215);

    failed to connect to "127.0.0.1:215": something bad happened

    { errno: 'ECONNREFUSED', remote_ip: '127.0.0.1', port: 215 }

    ConnectionError: failed to connect to "127.0.0.1:215": something bad happened

        at Object.<anonymous> (/home/dap/node-verror/examples/info.js:5:12)

        at Module._compile (module.js:456:26)

        at Object.Module._extensions..js (module.js:474:10)

        at Module.load (module.js:356:32)

        at Function.Module._load (module.js:312:12)

        at Function.Module.runMain (module.js:497:10)

Information properties are inherited up the cause chain, with values at the top

of the chain overriding same-named values lower in the chain.  To continue that

    request failed: failed to connect to "127.0.0.1:215": something bad happened

    { errno: 'EBADREQUEST', remote_ip: '127.0.0.1', port: 215 }

    RequestError: request failed: failed to connect to "127.0.0.1:215": something bad happened

        at Object.<anonymous> (/home/dap/node-verror/examples/info.js:20:12)

You can also print the complete stack trace of combined `Error`s by using

var err2 = new VError(err1, 'something really bad happened here');

    VError: something really bad happened here: something bad happened

        at Object.<anonymous> (/home/dap/node-verror/examples/fullStack.js:5:12)

        at Module._compile (module.js:409:26)

        at Object.Module._extensions..js (module.js:416:10)

        at Module.load (module.js:343:32)

        at Function.Module._load (module.js:300:12)

        at Function.Module.runMain (module.js:441:10)

    caused by: VError: something bad happened

        at Object.<anonymous> (/home/dap/node-verror/examples/fullStack.js:3:12)

		@@ -7,2 +7,6 @@ # Changelog

		## v1.9.0

		* #47 could use VError.hasCauseWithName()

		## v1.8.1
		@@ -9,0 +13,0 @@

		@@ -278,3 +278,3 @@ /*
		mod_assertplus.ok(mod_isError(err), 'err must be an Error');
		mod_assertplus.string(name);
		mod_assertplus.string(name, 'name');
		mod_assertplus.ok(name.length > 0, 'name cannot be empty');
		@@ -292,2 +292,7 @@

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

		VError.fullStack = function (err)
		@@ -294,0 +299,0 @@ {

		{
		"name": "verror",
		"version": "1.8.1",
		"version": "1.9.0",
		"description": "richer JavaScript errors",
		@@ -5,0 +5,0 @@ "main": "./lib/verror.js",

Improved metrics

Worsened metrics

		@@ -195,3 +195,3 @@ # verror: rich JavaScript errors
		rather than checking the `name` field directly.
		* If the caller logs this error, the logs can be analyzed to aggregate
		* If the caller logs this error, the logs can be analyzed to aggregate
		errors by cause, by RPC method name, by user, or whatever. Or the
		@@ -323,3 +323,22 @@ error can be correlated with other events for the same rpcMsgid.

		### `VError.findCauseByName(err, name)`

		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`.

		### `VError.hasCauseWithName(err, name)`

		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`.


		## Examples
		@@ -397,3 +416,3 @@
		at node.js:935:3


		You can also print the complete stack trace of combined `Error`s by using
		@@ -400,0 +419,0 @@ `VError.fullStack(err).`