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

destroyメソッドはNode.jsのStreamクラスのインスタンスで、ストリームを破棄し、関連するリソースを解放するメソッドです。このメソッドは、ストリームの処理を強制的に終了させたい場合や、エラーが発生してストリームを安全にクリーンアップしたい場合に非常に役立ちます。

destroyメソッドは、オプションでエラーオブジェクトを引数に取ることができます。エラーオブジェクトが渡された場合、ストリームはまず'error'イベントを発行し、そのエラーを処理する機会を提供します。その後、またはエラーオブジェクトが渡されなかった場合、ストリームは'close'イベントを発行します。'close'イベントは、ストリームに関連付けられているすべてのリソース（例えば、開いているファイルディスクリプタやネットワークソケットなど）が完全に解放されたことを示します。

このメソッドを呼び出すことで、進行中の非同期操作が中断され、ストリームの状態が「破壊済み」としてマークされます。一度破壊されたストリームは、それ以降のデータ操作を受け付けません。また、destroyメソッドは冪等性を持っています。つまり、すでに破壊されているストリームに対して複数回呼び出しても、追加の副作用はありません。これにより、誤って複数回呼び出してしまっても安全に動作します。ストリームのライフサイクルを適切に管理し、メモリリークやリソースリークを防ぐために重要な役割を果たすメソッドです。

Copy
1const streamInstance = require('stream').Readable();
2
3streamInstance.destroy(); // ストリームを破棄する
4
5// streamInstance.destroy(new Error('Optional error message')); // エラーを伴ってストリームを破棄する場合

error

• error: Error | null: ストリームの終了の原因となったエラーオブジェクト。指定しない場合はnullとなり、正常終了を示します。

Stream

Streamオブジェクト自身が返されます。これにより、メソッドチェーンでdestroyを呼び出すことが可能になります。