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][ci-image]][ci-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 ```console 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 ```js 57 var err = createError(404, 'This video does not exist!') 58 ``` 59 60 - `status: 500` - the status code as a number 61 - `message` - the message of the error, defaulting to node's text for that status code. 62 - `properties` - custom properties to attach to the object 63 64 ### createError([status], [error], [properties]) 65 66 Extend the given `error` object with `createError.HttpError` 67 properties. This will not alter the inheritance of the given 68 `error` object, and the modified `error` object is the 69 return value. 70 71 <!-- eslint-disable no-redeclare --> 72 73 ```js 74 fs.readFile('foo.txt', function (err, buf) { 75 if (err) { 76 if (err.code === 'ENOENT') { 77 var httpError = createError(404, err, { expose: false }) 78 } else { 79 var httpError = createError(500, err) 80 } 81 } 82 }) 83 ``` 84 85 - `status` - the status code as a number 86 - `error` - the error object to extend 87 - `properties` - custom properties to attach to the object 88 89 ### createError.isHttpError(val) 90 91 Determine if the provided `val` is an `HttpError`. This will return `true` 92 if the error inherits from the `HttpError` constructor of this module or 93 matches the "duck type" for an error this module creates. All outputs from 94 the `createError` factory will return `true` for this function, including 95 if an non-`HttpError` was passed into the factory. 96 97 ### new createError\[code || name\](\[msg]\)) 98 99 Create a new error object with the given message `msg`. 100 The error object inherits from `createError.HttpError`. 101 102 ```js 103 var err = new createError.NotFound() 104 ``` 105 106 - `code` - the status code as a number 107 - `name` - the name of the error as a "bumpy case", i.e. `NotFound` or `InternalServerError`. 108 109 #### List of all constructors 110 111 |Status Code|Constructor Name | 112 |-----------|-----------------------------| 113 |400 |BadRequest | 114 |401 |Unauthorized | 115 |402 |PaymentRequired | 116 |403 |Forbidden | 117 |404 |NotFound | 118 |405 |MethodNotAllowed | 119 |406 |NotAcceptable | 120 |407 |ProxyAuthenticationRequired | 121 |408 |RequestTimeout | 122 |409 |Conflict | 123 |410 |Gone | 124 |411 |LengthRequired | 125 |412 |PreconditionFailed | 126 |413 |PayloadTooLarge | 127 |414 |URITooLong | 128 |415 |UnsupportedMediaType | 129 |416 |RangeNotSatisfiable | 130 |417 |ExpectationFailed | 131 |418 |ImATeapot | 132 |421 |MisdirectedRequest | 133 |422 |UnprocessableEntity | 134 |423 |Locked | 135 |424 |FailedDependency | 136 |425 |TooEarly | 137 |426 |UpgradeRequired | 138 |428 |PreconditionRequired | 139 |429 |TooManyRequests | 140 |431 |RequestHeaderFieldsTooLarge | 141 |451 |UnavailableForLegalReasons | 142 |500 |InternalServerError | 143 |501 |NotImplemented | 144 |502 |BadGateway | 145 |503 |ServiceUnavailable | 146 |504 |GatewayTimeout | 147 |505 |HTTPVersionNotSupported | 148 |506 |VariantAlsoNegotiates | 149 |507 |InsufficientStorage | 150 |508 |LoopDetected | 151 |509 |BandwidthLimitExceeded | 152 |510 |NotExtended | 153 |511 |NetworkAuthenticationRequired| 154 155 ## License 156 157 [MIT](LICENSE) 158 159 [ci-image]: https://badgen.net/github/checks/jshttp/http-errors/master?label=ci 160 [ci-url]: https://github.com/jshttp/http-errors/actions?query=workflow%3Aci 161 [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/http-errors/master 162 [coveralls-url]: https://coveralls.io/r/jshttp/http-errors?branch=master 163 [node-image]: https://badgen.net/npm/node/http-errors 164 [node-url]: https://nodejs.org/en/download 165 [npm-downloads-image]: https://badgen.net/npm/dm/http-errors 166 [npm-url]: https://npmjs.org/package/http-errors 167 [npm-version-image]: https://badgen.net/npm/v/http-errors 168 [travis-image]: https://badgen.net/travis/jshttp/http-errors/master 169 [travis-url]: https://travis-ci.org/jshttp/http-errors