Server-Sent Events with Fetch API

Common errors

• ReferenceError: require is not defined

  cause Attempting to import `fetch-event-stream` using CommonJS `require()` syntax in an ESM context (e.g., in a Node.js project with `"type": "module"` or a browser environment).
  fix Use ESM `import` syntax: `import { events, stream } from 'fetch-event-stream';`.

• Uncaught (in promise) Response { status: 401, statusText: "Unauthorized", ... }

  cause The `stream()` function threw an HTTP `Response` object because the API request resulted in a non-`2xx` status code (e.g., 401 Unauthorized, 404 Not Found, 500 Internal Server Error).
  fix Wrap the `stream()` call in a `try...catch` block and specifically handle `Response` errors: `try { ... } catch (error) { if (error instanceof Response) { console.error('API Error:', error.status, await error.text()); } else { throw error; } }`.

• TypeError: (intermediate value)(intermediate value) is not async iterable

  cause Attempting to use `for await (const event of stream)` on a `ReadableStream` in an environment (typically an older browser or specific runtime) that does not fully support asynchronous iteration of `ReadableStream` objects, potentially with an `fetch-event-stream` version prior to `0.1.4`.
  fix Ensure you are using `fetch-event-stream@0.1.4` or newer. If the problem persists, verify your runtime environment's Web Streams API compatibility. For extremely old environments, you might need to use `events()` with a custom stream reader.

Warnings

• gotcha Older browser environments (non-canary versions prior to `fetch-event-stream@0.1.4`) might not fully support async iteration (`for await (let ... of ...)`) of `ReadableStream`. Version `0.1.4` introduced an internal rewrite to address this compatibility.
  Fix: Ensure you are using `fetch-event-stream@0.1.4` or newer for broadest browser compatibility with `for await...of` syntax.
• breaking The parsing logic for `event.id` was modified in `v0.1.6`. Previously, all `event.id` values were coerced to `number` if possible. Now, `event.id` is only converted to `number` if the value is *exactly* a number string (e.g., '123' -> 123). Strings like '003' will remain '003' (string), which might break existing numeric comparisons.
  Fix: Review existing code that relies on `event.id` being a number. Explicitly cast `event.id` to `Number(event.id)` if numeric comparison is always expected, or update logic to handle potential string values.
• gotcha The `stream()` convenience function will `throw` the raw `Response` object if the `fetch` call results in a non-`2xx` status code. This differs from standard `fetch` behavior where `response.ok` is false but the promise still resolves.
  Fix: Always wrap calls to `stream()` in a `try...catch` block. Within the `catch` block, check if the error `instanceof Response` to handle API errors gracefully, accessing `error.status` and `error.text()` for details.

Install

• npm install fetch-event-stream npm
• yarn add fetch-event-stream yarn
• pnpm add fetch-event-stream pnpm

Imports

• events
  wrong:

  const { events } = require('fetch-event-stream');

  correct:

  import { events } from 'fetch-event-stream';

  Package is ESM-only; CommonJS `require` is not supported. For Deno, use `https://deno.land/x/fetch_event_stream`.
• stream
  wrong:

  const { stream } = require('fetch-event-stream');

  correct:

  import { stream } from 'fetch-event-stream';

  Package is ESM-only; CommonJS `require` is not supported. For Deno, use `https://deno.land/x/fetch_event_stream`.

Quickstart

Demonstrates connecting to a streaming OpenAI API endpoint using the `stream` utility, handling API keys, request body, and iterating over Server-Sent Events.

import { stream } from 'fetch-event-stream';

const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? '';

async function getOpenAIStream() {
  try {
    const events = await stream('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${OPENAI_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: 'gpt-3.5-turbo',
        messages: [
          { role: 'system', content: 'You are a helpful assistant.' },
          { role: 'user', content: 'What is the capital of France?' }
        ],
        stream: true
      })
    });

    for await (const event of events) {
      if (event.data === '[DONE]') {
        console.log('Stream finished.');
        break;
      }
      try {
        const parsedData = JSON.parse(event.data);
        // Process your parsed SSE data here
        console.log('Received:', parsedData);
      } catch (e) {
        console.error('Failed to parse event data:', event.data, e);
      }
    }
  } catch (error) {
    if (error instanceof Response) {
      const errorText = await error.text();
      console.error('API Error:', error.status, errorText);
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

getOpenAIStream();