dgbuilder/dgeflows/node_modules/morgan/node_modules/on-finished/README.md

   1 # on-finished
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Node.js Version][node-version-image]][node-version-url]
   6 [![Build Status][travis-image]][travis-url]
   7 [![Test Coverage][coveralls-image]][coveralls-url]
   8
   9 Execute a callback when a request closes, finishes, or errors.
  10
  11 ## Install
  12
  13 ```sh
  14 $ npm install on-finished
  15 ```
  16
  17 ## API
  18
  19 ```js
  20 var onFinished = require('on-finished')
  21 ```
  22
  23 ### onFinished(res, listener)
  24
  25 Attach a listener to listen for the response to finish. The listener will
  26 be invoked only once when the response finished. If the response finished
  27 to to an error, the first argument will contain the error. If the response
  28 has already finished, the listener will be invoked.
  29
  30 Listening to the end of a response would be used to close things associated
  31 with the response, like open files.
  32
  33 Listener is invoked as `listener(err, res)`.
  34
  35 ```js
  36 onFinished(res, function (err, res) {
  37   // clean up open fds, etc.
  38   // err contains the error is request error'd
  39 })
  40 ```
  41
  42 ### onFinished(req, listener)
  43
  44 Attach a listener to listen for the request to finish. The listener will
  45 be invoked only once when the request finished. If the request finished
  46 to to an error, the first argument will contain the error. If the request
  47 has already finished, the listener will be invoked.
  48
  49 Listening to the end of a request would be used to know when to continue
  50 after reading the data.
  51
  52 Listener is invoked as `listener(err, req)`.
  53
  54 ```js
  55 var data = ''
  56
  57 req.setEncoding('utf8')
  58 res.on('data', function (str) {
  59   data += str
  60 })
  61
  62 onFinished(req, function (err, req) {
  63   // data is read unless there is err
  64 })
  65 ```
  66
  67 ### onFinished.isFinished(res)
  68
  69 Determine if `res` is already finished. This would be useful to check and
  70 not even start certain operations if the response has already finished.
  71
  72 ### onFinished.isFinished(req)
  73
  74 Determine if `req` is already finished. This would be useful to check and
  75 not even start certain operations if the request has already finished.
  76
  77 ### Example
  78
  79 The following code ensures that file descriptors are always closed
  80 once the response finishes.
  81
  82 ```js
  83 var destroy = require('destroy')
  84 var http = require('http')
  85 var onFinished = require('on-finished')
  86
  87 http.createServer(function onRequest(req, res) {
  88   var stream = fs.createReadStream('package.json')
  89   stream.pipe(res)
  90   onFinished(res, function (err) {
  91     destroy(stream)
  92   })
  93 })
  94 ```
  95
  96 ## License
  97
  98 [MIT](LICENSE)
  99
 100 [npm-image]: https://img.shields.io/npm/v/on-finished.svg?style=flat
 101 [npm-url]: https://npmjs.org/package/on-finished
 102 [node-version-image]: https://img.shields.io/node/v/on-finished.svg?style=flat
 103 [node-version-url]: http://nodejs.org/download/
 104 [travis-image]: https://img.shields.io/travis/jshttp/on-finished.svg?style=flat
 105 [travis-url]: https://travis-ci.org/jshttp/on-finished
 106 [coveralls-image]: https://img.shields.io/coveralls/jshttp/on-finished.svg?style=flat
 107 [coveralls-url]: https://coveralls.io/r/jshttp/on-finished?branch=master
 108 [downloads-image]: https://img.shields.io/npm/dm/on-finished.svg?style=flat
 109 [downloads-url]: https://npmjs.org/package/on-finished