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.

148 lines
3.9 KiB

  1. # finalhandler
  2. [![NPM Version][npm-image]][npm-url]
  3. [![NPM Downloads][downloads-image]][downloads-url]
  4. [![Node.js Version][node-image]][node-url]
  5. [![Build Status][travis-image]][travis-url]
  6. [![Test Coverage][coveralls-image]][coveralls-url]
  7. Node.js function to invoke as the final step to respond to HTTP request.
  8. ## Installation
  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. ```sh
  13. $ npm install finalhandler
  14. ```
  15. ## API
  16. <!-- eslint-disable no-unused-vars -->
  17. ```js
  18. var finalhandler = require('finalhandler')
  19. ```
  20. ### finalhandler(req, res, [options])
  21. Returns function to be invoked as the final step for the given `req` and `res`.
  22. This function is to be invoked as `fn(err)`. If `err` is falsy, the handler will
  23. write out a 404 response to the `res`. If it is truthy, an error response will
  24. be written out to the `res`.
  25. When an error is written, the following information is added to the response:
  26. * The `res.statusCode` is set from `err.status` (or `err.statusCode`). If
  27. this value is outside the 4xx or 5xx range, it will be set to 500.
  28. * The `res.statusMessage` is set according to the status code.
  29. * The body will be the HTML of the status code message if `env` is
  30. `'production'`, otherwise will be `err.stack`.
  31. * Any headers specified in an `err.headers` object.
  32. The final handler will also unpipe anything from `req` when it is invoked.
  33. #### options.env
  34. By default, the environment is determined by `NODE_ENV` variable, but it can be
  35. overridden by this option.
  36. #### options.onerror
  37. Provide a function to be called with the `err` when it exists. Can be used for
  38. writing errors to a central location without excessive function generation. Called
  39. as `onerror(err, req, res)`.
  40. ## Examples
  41. ### always 404
  42. ```js
  43. var finalhandler = require('finalhandler')
  44. var http = require('http')
  45. var server = http.createServer(function (req, res) {
  46. var done = finalhandler(req, res)
  47. done()
  48. })
  49. server.listen(3000)
  50. ```
  51. ### perform simple action
  52. ```js
  53. var finalhandler = require('finalhandler')
  54. var fs = require('fs')
  55. var http = require('http')
  56. var server = http.createServer(function (req, res) {
  57. var done = finalhandler(req, res)
  58. fs.readFile('index.html', function (err, buf) {
  59. if (err) return done(err)
  60. res.setHeader('Content-Type', 'text/html')
  61. res.end(buf)
  62. })
  63. })
  64. server.listen(3000)
  65. ```
  66. ### use with middleware-style functions
  67. ```js
  68. var finalhandler = require('finalhandler')
  69. var http = require('http')
  70. var serveStatic = require('serve-static')
  71. var serve = serveStatic('public')
  72. var server = http.createServer(function (req, res) {
  73. var done = finalhandler(req, res)
  74. serve(req, res, done)
  75. })
  76. server.listen(3000)
  77. ```
  78. ### keep log of all errors
  79. ```js
  80. var finalhandler = require('finalhandler')
  81. var fs = require('fs')
  82. var http = require('http')
  83. var server = http.createServer(function (req, res) {
  84. var done = finalhandler(req, res, {onerror: logerror})
  85. fs.readFile('index.html', function (err, buf) {
  86. if (err) return done(err)
  87. res.setHeader('Content-Type', 'text/html')
  88. res.end(buf)
  89. })
  90. })
  91. server.listen(3000)
  92. function logerror (err) {
  93. console.error(err.stack || err.toString())
  94. }
  95. ```
  96. ## License
  97. [MIT](LICENSE)
  98. [npm-image]: https://img.shields.io/npm/v/finalhandler.svg
  99. [npm-url]: https://npmjs.org/package/finalhandler
  100. [node-image]: https://img.shields.io/node/v/finalhandler.svg
  101. [node-url]: https://nodejs.org/en/download
  102. [travis-image]: https://img.shields.io/travis/pillarjs/finalhandler.svg
  103. [travis-url]: https://travis-ci.org/pillarjs/finalhandler
  104. [coveralls-image]: https://img.shields.io/coveralls/pillarjs/finalhandler.svg
  105. [coveralls-url]: https://coveralls.io/r/pillarjs/finalhandler?branch=master
  106. [downloads-image]: https://img.shields.io/npm/dm/finalhandler.svg
  107. [downloads-url]: https://npmjs.org/package/finalhandler