gerrit.onap Code Review - aai/esr-gui.git/blob

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