express-sse

Fork Differences

This project was forked from dpskvn/express-sse and introduces the following changes:

Heartbeat/ping event

Adds support for a ping event that can be used to keep idle connections alive through some networking middleware like haproxy.

Specify options.pingInterval with the desired heartbeat interval in ms.

The heartbeat event name will default to ping unless overridden with options.pingEvent.

new SSE([], { pingInterval: 20_000, pingEvent: 'thump' })

This approach can be utilized from the frontend to also detect stale connections (expect a ping event every N seconds.)

An alternative approach to this would be to emit a comment, which is not currently supported by this library.

Change initial event behavior

The original initial event implementation had the following unwanted behavior: When a new client connected, the initial event would be re-broadcast to all connected clients.

This has been changed to the expected approach of broadcasting the initial event only to new clients.

Make initial event optional

The initial event defaulted to [] when not defined. This implementation changes the default to be undefined and not being broadcast unless explicitly specified.

Retry support

SSE supports a retry field which instructs the client to change the default reconnection timeout.

Set options.retry to a value in milliseconds and the first event emitted will include a retry header field.

new SSE([], { retry: 5_000 });

Omit IDs option

The constructor options support .noID to skip assigning IDs to events that do not explicitly have one.

An Express middleware for quick'n'easy server-sent events.

Support for express without compression

The res.flush call is made optional, which enabled support for express without the compression middleware.

Error handling while setting headers

The header setting parts that can throw have been wrapped in a try/catch

The original README follows with the installation links replaced.

About

express-sse is meant to keep things simple. You need to send server-sent events without too many complications and fallbacks? This is the library to do so.

Installation:

npm install --save @takadenoshi/express-sse

or

yarn add @takadenoshi/express-sse

Usage example:

Options:

You can pass an optional options object to the constructor. Currently it only supports changing the way initial data is treated. If you set isSerialized to false, the initial data is sent as a single event. The default value is true.

var sse = new SSE(["array", "containing", "initial", "content", "(optional)"], { isSerialized: false, initialEvent: 'optional initial event name' });

Server:

var SSE = require('@takadenoshi/express-sse');
var sse = new SSE(["array", "containing", "initial", "content", "(optional)"]);

...

app.get('/stream', sse.init);

...

sse.send(content);
sse.send(content, eventName);
sse.send(content, eventName, customID);
sse.updateInit(["array", "containing", "new", "content"]);
sse.serialize(["array", "to", "be", "sent", "as", "serialized", "events"]);

Client:

var es = new EventSource('/stream');

es.onmessage = function (event) {
  ...
};

es.addEventListener(eventName, function (event) {
  ...
});