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