better-sse 0.13.0 → 0.14.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Matthew
+Copyright (c) 2024 Matthew W.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -27,20 +27,20 @@ Compared to WebSockets it has comparable performance and bandwidth usage, especi
 
 ## Highlights
 
-* Compatible with all popular Node HTTP frameworks ([http](https://nodejs.org/api/http.html), [Express](https://nodejs.org/api/http.html), [Koa](https://www.npmjs.com/package/koa), [Fastify](https://www.npmjs.com/package/fastify), etc.)
+* Compatible with all popular Node HTTP frameworks ([Express](https://nodejs.org/api/http.html), [Fastify](https://fastify.dev/), [Nest](https://nestjs.com/), [Next.js](https://nextjs.org/), etc.)
 * Fully written in TypeScript (+ ships with types directly).
 * [Thoroughly tested](./src/Session.test.ts) (+ 100% code coverage!).
-* [Comprehensively documented](./docs) with guides and API documentation.
-* [Channels](./docs/channels.md) allow you to broadcast events to many clients at once.
+* [Comprehensively documented](https://matthewwid.github.io/better-sse) with guides and API documentation.
+* [Channels](https://matthewwid.github.io/better-sse/guides/channels) allow you to broadcast events to many clients at once.
 * Configurable reconnection time, message serialization and data sanitization (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](./docs/api.md#eventbuffer) of events or by sending [full events with simple helpers](./docs/api.md#sessionpush-data-unknown-eventname-string-eventid-string--this).
+* Send [individual fields](https://matthewwid.github.io/better-sse/guides/batching#send-individual-event-fields) of events or send [full events with simple helpers](https://matthewwid.github.io/better-sse/reference/api/#sessionpush-data-unknown-eventname-string-eventid-string--this).
 * Pipe [streams](https://nodejs.org/api/stream.html#stream_readable_streams) and [iterables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators) directly from the server to the client as a series of events.
 * Support for popular EventSource polyfills [`event-source-polyfill`](https://www.npmjs.com/package/event-source-polyfill) and [`eventsource-polyfill`](https://www.npmjs.com/package/eventsource-polyfill).
 
-[See a comparison with other Node SSE libraries in the documentation.](./docs/comparison.md)
+[See a comparison with other Node SSE libraries in the documentation.](https://matthewwid.github.io/better-sse/reference/comparison)
 
 # Installation
 
@@ -61,11 +61,11 @@ _Better SSE ships with types built in. No need to install from DefinitelyTyped f
 
 The following example shows usage with [Express](http://expressjs.com/), but Better SSE works with any web-server framework that uses the underlying Node [HTTP module](https://nodejs.org/api/http.html).
 
-See the [Recipes](./docs/recipes.md) section of the documentation for use with other frameworks and libraries.
+See the [Recipes](https://matthewwid.github.io/better-sse/reference/recipes/) section of the documentation for use with other frameworks and libraries.
 
 ---
 
-Use [sessions](./docs/api.md#session) to push events to clients:
+Use [sessions](https://matthewwid.github.io/better-sse/reference/api/#sessionstate) to push events to clients:
 
 ```typescript
 // Server
@@ -83,13 +83,11 @@ app.get("/sse", async (req, res) => {
 const sse = new EventSource("/sse");
 
 sse.addEventListener("message", ({ data }) => {
-	console.log(data);
+	console.log(JSON.parse(data));
 });
 ```
 
----
-
-Use [channels](./docs/channels.md) to send events to many clients at once:
+Use [channels](https://matthewwid.github.io/better-sse/reference/api/#channelstate-sessionstate) to send events to many clients at once:
 
 ```typescript
 import { createSession, createChannel } from "better-sse";
@@ -105,9 +103,7 @@ app.get("/sse", async (req, res) => {
 });
 ```
 
----
-
-Loop over sync and async [iterables](./docs/api.md#sessioniterate-iterable-iterable--asynciterable-options-object--promisevoid) and send each value as an event:
+Loop over sync and async [iterables](https://matthewwid.github.io/better-sse/reference/api/#sessioniterate-iterable-iterable--asynciterable-options-object--promisevoid) and send each value as an event:
 
 ```typescript
 const session = await createSession(req, res);
@@ -117,9 +113,7 @@ const list = [1, 2, 3];
 await session.iterate(list);
 ```
 
----
-
-Pipe [readable stream](#sessionstream-stream-readable-options-object--promiseboolean) data to the client as a stream of events:
+Pipe [readable stream](https://matthewwid.github.io/better-sse/reference/api/#sessionstream-stream-readable-options-object--promiseboolean) data to the client as a stream of events:
 
 ```typescript
 const session = await createSession(req, res);
@@ -131,11 +125,11 @@ await session.stream(stream);
 
 ---
 
-Check the [API documentation](./docs/api.md) and [live examples](./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!
+Check the [API documentation](https://matthewwid.github.io/better-sse/reference/api) and [live examples](./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](./docs).
+API documentation, getting started guides and usage with other frameworks is [available on the documentation website](https://matthewwid.github.io/better-sse/).
 
 # Contributing
 

package/build/index.d.mts

@@ -0,0 +1,485 @@
+import * as stream from 'stream';
+import * as http from 'http';
+import { OutgoingHttpHeaders, IncomingMessage, ServerResponse } from 'http';
+import * as http2 from 'http2';
+import { Http2ServerRequest, Http2ServerResponse } from 'http2';
+import { EventEmitter } from 'events';
+
+interface IterateOptions {
+    /**
+     * Event name/type to be emitted when iterable data is sent to the client.
+     *
+     * Defaults to `"iteration"`.
+     */
+    eventName?: string;
+}
+
+interface StreamOptions {
+    /**
+     * Event name/type to be emitted when stream data is sent to the client.
+     *
+     * Defaults to `"stream"`.
+     */
+    eventName?: string;
+}
+
+/**
+ * Serialize arbitrary data to a string that can be sent over the wire to the client.
+ */
+interface SerializerFunction {
+    (data: unknown): string;
+}
+
+interface SanitizerFunction {
+    (text: string): string;
+}
+
+interface EventBufferOptions {
+    /**
+     * Serialize data to a string that can be written.
+     *
+     * Defaults to `JSON.stringify`.
+     */
+    serializer?: SerializerFunction;
+    /**
+     * Sanitize values so as to not prematurely dispatch events when writing fields whose text inadvertently contains newlines.
+     *
+     * By default, CR, LF and CRLF characters are replaced with a single LF character (`\n`) and then any trailing LF characters are stripped so as to prevent a blank line being written and accidentally dispatching the event before `.dispatch()` is called.
+     */
+    sanitizer?: SanitizerFunction;
+}
+/**
+ * An `EventBuffer` allows you to write raw spec-compliant SSE fields into a text buffer that can be sent directly over the wire.
+ */
+declare class EventBuffer {
+    private buffer;
+    private serialize;
+    private sanitize;
+    constructor(options?: EventBufferOptions);
+    /**
+     * Write a line with a field key and value appended with a newline character.
+     */
+    private writeField;
+    /**
+     * Write an event name field (also referred to as the event "type" in the specification).
+     *
+     * @param type - Event name/type.
+     */
+    event(type: string): 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: unknown) => this;
+    /**
+     * Write an event ID field.
+     *
+     * Defaults to an empty string if no argument is given.
+     *
+     * @param id - Identification string to write.
+     */
+    id: (id?: string) => this;
+    /**
+     * Write a retry field that suggests a reconnection time with the given milliseconds.
+     *
+     * @param time - Time in milliseconds to retry.
+     */
+    retry: (time: number) => 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?: string) => this;
+    /**
+     * Indicate that the event has finished being created by writing an additional newline character.
+     */
+    dispatch: () => 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: unknown, eventName?: string, eventId?: string) => 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 or rejects based on the success of the stream write finishing.
+     */
+    stream: (stream: stream.Readable, options?: StreamOptions) => Promise<boolean>;
+    /**
+     * 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: <DataType = unknown>(iterable: Iterable<DataType> | AsyncIterable<DataType>, options?: IterateOptions) => Promise<void>;
+    /**
+     * Clear the contents of the buffer.
+     */
+    clear: () => this;
+    /**
+     * Get a copy of the buffer contents.
+     */
+    read: () => string;
+}
+
+interface EventMap {
+    [name: string | symbol]: (...args: any[]) => void;
+}
+/**
+ * Get event names type
+ */
+type EventNames<T> = keyof {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: never;
+} | (string & {});
+/**
+ * Wraps the EventEmitter class to add types that map event names
+ * to types of arguments in the event handler callback.
+ */
+declare class TypedEmitter<Events extends EventMap> extends EventEmitter {
+    addListener<EventName extends EventNames<Events>>(event: EventName, listener: Events[EventName]): this;
+    prependListener<EventName extends EventNames<Events>>(event: EventName, listener: Events[EventName]): this;
+    prependOnceListener<EventName extends EventNames<Events>>(event: EventName, listener: Events[EventName]): this;
+    on<EventName extends EventNames<Events>>(event: EventName, listener: Events[EventName]): this;
+    once<EventName extends EventNames<Events>>(event: EventName, listener: Events[EventName]): this;
+    emit<EventName extends EventNames<Events>>(event: EventName, ...args: Parameters<Events[EventName]>): boolean;
+    off<EventName extends EventNames<Events>>(event: EventName, listener: Events[EventName]): this;
+    removeListener<EventName extends EventNames<Events>>(event: EventName, listener: Events[EventName]): this;
+}
+
+interface SessionOptions<State = DefaultSessionState> extends Pick<EventBufferOptions, "serializer" | "sanitizer"> {
+    /**
+     * Whether to trust or ignore the last event ID given by the client in the `Last-Event-ID` request header.
+     *
+     * When set to `false`, the `lastId` property will always be initialized to an empty string.
+     *
+     * Defaults to `true`.
+     */
+    trustClientEventId?: boolean;
+    /**
+     * Time in milliseconds for the client to wait before attempting to reconnect if the connection is closed.
+     *
+     * This is a request to the client browser, and does not guarantee that the client will actually respect the given time.
+     *
+     * Equivalent to immediately calling `.retry().dispatch().flush()` after a connection is made.
+     *
+     * Give as `null` to avoid sending an explicit reconnection time and allow the client browser to decide itself.
+     *
+     * Defaults to `2000` milliseconds.
+     *
+     * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#concept-event-stream-reconnection-time
+     */
+    retry?: number | null;
+    /**
+     * Time in milliseconds interval for the session to send a comment to keep the connection alive.
+     *
+     * Give as `null` to disable the connection keep-alive mechanism.
+     *
+     * Defaults to `10000` milliseconds (`10` seconds).
+     */
+    keepAlive?: number | null;
+    /**
+     * Status code to be sent to the client.
+     *
+     * Event stream requests can be redirected using HTTP 301 and 307 status codes.
+     * Make sure to set `Location` header when using these status codes using the `headers` property.
+     *
+     * A client can be asked to stop reconnecting by using 204 status code.
+     *
+     * Defaults to `200`.
+     */
+    statusCode?: number;
+    /**
+     * Additional headers to be sent along with the response.
+     */
+    headers?: OutgoingHttpHeaders;
+    /**
+     * Custom state for this session.
+     *
+     * Use this object to safely store information related to the session and user.
+     */
+    state?: State;
+}
+interface DefaultSessionState {
+    [key: string]: unknown;
+}
+interface SessionEvents extends EventMap {
+    connected: () => void;
+    disconnected: () => void;
+    push: (data: unknown, eventName: string, eventId: string) => void;
+}
+/**
+ * A `Session` represents an open connection between the server and a client.
+ *
+ * It extends from the {@link https://nodejs.org/api/events.html#events_class_eventemitter | EventEmitter} class.
+ *
+ * It emits the `connected` event after it has connected and sent all headers to the client, and the
+ * `disconnected` event after the connection has been closed.
+ *
+ * Note that creating a new session will immediately send the initial status code and headers to the client.
+ * Attempting to write additional headers after you have created a new session will result in an error.
+ *
+ * @param req - The Node HTTP {@link https://nodejs.org/api/http.html#http_class_http_incomingmessage | ServerResponse} object.
+ * @param res - The Node HTTP {@link https://nodejs.org/api/http.html#http_class_http_serverresponse | IncomingMessage} object.
+ * @param options - Options given to the session instance.
+ */
+declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionEvents> {
+    /**
+     * 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: string;
+    /**
+     * Indicates whether the session and underlying connection is open or not.
+     *
+     * @readonly
+     */
+    isConnected: boolean;
+    /**
+     * 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: State;
+    private buffer;
+    /**
+     * Raw HTTP request.
+     */
+    private req;
+    /**
+     * Raw HTTP response that is the minimal interface needed and forms the
+     * intersection between the HTTP/1.1 and HTTP/2 server response interfaces.
+     */
+    private res;
+    private serialize;
+    private sanitize;
+    private trustClientEventId;
+    private initialRetry;
+    private keepAliveInterval;
+    private keepAliveTimer?;
+    private statusCode;
+    private headers;
+    constructor(req: IncomingMessage | Http2ServerRequest, res: ServerResponse | Http2ServerResponse, options?: SessionOptions<State>);
+    private initialize;
+    private onDisconnected;
+    private keepAlive;
+    /**
+     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     */
+    event(type: string): this;
+    /**
+     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     */
+    data: (data: unknown) => this;
+    /**
+     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     */
+    id: (id?: string) => this;
+    /**
+     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     */
+    retry: (time: number) => this;
+    /**
+     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     */
+    comment: (text?: string) => this;
+    /**
+     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     */
+    dispatch: () => this;
+    /**
+     * Flush the contents of the internal buffer to the client and clear the buffer.
+     *
+     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     */
+    flush: () => this;
+    /**
+     * 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.
+     *
+     * 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: unknown, eventName?: string, eventId?: string) => 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 or rejects based on the success of the stream write finishing.
+     */
+    stream: (stream: stream.Readable, options?: StreamOptions) => Promise<boolean>;
+    /**
+     * 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: <DataType = unknown>(iterable: Iterable<DataType> | AsyncIterable<DataType>, options?: IterateOptions) => Promise<void>;
+    /**
+     * 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: (batcher: EventBuffer | ((buffer: EventBuffer) => void | Promise<void>)) => Promise<void>;
+}
+
+/**
+ * Create a new session and return the session instance once it has connected.
+ */
+declare const createSession: <State = DefaultSessionState>(req: http.IncomingMessage | http2.Http2ServerRequest, res: http.ServerResponse<http.IncomingMessage> | http2.Http2ServerResponse<http2.Http2ServerRequest>, options?: SessionOptions<State> | undefined) => Promise<Session<State>>;
+
+interface ChannelOptions<State = DefaultChannelState> {
+    /**
+     * Custom state for this channel.
+     *
+     * Use this object to safely store information related to the channel.
+     */
+    state?: State;
+}
+interface BroadcastOptions<SessionState = DefaultSessionState> {
+    /**
+     * Unique ID for the event being broadcast.
+     *
+     * If no event ID is given, the event ID is set to a unique string generated using a cryptographic pseudorandom number generator.
+     */
+    eventId?: string;
+    /**
+     * Filter sessions that should receive the event.
+     *
+     * Called with each session and should return `true` to allow the event to be sent and otherwise return `false` to prevent the session from receiving the event.
+     */
+    filter?: (session: Session<SessionState>) => boolean;
+}
+interface ChannelEvents<SessionState = DefaultSessionState> extends EventMap {
+    "session-registered": (session: Session<SessionState>) => void;
+    "session-deregistered": (session: Session<SessionState>) => void;
+    "session-disconnected": (session: Session<SessionState>) => void;
+    broadcast: (data: unknown, eventName: string, eventId: string) => void;
+}
+interface DefaultChannelState {
+    [key: string]: unknown;
+}
+/**
+ * A `Channel` is used to broadcast events to many sessions at once.
+ *
+ * It extends from the {@link https://nodejs.org/api/events.html#events_class_eventemitter | EventEmitter} class.
+ *
+ * You may use the second generic argument `SessionState` to enforce that only sessions with the same state type may be registered with this channel.
+ */
+declare class Channel<State = DefaultChannelState, SessionState = DefaultSessionState> extends TypedEmitter<ChannelEvents<SessionState>> {
+    /**
+     * Custom state for this channel.
+     *
+     * Use this object to safely store information related to the channel.
+     */
+    state: State;
+    private sessions;
+    constructor(options?: ChannelOptions<State>);
+    /**
+     * List of the currently active sessions subscribed to this channel.
+     */
+    get activeSessions(): ReadonlyArray<Session<SessionState>>;
+    /**
+     * Number of sessions subscribed to this channel.
+     */
+    get sessionCount(): number;
+    /**
+     * 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: Session<SessionState>): 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: Session<SessionState>): 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: unknown, eventName?: string, options?: BroadcastOptions<SessionState>) => this;
+}
+
+declare const createChannel: <State = DefaultChannelState, SessionState = DefaultSessionState>(options?: ChannelOptions<State> | undefined) => Channel<State, SessionState>;
+
+declare const createEventBuffer: (options?: EventBufferOptions | undefined) => EventBuffer;
+
+declare class SseError extends Error {
+    constructor(message: string);
+}
+
+export { type BroadcastOptions, Channel, type ChannelEvents, type ChannelOptions, type DefaultChannelState, type DefaultSessionState, EventBuffer, type EventBufferOptions, type IterateOptions, Session, type SessionEvents, type SessionOptions, SseError, type StreamOptions, createChannel, createEventBuffer, createSession };