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