ReadableStream: pipeThrough() メソッド

Baseline 2022

Newly available

Since June 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

pipeThrough()ReadableStream インターフェイスのメソッドで、変換ストリームまたはその他の書き込み可能/読み取り可能なペアを介して現在のストリームを接続する連鎖可能な方法を提供します。

ストリームを接続すると、通常、接続している間はストリームがロックされ、他のリーダーがロックできなくなります。

構文

js
pipeThrough(transformStream)
pipeThrough(transformStream, options)

引数

transformStream

読み取り可能なストリームと書き込み可能なストリームで構成され、データをある形式から別の形式に変換する TransformStream(または構造 {writable, readable} のオブジェクト)。 書き込み可能なストリーム(writable stream)に書き込まれたデータは、読み取り可能なストリーム(readable stream)によって何らかの変換された状態で読み取ることができます。 例えば、TextDecoder ではバイトが書き込まれ、そこから文字列が読み取られ、動画デコーダーではエンコードされたバイトが書き込まれ、非圧縮動画フレームが読み取られます。

options 省略可

書き込み可能な (writable) ストリームに接続するときに使用するオプションです。利用可能なオプションは次の通りです。

preventClose

これを true に設定すると入力元の ReadableStream を閉じても、出力先の WritableStream が閉じられることはなくなります。 このメソッドは、出力先を閉じる際にエラーが発生しない限り、この処理が完全に終了すると、履行されたプロミスを返します。

preventAbort

これを true に設定すると、入力元の ReadableStream でエラーが発生しても、出力先の WritableStream を中断させることができなくなります。 このメソッドは、入力元のエラー、または出力先を停止させる際に発生したエラーを含むプロミスを返します。

preventCancel

これを true に設定すると、出力先の WritableStream でエラーが発生しても、入力元の ReadableStream をキャンセルすることができなくなります。 この場合、このメソッドは、入力元のエラー、または入力元を取り消す際に発生したエラーを含む拒否されたプロミス を返します。 さらに、出力先の書き込み可能なストリームが閉じられたり開始された場合、入力元の読み取り可能なストリームは取り消されることはありません。 この場合、このメソッドは、閉じられたストリームへの接続に失敗したことを示すエラー、または入力元を取り消す際に発生する任意のエラーと共に、拒否されたプロミスを返します。

signal

AbortSignal オブジェクトに設定されている場合、 進行中のパイプ操作は、対応する AbortController を介して中断することが可能です。

返値

transformStreamreadable 側です。

例外

TypeError

transformStreamwritablereadable プロパティが未定義です。

次の例(ライブ実行中の完全なコードについては PNG のチャンクをアンパック、ソースコードについては png-transform-stream を参照)では、画像が取得され、その本体が ReadableStream として取得されます。

次に、読み取り可能なストリームのコンテンツをログに記録し、pipeThrough() を使用して、グレースケールバージョンのストリームを作成する新しい関数に送信し、新しいストリームのコンテンツもログに記録します。

js
// 元の画像を取得
fetch("png-logo.png")
  // その body を ReadableStream として取得
  .then((response) => response.body)
  .then((rs) => logReadableStream("Fetch Response Stream", rs))
  // 元の画像からグレースケール PNG ストリームを作成
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => logReadableStream("PNG Chunk Stream", rs));

仕様書

Specification
Streams Standard
# ref-for-rs-pipe-through②

ブラウザーの互換性

BCD tables only load in the browser

関連情報