Skip to content

Commit d3cdaed

Browse files
committed
doc: stream.finished cleanup
1 parent 5c42578 commit d3cdaed

File tree

1 file changed

+20
-0
lines changed

1 file changed

+20
-0
lines changed

doc/api/stream.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1298,6 +1298,8 @@ added: REPLACEME
12981298
* `stream` {Stream} A readable and/or writable stream.
12991299
* `callback` {Function} A callback function that takes an optional error
13001300
argument.
1301+
* Returns: {Function} A cleanup function which removes all registered
1302+
listeners.
13011303

13021304
A function to get notified when a stream is no longer readable, writable
13031305
or has experienced an error or a premature close event.
@@ -1338,6 +1340,20 @@ run().catch(console.error);
13381340
rs.resume(); // drain the stream
13391341
```
13401342

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+
13411357
### stream.pipeline(...streams[, callback])
13421358
<!-- YAML
13431359
added: REPLACEME
@@ -1391,6 +1407,10 @@ async function run() {
13911407
run().catch(console.error);
13921408
```
13931409

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+
13941414
## API for Stream Implementers
13951415

13961416
<!--type=misc-->

0 commit comments

Comments
 (0)