This module provides two classes:
Both support printf-style error messages using extsprintf.
var VError = ;var filename = '/etc/passwd';var err = 'missing file: "%s"' filename;console;
missing file: "/etc/passwd"
err.stack works the same as for built-in errors:
missing file: "/etc/passwd" at Object.<anonymous> (/Users/dap/node-verror/examples/varargs.js:4:11) at Module._compile (module.js:449:26) at Object.Module._extensions..js (module.js:467:10) at Module.load (module.js:356:32) at Function.Module._load (module.js:312:12) at Module.runMain (module.js:492:10) at process.startup.processNextTick.process._tickCallback (node.js:244:9)
You can also pass a
cause argument, which is another Error. For example:
var fs = ;var VError = ;var filename = '/nonexistent';fs;
This prints out:
stat "/nonexistent" failed: ENOENT, stat '/nonexistent'
which resembles how Unix programs typically report errors:
$ sort /nonexistent sort: open failed: /nonexistent: No such file or directory
To match the Unixy feel, just prepend the program's name to the VError's
You can also get the next-level Error using
ENOENT, stat '/nonexistent'
Of course, you can nest these as many times as you want:
var VError = ;var err1 = 'No such file or directory';var err2 = err1 'failed to stat "%s"' '/junk';var err3 = err2 'request failed';console;
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 (with a printf-like format string) and the result is a message that explains what happened at every level.
Sometimes you don't want an Error's "message" field to include the details of
all of the low-level errors, but you still want to be able to get at them
programmatically. For example, in an HTTP server, you probably don't want to
spew all of the low-level errors back to the client, but you do want to include
them in the audit log entry for the request. In that case, you can use a
WError, which is created exactly like VError (and also supports both
printf-style arguments and an optional cause), but the resulting "message" only
contains the top-level error. It's also more verbose, including the class
associated with each error in the cause chain. Using the same example above,
err3's VError with WError, so that it looks like this:
var verror = ;var err1 = 'No such file or directory';var err2 = err1 'failed to stat "%s"' '/junk';var err3 = err2 'request failed';console;
we get this output:
That's what we wanted -- just a high-level summary for the client. But we can get the object's toString() for the full details:
WError: request failed; caused by WError: failed to stat "/nonexistent"; caused by Error: No such file or directory
For a complete example, see examples/werror.js.
Contributions welcome. Code should be "make check" clean. To run "make check", you'll need these tools:
If you're changing something non-trivial or user-facing, you may want to submit an issue first.