From 3ba64646eddf18ea555a4dbdb14cb7db9259d49a 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: explain stream.finished cleanup

PR-URL: https://github.com/nodejs/node/pull/28935
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
---
 doc/api/stream.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/api/stream.md b/doc/api/stream.md
index 62e30d0e8bd13b..5875fc3396180a 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1478,6 +1478,8 @@ added: v10.0.0
     **Default**: `true`.
 * `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.
@@ -1518,6 +1520,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: v10.0.0
@@ -1571,6 +1587,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.
+
 ### stream.Readable.from(iterable, [options])
 <!-- YAML
 added: v12.3.0