better-sse

Better SSE

A dead simple, dependency-less, spec-compliant server-side events implementation for Node, written in TypeScript.

This package aims to be the easiest to use, most compliant and most streamlined solution to server-side events with Node that is framework agnostic and feature rich.

Please consider starring the project on GitHub ⭐.

Why use Server-sent Events?

Server-sent events (SSE) is a standardised protocol that allows web-servers to push data to clients without the need for alternative mechanisms such as pinging or long-polling.

Using SSE can allow for significant savings in bandwidth and battery life on portable devices, and will work with your existing infrastructure as it operates directly over the HTTP protocol without the need for the connection upgrade that WebSockets require.

Compared to WebSockets it has comparable performance and bandwidth usage, especially over HTTP/2, and natively includes event ID generation and automatic reconnection when clients are disconnected.

• Comparison: Server-sent Events vs WebSockets vs Polling
• WHATWG standards section for server-sent events
• MDN guide to server-sent events

Highlights

• Compatible with all popular Node HTTP frameworks (http, Express, Koa, Fastify, etc.)
• Fully written in TypeScript (+ ships with types directly).
• Thoroughly tested (+ 100% code coverage!).
• Comprehensively documented with guides and API documentation.
• Channels allow you to broadcast events to many clients at once.
• Configurable reconnection time, message serialization and data sanitization (but with good defaults).
• Trust or ignore the client-given last event ID.
• Automatically send keep-alive pings to keep connections open.
• Add or override the response status code and headers.
• Fine-grained control by either sending individual fields of events or sending full events with simple helpers.
• Pipe streams and iterables directly from the server to the client as a stream of events.
• Support for popular EventStream polyfills event-source-polyfill and eventsource-polyfill.

See a comparison with other Node SSE libraries in the documentation.

Installation

# npm
npm install better-sse

# Yarn
yarn add better-sse

# pnpm
pnpm add better-sse

Better SSE ships with types built in. No need to install from @types for TypeScript users!

Usage

The following example shows usage with Express, but Better SSE works with any web-server framework (that uses the underlying Node HTTP module).

See the Recipes section of the documentation for use with other frameworks and libraries.

---

Use sessions to push events to clients:

// Server
import {createSession} from "better-sse";

app.get("/sse", async (req, res) => {
	const session = await createSession(req, res);

	session.push("Hello world!");
});

// Client
const sse = new EventSource("/sse");

sse.addEventListener("message", ({data}) => {
	console.log(data);
});

---

Use channels to send events to many clients at once:

import {createSession, createChannel} from "better-sse";

const channel = createChannel();

app.get("/sse", async (req, res) => {
	const session = await createSession(req, res);

	channel.register(session);

	channel.broadcast("A user has joined.", "join-notification");
});

---

Loop over sync and async iterables and send each value as an event:

const session = await createSession(req, res);

const list = [1, 2, 3];

await session.iterate(list);

---

Pipe readable stream data to the client as a stream of events:

const session = await createSession(req, res);

const stream = Readable.from([1, 2, 3]);

await session.stream(stream);

---

Check the API documentation and live examples for information on getting more fine-tuned control over your data such as managing event IDs, data serialization, event filtering, dispatch controls and more!

Documentation

API documentation, getting started guides and usage with other frameworks is available on GitHub.

Contributing

This library is always open to contributions, whether it be code, bug reports, documentation or anything else.

Please submit suggestions, bugs and issues to the GitHub issues page.

For code or documentation changes, submit a pull request on GitHub.

Local Development

Install Node:

curl -L https://git.io/n-install | bash
n auto

Install pnpm:

npm i -g pnpm

Install dependencies:

pnpm i

Run tests:

pnpm t

License

This project is licensed under the MIT license.

Changelog

0.8.0 - 2022-06-02

Added

• Added an internal data buffer to Session that buffers written data internally until it is flushed to the client using the new Session#flush method.
• Added the Pragma, X-Accel-Buffering headers and add additional values to the Cache-Control default header to further disable all forms of caching.
• Added support for supplying the Node HTTP/2 compatibility API Http2ServerRequest and Http2ServerResponse objects to the Session constructor req and res parameters, respectively.

Changed

• Update the Session#event, Session#data, Session#id, Session#retry and Session#comment methods to write to the internal data buffer instead of sending the field data over the wire immediately.
• Update the Session#dispatch method to only write a newline (and to the internal data buffer) and not flush the written data to the client.
• Update the Channel#broadcast method to generate its own custom event ID and thus add it as an additional argument to its broadcast event callback function.
• Update the Channel#register and Channel#deregister to not do anything if the channel is already registered or deregistered, respectively.
• Update the Session constructor options header field to overwrite conflicting default headers instead of being ignored.
• Update auto-generated event IDs to be guaranteed to be a cryptographically unique string instead of a pseudorandomly generated string of eight characters.

Fixed

• Fixed the Channel session-disconnected being fired after instead of before the session is deregistered.

Removed

• Removed the ability to pass null to Session#id. Give no arguments at all instead.