【Node.js24.x】Stream::finished()メソッドの使い方

finishedメソッドは、Node.jsのストリームの完了を効率的に監視するためのユーティリティメソッドです。ストリームとは、ファイル読み込みやネットワーク通信など、データの連続的な流れを扱うための仕組みです。

このfinishedメソッドは、特定のストリームが「完了」したとみなされる状態を検知し、その完了を通知します。ここでいう「完了」には、ストリームが正常にすべてのデータ処理を終えた場合（'end'または'finish'イベント）、ストリーム処理中にエラーが発生した場合（'error'イベント）、またはストリームが閉じられた場合（'close'イベント）のいずれもが含まれます。

システムエンジニアがストリームを扱う際、いつストリームの操作が完全に終了したのかを正確に知ることは非常に重要です。例えば、ストリーム処理が終わった後に使用したリソースを解放したり、次の処理を開始したりする場面で、このfinishedメソッドは欠かせない役割を果たします。

利用方法は、async/await構文と組み合わせてPromiseとして使用することも、コールバック関数を渡して非同期に通知を受け取ることも可能です。特に、複数のストリームをパイプ（pipe()メソッド）で接続してデータを変換・転送するような場合に、全体の処理が完了したことを確実に待つために頻繁に利用されます。ストリームの正常な終了だけでなく、途中で発生したエラーも適切に捕捉してくれますので、信頼性の高いアプリケーションを構築する上で不可欠なツールと言えます。

Copy
1import { finished } from 'node:stream/promises';
2import { Readable } from 'node:stream';
3
4const myStream = new Readable({
5  read() {
6    this.push('データ');
7    this.push(null);
8  }
9});
10
11async function handleStreamCompletion() {
12  try {
13    await finished(myStream, { cleanup: true, error: true });
14  } catch (error) {
15    // ストリーム処理中にエラーが発生した場合の処理
16  }
17}
18
19handleStreamCompletion();

stream, options, callback

• stream: stream: 完了を監視するストリームオブジェクト
• options: object: 監視オプションを指定するオブジェクト
• callback: function: ストリームが完了したときに呼び出されるコールバック関数

Promise

Stream.finished メソッドは、ストリームが完了したときに解決される Promise を返します。この Promise は、ストリームが正常に終了した場合は成功し、エラーが発生した場合は失敗します。