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
は、パイプのプロセスが正常に完了した場合は履行され、エラーが発生した場合は拒否されます。
ストリームをパイプ接続すると、通常、接続している間はストリームがロックされ、他のリーダーがロックできなくなります。
構文
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
-
writableStream
やreadableStream
オブジェクトは、書き込み可能なストリーム/読み取り可能なストリームではないか、ストリームの一方または両方がロックされています。
例
// 元の画像を読み取る
fetch("png-logo.png")
// その body を ReadableStream として取得
.then((response) => response.body)
.then((body) => body.pipeThrough(new PNGTransformStream()))
.then((rs) => rs.pipeTo(new FinalDestinationStream()));
同じ例で await
使用すると次のようになります。
(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
関連情報
ReadableStream()
コンストラクター- パイプチェーン