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

isDisturbedメソッドは、Node.jsのStreamモジュールに属し、特定のストリームインスタンスが「消費された」状態にあるかどうかを判定するメソッドです。このメソッドは、主に読み込み可能なストリームであるReadableストリームの現在の状態を把握するために利用されます。

ストリームが「消費された」状態とは、一度でもストリームからデータが読み取られたり、ストリームがクローズされたり、エラーが発生したりした場合を指します。より具体的には、stream.pipe()メソッドによる別のストリームへのパイプ処理、for await...of構文による非同期イテレーション、あるいはstream.read()メソッドによる手動でのデータ読み取りなど、ストリームからデータが取り出される操作が行われた後にisDisturbed()を呼び出すとtrueを返します。これらの操作は、ストリームが既に何らかの形で利用され、内部バッファのデータが消費されたことを意味します。

このメソッドの主な目的は、ストリームが既に利用され始めているかどうかを示すことで、開発者がストリームを誤って再利用したり、データが既に失われている可能性のあるストリームに対して不適切な操作を行ったりするのを防ぐことです。例えば、一度消費されたReadableストリームを再び別の場所にパイプしようとすると、期待する結果が得られない可能性があるため、isDisturbedメソッドでその状態を事前に確認できます。これは、ストリームの適切なライフサイクル管理を支援する重要なツールであり、ストリームが消費されていればtrue、そうでなければfalseを返します。

Copy
1const stream = require('node:stream');
2const myStreamInstance = new stream.Readable({ read() {} });
3
4const isStreamDisturbed = stream.isDisturbed(myStreamInstance);

stream

• stream: Stream: チェック対象のStreamオブジェクト

boolean

このメソッドは、ストリームが内部状態の変更を伴う操作（例えば、データ読み取りや書き込み）によって「妨げられている」かどうかを示す真偽値を返します。