Skip to content

Latest commit

 

History

History
226 lines (192 loc) · 6.53 KB

README.md

File metadata and controls

226 lines (192 loc) · 6.53 KB
Raw

Tests

http-json-errors

A Node package that exposes standardized error creation functions and a class. This package was written for Express but doesn't have any dependencies on Express or any other package, except for development.

Example

import { BadRequest } from 'http-json-errors'

throw new BadRequest('You done messed up, son!')
{
  isHttpError: true,
  statusCode: 400,
  title: 'Bad Request',
  message: 'You done messed up, son!',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400',
  body: {
    error_text: 'You done messed up, son!'
  }
}

Generate Standard Errors by Http Status Code

If you don't know the error type up front, but do know the code, use the createError function to get a custom class, or a generic one, if the status code can't be matched:

import { createError } from 'http-json-errors'

throw createError(401, 'OMG!')
{
  isHttpError: true,
  statusCode: 401,
  title: 'Unauthorized',
  message: 'OMG!',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401',
  body: {
    error_text: 'OMG!'
  }
}

Roll your own

Create your own custom Error message using the HttpError class:

import { HttpError } from 'http-json-errors'

throw new HttpError(401, {message: 'OMG!', body: { error_code: 'OMG!', error_text: 'I wish you wouldn\'t have done that.' } });
{
  isHttpError: true,
  statusCode: 401,
  title: 'Internal Server Error',
  message: 'OMG!',
  body: {
    error_code: 'OMG!',
    error_text: "I wish you wouldn't have done that."
  }
}

TypeScript + ES6

This project was built in TypeScript and contains exported interfaces and type definitions for your convenience. The module is designed to use ES6 imports.

// Check out the Custom HTTP Error Classes section for a full list of custom classes!
import { BadRequest, HttpErrorOptions } from 'http-json-errors'

function totallyThrowsABadRequestError(options: HttpErrorOptions) {
  throw new BadRequest(options)
}
totallyThrowsABadRequestError('The user did something completely new that NOONE foresaw')
{
  isHttpError: true,
  statusCode: 400,
  title: 'Bad Request',
  message: 'The user did something completely new that NOONE foresaw',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400',
  body: {
    error_text: 'The user did something completely new that NOONE foresaw'
  }
}

Control over responses

Note that in the examples above the returned object contains both Error detail and a response body that can be returned to the user. The body defaults to an object with the format below. Any stand-alone strings will be assigned to the message property, and if the status is < 500, this will be copied to the body.

import { HttpError } from 'http-json-errors'

throw new HttpError(400, 'Bad stuff happened')
{
  isHttpError: true,
  statusCode: 400,
  title: 'Internal Server Error',
  message: 'Bad stuff happened',
  body: { error_text: 'Bad stuff happened' }
}

If the error code is >= 500, you should provide a body by passing an HttpErrorOptions object (one of the exported TypeScript interfaces). Note that any options provided in this way overwrite the default options.

import { HttpError } from 'http-json-errors'

throw new HttpError(500, 'Bad stuff happened', {body: {error_code: 'Why', error_description: 'You did the thing you should not have done' }})
{
  isHttpError: true,
  statusCode: 500,
  title: 'Internal Server Error',
  message: 'Bad stuff happened',
  body: {
    error_code: 'Why',
    error_description: 'You did the thing you should not have done'
  }
}
new BadRequest('Bad stuff happened', {body: 'That was not good'})
  isHttpError: true,
  statusCode: 400,
  title: 'Bad Request',
  message: 'Bad stuff happened',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400',
  body: 'That was not good'
}
import { NotImplemented } from 'http-json-errors'

throw new NotImplemented({body: {excuse: 'I just write the code. THEY designed the damn thing'}})
{
  isHttpError: true,
  statusCode: 501,
  title: 'Not Implemented',
  message: 'The request method is not supported by the server and cannot be handled.',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501',
  body: { excuse: 'I just write the code. THEY designed the damn thing' }
}

Custom HTTP Error Classes

The following custom classes are available:

HTTP Status Code Exported Class Name
400 BadRequest
401 Unauthorized
403 Forbidden
404 NotFound
405 MethodNotAllowed
406 NotAcceptable
407 ProxyAuthenticationRequired
408 RequestTimeout
409 Conflict
410 Gone
411 LengthRequired
412 PreconditionFailed
413 PayloadTooLarge
414 URITooLong
415 UnsupportedMediaType
416 RangeNotSatisfiable
417 ExpectationFailed
418 ImATeapot
421 MisdirectedRequest
422 UnprocessableEntity
423 Locked
424 FailedDependency
425 TooEarly
426 UpgradeRequired
428 PreconditionRequired
429 TooManyRequests
431 RequestHeaderFieldsTooLarge
451 UnavailableForLegalReasons
500 InternalServerError
501 NotImplemented
502 BadGateway
503 ServiceUnavailable
504 GatewayTimeout
505 HTTPVersionNotSupported
506 VariantAlsoNegotiates
507 InsufficientStorage
511 NetworkAuthenticationRequired

Changelog

Version Notes
1.2.0 Initial release: Why start at 1?
1.2.1 Updates to Readme; Added type file headers; Added .editorconfig;
1.2.2 Fixed name in readme
1.2.3 Added body and isHttpError properties to HttpError class; Security update for mocha; Updated Readme with new content and more examples
1.2.4 Changed statusCode to primary status property to be in line with NodeJS; status is now just a read-only property; Updated tests to reflect change
1.2.5 A string passed to a custom class will be set as the body error_text value. Updated examples to reflect the change. Updated dev dependency versions.
1.2.6 Developer environment updates: updated to mocha@7.2.0; Removed all implicit any values; replaced object with Record<string, any>; migrated from tslint to eslint; added VSCode settings.
1.2.7-1.2.8 Updates to NPM package
1.2.9 Updated mocha to address security advisory: https://github.com/advisories/GHSA-p9pc-299p-vxgp;
1.2.10 Updated typo for status 425
1.2.11 Fixed a bug where a value starting with 3 numbers would be mis-construed as a status code.
1.2.12 Updated mocha and chai to address vulnerabilities.