Tiny EventSource simplifies server-sent events (SSE) for API servers. An EventEmitter-based abstraction over the EventSource API for streaming events to HTTP clients.

• Installation
• Quick-Start
• Usage
• API
  • Constructor
  • eventsource()
  • init()
  • send()
  • listenerCount()
  • setMaxListeners()
  • stop()
• Options
• Events
  • close
• License

npm install tiny-eventsource

import { eventsource } from "tiny-eventsource";

const stream = eventsource({ ms: 2e4 });
stream.init(req, res);
stream.send({ data: "hello" });

import { eventsource } from "tiny-eventsource";
import { STATUS_CODES } from "node:http";

const streams = new Map();

export function stream(req, res) {
	if (req.isAuthenticated()) {
		const id = req.user.id;

		if (!streams.has(id)) {
			streams.set(id, eventsource({ ms: 2e4 }, "connected"));
		}

		streams.get(id).init(req, res);
	} else {
		res.statusCode = 401;
		res.writeHead(res.statusCode, { headers: { "cache-control": "no-cache, must re-validate" } });
		res.end(STATUS_CODES[res.statusCode]);
	}
}

Creates an EventSource instance with optional messages to be transmitted on successful connection.

new EventSource({event?: string, ms?: number, msg?: string}, ...msgs)

Returns: EventSource instance

Factory function that creates and returns an EventSource instance.

eventsource({event?: string, ms?: number, msg?: string}, ...msgs)

Returns: EventSource instance

Initializes the SSE stream, sets response headers, and starts the heartbeat if configured.

stream.init(req, res);

Returns: this (EventSource)

Emits a data event that is transmitted to the client.

stream.send(data, event, id);

Returns: this (EventSource)

Returns the number of listeners registered for the given event.

stream.listenerCount("data");

Returns: number — listener count

Sets the maximum number of listeners for the instance. Pass 0 to disable the limit.

stream.setMaxListeners(0);

Returns: this (EventSource)

Stops the heartbeat interval if one is active.

stream.stop();

Returns: this (EventSource)

Emitted when an EventSource request is closed or the client disconnects.

stream.on("close", () => {
	// cleanup
});

Copyright (c) 2023-2026 Jason Mulligan Licensed under the BSD-3 License