Streams API

概念と使用方法

ストリーミングでは、ネットワーク経由で受信するリソースを小さなチャンクに分割し、少しずつ処理します。 これは、ブラウザーがウェブページに表示されるアセットを受信するときにとにかく行うことです — 動画がバッファされて徐々に再生可能になり、画像が読み込まれるにつれて徐々に表示されることもあります。

しかし、これはこれまで JavaScript で利用できたことはありません。 以前は、何らかの種類のリソース（動画、テキストファイルなど）を処理したい場合は、ファイル全体をダウンロードし、適切な形式にデシリアライズされるのを待ってから、完全に受信した後に全部まとめて処理する必要がありました。

Streams が JavaScript で利用できるようになったことで、これがすべて変わりました — クライアント側で利用可能になると、バッファ、文字列、または blob を生成せずに、JavaScript で少しずつ生データの処理を開始できます。

さらに利点もあります。 ストリームの開始または終了の検出、ストリームの連鎖、エラー処理と必要に応じたストリームのキャンセル、ストリームの読み取り速度への対応が可能です。

Streams の基本的な使用法は、応答をストリームとして利用可能にすることにかかっています。 例えば、成功したフェッチ要求によって返された応答の Body は、ReadableStream として公開できます。 その後、ReadableStream.getReader() で作成したリーダーを使用して読み取り、ReadableStream.cancel() でキャンセルできます。

より複雑な用途では、例えばサービスワーカー内でデータを処理するために、ReadableStream() コンストラクターを使用して独自のストリームを作成します。

WritableStream を使用してストリームにデータを書き込むこともできます。

ストリームのインターフェイス

読み取り可能なストリーム

ReadableStream

読み取り可能なデータのストリームを表します。 Fetch API の応答ストリーム、または開発者定義のストリーム（カスタムの ReadableStream() コンストラクターなど）を処理するために使用できます。

ReadableStreamDefaultReader

ネットワークから提供されたストリームデータ（フェッチ要求など）を読み取るために使用できるデフォルトのリーダーを表します。

ReadableStreamDefaultController

ReadableStream の状態と内部キューの制御を許可するコントローラーを表します。 デフォルトのコントローラーは、バイトストリームではないストリーム用です。

書き込み可能なストリーム

WritableStream

シンク（sink）と呼ばれる宛先にストリーミングデータを書き込むための標準的な抽象化を提供します。 このオブジェクトには、組み込みのバックプレッシャー（受信側のバッファあふれの予防）とキューイングが付属しています。

WritableStreamDefaultWriter

データのチャンクを書き込み可能なストリームに書き込むために使用できるデフォルトの書き込み可能なストリームのライターを表します。

WritableStreamDefaultController

WritableStream の状態の制御を許可するコントローラーを表します。 WritableStream を構築するとき、基になるシンクには、対応する WritableStreamDefaultController インスタンスが与えられて操作します。

関連するストリームの API と操作

ByteLengthQueuingStrategy

ストリームを構築するときに使用できる組み込みのバイト長キューイング戦略（byte length queuing strategy）を提供します。

CountQueuingStrategy

ストリームを構築するときに使用できる組み込みのチャンクカウントキューイング戦略（chunk counting queuing strategy）を提供します。

他の API の拡張

Request

新しい Request オブジェクトが構築されると、その RequestInit ディクショナリの body プロパティで ReadableStream を渡すことができます。 次に、この Request を WindowOrWorkerGlobalScope.fetch() に渡して、ストリームのフェッチを開始できます。

Body

成功したフェッチ要求によって返された応答の Body は、デフォルトで ReadableStream として公開され、リーダーを取りつけることができます。

ByteStream 関連のインターフェイス

ReadableStreamBYOBReader

開発者が提供するストリームデータの読み取りに使用できる BYOB（bring your own buffer、独自のバッファを持ち込む）リーダーを表します（カスタムの ReadableStream() コンストラクターなど）。

ReadableByteStreamController

ReadableStream の状態と内部キューの制御を許可するコントローラーを表します。 バイトストリームコントローラーは、バイトストリーム用です。

ReadableStreamBYOBRequest

ReadableByteStreamController 内のプルインリクエストを表します。

例

Streams API のドキュメントに合わせてサンプルのディレクトリを作成しました。 mdn/dom-examples/streams を参照してください。 例は次のとおりです。

• Simple stream pump（単純なストリームポンプ）: この例は、ReadableStream を使用してそのデータを別のストリームに渡す方法を示しています。
• Grayscale a PNG（PNG のグレースケール化）: この例は、PNG の ReadableStream をグレースケールに変換する方法を示しています。
• Simple random stream（単純なランダムストリーム）: この例は、カスタムストリームを使用してランダムな文字列を生成し、それらをチャンクとしてキューに入れてから、再度読み取る方法を示しています。
• Simple tee example（単純な tee の例）: この例は、単純なランダムストリームの例を拡張したもので、ストリームを tee 化して、両方の結果のストリームの独立して読み取る方法を示しています。
• Simple writer（単純なライター）: この例では、書き込み可能なストリームに書き込み、ストリームをデコードして、コンテンツを UI に書き込む方法を示します。
• Unpack chunks of a PNG（PNG のチャンクをアンパックする）: この例は、PNG ファイルのデータを PNG チャンクのストリームに変換することにより、pipeThrough() を使用して ReadableStream を他のデータ型のストリームに変換する方法を示します。

他の開発者による例

• Streams、Service Worker、および Fetch を含む進行状況インジケーター（英語）。

仕様

ブラウザーの互換性

ReadableStream

WritableStream

関連情報

• Streams API の概念
• 読み取り可能なストリームの使用
• 書き込み可能なストリームの使用