From 9ca144e9cac84639273ff0d9de8d897d18fba0ab Mon Sep 17 00:00:00 2001
From: Renegade334 <contact.9a5d6388@renegade334.me.uk>
Date: Sat, 21 Sep 2024 14:23:09 +0100
Subject: [PATCH] doc: correct `cleanup` option in stream.(promises.)finished

---
 doc/api/stream.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/doc/api/stream.md b/doc/api/stream.md
index e18f456e8acfbf..a6897100f9832a 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -257,6 +257,11 @@ changes:
     - v18.14.0
     pr-url: https://github.com/nodejs/node/pull/46205
     description: Added support for `ReadableStream` and `WritableStream`.
+  - version:
+    - v19.1.0
+    - v18.13.0
+    pr-url: https://github.com/nodejs/node/pull/44862
+    description: The `cleanup` option was added.
 -->
 
 * `stream` {Stream|ReadableStream|WritableStream} A readable and/or writable
@@ -265,7 +270,9 @@ changes:
   * `error` {boolean|undefined}
   * `readable` {boolean|undefined}
   * `writable` {boolean|undefined}
-  * `signal`: {AbortSignal|undefined}
+  * `signal` {AbortSignal|undefined}
+  * `cleanup` {boolean} If `true`, removes the listeners registered by this function
+    before the promise is fulfilled. **Default:** `false`.
 * Returns: {Promise} Fulfills when the stream is no
   longer readable or writable.
 
@@ -301,6 +308,17 @@ rs.resume(); // Drain the stream.
 
 The `finished` API also provides a [callback version][stream-finished].
 
+`stream.finished()` leaves dangling event listeners (in particular
+`'error'`, `'end'`, `'finish'` and `'close'`) after the returned promise is
+resolved or rejected. 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 `options.cleanup` should be set to
+`true`:
+
+```js
+await finished(rs, { cleanup: true });
+```
+
 ### Object mode
 
 All streams created by Node.js APIs operate exclusively on strings, {Buffer},
@@ -2754,8 +2772,6 @@ changes:
     underlying stream will _not_ be aborted if the signal is aborted. The
     callback will get called with an `AbortError`. All registered
     listeners added by this function will also be removed.
-  * `cleanup` {boolean} remove all registered stream listeners.
-    **Default:** `false`.
 * `callback` {Function} A callback function that takes an optional error
   argument.
 * Returns: {Function} A cleanup function which removes all registered