http-json-errors
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.11 • Public • Published

    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.

    Install

    npm i http-json-errors

    DownloadsWeekly Downloads

    338

    Version

    1.2.11

    License

    MIT

    Unpacked Size

    102 kB

    Total Files

    15

    Last publish

    Collaborators

    • jobrad