JarCastingerror
Wrap errors with more context.
Inspiration
This module is inspired by the go error libraries that have simple functions for creating & wrapping errors.
This is based on libraries like eris & pkg/errors
Older version of error
If you are looking for the older v7 version of error you should check v7.x branch
Using error with async / await
Check out resultify !
The rest of the examples use plain vanilla callbacks.
Motivation
Wrapping errors when bubbling up instead of just doing if (err) return cb(err) allows you to pass more context up the stack.
Common example include passing along parameters from the DB read related to the failure or passing along any context from the user in a HTTP request when doing a failure.
This can give you nice to read messages that include more information about the failure as it bubbles up.
There is more information about how to handle errors in this article Don't just check errors, handle them gracefully
If you want a deep dive into the difference between Programming and Operational errors please check out this guide
examples:
const { wrapf } = require('error')
function authenticatRequest(req) {
authenticate(req.user, (err) => {
if (err) {
return cb(wrapf('authenticate failed', err))
}
cb(null)
})
}
or
const { wrapf } = require('error')
function readFile(path, cb) {
fs.open(path, 'r', (err, fd) => {
if (err) {
return cb(wrapf('open failed', err, { path }))
}
const buf = Buffer.alloc(64 * 1024)
fs.read(fd, buf, 0, buf.length, 0, (err) => {
if (err) {
return cb(wrapf('read failed', err, { path }))
}
fs.close(fd, (err) => {
if (err) {
return cb(wrapf('close failed', err, { path }))
}
cb(null, buf)
})
})
})
}
Structured errors
const { SError } = require('error')
class ServerError extends SError {}
class ClientError extends SError {}
const err = ServerError.create(
'{title} server error, status={statusCode}', {
title: 'some title',
statusCode: 500
}
)
const err2 = ClientError.create(
'{title} client error, status={statusCode}', {
title: 'some title',
statusCode: 404
}
)
Wrapped Errors
const net = require('net');
const { WError } = require('error')
class ServerListenError extends WError {}
var server = net.createServer();
server.on('error', function onError(err) {
if (err.code === 'EADDRINUSE') {
throw ServerListenFailedError.wrap(
'error in server, on port={requestPort}', err, {
requestPort: 3000,
host: null
}
)
} else {
throw err;
}
});
server.listen(3000);
Comparison to Alternatives.
There are alternative existing libraries for creating typed and wrapped errors on npm. Here's a quick comparison to some alternatives.
verror
This module takes inspiration from verror and adds improvements.
- You can pass extra fields as meta data on the error
- The templating forces dynamic strings to be extra fields.
- Uses ES6 classes for inheritance. This gives your errors unique class names and makes them show up in heapdumps.
- Has JSON.stringify support
[email protected]
This package used to have a completely different API on the 7.x branch.
- New
errormodule uses actual classes instead of dynamically monkey patching fields ontonew Error() - Implementation is more static, previous code was very dynamic
- Simpler API, see the message & properties in one place.
wrapf&errorfhelpers for less boilerplate.
Hand writing Error sub classes.
You can create your own Error classes by hand. This tends to lead to 10-20 lines of boilerplate per error which is replace with one line by using the error module; aka
class AccountsServerFailureError extends SError {}
class ConnectionResetError extends WError {}
ono
The ono package has similar functionality with a different API
onoencourages plain errors instead of custom errors by defaulterrorhas zero dependencieserroris only one simple file.onois 10.errorimplementation is more static, ono is very dynamic.
Documentation
This package implements three classes, WError; SError & MultiError
You are expected to subclass either WError or SError;
SErrorstands forStructured Error; it's an error base class for adding informational fields to your error beyond just having a message.WErrorstands forWrapped Error; it's an error base class for when you are wrapping an existing error with more information.
The MultiError class exists to store an array of errors but still return a single Error; This is useful if your doing a parallel operation and you want to wait for them all to finish and do something with all of the failures.
Some utility functions are also exported:
findCauseByName; See if error or any of it's causes is of the type name.fullStack; Take a wrapped error and compute a full stack.wrapf; Utility function to quickly wraperrorf; Utility function to quickly create an errorgetInfo; Utility function to get the info for any error object. Callserr.info()if the method exists.
WError
Example:
class ServerListenError extends WError {}
ServerListenError.wrap('error in server', err, {
port: 3000
})
When using the WError class it's recommended to always call the static wrap() method instead of calling the constructor directly.
Example (without cause message):
class ApplicationStartupError extends WError {}
ApplicationStartupError.wrap(
'Could not start the application cleanly: {reason}',
err,
{
skipCauseMessage: true,
reason: 'Failed to read from disk'
}
)
Setting skipCauseMessage: true will not append the cause error message but still make the cause object available.
const werr = new WError(message, cause, info)
Internal constructor, should pass a message string, a cause error and a info object (or null).
WError.wrap(msgTmpl, cause, info)
wrap() method to create error instances. This applies the string-template templating to msgTmpl with info as a parameter.
The cause parameter must be an error The info parameter is an object or null.
The info parameter can contain the field skipCauseMessage: true which will make WError not append : ${causeMessage} to the message of the error.
werr.type
The type field is the machine readable type for this error. Always use err.type and never err.message when trying to determine what kind of error it is.
The type field is unlikely to change but the message field can change.
werr.fullType()
Calling fullType will compute a full type for this error and any causes that it wraps. This gives you a long type string that's a concat for every wrapped cause.
werr.cause()
Returns the cause error.
werr.info()
Returns the info object passed on. This is merged with the info of all cause errors up the chain.
werr.toJSON()
The WError class implements toJSON() so that the JSON serialization makes sense.
WError.fullStack(err)
This returns a full stack; which is a concatenation of this stack trace and the stack trace of all causes in the cause chain
WError.findCauseByName(err, name)
Given an err and a name will find if the err or any causes implement the type of that name.
This allows you to check if a wrapped ApplicationError has for example a LevelReadError or LevelWriteError in it's cause chain and handle database errors differently from all other app errors.
SError
Example:
class LevelReadError extends SError {}
LevelReadError.create('Could not read key: {key}', {
key: '/some/key'
})
When using the SError class it's recommended to always call the static create() method instead of calling the constructor directly.
const serr = new SError(message, info)
Internal constructor that takes a message string & an info object.
SError.create(messageTmpl, info)
The main way to create error objects, takes a message template and an info object.
It will use string-template to apply the template with the info object as a parameter.
SError.getInfo(error)
Static method to getInfo on a maybe error. The error can be null or undefined, it can be a plain new Error() or it can be a structured or wrapped error.
Will return err.info() if it exists, returns {} if its null and returns { ...err } if its a plain vanilla error.
serr.type
Returns the type field. The err.type field is machine readable. Always use err.type & not err.message when trying to compare errors or do any introspection.
The type field is unlikely to change but the message field can change.
serr.info()
Returns the info object for this error.
serr.toJSON()
This class can JSON serialize cleanly.
MultiError
Example:
class FanoutError extends MultiError {}
function doStuff (filePath, cb) {
fanoutDiskReads(filePath, (errors, fileContents) => {
if (errors && errors.length > 0) {
const err = FanoutError.errorFromList(errors)
return cb(err)
}
// do stuff with files.
})
}
When using the MultiError class it's recommended to always call the static errorFromList method instead of calling the constructor directly.
Usage from typescript
The error library does not have an index.d.ts but does have full jsdoc annotations so it should be typesafe to use.
You will need to configure your tsconfig appropiately ...
{
"compilerOptions": {
...
"allowJs": true,
...
},
"include": [
"src/**/*.js",
"node_modules/error/index.js"
],
"exclude": [
"node_modules"
]
}
Typescript does not understand well type source code in node_modules without an index.d.ts by default, so you need to tell it to include the implementation of error/index.js during type checking and to allowJs to enable typechecking js + jsdoc comments.
Installation
npm install error
Contributors
- Raynos