modern-errors plugin to create HTTP error responses.

This adds error.httpResponse() which converts error to a plain object (RFC 7807, "problem details") to use in an HTTP response.

Example

Adding the plugin to modern-errors.

import ModernError from 'modern-errors'
import modernErrorsHttp from 'modern-errors-http'

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsHttp],
})

Configuring error fields.

export const AuthError = BaseError.subclass('AuthError', {
  http: {
    type: 'https://example.com/probs/auth',
    status: 401,
  },
})

Creating an HTTP error response.

const error = new AuthError('Could not authenticate.', {
  http: {
    instance: '/users/62',
    extra: { userId: 62 },
  },
})
const object = error.httpResponse()
// {
//   type: 'https://example.com/probs/auth',
//   status: 401,
//   title: 'AuthError',
//   detail: 'Could not authenticate.',
//   instance: '/users/62',
//   stack: `AuthError: Could not authenticate.
//     at ...`,
//   extra: { userId: 62 },
// }

Install

npm install modern-errors-http

This package works in both Node.js >=14.18.0 and browsers. It is an ES module and must be loaded using an import or import() statement, not require().

API

modernErrorsHttp

Type: Plugin

Plugin object to pass to the plugins option of ErrorClass.subclass().

error.httpResponse()

Return value: HttpResponse

Converts error to a plain object to use in an HTTP response. Its shape follows RFC 7807 ("problem details").

Options

Type: object

type

Type: urlString
Default: undefined

URI identifying and documenting the error class. Ideally, each error class should set one.

status

Type: integer
Default: undefined

HTTP status code.

title

Type: string
Default: error.name

Error class name.

detail

Type: string
Default: error.message

Error description.

instance

Type: urlString
Default: undefined

URI identifying the value which errored.

stack

Type: string
Default: error.stack

Error stack trace. Can be set to an empty string.

extra

Type: object
Default: any additional error properties

Additional information. This is always safe to serialize as JSON. Can be set to an empty object.

Configuration

Options can apply to (in priority order):

• Any error: second argument to ModernError.subclass()

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsHttp],
  http: { ...options },
})

• Any error of a specific class (and its subclasses): second argument to ErrorClass.subclass()

export const AuthError = BaseError.subclass('AuthError', {
  http: { ...options },
})

• A specific error: second argument to new ErrorClass()

throw new AuthError('...', { http: { ...options } })

• A specific error.httpResponse() call

error.httpResponse(...args, { ...options })

Related projects

• safe-json-value: ⛑️ JSON serialization should never fail
• modern-errors: Handle errors like it's 2022 🔮
• modern-errors-cli: Handle errors in CLI modules
• modern-errors-process: Handle process errors
• modern-errors-bugs: Print where to report bugs
• modern-errors-serialize: Serialize/parse errors
• modern-errors-clean: Clean stack traces
• modern-errors-winston: Log errors with Winston

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!