error

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][eris] & [pkg/errors][pkg-errors]

Older version of error

If you are looking for the older v7 version of error you should
check [v7.x][7.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][dave]

If you want a deep dive into the difference between
Programming and Operational errors
please check out this guide

examples:

``js
const { wrapf } = require('error')

function authenticatRequest(req) {
authenticate(req.user, (err) => {
if (err) {
return cb(wrapf('authenticate failed', err))
}
cb(null)
})
}
`

or

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

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

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

$3

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

$3

This package used to have a completely different API on the
[7.x][7.x] branch.
- New error module uses actual classes instead of dynamically
monkey patching fields onto new Error()
- Implementation is more static, previous code was very dynamic
- Simpler API, see the message & properties in one place.
- wrapf & errorf helpers for less boilerplate.

$3

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

`js
class AccountsServerFailureError extends SError {}
class ConnectionResetError extends WError {}
`

$3

The ono package has similar functionality with a different API
- ono encourages plain errors instead of custom errors by default
- error has zero dependencies
- error is only one simple file. ono is 10.
- error implementation 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;

- SError stands for Structured Error; it's an error base
class for adding informational fields to your error beyond
just having a message.
- WError stands for Wrapped 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 wrap
- errorf; Utility function to quickly create an error
- getInfo; Utility function to get the info for any error
object. Calls err.info() if the method exists.

$3

Example:

`js
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):

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

$3

Internal constructor, should pass a message string, a cause
error and a info object (or null).

$3

wrap() method to create error instances. This applies the
[string-template][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.

$3

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.

$3

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.

$3

Returns the cause error.

$3

Returns the info object passed on. This is merged with the
info of all cause errors up the chain.

$3

The WError class implements toJSON() so that the JSON
serialization makes sense.

$3

This returns a full stack; which is a concatenation of this
stack trace and the stack trace of all causes in the cause chain

$3

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.

$3

Example:

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

$3

Internal constructor that takes a message string & an info object.

$3

The main way to create error objects, takes a message template
and an info object.

It will use [string-template][string-template] to apply the
template with the info object as a parameter.

$3

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.

$3

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.

$3

Returns the info object for this error.

$3

This class can JSON serialize cleanly.

$3

Example:

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

`json
{
"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

MIT Licenced

[eris]: https://github.com/rotisserie/eris/tree/v0.1.0
[pkg-errors]: https://github.com/pkg/errors
[7.x]: https://github.com/Raynos/error/tree/v7.x
[dave]: https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully
[string-template]: https://github.com/Matt-Esch/string-template
[verror]: https://github.com/joyent/node-verror
[ono]: https://github.com/JS-DevTools/ono