diff --git a/doc/api/stream.md b/doc/api/stream.md index 0011796c369..03171f4a2e1 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1481,6 +1481,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. @@ -1521,6 +1523,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)