botched

Better error handling with JSON:API friendly error objects - inspired by restify-errors, verror and boom.

Documentation

• Installation
• Usage
• Extend
• API
  • BotchedError
  • createError
  • createSerializer
  • botch
  • wrap
  • isBotched
• License

Installation

Install botched in your project

$ npm i --save botched

Usage

Import the relevant error you need and use as you would using vanilla Errors. Using the built in error serializer you can effortlessly log errors in a useful format without losing precision.

import express from 'express';
import { createHttpError, createSerializer, Unauthorized } from 'botched';

// Create app
const app = express();
const serialize = createSerializer();

// Middleware that throws Unauthorized if `req.user` is not set
app.use((req, res, next) => {
  if (!req.user) {
    // Alternative 1: Create a new error instance of the type you need by
    let unauthorizedError = new Unauthorized('This endpoint requires authentication');

    // Alternative 2: It is also possible to dynamically create the error you need based on status code
    unauthorizedError = createHttpError(401, 'This endpoint requires authentication');

    return next(unauthorizedError);
  }
  return next();
});

// Error handling middleware to display beautiful errors and log the error details
app.use((err, req, res, next) => {
  // Serialize the error to a loggable format
  const serializedError = serialize(err);

  // Log it
  console.log(serializedError);

  // Respond with a http friendly error message while hiding sensitive details
  res.status(err.statusCode).json(err.toJSON());
});

// Listen
app.listen(3000);

Extend

It's very easy to extend with your own errors and it is highly recommended to do so. The only requirement is that you extend BotchedError.

import { BotchedError } from 'botched';

// Exports
export default class InvalidVersionError extends BotchedError {
  // Override default values
  static statusCode = 400;
  static title = 'Invalid Version Error';
}

API

All Error constructors are variadic and accept the following signatures, all of which are identical to the VError and WError signatures.

BotchedError

The base Error class with the core functionality.

new BotchedError(sprintf_args...)

new BotchedError(priorErr [, sprintf_args...])

new BotchedError(options [, sprinf_args...])

Parameters:

• options {object}
  • cause {Error} - A referenced error
  • id {string} - A unique identifier for this instance of the error. Useful for correlating logs. Autogenerated by default.
  • code {string} - An identifier for this type of error. Useful for grouping errors.
  • statusCode {number} - The http status code to respond with if this error is used in a http response
  • headers {object} - Any additional headers to set if this error is used in a http response
  • title {string} - The title of the error, e.g. Internal Server Error.
  • source {object} - Pointer to the cause of the error. Useful for validation with JSON Schema.
    • pointer {string} - A JSON pointer to the error in a JSON Schema
  • links {object} - A link to where this error is described in more detail - e.g some documentation.
    • about {object|string} - An uri to the detailed documentation or an object containing the uri.
      • href {string} - The uri to the detailed documentation
      • meta {object} - Any additional data about the link
  • meta {object} - Any additional non-sensitive data or information related to this error that will be visible in err.toJSON()
  • info {object} - Any additional data or information related to this error

botchedError.toJSON()

Returns a JSON:API compliant error object with sensitive information stripped out. In other words, botchedError.info is omitted.

createError

Create BotchedError from status code. Useful if you are dynamically creating errors.

createError(statusCode, sprintf_args...)

createError(statusCode, priorErr [, sprintf_args...])

createError(statusCode, options [, sprinf_args...])

createSerializer

Serialize error objects to logging friendly objects.

createSerializer([options])

Create an error serializer function. Provide the Error instance and receive a perfectly formatted object back when using the returned serializer function. Note that this will include sensitive information as the purpose is to create logging friendly objects - not objects to be sent in API responses. Use BotchedError for that.

Parameters:

• options {object}
  • fullStack {boolean} - Should top level Error have the full stack trace (including nested errors?) Default: true
  • maxDepth {number} - How deep should the serialization go? Default: 10

botch

botch(error)

Create a botched error from a source error or return the error directly if it is already a botched error.

Note: this will inherit information from the source error. Only use this if you are certain that the error does not contain sensitive information. See wrap for a safer alternative.

If the error is not already a botched error, then a botched error will be created and inherit all botched properties. The cause will be set to the source error.

wrap

wrap(error)

Wrap an error to a botched error or return the error directly if it is already a botched error. This is equivalent to botch, but does not inherit any properties except the status code. Use this if you cannot guarantee that the error does not include sensitive information.

If the error is not already a botched error, then a botched error will be created and only the status code will be inherited. The cause will be set to the source error.

isBotched

isBotched(error)

Convenience method to check if the error is a BotchedError. Returns true if the error is a BotchedError.

TODO

1. Consider whether isBotched should fail if the BotchedError.version is not compatible

License

MIT