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();
  // ...
});