node_modules/http-errors/README.md

   1 # http-errors
   2
   3 [![NPM Version][npm-version-image]][npm-url]
   4 [![NPM Downloads][npm-downloads-image]][node-url]
   5 [![Node.js Version][node-image]][node-url]
   6 [![Build Status][travis-image]][travis-url]
   7 [![Test Coverage][coveralls-image]][coveralls-url]
   8
   9 Create HTTP errors for Express, Koa, Connect, etc. with ease.
  10
  11 ## Install
  12
  13 This is a [Node.js](https://nodejs.org/en/) module available through the
  14 [npm registry](https://www.npmjs.com/). Installation is done using the
  15 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  16
  17 ```bash
  18 $ npm install http-errors
  19 ```
  20
  21 ## Example
  22
  23 ```js
  24 var createError = require('http-errors')
  25 var express = require('express')
  26 var app = express()
  27
  28 app.use(function (req, res, next) {
  29   if (!req.user) return next(createError(401, 'Please login to view this page.'))
  30   next()
  31 })
  32 ```
  33
  34 ## API
  35
  36 This is the current API, currently extracted from Koa and subject to change.
  37
  38 ### Error Properties
  39
  40 - `expose` - can be used to signal if `message` should be sent to the client,
  41   defaulting to `false` when `status` >= 500
  42 - `headers` - can be an object of header names to values to be sent to the
  43   client, defaulting to `undefined`. When defined, the key names should all
  44   be lower-cased
  45 - `message` - the traditional error message, which should be kept short and all
  46   single line
  47 - `status` - the status code of the error, mirroring `statusCode` for general
  48   compatibility
  49 - `statusCode` - the status code of the error, defaulting to `500`
  50
  51 ### createError([status], [message], [properties])
  52
  53 Create a new error object with the given message `msg`.
  54 The error object inherits from `createError.HttpError`.
  55
  56 <!-- eslint-disable no-undef, no-unused-vars -->
  57
  58 ```js
  59 var err = createError(404, 'This video does not exist!')
  60 ```
  61
  62 - `status: 500` - the status code as a number
  63 - `message` - the message of the error, defaulting to node's text for that status code.
  64 - `properties` - custom properties to attach to the object
  65
  66 ### createError([status], [error], [properties])
  67
  68 Extend the given `error` object with `createError.HttpError`
  69 properties. This will not alter the inheritance of the given
  70 `error` object, and the modified `error` object is the
  71 return value.
  72
  73 <!-- eslint-disable no-redeclare, no-undef, no-unused-vars -->
  74
  75 ```js
  76 fs.readFile('foo.txt', function (err, buf) {
  77   if (err) {
  78     if (err.code === 'ENOENT') {
  79       var httpError = createError(404, err, { expose: false })
  80     } else {
  81       var httpError = createError(500, err)
  82     }
  83   }
  84 })
  85 ```
  86
  87 - `status` - the status code as a number
  88 - `error` - the error object to extend
  89 - `properties` - custom properties to attach to the object
  90
  91 ### new createError\[code || name\](\[msg]\))
  92
  93 Create a new error object with the given message `msg`.
  94 The error object inherits from `createError.HttpError`.
  95
  96 <!-- eslint-disable no-undef, no-unused-vars -->
  97
  98 ```js
  99 var err = new createError.NotFound()
 100 ```
 101
 102 - `code` - the status code as a number
 103 - `name` - the name of the error as a "bumpy case", i.e. `NotFound` or `InternalServerError`.
 104
 105 #### List of all constructors
 106
 107 |Status Code|Constructor Name             |
 108 |-----------|-----------------------------|
 109 |400        |BadRequest                   |
 110 |401        |Unauthorized                 |
 111 |402        |PaymentRequired              |
 112 |403        |Forbidden                    |
 113 |404        |NotFound                     |
 114 |405        |MethodNotAllowed             |
 115 |406        |NotAcceptable                |
 116 |407        |ProxyAuthenticationRequired  |
 117 |408        |RequestTimeout               |
 118 |409        |Conflict                     |
 119 |410        |Gone                         |
 120 |411        |LengthRequired               |
 121 |412        |PreconditionFailed           |
 122 |413        |PayloadTooLarge              |
 123 |414        |URITooLong                   |
 124 |415        |UnsupportedMediaType         |
 125 |416        |RangeNotSatisfiable          |
 126 |417        |ExpectationFailed            |
 127 |418        |ImATeapot                    |
 128 |421        |MisdirectedRequest           |
 129 |422        |UnprocessableEntity          |
 130 |423        |Locked                       |
 131 |424        |FailedDependency             |
 132 |425        |UnorderedCollection          |
 133 |426        |UpgradeRequired              |
 134 |428        |PreconditionRequired         |
 135 |429        |TooManyRequests              |
 136 |431        |RequestHeaderFieldsTooLarge  |
 137 |451        |UnavailableForLegalReasons   |
 138 |500        |InternalServerError          |
 139 |501        |NotImplemented               |
 140 |502        |BadGateway                   |
 141 |503        |ServiceUnavailable           |
 142 |504        |GatewayTimeout               |
 143 |505        |HTTPVersionNotSupported      |
 144 |506        |VariantAlsoNegotiates        |
 145 |507        |InsufficientStorage          |
 146 |508        |LoopDetected                 |
 147 |509        |BandwidthLimitExceeded       |
 148 |510        |NotExtended                  |
 149 |511        |NetworkAuthenticationRequired|
 150
 151 ## License
 152
 153 [MIT](LICENSE)
 154
 155 [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/http-errors/master
 156 [coveralls-url]: https://coveralls.io/r/jshttp/http-errors?branch=master
 157 [node-image]: https://badgen.net/npm/node/http-errors
 158 [node-url]: https://nodejs.org/en/download
 159 [npm-downloads-image]: https://badgen.net/npm/dm/http-errors
 160 [npm-url]: https://npmjs.org/package/http-errors
 161 [npm-version-image]: https://badgen.net/npm/v/http-errors
 162 [travis-image]: https://badgen.net/travis/jshttp/http-errors/master
 163 [travis-url]: https://travis-ci.org/jshttp/http-errors