better-sse 0.15.1 → 0.16.0

package/build/index.d.cts

@@ -0,0 +1,662 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Http2ServerRequest, Http2ServerResponse } from "node:http2";
+import { Readable } from "node:stream";
+import { EventEmitter } from "node:events";
+
+//#region src/utils/createPushFromIterable.d.ts
+interface IterateOptions {
+  /**
+   * Event name/type to be emitted when iterable data is sent to the client.
+   *
+   * Defaults to `"iteration"`.
+   */
+  eventName?: string;
+}
+type PushFromIterable = (iterable: Iterable<unknown> | AsyncIterable<unknown>, options?: IterateOptions) => Promise<void>;
+//#endregion
+//#region src/utils/createPushFromStream.d.ts
+type WebReadableStream = ReadableStream;
+interface StreamOptions {
+  /**
+   * Event name/type to be emitted when stream data is sent to the client.
+   *
+   * Defaults to `"stream"`.
+   */
+  eventName?: string;
+}
+type PushFromStream = (stream: Readable | WebReadableStream, options?: StreamOptions) => Promise<boolean>;
+//#endregion
+//#region src/utils/sanitize.d.ts
+type SanitizerFunction = (text: string) => string;
+//#endregion
+//#region src/utils/serialize.d.ts
+/**
+ * Serialize arbitrary data to a string that can be sent over the wire to the client.
+ */
+type SerializerFunction = (data: unknown) => string;
+//#endregion
+//#region src/EventBuffer.d.ts
+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 randomly generated UUIDv4.
+   *
+   * @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 with `true` or rejects based on the success of the stream write finishing.
+   */
+  stream: PushFromStream;
+  /**
+   * 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: PushFromIterable;
+  /**
+   * Clear the contents of the buffer.
+   */
+  clear: () => this;
+  /**
+   * Get a copy of the buffer contents.
+   */
+  read: () => string;
+}
+//#endregion
+//#region src/utils/TypedEmitter.d.ts
+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 {
+  constructor(...args: ConstructorParameters<typeof 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;
+}
+//#endregion
+//#region src/Session.d.ts
+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.
+   *
+   * Ignored if passing a custom `Connection` instance to the `Session` constructor.
+   *
+   * Defaults to `200`.
+   */
+  statusCode?: number;
+  /**
+   * Additional headers to be sent along with the response.
+   *
+   * Ignored if passing a custom `Connection` instance to the `Session` constructor.
+   */
+  headers?: Record<string, string | string[] | undefined>;
+  /**
+   * 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 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.
+ *
+ * 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/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> {
+  /**
+   * 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;
+  private connection;
+  private sanitize;
+  private serialize;
+  private initialRetry;
+  private keepAliveInterval;
+  private keepAliveTimer?;
+  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>);
+  constructor(connection: Connection, options?: SessionOptions<State>);
+  private initialize;
+  private onDisconnected;
+  /**
+   * Write an empty comment and flush it to the client.
+   */
+  private keepAlive;
+  /**
+   * Flush the contents of the internal buffer to the client and clear the buffer.
+   */
+  private flush;
+  /**
+   * 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: () => any;
+  /**
+   * 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: () => any;
+  /**
+   * 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 randomly generated UUIDv4.
+   *
+   * 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: 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 with `true` or rejects based on the success of the stream write finishing.
+   */
+  stream: PushFromStream;
+  /**
+   * 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: PushFromIterable;
+  /**
+   * 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>;
+}
+//#endregion
+//#region src/adapters/Connection.d.ts
+type ConnectionConstants = Readonly<{
+  /**
+   * The default HTTP request method to apply to the `Connection#request` `status` property.
+   */
+  REQUEST_METHOD: string;
+  /**
+   * The default domain to apply to the `Connection#url` `host` property, typically overriden by the value of the `Host` header.
+   */
+  REQUEST_HOST: string;
+  /**
+   * The default HTTP response status code to apply to the `Connection#response` `status` property.
+   */
+  RESPONSE_CODE: number;
+  /**
+   * The default HTTP response headers to apply to the `Connection#response` `headers` property.
+   */
+  RESPONSE_HEADERS: Readonly<Record<string, string>>;
+}>;
+/**
+ * Represents the full request and response of an underlying network connection,
+ * abstracting away the differences between the Node HTTP/1, HTTP/2, Fetch and
+ * any other APIs.
+ *
+ * You can implement your own custom `Connection` subclass to make Better SSE
+ * compatible with any framework.
+ */
+declare abstract class Connection {
+  /**
+   * Useful constants that you may use when implementing your own custom connection.
+   */
+  static constants: Readonly<{
+    /**
+     * The default HTTP request method to apply to the `Connection#request` `status` property.
+     */
+    REQUEST_METHOD: string;
+    /**
+     * The default domain to apply to the `Connection#url` `host` property, typically overriden by the value of the `Host` header.
+     */
+    REQUEST_HOST: string;
+    /**
+     * The default HTTP response status code to apply to the `Connection#response` `status` property.
+     */
+    RESPONSE_CODE: number;
+    /**
+     * The default HTTP response headers to apply to the `Connection#response` `headers` property.
+     */
+    RESPONSE_HEADERS: Readonly<Record<string, string>>;
+  }>;
+  /**
+   * Utility method to consistently merge headers from an object into a `Headers` object.
+   *
+   * For each entry in `from`:
+   * - If the value is a `string`, it will replace the target header.
+   * - If the value is an `Array`, it will replace the target header and then append each item.
+   * - If the value is `undefined`, it will delete the target header.
+   */
+  static applyHeaders(from: Record<string, string | string[] | undefined> | Headers, to: Headers): void;
+  /**
+   * The URL used to open the connection to the server.
+   *
+   * For HTTP-based connections, this is typically constructured from the request `Host` header and URL path, including the query string.
+   *
+   * You should pass this to the constructor of the `Request` object stored in the `Connection#request` property.
+   */
+  abstract url: URL;
+  /**
+   * Represents the request that opened the connection.
+   *
+   * You should populate its `url` property - likely with the same value as the `url` property - its `method` and its `headers` properties.
+   *
+   * You should populate its `signal` property with an `AbortSignal` that gets triggered when the request *or* the response is closed, indicating to the session that the connection has disconnected.
+   */
+  abstract request: Request;
+  /**
+   * Represents the response that will be sent to the client.
+   *
+   * You should populate its `status` and `headers` properties.
+   *
+   * You *may* populate its `body` property with a `ReadableStream` that will enqueue any data written with the `sendChunk` method if you intend to use the session with a Fetch-based framework.
+   */
+  abstract response: Response;
+  /**
+   * Send the response head with status code and headers from the `response` instance.
+   */
+  abstract sendHead(): void;
+  /**
+   * Write a chunk of data to the socket.
+   *
+   * You should encode the data to UTF-8 beforehand.
+   */
+  abstract sendChunk(chunk: string): void;
+  /**
+   * Perform any necessary cleanup after the connection is closed.
+   */
+  abstract cleanup(): void;
+}
+/**
+ * Options passed from `Session` `options` argument to the built-in `Connection` implementations.
+ */
+interface BuiltInConnectionOptions extends Pick<SessionOptions, "statusCode" | "headers"> {}
+//#endregion
+//#region src/adapters/FetchConnection.d.ts
+declare class FetchConnection extends Connection {
+  private static encoder;
+  private writer;
+  url: URL;
+  request: Request;
+  response: Response;
+  constructor(request: Request, response: Response | null, options?: BuiltInConnectionOptions);
+  sendHead: () => void;
+  sendChunk: (chunk: string) => void;
+  cleanup: () => void;
+}
+//#endregion
+//#region src/adapters/NodeHttp1Connection.d.ts
+declare class NodeHttp1Connection extends Connection {
+  private req;
+  private res;
+  private controller;
+  url: URL;
+  request: Request;
+  response: Response;
+  constructor(req: IncomingMessage, res: ServerResponse, options?: BuiltInConnectionOptions);
+  private onClose;
+  sendHead: () => void;
+  sendChunk: (chunk: string) => void;
+  cleanup: () => void;
+}
+//#endregion
+//#region src/adapters/NodeHttp2CompatConnection.d.ts
+declare class NodeHttp2CompatConnection extends Connection {
+  private req;
+  private res;
+  private controller;
+  url: URL;
+  request: Request;
+  response: Response;
+  constructor(req: Http2ServerRequest, res: Http2ServerResponse, options?: BuiltInConnectionOptions);
+  private onClose;
+  sendHead: () => void;
+  sendChunk: (chunk: string) => void;
+  cleanup: () => void;
+}
+//#endregion
+//#region src/Channel.d.ts
+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 randomly generated UUIDv4.
+   */
+  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 registered with this channel.
+   */
+  get activeSessions(): ReadonlyArray<Session<SessionState>>;
+  /**
+   * Number of sessions registered with 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;
+}
+//#endregion
+//#region src/createChannel.d.ts
+declare const createChannel: <State = DefaultChannelState, SessionState = DefaultSessionState>(...args: ConstructorParameters<typeof Channel<State, SessionState>>) => Channel<State, SessionState>;
+//#endregion
+//#region src/createEventBuffer.d.ts
+declare const createEventBuffer: (...args: ConstructorParameters<typeof EventBuffer>) => EventBuffer;
+//#endregion
+//#region src/createResponse.d.ts
+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 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: Connection, callback: CreateResponseCallback<State>): Response;
+declare function createResponse<State = DefaultSessionState>(request: Connection, options: SessionOptions<State>, callback: CreateResponseCallback<State>): Response;
+declare function createResponse<State = DefaultSessionState>(request: Request, response: Response, options: SessionOptions<State>, callback: CreateResponseCallback<State>): Response;
+//#endregion
+//#region src/createSession.d.ts
+/**
+ * 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>>;
+declare function createSession<State = DefaultSessionState>(req: Connection, options?: SessionOptions<State>): Promise<Session<State>>;
+//#endregion
+//#region src/utils/SseError.d.ts
+declare class SseError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { type BroadcastOptions, type BuiltInConnectionOptions, Channel, type ChannelEvents, type ChannelOptions, Connection, type ConnectionConstants, type CreateResponseCallback, type DefaultChannelState, type DefaultSessionState, EventBuffer, type EventBufferOptions, FetchConnection, type IterateOptions, NodeHttp1Connection, NodeHttp2CompatConnection, Session, type SessionEvents, type SessionOptions, SseError, type StreamOptions, createChannel, createEventBuffer, createResponse, createSession };