
Security News
Deno 2.2 Improves Dependency Management and Expands Node.js Compatibility
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
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; null
otherwiselastEventId
: the last seen event ID, or the empty string if no event
with an ID was receiveddata
: the event data, unparsedSSE
, 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 SSE endpoint's response headers and the status code returned by the
server are exposed in the open
event that is fired at the beginning of
the stream, under the headers
and responseCode
properties,
respectivitely:
var source = new SSE(url);
source.addEventListener('open', function(e) {
console.log('Got a '
+ e.data.responseCode
+ ' response with headers: '
+ e.data.headers
);
});
source.stream();
The response headers are represented as a map of (lowercased) header names to array of header values.
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.
In a regular stream, you should expect to receive events in the following order:
readystatechange
event with a readyState
of CONNECTING (0)
;open
event, with the endpoint's responseCode
and headers
;readystatechange
event with a readyState
of OPEN (1)
;message
event for each received server-sent event, plus the
event-type-specific event for the same;When closing the stream, you should also expect:
readystatechange
event with a readyState
of CLOSED (2)
;abort
event.It is expected that the server will return the data in the following format, as defined here:
event: <type>\n
data: <data>\n
\n
withCredentials
supportThis 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.
CustomEvent
s. A dependency on custom-event-polyfill
is necessary
for IE11 compatibility.XmlHttpRequest
error handling and connection statessse.js
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.
FAQs
A flexible Server-Sent Events source; supports POST requests and custom headers
The npm package sse.js receives a total of 35,894 weekly downloads. As such, sse.js popularity was classified as popular.
We found that sse.js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.