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 |
|
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
|