ReadableStream: pipeTo() メソッド

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.

pipeTo()ReadableStream インターフェイスのメソッドで、現在の ReadableStream を与えられた WritableStream にパイプ接続します。返される Promise は、パイプのプロセスが正常に完了した場合は履行され、エラーが発生した場合は拒否されます。

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

構文

js
pipeTo(destination)
pipeTo(destination, options)

引数

destination

ReadableStream の最終的な宛先として機能する WritableStream

options 省略可

writable ストリームにパイプ接続するときに使用するオプションです。 利用できるオプションは以下の通りです。

preventClose

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

preventAbort

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

preventCancel

この値を true に設定すると、出力先の WritableStream でエラーが発生しても、入力元の ReadableStream を取り消すことができなくなります。 この場合、メソッドは、入力元のエラー、または入力元を取り消す際に発生するエラーで拒否されるプロミスを返します。 また、出力先の書き込み可能なストリームが閉じられたり開始されたりした場合、入力元の読み取り可能なストリームは取り消されなくなります。 この場合、メソッドは、閉じられたストリームへのパイプ処理に失敗したことを示すエラー、または入力元を取り消す際に発生するエラーとともに、拒否されるプロミスを返します。

signal

AbortSignal オブジェクトを設定すると、進行中のパイプ操作が対応する AbortController から中止できます。

返値

パイプのプロセスが完了したときに解決する Promise です。

例外

TypeError

writableStreamreadableStream オブジェクトは、書き込み可能なストリーム/読み取り可能なストリームではないか、ストリームの一方または両方がロックされています。

js
// 元の画像を読み取る
fetch("png-logo.png")
  // その body を ReadableStream として取得
  .then((response) => response.body)
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => rs.pipeTo(new FinalDestinationStream()));

同じ例で await 使用すると次のようになります。

js
(async () => {
  // 元の画像を読み取る
  const response = await fetch("png-logo.png");
  // その body を ReadableStream として取得
  response.body
    .pipeThrough(new PNGTransformStream())
    .pipeTo(new FinalDestinationStream());
})();

仕様書

Specification
Streams Standard
# ref-for-rs-pipe-to④

ブラウザーの互換性

BCD tables only load in the browser

関連情報