本文へ移動

k8o

お問い合わせ

255文字以内で入力してください

GitHub Issueからのお問い合わせもお待ちしております。

Blog

公開: 2026年4月5日(日)更新: 2026年11月9日(月)約20分で読めます

Readable Byte Streamsでバイナリを読み込む

Readable Byte Streamsは、読み取り側が確保したバッファにバイナリデータを書き込ませるReadableStreamです。fetchのレスポンスの先頭だけを読んだり、1つのバッファを使い回したりできます。

Newly availableReadable byte streams2026年〜
  • Chrome89
  • Edge89
  • Firefox102
  • Safari26.4

はじめに

Readable Byte Streamsは、type: 'bytes'を指定して作る、バイト列のためのReadableStreamです。BYOBリーダーを使うと、読み取り側が確保したバッファにデータを直接書き込ませられます。Safari 26.4が対応して、Baseline 2026に入りました。

レスポンスやファイルの全体を1つのArrayBufferにするときは、response.arrayBuffer()やblob.arrayBuffer()を使います。先頭の数バイトだけを読む、決まった大きさのバッファを使い回して大きなデータを最後まで読む、といった読む量と置き場所を自分で決めたい場面でBYOBリーダーを使います。fetch()のレスポンスのbodyとBlobのstream()はバイトストリームなので、そのままBYOBリーダーを取れます。

js
const response = await fetch(location.href);
const reader = response.body.getReader({ mode: 'byob' });
const { value } = await reader.read(new Uint8Array(15));
console.log(new TextDecoder().decode(value));

ブラウザで動かすと、そのページのHTMLの先頭15バイトを受け取り、<!doctype html>で始まるページなら<!doctype html>が出ます。どのブラウザでも同じです。1回のread()ではviewの一部しか埋まらないこともあり、read(view, { min: 15 })と書くと15バイト揃うまで待ちます。minもどのブラウザでも使えます。

new ReadableStream()のコンストラクタにデータの供給方法を定義すれば、ストリームを自分で作ることもできます。以下では、データを供給する側をデータソース側、リーダーで読む側を読み取り側と呼びます。

通常のReadableStreamではチャンクは内部キューを経由して読み取り側に届きます。大きなバイナリデータを扱う場合は、キューの経由がオーバーヘッドになることがあります。Readable Byte Streamsは、条件が揃えば内部キューを経由せず読み取り側のバッファに直接データを書き込む経路を提供します。

通常のストリームでバイナリデータを読む

ReadableStreamを自分で作って、バイナリデータを読む例です。以降のコード例では、sourceはファイルやソケットなどのデータソースを表す擬似的なオブジェクトです。

ReadableStreamのコンストラクタにはpull関数を渡します。ストリームがデータを必要とするたびにこの関数が呼ばれ、controller.enqueueでチャンクをキューに追加します。

ts
const stream = new ReadableStream({
  async pull(controller) {
    // 1024バイト分のバッファを確保してデータを読み取る
    const chunk = new Uint8Array(1024);
    const bytesRead = await source.read(chunk);

    if (bytesRead === 0) {
      // データの終端に達したらストリームを閉じる
      controller.close();
    } else {
      // 読み取ったバイト数分だけのビューを作ってキューに追加
      controller.enqueue(new Uint8Array(chunk.buffer, 0, bytesRead));
    }
  },
});

読み取り側ではgetReader()でリーダーを取得し、read()を繰り返し呼びます。

ts
const reader = stream.getReader();

const chunks: Uint8Array[] = [];
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

// すべてのチャンクを1つのバッファに結合
const totalLength = chunks.reduce((sum, c) => sum + c.byteLength, 0);
const result = new Uint8Array(totalLength);
let offset = 0;
for (const chunk of chunks) {
  result.set(chunk, offset);
  offset += chunk.byteLength;
}

チャンクは内部キューを経由して届くため、最終的に1つのバッファにまとめたい場合は結合のためのコピーが必要です。

バイトストリームで同じデータを読む

