Parse Server-Sent Events

Common errors

• ReferenceError: require is not defined

  cause 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

  cause 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

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

  cause `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())`.

Warnings

• 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.
• gotcha When 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())`.
• gotcha Server-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.

Install

• npm install parse-sse npm
• yarn add parse-sse yarn
• pnpm add parse-sse pnpm

Imports

• parseServerSentEvents
  wrong:

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

  correct:

  import { parseServerSentEvents } from 'parse-sse';

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

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

  correct:

  import { ServerSentEventTransformStream } from 'parse-sse';

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

Quickstart

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