Tiny EventSource

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

Installation

npm install tiny-eventsource

Quick-Start

import { eventsource } from "tiny-eventsource";

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

Usage

Basic Express Example

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]);
	}
}

API

Constructor

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

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

| Parameter | Type | Default | Description | | --------- | ---------------- | ----------- | ------------------------------------------- | | config | object\|string | undefined | Options object or initial event name string | | ...msgs | string[] | [] | Initial messages to send on connection |

Returns: EventSource instance

eventsource()

Factory function that creates and returns an EventSource instance.

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

| Parameter | Type | Default | Description | | --------- | ---------------- | ------- | ----------------------------------- | | ...args | string\|object | — | Config options and initial messages |

Returns: EventSource instance

init(req, res)

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

stream.init(req, res);

| Parameter | Type | Default | Description | | --------- | ----------------- | ----------- | ---------------------------------------------------------------------------------- | | req | IncomingMessage | undefined | HTTP incoming request — supports socket.setTimeout, setNoDelay, setKeepAlive | | res | ServerResponse | undefined | HTTP server response — sets Content-Type, Cache-Control, Connection headers |

Returns: this (EventSource)

send(msg[, event, id])

Emits a data event that is transmitted to the client.

stream.send(data, event, id);

| Parameter | Type | Required | Description | | --------- | ---------------- | -------- | ------------------------------------------- | | data | string\|object | yes | Message data — objects are JSON-stringified | | event | string | no | Custom event name (default: "message") | | id | number | no | Message ID for client reconnection |

Returns: this (EventSource)

listenerCount(event)

Returns the number of listeners registered for the given event.

stream.listenerCount("data");

| Parameter | Type | Required | Description | | --------- | -------- | -------- | --------------------------------- | | event | string | yes | Event name to count listeners for |

Returns: number — listener count

setMaxListeners(n)

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

stream.setMaxListeners(0);

| Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------ | | n | number | yes | Maximum number of listeners; 0 means unlimited |

Returns: this (EventSource)

stop()

Stops the heartbeat interval if one is active.

stream.stop();

Returns: this (EventSource)

Options

| Option | Type | Default | Description | | ------- | -------- | ----------- | ------------------------------------------------------- | | event | string | "message" | Event name for heartbeat/ping | | ms | number | 0 | Heartbeat interval in milliseconds; set > 0 to enable | | msg | string | "ping" | Message sent for heartbeat pings |

Events

close

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

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

License

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