ReadableStream: ReadableStream() コンストラクター

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2020年1月.

ReadableStream() コンストラクターは、指定されたハンドラーから読み取り可能なストリームのオブジェクトを作成して返します。

すべての引数は技術的にオプションですが、 underlyingSource を省略すると、ソースを持たないストリームになり、そこから読み込むことができなくなることに注意してください（リーダーは決して解決されないプロミスを返します）。

構文

js
new ReadableStream()
new ReadableStream(underlyingSource)
new ReadableStream(underlyingSource, queuingStrategy)

引数

underlyingSource 省略可

構築されたストリームのインスタンスの動作を定義するメソッドとプロパティを含むオブジェクト。 underlyingSource には次のものを含めることができます。

start (controller) 省略可

これは、オブジェクトが構築されるとすぐに呼び出されるメソッドです。このメソッドの内容は開発者が定義し、ストリームのソースへのアクセスを取得し、ストリーム機能を設定するために必要な他のすべての操作を行う必要があります。このプロセスを非同期で実行する場合、成功または失敗を通知するプロミスを返すことができます。このメソッドに渡される controller 引数は、 ReadableStreamDefaultController または ReadableByteStreamController を type プロパティの値に応じて指定します。開発者はこれを使用して、セットアップ中にストリームを制御できます。

pull (controller) 省略可

このメソッドは、開発者が定義し、ストリームの内部にあるチャンクのキューがいっぱいになっていない場合、最高水準点に達するまで繰り返し呼び出されます。 pull() がプロミスを返す場合、そのプロミスが満たされるまで再び呼び出されません。プロミスが拒否された場合、ストリームはエラーになります。このメソッドに渡される controller 引数は、 ReadableStreamDefaultController または ReadableByteStreamController を type プロパティの値に応じて指定します。開発者はこれを使用して、より多くのチャンクが読み取られるようストリームを制御できます。この関数は start() が完全に終了するまで呼び出されません。さらに、この関数は少なくとも一つのチャンクがキューに入れられるか、BYOB リクエストが履行された場合にのみ繰り返し呼び出されます。

cancel (reason) 省略可

このメソッドは、開発者が定義し、ストリームがキャンセルされることをアプリが通知した場合に呼び出されます（例えば、ReadableStream.cancel() が呼び出された場合）。内容は、ストリームのソースへのアクセスを解放するために必要なことを行う必要があります。このプロセスが非同期の場合、成功または失敗を通知するプロミスを返すことができます。 reason 引数には、ストリームがキャンセルされた理由を説明する文字列が含まれています。

type 省略可

このプロパティは、どの種類の読み取り可能なストリームが処理されるかを制御します。 "bytes" に設定された値が含まれている場合、渡されるコントローラーオブジェクトは、 BYOB （独自のバッファーを持ち込む）/バイトストリームを処理できる ReadableByteStreamController になります。含まれていない場合、渡されるコントローラーは ReadableStreamDefaultController になります。

autoAllocateChunkSize 省略可

バイトストリームの場合、開発者は autoAllocateChunkSize に正の整数値を設定して、ストリームの自動割り当て機能をオンにできます。これを設定すると、ストリームの実装は、必要なときに自動的に ReadableByteStreamController.byobRequest に指定したサイズのビューバッファーを確保するようになります。

既定の ReadableStreamDefaultReader でゼロコピー転送を使用するためには、この設定をしなければなりません。設定されていない場合、既定のリーダーはデータをストリームしますが、 ReadableByteStreamController.byobRequest は常に null となり、コンシューマーへの転送はストリーム内のキューを経由しなければなりません。

queuingStrategy 省略可

オプションでストリームのキューイング戦略を定義するオブジェクト。これには次の 2 つの引数が必要です。

highWaterMark

負でない整数 — これは、バックプレッシャーが適用される前に内部キューに含めることができるチャンクの総数を定義します。

size(chunk)

引数 chunk を含むメソッド — これは、各チャンクに使用するサイズをバイト単位で示します。

メモ: 独自のカスタム queuingStrategy を定義するか、このオブジェクト値に ByteLengthQueuingStrategy または CountQueuingStrategy のインスタンスを使用できます。 queuingStrategy が指定されていない場合、使用される既定値は、最高水準点が 1 の CountQueuingStrategy と同じです。

js
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();

      // ストリームに文字列を追加
      controller.enqueue(string);

      // それを画面に表示
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);

    button.addEventListener("click", () => {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // この例では実際には pull は必要ありません
  },
  cancel() {
    // リーダーがキャンセルされた場合に呼び出されるため、
    // 文字列の生成を停止する必要があります
    clearInterval(interval);
  },
});