From d3cdaedf6345669fbc64bf7d12bf87c8af2e05fa Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Fri, 2 Aug 2019 08:59:44 +0200
Subject: [PATCH] doc: stream.finished cleanup

---
 doc/api/stream.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/api/stream.md b/doc/api/stream.md
index 705b58a31c5ce9..943146dee90494 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1298,6 +1298,8 @@ added: REPLACEME
 * `stream` {Stream} A readable and/or writable stream.
 * `callback` {Function} A callback function that takes an optional error
   argument.
+* Returns: {Function} A cleanup function which removes all registered
+  listeners.
 
 A function to get notified when a stream is no longer readable, writable
 or has experienced an error or a premature close event.
@@ -1338,6 +1340,20 @@ run().catch(console.error);
 rs.resume(); // drain the stream
 ```
 
+`stream.finished()` leaves dangling event listeners (in particular
+`'error'`, `'end'`, `'finish'` and `'close'`) after `callback` has been
+invoked. The reason for this is so that unexpected `'error'` events (due to
+incorrect stream implementations) do not cause unexpected crashes.
+If this is unwanted behavior then the returned cleanup function needs to be
+invoked in the callback:
+
+```js
+const cleanup = finished(...streams, err => {
+  cleanup();
+  // ...
+});
+```
+
 ### stream.pipeline(...streams[, callback])
 <!-- YAML
 added: REPLACEME
@@ -1391,6 +1407,10 @@ async function run() {
 run().catch(console.error);
 ```
 
+`stream.pipeline()` leaves dangling event listeners on the streams
+after the `callback` has been invoked. In the case of reuse of streams after
+failure, this can cause event listener leaks and swallowed errors.
+
 ## API for Stream Implementers
 
 <!--type=misc-->