stream.finished(stream[, options], callback)

版本历史

版本	变更
v19.5.0	Added support for `ReadableStream` and `WritableStream`.
v15.11.0	The `signal` option was added.
v14.0.0	The `finished(stream, cb)` will wait for the `'close'` event before invoking the callback. The implementation tries to detect legacy streams and only apply this behavior to streams which are expected to emit `'close'`.
v14.0.0	Emitting `'close'` before `'end'` on a `Readable` stream will cause an `ERR_STREAM_PREMATURE_CLOSE` error.
v14.0.0	Callback will be invoked on streams which have already finished before the call to `finished(stream, cb)`.
v10.0.0	新增于: v10.0.0

stream <Stream> | <ReadableStream> | <WritableStream> 一个可读和/或可写的流/网络流。
options <Object>
- error <boolean> 如果设置为 false，则调用 emit('error', err) 不会被视为完成。默认值: true。
- readable <boolean> 当设置为 false 时，即使流仍然可读，也会在流结束时调用回调。默认值： true。
- writable <boolean> 当设置为 false 时，即使流仍然可写，也会在流结束时调用回调。默认值： true。
- signal <AbortSignal> 允许中止等待流完成。如果信号被中止，底层流不会被中止。回调函数会被调用，并带有 AbortError。所有通过此函数添加的已注册监听器也将被移除。
callback <Function> 一个可选接收错误参数的回调函数。
返回：<Function> 一个清理函数，用于移除所有注册的监听器。

一个用于在流不再可读、不可写或发生错误或提前关闭事件时接收通知的函数。

【A function to get notified when a stream is no longer readable, writable or has experienced an error or a premature close event.】

const { finished } = require('node:stream');
const fs = require('node:fs');

const rs = fs.createReadStream('archive.tar');

finished(rs, (err) => {
  if (err) {
    console.error('Stream failed.', err);
  } else {
    console.log('Stream is done reading.');
  }
});

rs.resume(); // Drain the stream.

在错误处理场景中尤其有用，例如流被提前销毁（如中止的 HTTP 请求），并且不会触发 'end' 或 'finish'。

【Especially useful in error handling scenarios where a stream is destroyed prematurely (like an aborted HTTP request), and will not emit 'end' or 'finish'.】

finished API 提供承诺版本。

【The finished API provides promise version.】

stream.finished() 在调用 callback 后会留下悬挂的事件监听器（特别是 'error'、'end'、'finish' 和 'close'）。这样做的原因是为了防止由于流实现不正确而导致的意外 'error' 事件引起程序意外崩溃。如果不希望出现这种行为，则需要在回调中调用返回的清理函数：

const cleanup = finished(rs, (err) => {
  cleanup();
  // ...
});