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