From 32bb58ba9cff3f1f27e3275625b9a45864d94e7c Mon Sep 17 00:00:00 2001
From: Chetan Karande <kchetan.tech@gmail.com>
Date: Tue, 3 Sep 2019 13:34:36 -0400
Subject: [PATCH] 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>
---
 doc/api/stream.md | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/doc/api/stream.md b/doc/api/stream.md
index 064b23d78faa9c..7fc4dd4452e433 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -2556,6 +2556,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');
 
@@ -2567,18 +2568,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');
 
@@ -2586,7 +2593,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);
 })();
 ```