better-sse
Version:
Dead simple, dependency-less, spec-compliant server-sent events implementation written in TypeScript.
808 lines (786 loc) • 25.6 kB
JavaScript
"use strict";
var __defProp = Object.defineProperty;
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
var __getOwnPropNames = Object.getOwnPropertyNames;
var __hasOwnProp = Object.prototype.hasOwnProperty;
var __export = (target, all) => {
for (var name in all)
__defProp(target, name, { get: all[name], enumerable: true });
};
var __copyProps = (to, from, except, desc) => {
if (from && typeof from === "object" || typeof from === "function") {
for (let key of __getOwnPropNames(from))
if (!__hasOwnProp.call(to, key) && key !== except)
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
}
return to;
};
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
// src/index.ts
var src_exports = {};
__export(src_exports, {
Channel: () => Channel,
EventBuffer: () => EventBuffer,
Session: () => Session,
SseError: () => SseError,
createChannel: () => createChannel,
createEventBuffer: () => createEventBuffer,
createResponse: () => createResponse,
createSession: () => createSession
});
module.exports = __toCommonJS(src_exports);
// src/Session.ts
var import_node_http = require("http");
var import_node_http2 = require("http2");
var import_node_timers = require("timers");
// src/lib/createPushFromIterable.ts
var createPushFromIterable = (push) => async (iterable, options = {}) => {
const { eventName = "iteration" } = options;
for await (const data of iterable) {
push(data, eventName);
}
};
// src/lib/createPushFromStream.ts
var import_node_stream = require("stream");
var createPushFromStream = (push) => async (stream, options = {}) => {
const { eventName = "stream" } = options;
if (stream instanceof import_node_stream.Readable) {
return await new Promise((resolve, reject) => {
stream.on("data", (chunk) => {
let data;
if (Buffer.isBuffer(chunk)) {
data = chunk.toString();
} else {
data = chunk;
}
push(data, eventName);
});
stream.once("end", () => resolve(true));
stream.once("close", () => resolve(true));
stream.once("error", (err) => reject(err));
});
}
for await (const chunk of stream) {
if (Buffer.isBuffer(chunk)) {
push(chunk.toString(), eventName);
} else {
push(chunk, eventName);
}
}
return true;
};
// src/lib/generateId.ts
var import_node_crypto = require("crypto");
var generateId;
if (import_node_crypto.randomUUID) {
generateId = () => (0, import_node_crypto.randomUUID)();
} else {
generateId = () => (0, import_node_crypto.randomBytes)(4).toString("hex");
}
// src/lib/sanitize.ts
var newlineVariantsRegex = /(\r\n|\r|\n)/g;
var newlineTrailingRegex = /\n+$/g;
var sanitize = (text) => {
let sanitized = text;
sanitized = sanitized.replace(newlineVariantsRegex, "\n");
sanitized = sanitized.replace(newlineTrailingRegex, "");
return sanitized;
};
// src/lib/serialize.ts
var serialize = (data) => JSON.stringify(data);
// src/EventBuffer.ts
var EventBuffer = class {
buffer = "";
serialize;
sanitize;
constructor(options = {}) {
this.serialize = options.serializer ?? serialize;
this.sanitize = options.sanitizer ?? sanitize;
}
/**
* Write a line with a field key and value appended with a newline character.
*/
writeField = (name, value) => {
const sanitized = this.sanitize(value);
this.buffer += name + ":" + sanitized + "\n";
return this;
};
/**
* Write an event name field (also referred to as the event "type" in the specification).
*
* @param type - Event name/type.
*/
event(type) {
this.writeField("event", type);
return this;
}
/**
* Write arbitrary data into a data field.
*
* Data is serialized to a string using the given `serializer` function option or JSON stringification by default.
*
* @param data - Data to serialize and write.
*/
data = (data) => {
const serialized = this.serialize(data);
this.writeField("data", serialized);
return this;
};
/**
* Write an event ID field.
*
* Defaults to an empty string if no argument is given.
*
* @param id - Identification string to write.
*/
id = (id = "") => {
this.writeField("id", id);
return this;
};
/**
* Write a retry field that suggests a reconnection time with the given milliseconds.
*
* @param time - Time in milliseconds to retry.
*/
retry = (time) => {
const stringifed = time.toString();
this.writeField("retry", stringifed);
return this;
};
/**
* Write a comment (an ignored field).
*
* This will not fire an event but is often used to keep the connection alive.
*
* @param text - Text of the comment. Otherwise writes an empty field value.
*/
comment = (text = "") => {
this.writeField("", text);
return this;
};
/**
* Indicate that the event has finished being created by writing an additional newline character.
*/
dispatch = () => {
this.buffer += "\n";
return this;
};
/**
* Create, write and dispatch an event with the given data all at once.
*
* This is equivalent to calling the methods `event`, `id`, `data` and `dispatch` in that order.
*
* If no event name is given, the event name is set to `"message"`.
*
* If no event ID is given, the event ID is set to a unique string generated using a cryptographic pseudorandom number generator.
*
* @param data - Data to write.
* @param eventName - Event name to write.
* @param eventId - Event ID to write.
*/
push = (data, eventName = "message", eventId = generateId()) => {
this.event(eventName).id(eventId).data(data).dispatch();
return this;
};
/**
* Pipe readable stream data as a series of events into the buffer.
*
* This uses the `push` method under the hood.
*
* If no event name is given in the `options` object, the event name is set to `"stream"`.
*
* @param stream - Readable stream to consume data from.
* @param options - Event name to use for each event created.
*
* @returns A promise that resolves with `true` or rejects based on the success of the stream write finishing.
*/
stream = createPushFromStream(this.push);
/**
* Iterate over an iterable and write yielded values as events into the buffer.
*
* This uses the `push` method under the hood.
*
* If no event name is given in the `options` object, the event name is set to `"iteration"`.
*
* @param iterable - Iterable to consume data from.
*
* @returns A promise that resolves once all data has been successfully yielded from the iterable.
*/
iterate = createPushFromIterable(this.push);
/**
* Clear the contents of the buffer.
*/
clear = () => {
this.buffer = "";
return this;
};
/**
* Get a copy of the buffer contents.
*/
read = () => this.buffer;
};
// src/lib/applyHeaders.ts
var applyHeaders = (from, to) => {
const fromMap = from instanceof Headers ? Object.fromEntries(from) : from;
for (const [key, value] of Object.entries(fromMap)) {
if (Array.isArray(value)) {
to.delete(key);
for (const item of value) {
to.append(key, item);
}
} else if (value === void 0) {
to.delete(key);
} else {
to.set(key, value);
}
}
};
// src/lib/constants.ts
var DEFAULT_REQUEST_HOST = "localhost";
var DEFAULT_REQUEST_METHOD = "GET";
var DEFAULT_RESPONSE_CODE = 200;
var DEFAULT_RESPONSE_HEADERS = {
"Content-Type": "text/event-stream",
"Cache-Control": "private, no-cache, no-store, no-transform, must-revalidate, max-age=0",
Connection: "keep-alive",
Pragma: "no-cache",
"X-Accel-Buffering": "no"
};
// src/adapters/FetchConnection.ts
var FetchConnection = class _FetchConnection {
static encoder = new TextEncoder();
writer;
url;
request;
response;
constructor(request, response, options = {}) {
this.url = new URL(request.url);
this.request = request;
const { readable, writable } = new TransformStream();
this.writer = writable.getWriter();
this.response = new Response(readable, {
status: options.statusCode ?? response?.status ?? DEFAULT_RESPONSE_CODE,
headers: DEFAULT_RESPONSE_HEADERS
});
if (response) {
applyHeaders(response.headers, this.response.headers);
}
}
sendHead = () => {
};
sendChunk = (chunk) => {
const encoded = _FetchConnection.encoder.encode(chunk);
this.writer.write(encoded);
};
cleanup = () => {
this.writer.close();
};
};
// src/adapters/NodeHttp1Connection.ts
var NodeHttp1Connection = class {
constructor(req, res, options = {}) {
this.req = req;
this.res = res;
this.url = new URL(
`http://${req.headers.host ?? DEFAULT_REQUEST_HOST}${req.url}`
);
this.controller = new AbortController();
req.once("close", this.onClose);
res.once("close", this.onClose);
this.request = new Request(this.url, {
method: req.method ?? DEFAULT_REQUEST_METHOD,
signal: this.controller.signal
});
applyHeaders(req.headers, this.request.headers);
this.response = new Response(null, {
status: options.statusCode ?? res.statusCode ?? DEFAULT_RESPONSE_CODE,
headers: DEFAULT_RESPONSE_HEADERS
});
if (res) {
applyHeaders(
res.getHeaders(),
this.response.headers
);
}
}
controller;
url;
request;
response;
onClose = () => {
this.controller.abort();
};
sendHead = () => {
this.res.writeHead(
this.response.status,
Object.fromEntries(this.response.headers)
);
};
sendChunk = (chunk) => {
this.res.write(chunk);
};
cleanup = () => {
this.req.removeListener("close", this.onClose);
this.res.removeListener("close", this.onClose);
};
};
// src/adapters/NodeHttp2CompatConnection.ts
var NodeHttp2CompatConnection = class {
constructor(req, res, options = {}) {
this.req = req;
this.res = res;
this.url = new URL(
`http://${req.headers.host ?? DEFAULT_REQUEST_HOST}${req.url}`
);
this.controller = new AbortController();
req.once("close", this.onClose);
res.once("close", this.onClose);
this.request = new Request(this.url, {
method: req.method ?? DEFAULT_REQUEST_METHOD,
signal: this.controller.signal
});
const allowedHeaders = { ...req.headers };
for (const header of Object.keys(allowedHeaders)) {
if (header.startsWith(":")) {
delete allowedHeaders[header];
}
}
applyHeaders(allowedHeaders, this.request.headers);
this.response = new Response(null, {
status: options.statusCode ?? res.statusCode ?? DEFAULT_RESPONSE_CODE,
headers: DEFAULT_RESPONSE_HEADERS
});
if (res) {
applyHeaders(
res.getHeaders(),
this.response.headers
);
}
}
controller;
url;
request;
response;
onClose = () => {
this.controller.abort();
};
sendHead = () => {
this.res.writeHead(
this.response.status,
Object.fromEntries(this.response.headers)
);
};
sendChunk = (chunk) => {
this.res.write(chunk);
};
cleanup = () => {
this.req.removeListener("close", this.onClose);
this.res.removeListener("close", this.onClose);
};
};
// src/lib/SseError.ts
var SseError = class extends Error {
constructor(message) {
super(message);
this.message = `better-sse: ${message}`;
}
};
// src/lib/TypedEmitter.ts
var import_node_events = require("events");
var TypedEmitter = class extends import_node_events.EventEmitter {
addListener(event, listener) {
return super.addListener(event, listener);
}
prependListener(event, listener) {
return super.prependListener(event, listener);
}
prependOnceListener(event, listener) {
return super.prependOnceListener(event, listener);
}
on(event, listener) {
return super.on(event, listener);
}
once(event, listener) {
return super.once(event, listener);
}
emit(event, ...args) {
return super.emit(event, ...args);
}
off(event, listener) {
return super.off(event, listener);
}
removeListener(event, listener) {
return super.removeListener(event, listener);
}
};
// src/Session.ts
var Session = class extends TypedEmitter {
/**
* The last event ID sent to the client.
*
* This is initialized to the last event ID given by the user, and otherwise is equal to the last number given to the `.id` method.
*
* For security reasons, keep in mind that the client can provide *any* initial ID here. Use the `trustClientEventId` constructor option to ignore the client-given initial ID.
*
* @readonly
*/
lastId = "";
/**
* Indicates whether the session and underlying connection is open or not.
*
* @readonly
*/
isConnected = false;
/**
* Custom state for this session.
*
* Use this object to safely store information related to the session and user.
*
* Use [module augmentation and declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)
* to safely add new properties to the `DefaultSessionState` interface.
*/
state;
buffer;
connection;
sanitize;
serialize;
initialRetry;
keepAliveInterval;
keepAliveTimer;
constructor(req, res, options) {
super();
let givenOptions = options ?? {};
if (req instanceof Request) {
let givenRes = null;
if (res) {
if (res instanceof Response) {
givenRes = res;
} else {
if (options) {
throw new SseError(
"When providing a Fetch Request object but no Response object, you may pass options as the second OR third argument to the session constructor, but not to both."
);
}
givenOptions = res;
}
}
this.connection = new FetchConnection(req, givenRes, givenOptions);
} else if (req instanceof import_node_http.IncomingMessage) {
if (res instanceof import_node_http.ServerResponse) {
this.connection = new NodeHttp1Connection(req, res, givenOptions);
} else {
throw new SseError(
"When providing a Node IncomingMessage object, a corresponding ServerResponse object must also be provided."
);
}
} else if (req instanceof import_node_http2.Http2ServerRequest) {
if (res instanceof import_node_http2.Http2ServerResponse) {
this.connection = new NodeHttp2CompatConnection(req, res, givenOptions);
} else {
throw new SseError(
"When providing a Node HTTP2ServerRequest object, a corresponding HTTP2ServerResponse object must also be provided."
);
}
} else {
throw new SseError(
"Malformed request or response objects given to session constructor. Must be one of IncomingMessage/ServerResponse from the Node HTTP/1 API, HTTP2ServerRequest/HTTP2ServerResponse from the Node HTTP/2 Compatibility API, or Request/Response from the Fetch API."
);
}
if (givenOptions.headers) {
applyHeaders(givenOptions.headers, this.connection.response.headers);
}
if (givenOptions.trustClientEventId !== false) {
this.lastId = this.connection.request.headers.get("last-event-id") ?? this.connection.url.searchParams.get("lastEventId") ?? this.connection.url.searchParams.get("evs_last_event_id") ?? "";
}
this.state = givenOptions.state ?? {};
this.initialRetry = givenOptions.retry === null ? null : givenOptions.retry ?? 2e3;
this.keepAliveInterval = givenOptions.keepAlive === null ? null : givenOptions.keepAlive ?? 1e4;
this.serialize = givenOptions.serializer ?? serialize;
this.sanitize = givenOptions.sanitizer ?? sanitize;
this.buffer = new EventBuffer({
serializer: this.serialize,
sanitizer: this.sanitize
});
this.connection.request.signal.addEventListener(
"abort",
this.onDisconnected
);
(0, import_node_timers.setImmediate)(this.initialize);
}
initialize = () => {
this.connection.sendHead();
if (this.connection.url.searchParams.has("padding")) {
this.buffer.comment(" ".repeat(2049)).dispatch();
}
if (this.connection.url.searchParams.has("evs_preamble")) {
this.buffer.comment(" ".repeat(2056)).dispatch();
}
if (this.initialRetry !== null) {
this.buffer.retry(this.initialRetry).dispatch();
}
this.flush();
if (this.keepAliveInterval !== null) {
this.keepAliveTimer = setInterval(this.keepAlive, this.keepAliveInterval);
}
this.isConnected = true;
this.emit("connected");
};
onDisconnected = () => {
this.connection.request.signal.removeEventListener(
"abort",
this.onDisconnected
);
this.connection.cleanup();
if (this.keepAliveTimer) {
clearInterval(this.keepAliveTimer);
}
this.isConnected = false;
this.emit("disconnected");
};
/**
* Write an empty comment and flush it to the client.
*/
keepAlive = () => {
this.buffer.comment().dispatch();
this.flush();
};
/**
* Flush the contents of the internal buffer to the client and clear the buffer.
*/
flush = () => {
const contents = this.buffer.read();
this.buffer.clear();
this.connection.sendChunk(contents);
};
/**
* Get a Request object representing the request of the underlying connection this session manages.
*
* When using the Fetch API, this will be the original Request object passed to the session constructor.
*
* When using the Node HTTP APIs, this will be a new Request object with status code and headers copied from the original request.
* When the originally given request or response is closed, the abort signal attached to this Request will be triggered.
*/
getRequest = () => this.connection.request;
/**
* Get a Response object representing the response of the underlying connection this session manages.
*
* When using the Fetch API, this will be a new Response object with status code and headers copied from the original response if given.
* Its body will be a ReadableStream that should begin being consumed for the session to consider itself connected.
*
* When using the Node HTTP APIs, this will be a new Response object with status code and headers copied from the original response.
* Its body will be `null`, as data is instead written to the stream of the originally given response object.
*/
getResponse = () => this.connection.response;
/**
* Push an event to the client.
*
* If no event name is given, the event name is set to `"message"`.
*
* If no event ID is given, the event ID (and thus the `lastId` property) is set to a unique string generated using a cryptographic pseudorandom number generator.
*
* If the session has disconnected, an `SseError` will be thrown.
*
* Emits the `push` event with the given data, event name and event ID in that order.
*
* @param data - Data to write.
* @param eventName - Event name to write.
* @param eventId - Event ID to write.
*/
push = (data, eventName = "message", eventId = generateId()) => {
if (!this.isConnected) {
throw new SseError(
"Cannot push data to a non-active session. Ensure the session is connected before attempting to push events. If using the Fetch API, the response stream must begin being consumed before the session is considered connected."
);
}
this.buffer.push(data, eventName, eventId);
this.flush();
this.lastId = eventId;
this.emit("push", data, eventName, eventId);
return this;
};
/**
* Pipe readable stream data as a series of events to the client.
*
* This uses the `push` method under the hood.
*
* If no event name is given in the `options` object, the event name is set to `"stream"`.
*
* @param stream - Readable stream to consume data from.
* @param options - Options to alter how the stream is flushed to the client.
*
* @returns A promise that resolves with `true` or rejects based on the success of the stream write finishing.
*/
stream = createPushFromStream(this.push);
/**
* Iterate over an iterable and send yielded values as events to the client.
*
* This uses the `push` method under the hood.
*
* If no event name is given in the `options` object, the event name is set to `"iteration"`.
*
* @param iterable - Iterable to consume data from.
*
* @returns A promise that resolves once all data has been successfully yielded from the iterable.
*/
iterate = createPushFromIterable(this.push);
/**
* Batch and send multiple events at once.
*
* If given an `EventBuffer` instance, its contents will be sent to the client.
*
* If given a callback, it will be passed an instance of `EventBuffer` which uses the same serializer and sanitizer as the session.
* Once its execution completes - or once it resolves if it returns a promise - the contents of the passed `EventBuffer` will be sent to the client.
*
* @param batcher - Event buffer to get contents from, or callback that takes an event buffer to write to.
*
* @returns A promise that resolves once all data from the event buffer has been successfully sent to the client.
*
* @see EventBuffer
*/
batch = async (batcher) => {
if (batcher instanceof EventBuffer) {
this.connection.sendChunk(batcher.read());
} else {
const buffer = new EventBuffer({
serializer: this.serialize,
sanitizer: this.sanitize
});
await batcher(buffer);
this.connection.sendChunk(buffer.read());
}
};
};
// src/createSession.ts
function createSession(req, res, options) {
return new Promise((resolve) => {
const session = new Session(req, res, options);
if (req instanceof Request) {
resolve(session);
} else {
session.once("connected", () => {
resolve(session);
});
}
});
}
// src/createResponse.ts
function createResponse(request, response, options, callback) {
const args = [request, response, options, callback];
let givenCallback;
for (let index = args.length - 1; index >= 0; --index) {
const arg = args.pop();
if (arg) {
givenCallback = arg;
break;
}
}
if (typeof givenCallback !== "function") {
throw new SseError(
"Last argument given to createResponse must be a callback function."
);
}
const session = new Session(...args);
session.once("connected", () => {
givenCallback(session);
});
return session.getResponse();
}
// src/Channel.ts
var Channel = class extends TypedEmitter {
/**
* Custom state for this channel.
*
* Use this object to safely store information related to the channel.
*/
state;
sessions = /* @__PURE__ */ new Set();
constructor(options = {}) {
super();
this.state = options.state ?? {};
}
/**
* List of the currently active sessions subscribed to this channel.
*/
get activeSessions() {
return Array.from(this.sessions);
}
/**
* Number of sessions subscribed to this channel.
*/
get sessionCount() {
return this.sessions.size;
}
/**
* Register a session so that it can start receiving events from this channel.
*
* If the session was already registered to begin with this method does nothing.
*
* @param session - Session to register.
*/
register(session) {
if (this.sessions.has(session)) {
return this;
}
if (!session.isConnected) {
throw new SseError("Cannot register a non-active session.");
}
session.once("disconnected", () => {
this.emit("session-disconnected", session);
this.deregister(session);
});
this.sessions.add(session);
this.emit("session-registered", session);
return this;
}
/**
* Deregister a session so that it no longer receives events from this channel.
*
* If the session was not registered to begin with this method does nothing.
*
* @param session - Session to deregister.
*/
deregister(session) {
if (!this.sessions.has(session)) {
return this;
}
this.sessions.delete(session);
this.emit("session-deregistered", session);
return this;
}
/**
* Broadcast an event to every active session registered with this channel.
*
* Under the hood this calls the `push` method on every active session.
*
* If no event name is given, the event name is set to `"message"`.
*
* Note that the broadcasted event will have the same ID across all receiving sessions instead of generating a unique ID for each.
*
* @param data - Data to write.
* @param eventName - Event name to write.
*/
broadcast = (data, eventName = "message", options = {}) => {
const eventId = options.eventId ?? generateId();
const sessions = options.filter ? this.activeSessions.filter(options.filter) : this.sessions;
for (const session of sessions) {
session.push(data, eventName, eventId);
}
this.emit("broadcast", data, eventName, eventId);
return this;
};
};
// src/createChannel.ts
var createChannel = (...args) => new Channel(...args);
// src/createEventBuffer.ts
var createEventBuffer = (...args) => new EventBuffer(...args);
// Annotate the CommonJS export names for ESM import in node:
0 && (module.exports = {
Channel,
EventBuffer,
Session,
SseError,
createChannel,
createEventBuffer,
createResponse,
createSession
});