parse-sse

library0.0.0.1jsnpmunverified

`parse-sse` is a lightweight, spec-compliant JavaScript library designed for parsing Server-Sent Events (SSE) from a standard Web `Response` object, typically obtained via the native Fetch API. Currently at version 0.1.0, it is a new release focused on providing a robust and efficient way to consume streaming APIs. The library differentiates itself by being fully compatible with native `ReadableStream` and `TransformStream` interfaces, enabling maximum composability with other stream-based operations. It is particularly well-suited for integrating with modern streaming services like OpenAI and Anthropic, which extensively utilize SSE for real-time data delivery. As a relatively new package, a specific release cadence has not yet been established, but its focus on web platform standards and minimal dependencies suggests a stable foundation.

http-networking llm-agents

npm install parse-sse

github ↗package ↗

INSTALL

IMPORT

SIG · PARSE-SSE

parse-sse

http-networkingjavascriptv0.0.0.1

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.

parseServerSentEvents

✓ import { parseServerSentEvents } from 'parse-sse';

✗ const { parseServerSentEvents } = require('parse-sse');

`parse-sse` is an ESM-only package, requiring `import` syntax. Attempting to use `require()` will result in a runtime error.

ServerSentEventTransformStream

✓ import { ServerSentEventTransformStream } from 'parse-sse';

✗ const { ServerSentEventTransformStream } = require('parse-sse');

This named export is for advanced stream pipeline construction. Like all exports from `parse-sse`, it's ESM-only.

Demonstrates how to consume a streaming chat completion from OpenAI using `parse-sse` with the Fetch API, showing real-time output and handling the `[DONE]` signal.

import { parseServerSentEvents } from 'parse-sse'; const apiKey = process.env.OPENAI_API_KEY ?? 'YOUR_OPENAI_API_KEY_HERE'; async function getStreamingCompletion() { const response = await fetch('https://api.openai.com/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}`, }, body: JSON.stringify({ model: 'gpt-4', messages: [{ role: 'user', content: 'Tell me a story about a futuristic city.' }], stream: true, }), }); if (!response.body) { throw new Error('Response body is null, expected a ReadableStream.'); } console.log('--- Streaming Chat Completion ---\n'); for await (const event of parseServerSentEvents(response)) { if (event.data === '[DONE]') { console.log('\n--- Stream Ended ---'); break; } try { const data = JSON.parse(event.data); process.stdout.write(data.choices[0]?.delta?.content || ''); } catch (error) { console.error('Error parsing event data:', event.data, error); } } } getStreamingCompletion().catch(console.error);

Debug

Known issues

breaking`parse-sse` is an ESM-only package and explicitly requires Node.js version 20 or higher. Older Node.js versions or CommonJS environments are not supported.

fix

Ensure your project runs on Node.js 20+ and uses ES module syntax (`import`/`export`). For CommonJS projects, consider using a tool like `esm` or migrating to ESM.

affects: <=0.1.0

gotchaWhen using `ServerSentEventTransformStream` directly, the input stream is expected to consist of string chunks. If you are piping from a raw byte stream (e.g., `response.body`), you must pipe through a `TextDecoderStream` first to ensure proper Unicode decoding and chunk handling.

fix

Pipe your byte stream through `new TextDecoderStream()` before `ServerSentEventTransformStream`, e.g., `response.body.pipeThrough(new TextDecoderStream()).pipeThrough(new ServerSentEventTransformStream())`.

affects: >=0.1.0

gotchaServer-Sent Events are processed based on `\n\n` delimiters. If your `data` field contains literal newline characters that are *not* part of a JSON string or properly escaped, it can lead to misinterpretation by the parser, breaking multi-line data.

fix

Always serialize complex data (like multi-line strings or objects) within the `data` field as JSON, and then parse it on the client side, e.g., `JSON.parse(event.data)`. This ensures proper handling of internal newlines.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use CommonJS `require()` syntax in an ES module environment, which `parse-sse` exclusively supports.

fix

Change `const { parseServerSentEvents } = require('parse-sse');` to `import { parseServerSentEvents } from 'parse-sse';` and ensure your `package.json` has `"type": "module"` or your file has `.mjs` extension.

TypeError: parseServerSentEvents is not a function

Incorrectly importing the `parseServerSentEvents` function, often due to a mixed CommonJS/ESM environment issue or incorrect named import.

fix

Verify that your environment is set up for ES modules (Node.js 20+ and correct `package.json` `type` field) and that you are using `import { parseServerSentEvents } from 'parse-sse';`.

Error: Response body is null

The `Response` object from `fetch` did not contain a readable body, possibly due to a non-streaming response type, an error status, or the body already being consumed.

fix

Ensure the server is actually sending a stream (`Content-Type: text/event-stream`) and the `response.ok` is true. Handle cases where `response.body` might be `null` or already consumed before passing it to `parseServerSentEvents`.

TypeError: If you pass byte chunks, a TypeError will be thrown.

`ServerSentEventTransformStream` received byte chunks (e.g., from `response.body`) instead of decoded string chunks.

fix

Prepend a `TextDecoderStream` to the pipeline: `response.body.pipeThrough(new TextDecoderStream()).pipeThrough(new ServerSentEventTransformStream())`.

Upgrade

Version history

0.0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/sindresorhus/parse-sse ↗

packagehttps://www.npmjs.com/package/parse-sse ↗