better-sse 0.14.1 → 0.15.1

package/build/index.d.ts

@@ -1,9 +1,7 @@
-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';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Http2ServerRequest, Http2ServerResponse } from 'node:http2';
+import { Readable } from 'node:stream';
+import { EventEmitter } from 'node:events';
 
 interface IterateOptions {
     /**
@@ -13,7 +11,9 @@ interface IterateOptions {
      */
     eventName?: string;
 }
+type PushFromIterable = (iterable: Iterable<unknown> | AsyncIterable<unknown>, options?: IterateOptions) => Promise<void>;
 
+type WebReadableStream = ReadableStream;
 interface StreamOptions {
     /**
      * Event name/type to be emitted when stream data is sent to the client.
@@ -22,17 +22,14 @@ interface StreamOptions {
      */
     eventName?: string;
 }
+type PushFromStream = (stream: Readable | WebReadableStream, options?: StreamOptions) => Promise<boolean>;
+
+type SanitizerFunction = (text: string) => 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;
-}
+type SerializerFunction = (data: unknown) => string;
 
 interface EventBufferOptions {
     /**
@@ -124,9 +121,9 @@ declare class EventBuffer {
      * @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.
+     * @returns A promise that resolves with `true` or rejects based on the success of the stream write finishing.
      */
-    stream: (stream: stream.Readable, options?: StreamOptions) => Promise<boolean>;
+    stream: PushFromStream;
     /**
      * Iterate over an iterable and write yielded values as events into the buffer.
      *
@@ -138,7 +135,7 @@ declare class EventBuffer {
      *
      * @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>;
+    iterate: PushFromIterable;
     /**
      * Clear the contents of the buffer.
      */
@@ -218,7 +215,7 @@ interface SessionOptions<State = DefaultSessionState> extends Pick<EventBufferOp
     /**
      * Additional headers to be sent along with the response.
      */
-    headers?: OutgoingHttpHeaders;
+    headers?: Record<string, string | string[] | undefined>;
     /**
      * Custom state for this session.
      *
@@ -239,15 +236,19 @@ interface SessionEvents extends EventMap {
  *
  * 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.
+ * It emits the `connected` event after it has connected and sent the response head to the client.
+ * It emits the `disconnected` event after the connection has been closed.
+ *
+ * When using the Fetch API, the session is considered connected only once the `ReadableStream` contained in the body
+ * of the `Response` returned by `getResponse` has began being consumed.
  *
- * 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.
+ * When using the Node HTTP APIs, the session will send the response with status code, headers and other preamble data ahead of time,
+ * allowing the session to connect and start pushing events immediately. As such, keep in mind that attempting
+ * to write additional headers after the session has been created will result in an error being thrown.
  *
- * @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.
+ * @param req - The Node HTTP/1 {@link https://nodejs.org/api/http.html#http_class_http_incomingmessage | ServerResponse}, HTTP/2 {@link https://nodejs.org/api/http2.html#class-http2http2serverrequest | Http2ServerRequest} or the Fetch API {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request} object.
+ * @param res - The Node HTTP {@link https://nodejs.org/api/http.html#http_class_http_serverresponse | IncomingMessage}, HTTP/2 {@link https://nodejs.org/api/http2.html#class-http2http2serverresponse | Http2ServerResponse} or the Fetch API {@link https://developer.mozilla.org/en-US/docs/Web/API/Response | Response} object. Optional if using the Fetch API.
+ * @param options - Optional additional configuration for the session.
  */
 declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionEvents> {
     /**
@@ -276,57 +277,45 @@ declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionE
      */
     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 connection;
     private sanitize;
-    private trustClientEventId;
+    private serialize;
     private initialRetry;
     private keepAliveInterval;
     private keepAliveTimer?;
-    private statusCode;
-    private headers;
-    constructor(req: IncomingMessage | Http2ServerRequest, res: ServerResponse | Http2ServerResponse, options?: SessionOptions<State>);
+    constructor(req: IncomingMessage, res: ServerResponse, options?: SessionOptions<State>);
+    constructor(req: Http2ServerRequest, res: Http2ServerResponse, options?: SessionOptions<State>);
+    constructor(req: Request, res?: Response, options?: SessionOptions<State>);
+    constructor(req: Request, 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
+     * Write an empty comment and flush it to the client.
      */
-    data: (data: unknown) => this;
-    /**
-     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
-     */
-    id: (id?: string) => this;
+    private keepAlive;
     /**
-     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     * Flush the contents of the internal buffer to the client and clear the buffer.
      */
-    retry: (time: number) => this;
+    private flush;
     /**
-     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
-     */
-    comment: (text?: string) => this;
-    /**
-     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     * 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.
      */
-    dispatch: () => this;
+    getRequest: () => Request;
     /**
-     * Flush the contents of the internal buffer to the client and clear the buffer.
+     * 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.
      *
-     * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+     * 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.
      */
-    flush: () => this;
+    getResponse: () => Response;
     /**
      * Push an event to the client.
      *
@@ -334,6 +323,8 @@ declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionE
      *
      * 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.
@@ -351,9 +342,9 @@ declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionE
      * @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.
+     * @returns A promise that resolves with `true` or rejects based on the success of the stream write finishing.
      */
-    stream: (stream: stream.Readable, options?: StreamOptions) => Promise<boolean>;
+    stream: PushFromStream;
     /**
      * Iterate over an iterable and send yielded values as events to the client.
      *
@@ -365,7 +356,7 @@ declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionE
      *
      * @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>;
+    iterate: PushFromIterable;
     /**
      * Batch and send multiple events at once.
      *
@@ -384,9 +375,30 @@ declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionE
 }
 
 /**
- * Create a new session and return the session instance once it has connected.
+ * Create a new session.
+ *
+ * When using the Fetch API, resolves immediately with a session instance before it has connected.
+ * You can listen for the `connected` event on the session to know when it has connected, or
+ * otherwise use the shorthand `createResponse` function that does so for you instead.
+ *
+ * When using the Node HTTP APIs, waits for the session to connect before resolving with its instance.
+ */
+declare function createSession<State = DefaultSessionState>(req: IncomingMessage, res: ServerResponse, options?: SessionOptions<State>): Promise<Session<State>>;
+declare function createSession<State = DefaultSessionState>(req: Http2ServerRequest, res: Http2ServerResponse, options?: SessionOptions<State>): Promise<Session<State>>;
+declare function createSession<State = DefaultSessionState>(req: Request, res?: Response, options?: SessionOptions<State>): Promise<Session<State>>;
+declare function createSession<State = DefaultSessionState>(req: Request, options?: SessionOptions<State>): Promise<Session<State>>;
+
+type CreateResponseCallback<State> = (session: Session<State>) => void;
+/**
+ * Create a new session using the Fetch API and return its corresponding `Response` object.
+ *
+ * The last argument should be a callback function that will be invoked with
+ * 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>>;
+declare function createResponse<State = DefaultSessionState>(request: Request, callback: CreateResponseCallback<State>): Response;
+declare function createResponse<State = DefaultSessionState>(request: Request, response: Response, callback: CreateResponseCallback<State>): Response;
+declare function createResponse<State = DefaultSessionState>(request: Request, options: SessionOptions<State>, callback: CreateResponseCallback<State>): Response;
+declare function createResponse<State = DefaultSessionState>(request: Request, response: Response, options: SessionOptions<State>, callback: CreateResponseCallback<State>): Response;
 
 interface ChannelOptions<State = DefaultChannelState> {
     /**
@@ -482,4 +494,4 @@ 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 };
+export { type BroadcastOptions, Channel, type ChannelEvents, type ChannelOptions, type CreateResponseCallback, type DefaultChannelState, type DefaultSessionState, EventBuffer, type EventBufferOptions, type IterateOptions, Session, type SessionEvents, type SessionOptions, SseError, type StreamOptions, createChannel, createEventBuffer, createResponse, createSession };