Registry / http-networking / fetch-event-stream

fetch-event-stream

library0.1.6jsnpmunverified

fetch-event-stream is a lightweight (741 bytes gzipped) utility designed to parse Server-Sent Events (SSE) from `fetch` responses using the native Web Streams API. It's currently at version 0.1.6 and has a frequent patch release cadence, addressing compatibility and feature enhancements. Unlike the browser's native `EventSource` which is limited to GET requests and lacks custom headers, `fetch-event-stream` allows any HTTP method (e.g., POST for APIs like Anthropic or OpenAI) and supports custom headers and JSON payloads, making it suitable for modern API interactions that often require authentication. It differentiates itself by leveraging native Web Streams without heavy polyfills, ensuring a small bundle size and broad compatibility across browsers, Node.js, Deno, Bun, Cloudflare Workers, and Web/Service Workers. This approach avoids the common pain point of bloated SDKs, such as the `openai` library's larger size due to stream polyfills, offering a more streamlined and performant solution for SSE consumption.

http-networking llm-agents

npm install fetch-event-stream

github ↗package ↗

INSTALL

IMPORT

SIG · FETCH-EVENT-STREAM

fetch-event-stream

http-networkingjavascriptv0.1.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

events

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

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

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

stream

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

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

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

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();

Debug

Known issues

gotchaOlder 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.

affects: <0.1.4

breakingThe 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.

affects: >=0.1.6

gotchaThe `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.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined

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", ... }

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

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.

Upgrade

Version history

0.1.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lukeed/fetch-event-stream ↗

packagehttps://www.npmjs.com/package/fetch-event-stream ↗