better-sse 0.13.0 → 0.14.1

package/build/index.d.ts

@@ -1,9 +1,485 @@
-export * from "./Session";
-export * from "./createSession";
-export * from "./Channel";
-export * from "./createChannel";
-export * from "./EventBuffer";
-export * from "./createEventBuffer";
-export type { StreamOptions } from "./lib/createPushFromStream";
-export type { IterateOptions } from "./lib/createPushFromIterable";
-export * from "./lib/SseError";
+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 };