source: trip-planner-front/node_modules/on-finished/README.md@ 6c1585f

Last change on this file since 6c1585f was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 4.8 KB
Line 
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 HTTP 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 an error, the first argument will contain the error. If the response
28has already finished, the listener will be invoked.
29
30Listening to the end of a response would be used to close things associated
31with the response, like open files.
32
33Listener is invoked as `listener(err, res)`.
34
35```js
36onFinished(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
44Attach a listener to listen for the request to finish. The listener will
45be invoked only once when the request finished. If the request finished
46to an error, the first argument will contain the error. If the request
47has already finished, the listener will be invoked.
48
49Listening to the end of a request would be used to know when to continue
50after reading the data.
51
52Listener is invoked as `listener(err, req)`.
53
54```js
55var data = ''
56
57req.setEncoding('utf8')
58res.on('data', function (str) {
59 data += str
60})
61
62onFinished(req, function (err, req) {
63 // data is read unless there is err
64})
65```
66
67### onFinished.isFinished(res)
68
69Determine if `res` is already finished. This would be useful to check and
70not even start certain operations if the response has already finished.
71
72### onFinished.isFinished(req)
73
74Determine if `req` is already finished. This would be useful to check and
75not even start certain operations if the request has already finished.
76
77## Special Node.js requests
78
79### HTTP CONNECT method
80
81The meaning of the `CONNECT` method from RFC 7231, section 4.3.6:
82
83> The CONNECT method requests that the recipient establish a tunnel to
84> the destination origin server identified by the request-target and,
85> if successful, thereafter restrict its behavior to blind forwarding
86> of packets, in both directions, until the tunnel is closed. Tunnels
87> are commonly used to create an end-to-end virtual connection, through
88> one or more proxies, which can then be secured using TLS (Transport
89> Layer Security, [RFC5246]).
90
91In Node.js, these request objects come from the `'connect'` event on
92the HTTP server.
93
94When this module is used on a HTTP `CONNECT` request, the request is
95considered "finished" immediately, **due to limitations in the Node.js
96interface**. This means if the `CONNECT` request contains a request entity,
97the request will be considered "finished" even before it has been read.
98
99There is no such thing as a response object to a `CONNECT` request in
100Node.js, so there is no support for for one.
101
102### HTTP Upgrade request
103
104The meaning of the `Upgrade` header from RFC 7230, section 6.1:
105
106> The "Upgrade" header field is intended to provide a simple mechanism
107> for transitioning from HTTP/1.1 to some other protocol on the same
108> connection.
109
110In Node.js, these request objects come from the `'upgrade'` event on
111the HTTP server.
112
113When this module is used on a HTTP request with an `Upgrade` header, the
114request is considered "finished" immediately, **due to limitations in the
115Node.js interface**. This means if the `Upgrade` request contains a request
116entity, the request will be considered "finished" even before it has been
117read.
118
119There is no such thing as a response object to a `Upgrade` request in
120Node.js, so there is no support for for one.
121
122## Example
123
124The following code ensures that file descriptors are always closed
125once the response finishes.
126
127```js
128var destroy = require('destroy')
129var http = require('http')
130var onFinished = require('on-finished')
131
132http.createServer(function onRequest(req, res) {
133 var stream = fs.createReadStream('package.json')
134 stream.pipe(res)
135 onFinished(res, function (err) {
136 destroy(stream)
137 })
138})
139```
140
141## License
142
143[MIT](LICENSE)
144
145[npm-image]: https://img.shields.io/npm/v/on-finished.svg
146[npm-url]: https://npmjs.org/package/on-finished
147[node-version-image]: https://img.shields.io/node/v/on-finished.svg
148[node-version-url]: http://nodejs.org/download/
149[travis-image]: https://img.shields.io/travis/jshttp/on-finished/master.svg
150[travis-url]: https://travis-ci.org/jshttp/on-finished
151[coveralls-image]: https://img.shields.io/coveralls/jshttp/on-finished/master.svg
152[coveralls-url]: https://coveralls.io/r/jshttp/on-finished?branch=master
153[downloads-image]: https://img.shields.io/npm/dm/on-finished.svg
154[downloads-url]: https://npmjs.org/package/on-finished
Note: See TracBrowser for help on using the repository browser.