sse-ts

Forked from https://github.com/mpetazzoni/sse.js. Made the library strongly typed and added support for ES6 modules. So this library can now be imported as a ES6 module and compiled with TS.

sse-ts is a strongly-typed ES6 module-based flexible EventSource replacement for Typescript designed to consume Server-Sent Events (SSE) streams with more control and options than the standard EventSource. The main limitations of EventSource are that it only supports no-payload GET requests, and does not support specifying additional custom headers to the HTTP request. This library solves the problem by providing:

• Support for GET and POST requests to a SSE endpoint
• Support for additional headers that can be passed
• Support for withCredentials flag

Installation

npm i sse-ts

OR

yarn add sse-ts

Basic usage

The most simple way to use SSE is to create the SSE object, attach one or more listeners, and activate the stream:

import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            method: SSEOptionsMethod.GET
        };


const source = new SSE(backendURL, sseOptions);
source.addEventListener('message', (event: CustomEventType) => {
            const dataEvent = event as CustomEventDataType;
            // Assuming we receive JSON-encoded data payloads:
            var payload = JSON.parse(dataEvent.data);
            console.log(payload);
          });

source.stream();

Events

SSE implements the EventTarget interface (just like EventSource) and emits fully constructed Event objects. The type of the event corresponds to the Server-Sent Event's name, and the event's timestamp is the UNIX timestamp of the reception of the event.

Additionally, the events will have the following fields if the event type is CustomEventDataType:

• id: the event ID, if present; null otherwise
• data: the event data, unparsed

SSE, like EventSource, will emit the following events:

• open, when the first block of data is received from the event stream;
• error, if an error occurs while making the request;
• readystatechange, to notify of a change in the ready state of the event source.

Note that all events dispatched by SSE will have the event target initially set to the SSE object itself.

Listening for specific event types

The Server-Sent Events specification allows for arbitrary event types, as the event field of the event. The default event type is message, so you'll most likely want to register a listener for this kind of events. If you expect another type of events, simply register your callback with the appropriate event type:

import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            method: SSEOptionsMethod.GET
        };
        
const source = new SSE(backendURL, sseOptions);
source.addEventListener('status', (event: CustomEventType) => {
        const dataEvent = event as CustomEventDataType;
        console.log('System status is now: ' + dataEvent.data);
        });

        source.stream();

Passing custom headers

import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            headers: { 'Content-Type': 'application/json', 'api-key': "apiKey" },
            method: SSEOptionsMethod.GET,
        };

const source = new SSE(backendURL, sseOptions);
        

Making a POST request and overriding the HTTP method

To make a HTTP POST request, simply specify a payload in the options:

import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            headers: { 'Content-Type': 'application/json', 'api-key': "apiKey" },
            method: SSEOptionsMethod.POST,
            payload: JSON.stringify({
                foo: "bar"
            })
        };

const source = new SSE(backendURL, sseOptions);

withCredentials support

This EventSource polyfill supports the withCredentials option to request that the outgoing HTTP request be made with a CORS credentials mode of include, as per the HTML Living Standard.

Options reference

Name	Description
headers	A map of additional headers to use on the HTTP request
method	(Required) Override HTTP method (GET or POST)
payload	The request payload to sent with the request
withCredentials	If set to true, CORS requests will be set to include credentials

TODOs and caveats

• Internet Explorer 11 does not support arbitrary values in CustomEvents. A dependency on custom-event-polyfill is necessary for IE11 compatibility.
• Improve XmlHttpRequest error handling and connection states
• Automatically reconnect with Last-Event-ID