3.0.0 • Published 12 months ago

eventsource-parser v3.0.0

Weekly downloads
-
License
MIT
Repository
github
Last release
12 months ago

eventsource-parser

npm versionnpm bundle sizenpm weekly downloads

A streaming parser for server-sent events/eventsource, without any assumptions about how the actual stream of data is retrieved. It is intended to be a building block for clients and polyfills in javascript environments such as browsers, node.js and deno.

If you are looking for a modern client implementation, see eventsource-client.

You create an instance of the parser, and feed it chunks of data - partial or complete, and the parse emits parsed messages once it receives a complete message. A TransformStream variant is also available for environments that support it (modern browsers, Node 18 and higher).

Other modules in the EventSource family:

  • eventsource-client: modern, feature rich eventsource client for browsers, node.js, bun, deno and other modern JavaScript environments.
  • eventsource-encoder: encodes messages in the EventSource/Server-Sent Events format.
  • eventsource: Node.js polyfill for the WhatWG EventSource API.

!NOTE Migrating from eventsource-parser 1.x/2.x? See the migration guide.

Installation

npm install --save eventsource-parser

Usage

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

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

const parser = createParser({onEvent})
const sseStream = getSomeReadableStream()

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

// If you want to re-use the parser for a new stream of events, make sure to reset it!
parser.reset()
console.log('Done!')

Retry intervals

If the server sends a retry field in the event stream, the parser will call any onRetry callback specified to the createParser function:

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

Parse errors

If the parser encounters an error while parsing, it will call any onError callback provided to the createParser function:

import {type ParseError} from 'eventsource-parser'

const parser = createParser({
  onError(error: ParseError) {
    console.error('Error parsing event:', error)
    if (error.type === 'invalid-field') {
      console.error('Field name:', error.field)
      console.error('Field value:', error.value)
      console.error('Line:', error.line)
    } else if (error.type === 'invalid-retry') {
      console.error('Invalid retry interval:', error.value)
    }
  },
  onEvent(event) {
    // …
  },
})

Note that invalid-field errors will usually be called for any invalid data - not only data shaped as field: value. This is because the EventSource specification says to treat anything prior to a : as the field name. Use the error.line property to get the full line that caused the error.

!NOTE When encountering the end of a stream, calling .reset({consume: true}) on the parser to flush any remaining data and reset the parser state. This will trigger the onError callback if the pending data is not a valid event.

Comments

The parser will ignore comments (lines starting with :) by default. If you want to handle comments, you can provide an onComment callback to the createParser function:

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

!NOTE Leading whitespace is not stripped from comments, eg : comment will give comment as the comment value, not comment (note the leading space).

Stream usage

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

const eventStream = response.body
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(new EventSourceParserStream())

Note that the TransformStream is exposed under a separate export (eventsource-parser/stream), in order to maximize compatibility with environments that do not have the TransformStream constructor available.

License

MIT © Espen Hovlandsdal

eventsource@chat-bots/commoncustom-gpt-api@trelent/openai-streamsryan-test1ryan-test2mingdao-web-mo@everything-registry/sub-chunk-1623custom-gpt-user@hackdance/agents-coresupanovel@helixai/chat-widget@sshkeda/aiarakoodevtapformtangdy_chatgpttaokwiz-cliwechaty-web-panelxmllmsparkai-jssparkaiv2-jssparkaiv3-jssparkaiv4-jssparkaiv5-jssparkaiv6-jssparkaiv7-jsspiceflowtext-to-aitext@devahmadsalameh/vercel-ai@braintrust/proxy@blocklet/pages-kit@blocklet/ai-kit@blocklet/ai-runtime@blocklet/aigne-sdk@princejoogie/chatgpt-cli@rbxdiscord/chatjs-proincjsongpt-jslattis-editorinexusinkejsi-knew-that-filehackburgerhamnet-editorhydrogen-js-sdklin-chatgptllm-api-clientmamba-chat-ailoft-editorllm-playground-chainluffy-chatgptkoishi-plugin-chatgptkoishi-plugin-chatgpt-editmbeeman-text-editormcf-r-editor@watercrawl/nodejs@wfatec/chatgpt@webriq-pagebuilder/sanity-plugin-input-component-gpt3@wp2/nextjs@twinklepkg/chatgpt@tzzack/chatgpt@typeflowai/workflows@thingcode/node-red-plugin-openai@trigger.dev/core@valiantpepper/chatgpt@valiantpepper/chatgpt-streamable@voiceflow/sdk-runtime@vertesia/api-fetch-client@vercel/ai-utils@yhostc/chatgpt@xx-johnwick-xx/cloud9@zalastax/nolb-events@zenghongtu/chatgpt@zhengxs/ernie-api@zhengxs/wechaty-plugin-assistantandy-chatgptandrew-layer@zhujunsan/chatgpt-apiagent-formationagent-dexterabccorea-jsabcaskcorea-jsai-utils.jsai_dryamvladaimixaireaderaero-chataiai-azyriai-connectai-connectoradccorea-jsadcorea-jsai-karelai-hjki2n3iuai-proxyai-sdk-solid-updatedai-njkcad81ai-stream
3.0.0-beta.0

12 months ago

3.0.0

12 months ago

2.0.1

1 year ago

2.0.0

1 year ago

1.1.2

2 years ago

1.1.1

2 years ago

1.1.0

2 years ago

1.0.0

3 years ago

0.1.0

3 years ago

0.0.5

3 years ago

0.0.4

3 years ago

0.0.3

3 years ago

0.0.2

3 years ago