README.md (5554B)
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