http-errors-enhanced

Create HTTP errors with additional properties for any framework.

View on GitHub

Introduction

%s %s %s %s

Create HTTP errors with additional properties for any framework.

http://sw.cowtech.it/http-errors-enhanced

Installation

Just run:

npm install http-errors-enhanced --save

Usage

You can create an error by using the generic base class.

import { HttpError } from 'http-errors-enhanced' 
 
// Any of the following will return the same error 
const error1 = new HttpError(404, 'Page not found.', { key1: 'prop1' }) 
const error2 = new HttpError(404, { key1: 'prop1', message: 'Page not found.' }) 
const error3 = new HttpError('NotFound', 'Page not found.') 
const error4 = new HttpError('NotFound', { key1: 'prop1', message: 'Page not found.' })

Or you can import a specific error class and instantiate that, to have some status and messages set up for you automatically.

import { NotFoundError } from 'http-errors-enhanced' 
 
// Any of the following will return the same error 
const error1 = new NotFoundError('Page not found.', { key1: 'prop1' }) 
const error2 = new NotFoundError({ key1: 'prop1', message: 'Page not found.' })

Or, if you don't want to use the new operator, you can use the createError function:

import { createError } from 'http-errors-enhanced' 
 
// Any of the following will return the same error 
const error1 = createError(404, 'Page not found.', { key1: 'prop1' }) 
const error2 = createError(404, { key1: 'prop1', message: 'Page not found.' }) 
const error3 = createError('NotFound', 'Page not found.') 
const error4 = createError('NotFound', { key1: 'prop1', message: 'Page not found.' })

API

HttpError

The main error class.

The constructor signature is the following:

constructor(status, message, properties)

Where:

The returned instance is a descendant class of Error with the following base properties, plus all the other properties specified in the constructor:

Each instance has a serialize(extended, omitStack) function.

If called without argument, it will return a object with the properties statusCode, error and message copied from the instance.

If called with extended set to true, it will call serializeError (see below) on the instance.

Named error classes

For each known HTTP error, taken from Node.js http.STATUS_CODES, there is an exported named class.

For instance, for the HTTP error 404, there is the NotFoundError which inherits from HttpError.

The constructor of a named class is the following:

constructor([message], [properties])

createError(status, [message], [properties])

The function can be used to create an HttpError without using the new operator.

It accepts the same arguments of the HttpError constructor.

isHttpError(val)

The function can be used to check if an value is a HttpError or it has compatible properties. It follows the same semantic of the hononym function of http-errors.

The function returns true if the value is an instance of HttpError or if the value is an object with a status property which is a number (and it is mirrored by the statusCode property) and a expose property which is a boolean.

addAdditionalProperties(target, source)

Copies all enumerable properties from source to target, skipping the ones which are already defined.

serializeError(val, [omitStack])

The function extracts the message, code (or name if no code is present) and stack properties from an object (typically a descendant of Error).

The extract properties are formatted and returned in a plain object containing message (string) and stack (array of strings) properties.

The object also contains all the other properties of the original object.

If omitStack is true, the stack property is omitted.

Constants

The package exports several utility constants to make HTTP status handling easier

identifierByCodes and codesByIdentifier

A map of statuses identifiers indexed by HTTP status code and its reverse. This also exports HTTP classes 100, 200 and 300.

console.log(identifierByCodes[404]) 
// => NotFound 
 
console.log(codesByIdentifier['NotFound']) 
// => 404

messagesByCodes and phrasesByCodes

A map of statuses descriptions and phrases indexed by HTTP status code. This also exports HTTP classes 100, 200 and 300.

console.log(messagesByCodes[404]) 
// => Not Found 
 
console.log(phrasesByCodes[404]) 
// => Not found.

Named status constants

For each HTTP status there is a upper snake case constant exported.

console.log(CREATED) 
// => 201 
 
console.log(NOT_FOUND) 
// => 404

JSON Schemas definitions

The package defines a schema for commonly used error codes, in order to easily include them in JSON Schema and OpenAPI based validation frameworks.

console.log(JSON.stringify(notFoundErrorSchema)) 
/* 
=> { 
  "type": "object", 
  "$id": "errors/404", 
  "description": "Error returned when the requested resource is not found.", 
  "properties": { 
    "statusCode": { 
      "type": "number", 
      "description": "The error code", 
      "enum": [ 
        404 
      ], 
      "example": 404 
    }, 
    "error": { 
      "type": "string", 
      "description": "The error title", 
      "enum": [ 
        "NotFound" 
      ], 
      "example": "NotFound" 
    }, 
    "message": { 
      "type": "string", 
      "description": "The error message", 
      "pattern": ".+", 
      "example": "NotFound." 
    } 
  }, 
  "required": [ 
    "statusCode", 
    "error", 
    "message" 
  ], 
  additionalProperties: false 
} 
*/

ESM Only

This package only supports to be directly imported in a ESM context.

For informations on how to use it in a CommonJS context, please check this page.

Credits

This project has been heavily inspired by http-errors, of which is a indipendent and unrelated project.

Contributing to http-errors-enhanced

Copyright

Copyright (C) 2020 and above Shogun (shogun@cowtech.it).

Licensed under the ISC license, which can be found at https://choosealicense.com/licenses/isc.