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
インターフェイスのメソッドで、変換ストリームまたはその他の書き込み可能/読み取り可能なペアを介して現在のストリームを接続する連鎖可能な方法を提供します。
ストリームを接続すると、通常、接続している間はストリームがロックされ、他のリーダーがロックできなくなります。
構文
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
を介して中断することが可能です。
返値
transformStream
の readable
側です。
例外
TypeError
-
transformStream
のwritable
やreadable
プロパティが未定義です。
例
次の例(ライブ実行中の完全なコードについては PNG のチャンクをアンパック、ソースコードについては png-transform-stream を参照)では、画像が取得され、その本体が ReadableStream
として取得されます。
次に、読み取り可能なストリームのコンテンツをログに記録し、pipeThrough()
を使用して、グレースケールバージョンのストリームを作成する新しい関数に送信し、新しいストリームのコンテンツもログに記録します。
// 元の画像を取得
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
関連情報
ReadableStream()
コンストラクター- パイプチェーン