ump-plugin-eventsource

EventSource — Server-Sent Events (text/event-stream) client for UMP apps.

DOM-style API, mirrors the WHATWG HTML Living Standard so off-the-shelf SSE libraries (chat clients, notification streams, GraphQL-over-SSE, OpenAI streaming) can use the bare EventSource global.

Install

npm install ump-plugin-eventsource

Peer dependencies (must already be installed in your app):

• ump-core
• ump-native

Usage

import { EventSource } from 'ump-plugin-eventsource';

const es = new EventSource('https://api.example.com/stream');

es.onopen = () => console.log('connected');
es.onmessage = (ev) => console.log('message:', ev.data);
es.onerror = () => console.warn('connection error — auto-reconnecting');

// Named events go through addEventListener, not onmessage.
es.addEventListener('user-update', (ev) => {
    console.log('user-update:', ev.data, 'id=', ev.lastEventId);
});

// Close when done.
es.close();

Importing this module also installs globalThis.EventSource (only when the host hasn't already provided one), so libraries that reach for the bare global name keep working.

Constructor

new EventSource(url: string, init?: { withCredentials?: boolean })

| Arg | Notes | |-----|-------| | url | URL of the SSE endpoint. Used as the origin of dispatched events. | | init.withCredentials | Forwarded as a hint only — UMP fetch always sends platform credentials; v2 deferred. |

Instance properties

| Property | Notes | |----------|-------| | url | Read-only. The URL passed to the constructor. | | withCredentials | Read-only. | | readyState | CONNECTING (0), OPEN (1), CLOSED (2). | | onopen / onmessage / onerror | Property-style listeners. Only the default 'message' channel maps to onmessage — named events are addEventListener-only. | | CONNECTING / OPEN / CLOSED | Mirrored from the static constants. |

SSE field handling

| Field | Behavior | |-------|----------| | event: | Dispatches the next event under that name (not 'message'). | | data: | Appended to the event data buffer; multi-line data joined by \n. | | id: | Sticky — sets lastEventId for all subsequent events. Preserved across reconnects via Last-Event-ID. | | retry: | Updates the reconnect delay (ms). Default 3000ms. | | : (leading) | Comment line, ignored. |

Line terminators \n, \r\n, and \r are all accepted per spec.

Reconnect behavior

On any transport error or remote close (and unless you called close()), EventSource flips readyState back to CONNECTING, fires error, and re-opens after retry ms. The sticky id is sent as the Last-Event-ID request header on reconnect so the server can resume.

Migration from ump-native

In ump-native 0.1.x, EventSource was bundled with the main package. Starting 0.2.x, it ships as this separate plugin.

- import { EventSource } from 'ump-native';
+ import { EventSource } from 'ump-plugin-eventsource';

The global-install side-effect on globalThis.EventSource is preserved. No API changes.