better-sse 0.14.0 → 0.15.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Matthew W.
+Copyright (c) 2025 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

@@ -7,9 +7,9 @@
 	<a href="https://github.com/MatthewWid/better-sse"><img src="https://img.shields.io/github/stars/MatthewWid/better-sse?style=social" /></a>
 </p>
 
-A dead simple, dependency-less, spec-compliant server-sent events implementation for Node, written in TypeScript.
+A dead simple, dependency-less, spec-compliant server-sent events implementation written in TypeScript.
 
-This package aims to be the easiest to use, most compliant and most streamlined solution to server-sent events with Node that is framework-agnostic and feature-rich.
+This package aims to be the easiest to use, most compliant and most streamlined solution to server-sent events that is framework-agnostic and feature-rich.
 
 Please consider starring the project [on GitHub ⭐](https://github.com/MatthewWid/better-sse).
 
@@ -21,115 +21,144 @@ Using SSE can allow for significant savings in bandwidth and battery life on por
 
 Compared to WebSockets it has comparable performance and bandwidth usage, especially over HTTP/2, and natively includes event ID generation and automatic reconnection when clients are disconnected.
 
+Read the [Getting Started](https://matthewwid.github.io/better-sse/guides/getting-started/) guide for more.
+
 * [Comparison: Server-sent Events vs WebSockets vs Polling](https://medium.com/dailyjs/a-comparison-between-websockets-server-sent-events-and-polling-7a27c98cb1e3)
 * [WHATWG standards section for server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
 * [MDN guide to server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
+* [Can I use... Server-sent events](https://caniuse.com/eventsource)
 
 ## Highlights
 
-* 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.)
+* Compatible with all popular HTTP frameworks ([Express](https://nodejs.org/api/http.html), [Hono](https://hono.dev/), [Fastify](https://fastify.dev/), [Nest](https://nestjs.com/), [Next.js](https://nextjs.org/), [Bun](https://bun.sh/docs/api/http), [Deno](https://docs.deno.com/runtime/fundamentals/http_server/), [etc.](https://matthewwid.github.io/better-sse/reference/recipes/))
 * 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.
+* [Event buffers](https://matthewwid.github.io/better-sse/guides/batching/) allow you to batch events for increased performance and lower bandwidth usage.
 * 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.
-* Send [individual fields](./docs/api.md#eventbuffer) of events or send [full events with simple helpers](./docs/api.md#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 SSE libraries in the documentation.](https://matthewwid.github.io/better-sse/reference/comparison)
 
 # Installation
 
-```bash
-# npm
+Install with any package manager:
+
+```sh
 npm install better-sse
+```
 
-# Yarn
+```sh
 yarn add better-sse
+```
 
-# pnpm
+```sh
 pnpm add better-sse
 ```
 
+```sh
+bun add better-sse
+```
+
+```sh
+deno install npm:better-sse
+```
+
 _Better SSE ships with types built in. No need to install from DefinitelyTyped for TypeScript users!_
 
 # Usage
 
-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).
+The examples below show usage with [Express](http://expressjs.com/) and [Hono](https://hono.dev/), but Better SSE works with any web-server framework that uses the Node [HTTP module](https://nodejs.org/api/http.html) or the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
 
-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/guides/getting-started/#create-a-session) to push events to clients:
 
 ```typescript
-// Server
-import { createSession } from "better-sse";
+// Server - Express
+import { createSession } from "better-sse"
 
 app.get("/sse", async (req, res) => {
-	const session = await createSession(req, res);
+	const session = await createSession(req, res)
+	session.push("Hello world!", "message")
+})
+```
 
-	session.push("Hello world!");
-});
+```typescript
+// Server - Hono
+import { createResponse } from "better-sse"
+
+app.get("/sse", (c) =>
+    createResponse(c.req.raw, (session) => {
+        session.push("Hello world!", "message")
+    })
+)
 ```
 
 ```typescript
 // Client
-const sse = new EventSource("/sse");
+const eventSource = new EventSource("/sse")
 
-sse.addEventListener("message", ({ data }) => {
-	console.log(JSON.parse(data));
-});
+eventSource.addEventListener("message", ({ data })) => {
+	const contents = JSON.parse(data)
+	console.log(contents) // Hello world!
+})
 ```
 
-Use [channels](./docs/channels.md) to send events to many clients at once:
+Use [channels](https://matthewwid.github.io/better-sse/guides/channels/#create-a-channel) to send events to many clients at once:
 
 ```typescript
-import { createSession, createChannel } from "better-sse";
+import { createSession, createChannel } from "better-sse"
 
-const channel = createChannel();
+const channel = createChannel()
 
 app.get("/sse", async (req, res) => {
-	const session = await createSession(req, res);
+	const session = await createSession(req, res)
 
-	channel.register(session);
+	channel.register(session)
 
-	channel.broadcast("A user has joined.", "join-notification");
-});
+	channel.broadcast("A user has joined.", "join-notification")
+})
 ```
 
-Loop over sync and async [iterables](./docs/api.md#sessioniterate-iterable-iterable--asynciterable-options-object--promisevoid) and send each value as an event:
+Use [batching](https://matthewwid.github.io/better-sse/guides/batching/) to send multiple events at once for improved performance and lower bandwidth usage:
 
 ```typescript
-const session = await createSession(req, res);
+await session.batch(async (buffer) => {
+    await buffer.iterate(["My", "huge", "event", "list"])
+})
+```
 
-const list = [1, 2, 3];
+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:
 
-await session.iterate(list);
+```typescript
+const iterable = [1, 2, 3]
+
+await session.iterate(iterable)
 ```
 
-Pipe [readable stream](./docs/api.md#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);
-
-const stream = Readable.from([1, 2, 3]);
+const stream = Readable.from([1, 2, 3])
 
-await session.stream(stream);
+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
 
@@ -141,29 +170,37 @@ For code or documentation changes [submit a pull request on GitHub](https://gith
 
 ## Local Development
 
-Install Node:
+Install [Node](https://nodejs.org/en) (with [n](https://github.com/tj/n)):
 
 ```bash
 curl -L https://git.io/n-install | bash
 n auto
 ```
 
-Install pnpm:
+Install dependencies (with [pnpm](https://pnpm.io/)):
 
 ```bash
 npm i -g pnpm
+pnpm i
 ```
 
-Install dependencies:
+Run tests (with [Vitest](https://vitest.dev/)):
 
 ```bash
-pnpm i
+pnpm t
 ```
 
-Run tests:
+Lint and format (with [Biome](https://biomejs.dev/)):
 
 ```bash
-pnpm t
+pnpm lint
+pnpm format
+```
+
+Bundle for distribution (with [tsup](https://tsup.egoist.dev/)):
+
+```bash
+pnpm build
 ```
 
 # License

package/build/index.d.mts

@@ -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 { EventEmitter } from 'node:events';
 
 interface IterateOptions {
     /**
@@ -23,16 +21,12 @@ interface StreamOptions {
     eventName?: string;
 }
 
+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 {
     /**
@@ -126,7 +120,7 @@ declare class EventBuffer {
      *
      * @returns A promise that resolves or rejects based on the success of the stream write finishing.
      */
-    stream: (stream: stream.Readable, options?: StreamOptions) => Promise<boolean>;
+    stream: (stream: stream.Readable | ReadableStream<any>, options?: StreamOptions) => Promise<boolean>;
     /**
      * Iterate over an iterable and write yielded values as events into the buffer.
      *
@@ -218,7 +212,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 +233,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 +274,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 +320,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.
@@ -353,7 +341,7 @@ declare class Session<State = DefaultSessionState> extends TypedEmitter<SessionE
      *
      * @returns A promise that resolves or rejects based on the success of the stream write finishing.
      */
-    stream: (stream: stream.Readable, options?: StreamOptions) => Promise<boolean>;
+    stream: (stream: stream.Readable | ReadableStream<any>, options?: StreamOptions) => Promise<boolean>;
     /**
      * Iterate over an iterable and send yielded values as events to the client.
      *
@@ -384,9 +372,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 +491,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 };