sse.js
is a flexible EventSource
replacement for JavaScript 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 package is designed to provide a usable replacement to
EventSource
that makes all of this possible: SSE
. It is a fully
compatible EventSource
polyfill so you should be able to do this if
you want/need to:
EventSource = SSE;
The most simple way to use SSE
is to create the SSE
object, attach
one or more listeners, and activate the stream:
var source = new SSE(url);
source.addEventListener('message', function(e) {
// Assuming we receive JSON-encoded data payloads:
var payload = JSON.parse(e.data);
console.log(payload);
});
source.stream();
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:
id
: the event ID, if present;null
otherwisedata
: 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;abort
, as a response to the stream being explicitely aborted by the client;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.
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:
var source = new SSE(url);
source.addEventListener('status', function(e) {
console.log('System status is now: ' e.data);
});
source.stream();
You can also register an event listener with the on<event>
style:
var source = new SSE(url);
source.onstatus = function(e) { ... };
You can mix both on<event>
and addEventListener()
. The on<event>
handler is always called first if it is defined.
var source = new SSE(url, {headers: {'Authorization': 'Bearer 0xdeadbeef'}});
To make a HTTP POST request, simply specify a payload
in the options:
var source = new SSE(url, {headers: {'Content-Type': 'text/plain'},
payload: 'Hello, world!'});
Alternatively, you can also manually override the HTTP method used to
perform the request, regardless of the presence of a payload
option, by
specifying the method
option:
var source = new SSE(url, {headers: {'Content-Type': 'text/plain'},
payload: 'Hello, world!',
method: 'GET'});
It is expected that the server will return the data in the following format, as defined here:
event: <type>\n
data: <data>\n
\n
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.
Name | Description |
---|---|
headers |
A map of additional headers to use on the HTTP request |
method |
Override HTTP method (defaults to GET , unless a payload is given, in which case it defaults to POST ) |
payload |
An optional request payload to sent with the request |
withCredentials |
If set to true , CORS requests will be set to include credentials |
- Internet Explorer 11 does not support arbitrary values in
CustomEvent
s. A dependency oncustom-event-polyfill
is necessary for IE11 compatibility. - Improve
XmlHttpRequest
error handling and connection states - Automatically reconnect with
Last-Event-ID