doc: fix unsafe writable stream code example

ckarande · Trott · commit 02f3dd24f389 · 2019-09-05T21:08:06.000-07:00
Update writable stream code example using async iterator to use safer `finished()` method instead of a `finish` event to avoid uncaught exceptions Fixes: #29397 PR-URL: #29425 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
diff --git 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,26 +2571,45 @@ 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');
 
 (async function() {
   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);
 })();
 ```
 
