eventsource-parser

Install the package using npm to use it as a streaming parser for Server-Sent Events (SSE) in browsers, Node.js, or Deno.

npm install --save eventsource-parser

When configuring onError, you can choose to either terminate the stream or handle the error manually.

If you set onError: 'terminate', the stream will emit an error and stop. If you provide a custom function, you can perform side effects (like logging) without necessarily stopping the stream.

Critical Note: If the parser exceeds the maxBufferSize, it is considered unrecoverable. In this specific case, the stream will always error out with a ParseError (specifically with the type max-buffer-size-exceeded), even if you provided a custom error handler or a value other than 'terminate'.

To prevent unbounded memory growth from misbehaving servers or proxies, you can set maxBufferSize (in characters) in the createParser options.

If the combined size of the pending line buffer and the in-progress event's data buffer exceeds this limit, the parser emits a ParseError with type: 'max-buffer-size-exceeded' and terminates. Subsequent calls to .feed() will throw until .reset() is called.

const parser = createParser({
  maxBufferSize: 1024 * 1024, // 1 MB
  onEvent(event) {
    // …
  },
  onError(error) {
    if (error.type === 'max-buffer-size-exceeded') {
      // Handle error
    }
  },
})

The parser dispatches information through several configurable callbacks in ParserConfig:

• onEvent: Called when a complete event is parsed. Receives an object with { id, event, data }.
• onRetry: Called when a retry: [value] field is parsed. The value is an integer representing the reconnection time in milliseconds.
• onComment: Called when a line starting with : is encountered. The callback receives the comment string (stripping the leading colon and optional space).
• onError: Called when a ParseError occurs (e.g., max-buffer-size-exceeded, invalid-retry, or unknown-field).

If the server sends a retry field in the event stream, the parser triggers the onRetry callback provided in the createParser options. This callback receives the requested retry interval in milliseconds.

const parser = createParser({
  onRetry(retryInterval) {
    console.log('Server requested retry interval of %dms', retryInterval)
  },
  onEvent(event) {
    // …
  },
})

In environments supporting TransformStream (modern browsers, Node 18+), you can use EventSourceParserStream from the eventsource-parser/stream export. This allows you to pipe a readable stream through the parser.

Events are delivered directly through the stream rather than via a callback. The constructor accepts onComment, onRetry, maxBufferSize, and onError (which can be a function or the string 'terminate').

import {EventSourceParserStream} from 'eventsource-parser/stream'

const eventStream = response.body
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(new EventSourceParserStream({
    maxBufferSize: 1024 * 1024,
    onError: 'terminate',
  }))

By default, the parser ignores lines starting with : (comments). To process them, provide an onComment callback. Note that leading whitespace is not stripped from the comment value (e.g., : comment results in comment).

const parser = createParser({
  onComment(comment) {
    console.log('Received comment:', comment)
  },
  onEvent(event) {
    // …
  },
})

The core way to use the library is by creating a parser instance with createParser. You then manually feed chunks of data (partial or complete) into the parser using the .feed(chunk) method. The parser emits parsed messages via the onEvent callback once a complete message is received.

To reuse a parser for a new stream, you must call .reset().

import {createParser, type EventSourceMessage} from 'eventsource-parser'

function onEvent(event: EventSourceMessage) {
  console.log('Received event!')
  console.log('id: %s', event.id || '<none>')
  console.log('event: %s', event.event || '<none>')
  console.log('data: %s', event.data)
}

const parser = createParser({onEvent})
const sseStream = getSomeReadableStream() // Your data source

for await (const chunk of sseStream) {
  parser.feed(chunk)
}

// Reset to reuse for a new stream
parser.reset()