Readable Byte Streamsでは、読み取り側が自分でバッファを用意し、データソースにそのバッファへ直接書き込んでもらえます。自分のバッファを持ち込むこの仕組みを、BYOB(Bring Your Own Buffer)と呼びます。

コンストラクタにtype: 'bytes'を指定するとバイトストリームになります。pull関数で受け取るコントローラーは通常と異なり、byobRequestというプロパティを持ちます。これは、読み取り側がこのバッファにデータを書き込むよう求めていることを表すオブジェクトです。

js
const stream = new ReadableStream({
  type: 'bytes',

  async pull(controller) {
    // controller.byobRequestは読み取り側が渡したバッファへの参照
    // このバッファに直接データを書き込む
    const view = controller.byobRequest.view;
    const bytesRead = await source.read(
      new Uint8Array(view.buffer, view.byteOffset, view.byteLength),
    );

    if (bytesRead === 0) {
      controller.close();
      controller.byobRequest.respond(0);
    } else {
      // 書き込んだバイト数を通知
      controller.byobRequest.respond(bytesRead);
    }
  },
});

データの終端でclose()を呼んだら、続けてbyobRequest.respond(0)で0バイト書き込んだことを伝えます。BYOBリーダーのread()が待っているところでclose()だけを呼ぶと、そのread()はいつまでも終わりません。どのブラウザでも、respond(0)を足すとdone: trueが返ります。

読み取り側ではgetReader({ mode: 'byob' })でBYOBリーダーを取得します。通常のread()と異なり、BYOBリーダーのread()には書き込み先のメモリ領域をUint8Arrayで指定します。データソースはそのメモリ領域に直接データを書き込みます。

以下はデータの総サイズが事前にわかっている場合の例です。1つのバッファを確保し、未使用部分を順番に渡していきます。バッファが埋まったら、doneを待たずにループを抜けます。埋まったあとに長さ0のviewでread()を呼ぶと、どのブラウザでもTypeErrorになります。

ts
const reader = stream.getReader({ mode: 'byob' });

// 書き込み先のメモリ領域を確保する
let buffer = new ArrayBuffer(knownSize);
let offset = 0;

// 埋まったら抜ける。長さ0のviewを渡すとread()がTypeErrorになる
while (offset < buffer.byteLength) {
  // bufferの未使用部分をUint8Arrayで指定して渡す
  const view = new Uint8Array(buffer, offset, buffer.byteLength - offset);
  // read(view)は「viewが指すメモリ領域にデータを書き込んで」という意味
  const { done, value } = await reader.read(view);

  if (value) {
    // read()後は渡したviewが使用不可になり、valueから取り戻す
    buffer = value.buffer;
    offset += value.byteLength;
  }

  if (done) break;
}

const result = new Uint8Array(buffer, 0, offset);

内部キューが空でbyobRequestが使われた場合、キューを経由せず読み取り側のバッファに直接データが書き込まれます。通常のストリームのようにチャンクを配列に蓄積して結合する処理も不要です。

なお、データの総サイズが事前にわからない場合は、バッファの拡張処理が必要になります。

ReadableByteStreamController

バイトストリームのpullで受け取るコントローラーはReadableByteStreamControllerです。先ほどの例ではbyobRequestを使いましたが、読み取り側がBYOBリーダーを使っていない場合や、キューにデータが残っている場合はbyobRequestがnullになります。その場合は通常のストリームと同様にenqueueでキューにデータを追加します。

getReader()で読み取った場合は、データソース側のpullでbyobRequestがnullになるため、enqueueでデータを渡します。

js
// データソース側: byobRequestの有無で分岐
const stream = new ReadableStream({
  type: 'bytes',

  async pull(controller) {
    if (controller.byobRequest) {
      // BYOBリーダーが使われている場合: 直接書き込み
      const view = controller.byobRequest.view;
      const bytesRead = await source.read(
        new Uint8Array(view.buffer, view.byteOffset, view.byteLength),
      );

      if (bytesRead === 0) {
        controller.close();
        controller.byobRequest.respond(0);
      } else {
        controller.byobRequest.respond(bytesRead);
      }
    } else {
      // 通常のリーダーが使われている場合: キューに追加
      const chunk = new Uint8Array(1024);
      const bytesRead = await source.read(chunk);

      if (bytesRead === 0) {
        controller.close();
      } else {
        controller.enqueue(new Uint8Array(chunk.buffer, 0, bytesRead));
      }
    }
  },
});

