What is verror?
The verror npm package provides utilities for constructing and formatting errors in Node.js applications. It allows for richer error information, chaining of errors, and better error handling mechanisms. This package is particularly useful for applications that require detailed error tracking and reporting.
What are verror's main functionalities?
Creating rich errors
This feature allows developers to create errors that can encapsulate more information than standard Error objects. It is useful for debugging and error tracking.
const VError = require('verror');
const err = new VError('This is a rich error with a cause.');
Chaining errors
Chaining errors enables developers to trace through a sequence of errors that led to a failure, making it easier to understand the context and root cause of an issue.
const VError = require('verror');
const cause = new Error('cause');
const err = new VError(cause, 'A higher-level error.');
Formatting error messages
This feature allows for the inclusion of additional information within error objects and provides a structured way to access this information. It's particularly useful for logging and reporting errors with specific codes or data.
const VError = require('verror');
const err = new VError({
name: 'MyError',
info: { errorCode: 'E123' }
}, 'An error occurred.');
const info = VError.info(err);
console.log(info.errorCode); // Outputs: E123
Other packages similar to verror
winston
Winston is a multi-transport async logging library for Node.js. While primarily focused on logging rather than error handling, it shares the goal of providing rich information for debugging purposes. Unlike verror, winston is more about logging levels and transports rather than constructing and chaining errors.
pino
Pino is a very low overhead Node.js logger, which, like winston, focuses on logging rather than error handling. It provides mechanisms for structured logging and performance. Pino and verror serve different aspects of application diagnostics; pino does not offer features for error object enhancement or chaining.
verror: richer JavaScript errors
This module provides two classes: VError, for accretive errors, and WError, for
wrapping errors. Both support printf-style error messages using extsprintf.
Printf-style errors
At the most basic level, VError is just like JavaScript's Error class, but with
printf-style arguments:
var verror = require('verror');
var opname = 'read';
var err = new verror.VError('"%s" operation failed', opname);
console.log(err.message);
console.log(err.stack);
This prints:
"read" operation failed
"read" operation failed
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)
VError for accretive error messages
More interestingly, you can use VError to build up an error describing what
happened at various levels in the stack. For example, suppose you have a
request handler that stats a file and fails if it doesn't exist:
var fs = require('fs');
var verror = require('verror');
function checkFile(filename, callback) {
fs.stat(filename, function (err) {
if (err)
/* Annotate the "stat" error with what we were doing. */
return (callback(new verror.VError(err,
'failed to check "%s"', filename)));
/* ... */
});
}
function handleRequest(filename, callback) {
checkFile('/nonexistent', function (err) {
if (err) {
/* Annotate the "checkFile" error with what we were doing. */
return (callback(new verror.VError(err, 'request failed')));
}
/* ... */
});
}
handleRequest('/nonexistent', function (err) {
if (err)
console.log(err.message);
/* ... */
});
Since the file "/nonexistent" doesn't exist, this prints out:
request failed: failed to check "/nonexistent": ENOENT, stat '/nonexistent'
The idea here is that the lowest level (Node's "fs.stat" function) generates an
arbitrary error, and each higher level (request handler and stat callback)
creates a new VError that annotates the previous error with what it was doing,
so that the result is a clear message explaining what failed at each level.
This plays nicely with extsprintf's "%r" specifier, which prints out a
Java-style stacktrace with the whole chain of exceptions:
EXCEPTION: VError: request failed: failed to check "/nonexistent": ENOENT, stat '/nonexistent'
at /Users/dap/work/node-verror/examples/levels.js:21:21
at /Users/dap/work/node-verror/examples/levels.js:9:12
at Object.oncomplete (fs.js:297:15)
Caused by: EXCEPTION: VError: failed to check "/nonexistent": ENOENT, stat '/nonexistent'
at /Users/dap/work/node-verror/examples/levels.js:9:21
at Object.oncomplete (fs.js:297:15)
Caused by: EXCEPTION: Error: Error: ENOENT, stat '/nonexistent'
WError for wrapped errors
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,
but replacing the VError in handleRequest with WError, we get this output:
request failed
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 check "/nonexistent";
caused by Error: ENOENT, stat '/nonexistent'
Contributing
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.