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