@@ -1298,6 +1298,8 @@ added: REPLACEME
1298
1298
* ` stream ` {Stream} A readable and/or writable stream.
1299
1299
* ` callback ` {Function} A callback function that takes an optional error
1300
1300
argument.
1301
+ * Returns: {Function} A cleanup function which removes all registered
1302
+ listeners.
1301
1303
1302
1304
A function to get notified when a stream is no longer readable, writable
1303
1305
or has experienced an error or a premature close event.
@@ -1338,6 +1340,20 @@ run().catch(console.error);
1338
1340
rs .resume (); // drain the stream
1339
1341
```
1340
1342
1343
+ ` stream.finished() ` leaves dangling event listeners (in particular
1344
+ ` 'error' ` , ` 'end' ` , ` 'finish' ` and ` 'close' ` ) after ` callback ` has been
1345
+ invoked. The reason for this is so that unexpected ` 'error' ` events (due to
1346
+ incorrect stream implementations) do not cause unexpected crashes.
1347
+ If this is unwanted behavior then the returned cleanup function needs to be
1348
+ invoked in the callback:
1349
+
1350
+ ``` js
1351
+ const cleanup = finished (... streams, err => {
1352
+ cleanup ();
1353
+ // ...
1354
+ });
1355
+ ```
1356
+
1341
1357
### stream.pipeline(...streams[ , callback] )
1342
1358
<!-- YAML
1343
1359
added: REPLACEME
@@ -1391,6 +1407,10 @@ async function run() {
1391
1407
run ().catch (console .error );
1392
1408
```
1393
1409
1410
+ ` stream.pipeline() ` leaves dangling event listeners on the streams
1411
+ after the ` callback ` has been invoked. In the case of reuse of streams after
1412
+ failure, this can cause event listener leaks and swallowed errors.
1413
+
1394
1414
## API for Stream Implementers
1395
1415
1396
1416
<!-- type=misc-->
0 commit comments