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

Transformメソッドは、Node.jsのStreamモジュールにおいて、書き込まれたデータを内部で加工し、異なる形式や内容のデータとして読み出し可能な状態に変換する処理を実行する機能を提供するメソッドです。これは、stream.Writable（書き込み可能）とstream.Readable（読み出し可能）の両方のインターフェースを実装したDuplexストリームの一種として機能します。

ストリームパイプラインの中間に位置し、入力データを受け取って加工処理を施した後、その結果を出力データとして次のストリームへ供給する仲介役を担います。開発者がこの機能を活用するには、Transformの概念に基づいた独自の変換ロジックを定義する必要があります。具体的には、_transform()という内部メソッドを実装することで、入力データチャンクごとに適用される変換処理を記述し、変換後のデータをpush()メソッドで出力します。

例えば、テキストデータのエンコード変換、ファイルの圧縮や解凍、データ内容の暗号化や復号化、あるいは特定のデータフォーマットから別のフォーマットへの変換など、多岐にわたるデータ加工処理の実装に利用されます。このように、データフローを透過的に操作し、データの形を効率的に変更できるため、Node.jsアプリケーションにおける複雑なデータ処理パイプラインを構築する上で不可欠な要素となっています。

Copy
1const { Transform } = require('stream');
2
3const transformStream = new Transform({
4  transform(chunk, encoding, callback) {
5    // chunk（入力データ）を加工し、this.push()で出力する
6    // 例: 入力データを大文字に変換して出力
7    this.push(chunk.toString().toUpperCase());
8    // 処理が完了したらcallback()を呼び出す
9    callback();
10  }
11});

options

• options: TransformStream を設定するためのオプションオブジェクト
  • writable: boolean: この TransformStream を書き込み可能にするかどうか (デフォルト: true)
  • readable: boolean: この TransformStream を読み取り可能にするかどうか (デフォルト: true)
  • allowHalfOpen: boolean: 書き込み側が閉じられた後も、読み取り側が開いたままになることを許可するかどうか (デフォルト: false)
  • decodeStrings: boolean: 文字列を Buffer にデコードするかどうか (デフォルト: true)
  • encoding: string: 出力されるデータのエンコーディング (デフォルト: null)
  • objectMode: boolean: オブジェクトモードで動作するかどうか (デフォルト: false)
  • highWaterMark: number: 内部バッファの最大サイズ (デフォルト: 16 * 1024)
  • transform: function: データを変換する関数。(chunk, encoding) => void または (chunk, encoding, callback) => void
  • flush: function: ストリームの終わりに呼ばれる関数。(callback) => void
  • readableObjectMode: boolean: 読み取り側がオブジェクトモードで動作するかどうか (デフォルト: objectMode)
  • writableObjectMode: boolean: 書き込み側がオブジェクトモードで動作するかどうか (デフォルト: objectMode)

Transform

Stream.Transform メソッドは、新しい Transform ストリームインスタンスを返します。このインスタンスは、入力データを処理し、変換されたデータを後続のストリームに渡すことができます。