eventsource-client

The eventsource-client package provides a way to consume Server-Sent Events (SSE) using modern web standards like fetch and AsyncIterators.

While the core createEventSource function is marked as @internal and intended for use by environment-specific entry points, the client instance it returns provides the following public interface:

Consumption Patterns

1. Async Iteration (Recommended)

Use the for await...of syntax to consume messages as they arrive. This is the most idiomatic way to handle the stream.

2. Callback Pattern

Provide an onMessage callback in the options object to handle incoming EventSourceMessage objects.

Client Instance API

• connect(): Initiates or re-establishes the connection.
• close(): Manually closes the connection and stops reconnection attempts.
• lastEventId: A getter that returns the id of the last received message.
• url: A getter that returns the current URL (useful if redirects occurred).
• readyState: A getter that returns the current state (CONNECTING, OPEN, or CLOSED).
• [Symbol.asyncIterator]: Enables the for await...of loop.

// Example: Using Async Iteration
// Note: You would typically import the environment-specific client,
// not the internal createEventSource directly.

for await (const message of eventSource) {
  console.log('Received message:', message.data);
  console.log('Message ID:', message.id);
}

Instead of an async iterator, you can provide an onMessage callback in the configuration object. This callback receives an object with {data, event, id}.

You can check the connection state using es.readyState (which returns 'open', 'closed', or 'connecting') and access the current es.lastEventId.

import {createEventSource} from 'eventsource-client'

const es = createEventSource({
  url: 'https://my-server.com/sse',

  onMessage: ({data, event, id}) => {
    console.log('Data: %s', data)
    console.log('Event ID: %s', id) // Note: can be undefined
    console.log('Event: %s', event) // Note: can be undefined
  },

  // your `fetch()` implementation of choice, or `globalThis.fetch` if not set
  fetch: myFetch,
})

console.log(es.readyState) // `open`, `closed` or `connecting`
console.log(es.lastEventId)

// Later, to terminate and prevent reconnections:
es.close()

You can consume SSE messages using the for await...of syntax. Each yielded object contains {data, event, id}.

Important: The connection is not automatically closed when you break out of the loop. You must manually call es.close() to terminate the connection and prevent further reconnections.

import {createEventSource} from 'eventsource-client'

const es = createEventSource({
  url: 'https://my-server.com/sse',

  // your `fetch()` implementation of choice, or `globalThis.fetch` if not set
  fetch: myFetch,
})

let seenMessages = 0
for await (const {data, event, id} of es) {
  console.log('Data: %s', data)
  console.log('Event ID: %s', id) // Note: can be undefined
  console.log('Event: %s', event) // Note: can be undefined

  if (++seenMessages === 10) {
    break
  }
}

// IMPORTANT: EventSource is _not_ closed automatically when breaking out of
// loop. You must manually call `close()` to close the connection.
es.close()

When initializing an EventSourceClient, you provide an EventSourceOptions object. This object allows you to configure the connection URL, lifecycle callbacks, and underlying fetch request parameters.

Lifecycle Callbacks

• onMessage: Fired when a new EventSourceMessage is received.
• onConnect: Fired when the connection is established (including reconnects).
• onScheduleReconnect: Fired when a reconnect is scheduled. Receives an object { delay: number } indicating the millisecond delay.
• onDisconnect: Fired when the connection is broken (the client will still attempt to reconnect unless close() is called).
• onComment: Fired when a comment is received. The comment string has one leading space trimmed if present.

Request Configuration

Options like headers, mode, credentials, method, redirect, referrer, and referrerPolicy are passed to the underlying fetch implementation to control the HTTP request.

const options: EventSourceOptions = {
  url: 'https://example.com/events',
  onMessage: (event) => console.log('New message:', event),
  onConnect: () => console.log('Connected!'),
  onScheduleReconnect: ({ delay }) => console.log(`Reconnecting in ${delay}ms`),
  headers: {
    'Authorization': 'Bearer token'
  }
};