Node.js stream.finished(stream[, options], callback)用法及代码示例

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

参数

• stream <Stream> 可读和/或可写流。
• options <Object>
  • error <boolean> 如果设置为 false ，则对 emit('error', err) 的调用不会被视为已完成。 默认： true 。
  • readable <boolean> 当设置为 false 时，将在流结束时调用回调，即使流可能仍然可读。 默认： true 。
  • writable <boolean> 当设置为 false 时，将在流结束时调用回调，即使流可能仍然是可写的。 默认： true 。
  • signal <AbortSignal>允许中止等待流完成。底层流将不是如果信号被中止，则被中止。回调将被调用AbortError.此函数添加的所有已注册侦听器也将被删除。
• callback <Function> 采用可选错误参数的回调函数。
• 返回： <Function> 清除所有已注册侦听器的清理函数。

当流不再可读、可写或遇到错误或过早关闭事件时获取通知的函数。

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

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' 的错误处理场景中特别有用。

finished API 提供了 Promise 版本：

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

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

async function run() {
  await finished(rs);
  console.log('Stream is done reading.');
}

run().catch(console.error);
rs.resume(); // Drain the stream.

stream.finished() 在调用 callback 后留下悬空事件侦听器(特别是 'error' 、 'end' 、 'finish' 和 'close' )。这样做的原因是意外的 'error' 事件(由于不正确的流实现)不会导致意外的崩溃。如果这是不需要的行为，则需要在回调中调用返回的清理函数：

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