diff options
author | Chetan Karande <kchetan.tech@gmail.com> | 2019-09-03 13:34:36 -0400 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2019-09-05 21:08:06 -0700 |
commit | 02f3dd24f38983b3211bcec7e96cb005c3babef8 (patch) | |
tree | 45103b795438823e89c357be1b762f86a92efe14 /doc/api/stream.md | |
parent | 9c57e4dedbe5e72a226180f1440cf2884e3cad5c (diff) | |
download | android-node-v8-02f3dd24f38983b3211bcec7e96cb005c3babef8.tar.gz android-node-v8-02f3dd24f38983b3211bcec7e96cb005c3babef8.tar.bz2 android-node-v8-02f3dd24f38983b3211bcec7e96cb005c3babef8.zip |
doc: fix unsafe writable stream code example
Update writable stream code example using async iterator to use safer
`finished()` method instead of a `finish` event to avoid uncaught
exceptions
Fixes: https://github.com/nodejs/node/issues/29397
PR-URL: https://github.com/nodejs/node/pull/29425
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Diffstat (limited to 'doc/api/stream.md')
-rw-r--r-- | doc/api/stream.md | 32 |
1 files changed, 26 insertions, 6 deletions
diff --git a/doc/api/stream.md b/doc/api/stream.md index 6510dec541..73659524ec 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -2559,6 +2559,7 @@ it is important to ensure the correct handling of backpressure and errors. ```js const { once } = require('events'); +const finished = util.promisify(stream.finished); const writable = fs.createWriteStream('./file'); @@ -2570,18 +2571,24 @@ const writable = fs.createWriteStream('./file'); } writable.end(); // Ensure completion without errors. - await once(writable, 'finish'); + await finished(writable); })(); ``` -In the above, errors on the write stream would be caught and thrown by the two -`once()` listeners, since `once()` will also handle `'error'` events. +In the above, errors on `write()` would be caught and thrown by the +`once()` listener for the `'drain'` event, since `once()` will also handle the +`'error'` event. To ensure completion of the write stream without errors, +it is safer to use the `finished()` method as above, instead of using the +`once()` listener for the `'finish'` event. Under certain cases, an `'error'` +event could be emitted by the writable stream after `'finish'` and as `once()` +will release the `'error'` handler on handling the `'finish'` event, it could +result in an unhandled error. -Alternatively the readable stream could be wrapped with `Readable.from()` and +Alternatively, the readable stream could be wrapped with `Readable.from()` and then piped via `.pipe()`: ```js -const { once } = require('events'); +const finished = util.promisify(stream.finished); const writable = fs.createWriteStream('./file'); @@ -2589,7 +2596,20 @@ const writable = fs.createWriteStream('./file'); const readable = Readable.from(iterator); readable.pipe(writable); // Ensure completion without errors. - await once(writable, 'finish'); + await finished(writable); +})(); +``` + +Or, using `stream.pipeline()` to pipe streams: + +```js +const pipeline = util.promisify(stream.pipeline); + +const writable = fs.createWriteStream('./file'); + +(async function() { + const readable = Readable.from(iterator); + await pipeline(readable, writable); })(); ``` |