node_modules/finalhandler/README.md

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