You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 5.4KB

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