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

error@7.x

This package used to have a completely different API on the 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.

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

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

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

MIT Licenced