// 読み取り側: 通常のリーダーで読み取る
// BYOBリーダーとは異なり、バッファを渡す必要がない
const reader = stream.getReader();

const chunks = [];
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

ただし、通常のリーダーで読むとキューを経由するので、読み取り側のバッファへの直接書き込みにはなりません。

バッファの所有権

BYOBリーダーのread(view)を呼ぶと、渡したviewは使用不可(detached)になります。これは、データの書き込み中にアプリケーション側が同じメモリ領域を変更してしまうことを防ぐためです。書き込みが完了すると、戻り値のvalueから同じメモリ領域にアクセスできるようになります。

js
const view = new Uint8Array(new ArrayBuffer(1024));
const { value } = await reader.read(view);

// viewはdetachedなので再利用してはいけない
// 書き込まれたデータはvalueから読める
console.log(value[0]);

データソース側でも同様に、byobRequest.respond()を呼んだ時点で、取り出しておいたbyobRequest.viewはdetachedになり、controller.byobRequestはnullに戻ります。どのブラウザでも、read(view)を呼んだ直後のview.byteLengthも、respond()の後のview.byteLengthも0になります。

value.bufferは渡したバッファと同じ大きさのまま戻ってくるので、次のread()にそれを渡せば、1つのバッファを使い回して大きなファイルを最後まで読めます。

js
// fileはinput要素などで受け取ったFile
const reader = file.stream().getReader({ mode: 'byob' });
let buffer = new ArrayBuffer(65536);
let total = 0;

while (true) {
  const { done, value } = await reader.read(new Uint8Array(buffer));
  if (done) break;
  // valueには、今回書き込まれたバイト列が入っている
  total += value.byteLength;
  // 戻ってきたメモリを次のread()に渡す
  buffer = value.buffer;
}

console.log(total);

1MBのFileを64KBのバッファで読むと、どのブラウザでも16回のread()で読み終わり、value.bufferは毎回64KBのままです。

autoAllocateChunkSize

バイトストリームの例ではBYOBリーダーを使いましたが、既存のコードが通常のgetReader()を使っている場合もあります。autoAllocateChunkSizeを指定すると、通常のリーダーからの読み取り時にストリームが自動でバッファを確保し、データソース側でbyobRequestを通じた書き込みが利用できるようになります。ただし、キューにデータが残っている場合は通常通りbyobRequestがnullになります。

js
const stream = new ReadableStream({
  type: 'bytes',
  // 通常のリーダーからの読み取り時に自動で1024バイトのバッファを確保
  autoAllocateChunkSize: 1024,

  async pull(controller) {
    if (!controller.byobRequest) {
      // キューにデータが残っている場合はbyobRequestがnullになるため、何もしない
      return;
    }

    const view = controller.byobRequest.view;
    const bytesRead = await source.read(
      new Uint8Array(view.buffer, view.byteOffset, view.byteLength),
    );

    if (bytesRead === 0) {
      controller.close();
      controller.byobRequest.respond(0);
    } else {
      controller.byobRequest.respond(bytesRead);
    }
  },
});

// BYOBリーダーではなく通常のリーダーでも動作する
const reader = stream.getReader();
const { value } = await reader.read();

autoAllocateChunkSizeを指定しない場合、通常のリーダーではbyobRequestが常にnullになります。BYOBリーダーと通常のリーダーの両方で読めるようにするには、autoAllocateChunkSizeを指定するか、ReadableByteStreamControllerの節の例のようにbyobRequestの有無で分岐します。

おわりに

Readable Byte Streamsは、条件が揃えば内部キューを経由せず、読み取り側のバッファへ直接書き込めるストリームです。BYOBリーダーで読む量と置き場所を決められ、autoAllocateChunkSizeを指定すれば通常のリーダーからも同じ書き込みを使えます。