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;var source = new SSE(url, options);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);
});Like EventSource, SSE will automatically execute the request and
start streaming. If you want to disable this behavior, and be more
specific as to when the request should be triggered, you can pass
the start: false option and later call the stream() method:
var source = new SSE(url, {start: false});
source.addEventListener('message', (e) => { ... });
// ... later on
source.stream();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'});| 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 |
start |
Automatically execute the request and start streaming (defaults to true) |
debug |
Log debug messages to the console about received chunks and dispatched events (defaults to false) |
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;nullotherwiselastEventId: the last seen event ID, or the empty string if no event with an ID was receiveddata: 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.
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.
SSE.js does not (yet) automatically reconnect on failure; you can listen
for the abort event and decide whether to reconnect and restart the
event stream by calling stream().
SSE.js will set the Last-Event-ID header on reconnection to the last
seen event ID value (if any), as per the EventSource specification.
- Internet Explorer 11 does not support arbitrary values in
CustomEvents. A dependency oncustom-event-polyfillis necessary for IE11 compatibility. - Improve
XmlHttpRequesterror handling and connection states
Increment the package version with npm version, and publish to GitHub
and NPM.js:
$ npm version {major,minor,patch}
$ git publish --tags
$ npm publish --otp <otp>
Then, create a new GitHub release for the new tagged version.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent