Fetch APIはここまで進化していた

外部との通信に使用するFetch。もはや使わないプロジェクトの方が珍しいレベルで頻繁に使用するFetch。

基本的な使い方は今も変わりませんが、レスポンスを少しずつ処理するストリーム、複数条件でのキャンセル、タイムアウト、バイト列の取得など、実務で役立つ周辺機能が地味に増えています。

この記事は、自分のためにAIにまとめてもらったFetch APIの現代技術を記事にしたものです。

実験的機能やブラウザ対応が限定的な機能は除外しています。またブラウザによって対応差があるものは明記します。

レスポンスを到着した分から処理する

response.json() や response.text() は、レスポンス本文を最後まで受け取ってから結果を返します。

APIレスポンスが小さければ十分ですが、長いテキスト、ログ、行単位のデータ、生成AIの出力などでは、到着した分から画面に表示したい場面があります。

Response.body は ReadableStream です。バイト列のストリームを TextDecoderStream に通すと、UTF-8のテキストとしてチャンクごとに扱えます。

async function readTextStream(url, onChunk) {
  const res = await fetch(url);

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }
  if (!res.body) {
    return;
  }

  const reader = res.body
    .pipeThrough(new TextDecoderStream())
    .getReader();

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

    onChunk(value);
  }
}

次のように使うと、サーバーが送信したテキストを少しずつ画面へ追加できます。

let output = '';

await readTextStream('/api/logs/live', (chunk) => {
  output += chunk;
  document.querySelector('#output').textContent = output;
});

ただし、チャンクはアプリケーション上の意味のある単位で届くとは限りません。たとえばJSON文字列の途中や、1行の途中で分割されることがあります。

行単位のデータなら改行でバッファリングする、JSONならNDJSONやServer-Sent Eventsなど、ストリーミングに適した形式をサーバー側とあわせて設計します。

対応状況:
Response.body と ReadableStream は広く利用できます。TextDecoderStream も主要ブラウザで利用可能です。古いブラウザやWebViewまで対象に含める場合は、対象環境で確認するか、ストリームを使わず response.text() で一括読み込みする代替経路を用意します。
textStream()という新しいメソッドを使えばさらに短く書くことができますが、まだchromeブラウザ以外未対応(執筆時時点)ですのでここでは紹介しません。

ユーザー操作とタイムアウトで通信を止める

検索語を入力するたびに候補を取得する画面や、時間のかかるダウンロードでは、不要になったリクエストを中断したいことがあります。

AbortController と AbortSignal を fetch() の signal に渡すと通信キャンセルを制御できます。

let currentController;

async function searchProducts(keyword) {
  // 前回の検索が残っていれば中断する
  currentController?.abort();
  currentController = new AbortController();

  try {
    const res = await fetch(
      `/api/products?q=${encodeURIComponent(keyword)}`,
      { signal: currentController.signal }
    );

    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } catch (error) {
    if (error.name === 'AbortError') return;
    throw error;
  }
}

タイムアウトだけを設定する場合は、AbortSignal.timeout() が使えます。

タイムアウトによる中断は TimeoutError として扱えるため、ユーザーがキャンセルした場合とメッセージを分けられます。

try {
  const response = await fetch('/api/report', {
    signal: AbortSignal.timeout(10_000)
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const report = await response.json();
} catch (error) {
  if (error.name === 'TimeoutError') {
    console.error('10秒以内に応答がありませんでした');
  } else {
    throw error;
  }
}

ユーザーキャンセルとタイムアウトを両方受け付けたい場合は、AbortSignal.any() で複数のシグナルをまとめます。

const controller = new AbortController();

const signal = AbortSignal.any([
  controller.signal,
  AbortSignal.timeout(10_000)
]);

cancelButton.addEventListener('click', () => controller.abort(), { once: true });

const response = await fetch('/api/export', { signal });

対応状況:
AbortController は広く利用できます。AbortSignal.timeout() と AbortSignal.any() は主要ブラウザで2024年から利用可能です。ただし古いブラウザ・古いWebViewをサポートする場合は未対応の可能性があります。必要に応じて機能検出を行い、setTimeout() と AbortController を組み合わせる代替実装を用意します。

Response.bytes()でUint8Arrayを受け取る

Response.bytes() はレスポンス本文を最後まで読み込み、Uint8Array として返します。

従来の arrayBuffer() より、バイト列を扱う意図がそのままコードに表れます。

const response = await fetch('/assets/sample.bin');

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const bytes = await response.bytes();
console.log(bytes.length);
console.log(bytes[0]);

ファイルシグネチャの確認、独自バイナリ形式の解析、Uint8Array をそのまま受け取るWeb APIとの連携などに向いています。画像や大きなファイルを単に表示・保存する目的なら、blob() の方が自然な場合もあります。

対応状況:
Response.bytes() はBaseline 2025の機能です。最新ブラウザでは使えますが、古いブラウザや端末では未対応の可能性があります。広い互換性が必要なら、response.arrayBuffer() の結果を Uint8Array で包む方法をフォールバックにします。

const bytes = 'bytes' in Response.prototype
  ? await response.bytes()
  : new Uint8Array(await response.arrayBuffer());

Response.json()は「読む」ためだけのメソッドではない

よく使う response.json() は、サーバーから来たJSONを読むインスタンスメソッドです。

一方、Response.json() はJSONを本文に持つ新しい Response を作る静的メソッドです。大文字小文字の違いだけではなく、役割が異なります。

// 受信したJSONを読む
const data = await response.json();

// JSONを返すResponseを作る
const jsonResponse = Response.json(
  { error: 'not found' },
  { status: 404 }
);

後者はService Workerでリクエストを横取りして応答を返すときや、Fetch API互換の Response を返すランタイム・テストコードで便利です。Content-Type: application/json を設定した Response を簡潔に作れます。

対応状況:
Response.json() は主要ブラウザで2023年から利用可能です。古い環境を対象にする場合は、new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } }) という従来の書き方も使えます。

参考・まとめ

参考:MDN: Using the Fetch API / MDN: AbortSignal: timeout() /MDN: Response.bytes()

本記事での機能の位置付け:

紹介してきた機能は、すべてが同じ時期に追加された「Fetch APIの新機能」ではありません。Fetch API本体、Streams API、DOM API、HTTP仕様が連携して、通信処理の選択肢を広げています。

分類主な機能この記事での扱い
Fetch APIResponse.body、Response.bytes()、Response.json()レスポンスを段階的に読む、バイト列を読む、JSONレスポンスを作る
Streams API / Encoding APIReadableStream、TextDecoderStream受信したテキストをチャンク単位で処理する
DOM APIAbortController、AbortSignal.timeout()、AbortSignal.any()ユーザー操作とタイムアウトで通信を中断する

以下は執筆時点で実験的、またはブラウザ対応が限定的ですので、本記事では採用判断の対象から外しています。

  • Response.textStream()、
  • ストリーミングアップロードで必要になる duplex: 'half'、
  • fetchLater()、
  • priority

タイトルとURLをコピーしました