better-sse 0.7.1 → 0.8.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2020 Matthew
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2020 Matthew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,177 +1,177 @@
-# Better SSE
-
-<p>
-	<img src="https://img.shields.io/npm/v/better-sse?color=blue&style=flat-square" />
-	<img src="https://img.shields.io/npm/l/better-sse?color=green&style=flat-square" />
-	<img src="https://img.shields.io/npm/dt/better-sse?color=grey&style=flat-square" />
-	<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-side events implementation for Node, written in TypeScript.
-
-This package aims to be the easiest to use, most compliant and most streamlined solution to server-side events with Node that is framework agnostic and feature rich.
-
-Please consider starring the project [on GitHub ⭐](https://github.com/MatthewWid/better-sse).
-
-## Why use Server-sent Events?
-
-Server-sent events (SSE) is a standardised protocol that allows web-servers to push data to clients without the need for alternative mechanisms such as pinging or long-polling.
-
-Using SSE can allow for significant savings in bandwidth and battery life on portable devices, and will work with your existing infrastructure as it operates directly over the HTTP protocol without the need for the connection upgrade that [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) require.
-
-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.
-
-* [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)
-
-## 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.)
-* 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.
-* Configurable reconnection time, message serialization and data sanitization (but 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](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#fields) of events or sending full events with simple helpers.
-* 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 stream of events.
-* Support for popular EventStream 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)
-
-# Installation
-
-```bash
-# npm
-npm install better-sse
-
-# Yarn
-yarn add better-sse
-
-# pnpm
-pnpm add better-sse
-```
-
-_Better SSE ships with types built in. No need to install from `@types` 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)).
-
-See the [Recipes](./docs/recipes.md) section of the documentation for use with other frameworks and libraries.
-
----
-
-Use [sessions](./docs/api.md#session) to push events to clients:
-
-```typescript
-// Server
-import {createSession} from "better-sse";
-
-app.get("/sse", async (req, res) => {
-	const session = await createSession(req, res);
-
-	session.push("Hello world!");
-});
-```
-
-```typescript
-// Client
-const sse = new EventSource("/sse");
-
-sse.addEventListener("message", ({data}) => {
-	console.log(data);
-});
-```
-
----
-
-Use [channels](./docs/channels.md) to send events to many clients at once:
-
-```typescript
-import {createSession, createChannel} from "better-sse";
-
-const channel = createChannel();
-
-app.get("/sse", async (req, res) => {
-	const session = await createSession(req, res);
-
-	channel.register(session);
-
-	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:
-
-```typescript
-const session = await createSession(req, res);
-
-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:
-
-```typescript
-const session = await createSession(req, res);
-
-const stream = Readable.from([1, 2, 3]);
-
-await session.stream(stream);
-```
-
----
-
-Check the [API documentation](./docs/api.md) and [live examples](https://github.com/MatthewWid/better-sse/tree/master/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](https://github.com/MatthewWid/better-sse/tree/master/docs).
-
-# Contributing
-
-This library is always open to contributions, whether it be code, bug reports, documentation or anything else.
-
-Please submit suggestions, bugs and issues to the [GitHub issues page](https://github.com/MatthewWid/better-sse/issues).
-
-For code or documentation changes, [submit a pull request on GitHub](https://github.com/MatthewWid/better-sse/pulls).
-
-## Local Development
-
-Install Node:
-
-```bash
-curl -L https://git.io/n-install | bash
-n auto
-```
-
-Install pnpm:
-
-```bash
-npm i -g pnpm
-```
-
-Install dependencies:
-
-```bash
-pnpm i
-```
-
-Run tests:
-
-```bash
-pnpm t
-```
-
-# License
-
-This project is licensed under the MIT license.
+# Better SSE
+
+<p>
+	<img src="https://img.shields.io/npm/v/better-sse?color=blue&style=flat-square" />
+	<img src="https://img.shields.io/npm/l/better-sse?color=green&style=flat-square" />
+	<img src="https://img.shields.io/npm/dt/better-sse?color=grey&style=flat-square" />
+	<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-side events implementation for Node, written in TypeScript.
+
+This package aims to be the easiest to use, most compliant and most streamlined solution to server-side events with Node that is framework agnostic and feature rich.
+
+Please consider starring the project [on GitHub ⭐](https://github.com/MatthewWid/better-sse).
+
+## Why use Server-sent Events?
+
+Server-sent events (SSE) is a standardised protocol that allows web-servers to push data to clients without the need for alternative mechanisms such as pinging or long-polling.
+
+Using SSE can allow for significant savings in bandwidth and battery life on portable devices, and will work with your existing infrastructure as it operates directly over the HTTP protocol without the need for the connection upgrade that [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) require.
+
+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.
+
+* [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)
+
+## 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.)
+* 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.
+* Configurable reconnection time, message serialization and data sanitization (but 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](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#fields) of events or sending full events with simple helpers.
+* 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 stream of events.
+* Support for popular EventStream 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)
+
+# Installation
+
+```bash
+# npm
+npm install better-sse
+
+# Yarn
+yarn add better-sse
+
+# pnpm
+pnpm add better-sse
+```
+
+_Better SSE ships with types built in. No need to install from `@types` 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)).
+
+See the [Recipes](./docs/recipes.md) section of the documentation for use with other frameworks and libraries.
+
+---
+
+Use [sessions](./docs/api.md#session) to push events to clients:
+
+```typescript
+// Server
+import {createSession} from "better-sse";
+
+app.get("/sse", async (req, res) => {
+	const session = await createSession(req, res);
+
+	session.push("Hello world!");
+});
+```
+
+```typescript
+// Client
+const sse = new EventSource("/sse");
+
+sse.addEventListener("message", ({data}) => {
+	console.log(data);
+});
+```
+
+---
+
+Use [channels](./docs/channels.md) to send events to many clients at once:
+
+```typescript
+import {createSession, createChannel} from "better-sse";
+
+const channel = createChannel();
+
+app.get("/sse", async (req, res) => {
+	const session = await createSession(req, res);
+
+	channel.register(session);
+
+	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:
+
+```typescript
+const session = await createSession(req, res);
+
+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:
+
+```typescript
+const session = await createSession(req, res);
+
+const stream = Readable.from([1, 2, 3]);
+
+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!
+
+# Documentation
+
+API documentation, getting started guides and usage with other frameworks is [available on GitHub](./docs).
+
+# Contributing
+
+This library is always open to contributions, whether it be code, bug reports, documentation or anything else.
+
+Please submit suggestions, bugs and issues to the [GitHub issues page](https://github.com/MatthewWid/better-sse/issues).
+
+For code or documentation changes, [submit a pull request on GitHub](https://github.com/MatthewWid/better-sse/pulls).
+
+## Local Development
+
+Install Node:
+
+```bash
+curl -L https://git.io/n-install | bash
+n auto
+```
+
+Install pnpm:
+
+```bash
+npm i -g pnpm
+```
+
+Install dependencies:
+
+```bash
+pnpm i
+```
+
+Run tests:
+
+```bash
+pnpm t
+```
+
+# License
+
+This project is licensed under the MIT license.

package/build/Channel.d.ts

@@ -12,7 +12,7 @@ interface ChannelEvents extends EventMap {
     "session-registered": (session: Session) => void;
     "session-deregistered": (session: Session) => void;
     "session-disconnected": (session: Session) => void;
-    broadcast: (data: unknown, eventName: string) => void;
+    broadcast: (data: unknown, eventName: string, eventId: string) => void;
 }
 /**
  * A Channel is used to broadcast events to many sessions at once.
@@ -38,12 +38,16 @@ declare class Channel<State extends Record<string, unknown> = Record<string, unk
     /**
      * Register a session so that it can start receiving events from this channel.
      *
+     * If the session is already registered this method does nothing.
+     *
      * @param session - Session to register.
      */
     register(session: Session): 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): this;
@@ -52,7 +56,7 @@ declare class Channel<State extends Record<string, unknown> = Record<string, unk
      *
      * Takes the same arguments as the `Session#push` method.
      */
-    broadcast: (data: unknown, eventName?: string | undefined, options?: BroadcastOptions) => this;
+    broadcast: (data: unknown, eventName?: string, options?: BroadcastOptions) => this;
 }
 export type { BroadcastOptions, ChannelEvents };
 export { Channel };

package/build/Session.d.ts

@@ -1,6 +1,8 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { Readable } from "stream";
-import { IncomingMessage, ServerResponse, OutgoingHttpHeaders } from "http";
+import { IncomingMessage as Http1ServerRequest, ServerResponse as Http1ServerResponse, OutgoingHttpHeaders } from "http";
+import { Http2ServerRequest, Http2ServerResponse } from "http2";
 import { TypedEmitter, EventMap } from "./lib/TypedEmitter";
 import { SerializerFunction } from "./lib/serialize";
 import { SanitizerFunction } from "./lib/sanitize";
@@ -28,9 +30,11 @@ interface SessionOptions {
      */
     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.
+     * 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.
      *
-     * This is equivalent to immediately calling `.retry().dispatch()` after a connection is made.
+     * 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.
      *
@@ -103,6 +107,7 @@ interface SessionEvents extends EventMap {
 declare class Session<State extends Record<string, unknown> = SessionState> extends TypedEmitter<SessionEvents> {
     /**
      * The last 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.
      *
      * @readonly
@@ -116,10 +121,24 @@ declare class Session<State extends Record<string, unknown> = SessionState> exte
     isConnected: boolean;
     /**
      * Custom state for this session.
+     *
      * Use this object to safely store information related to the session and user.
      */
     state: State;
+    /**
+     * Internal buffer used to store raw data from written fields.
+     *
+     * When Session#dispatch is called its buffer data will be flushed.
+     */
+    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;
@@ -129,18 +148,14 @@ declare class Session<State extends Record<string, unknown> = SessionState> exte
     private keepAliveTimer?;
     private statusCode;
     private headers;
-    constructor(req: IncomingMessage, res: ServerResponse, options?: SessionOptions);
-    private onConnected;
+    constructor(req: Http1ServerRequest | Http2ServerRequest, res: Http1ServerResponse | Http2ServerResponse, options?: SessionOptions);
+    private initialize;
     private onDisconnected;
     /**
      * Write a line with a field key and value appended with a newline character.
      */
     private writeField;
     private keepAlive;
-    /**
-     * Flush the buffered data to the client by writing an additional newline.
-     */
-    dispatch: () => this;
     /**
      * Set the event to the given name (also referred to as "type" in the specification).
      *
@@ -148,7 +163,7 @@ declare class Session<State extends Record<string, unknown> = SessionState> exte
      */
     event(type: string): this;
     /**
-     * Write arbitrary data onto the wire that is automatically serialized to a string using the given `serializer` function option or JSON stringification by default.
+     * Write an arbitrary data field that is automatically serialized to a string using the given `serializer` function option or JSON stringification by default.
      *
      * @param data - Data to serialize and write.
      */
@@ -156,11 +171,11 @@ declare class Session<State extends Record<string, unknown> = SessionState> exte
     /**
      * Set the event ID to the given string.
      *
-     * Passing `null` will set the event ID to an empty string value.
+     * Defaults to an empty string if no argument is given.
      *
      * @param id - Identification string to write.
      */
-    id: (id: string | null) => this;
+    id: (id?: string) => this;
     /**
      * Set the suggested reconnection time to the given milliseconds.
      *
@@ -174,19 +189,33 @@ declare class Session<State extends Record<string, unknown> = SessionState> exte
      *
      * @param text - Text of the comment. Otherwise writes an empty field value.
      */
-    comment: (text?: string | undefined) => this;
+    comment: (text?: string) => this;
     /**
-     * Create and dispatch an event with the given data all at once.
-     * This is equivalent to calling `.event()`, `.id()`, `.data()` and `.dispatch()` in that order.
+     * Indicate that the event has finished being created by writing an additional newline character.
+     *
+     * Note that this does **not** send the written data to the client. Use `flush` to flush the internal buffer.
+     */
+    dispatch: () => this;
+    /**
+     * Flush the buffered data to the client and clear the buffer.
+     */
+    flush: () => this;
+    /**
+     * Create, dispatch and flush an event with the given data all at once.
+     *
+     * This is equivalent to calling the methods `event`, `id`, `data`, `dispatch` and `flush` in that order.
+     *
+     * If no event name is given, the event name is set to `"message"`.
      *
-     * If no event name is given, the event name (type) 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.
      *
-     * Note that this sets the event ID (and thus the `lastId` property) to a string of eight random characters (`a-z0-9`).
+     * 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 | undefined, eventId?: string | undefined) => this;
+    push: (data: unknown, eventName?: string, eventId?: string) => this;
     /**
      * Pipe readable stream data to the client.
      *

package/build/createSession.d.ts

@@ -2,5 +2,5 @@ import { Session, SessionState } from "./Session";
 /**
  * Create a new session and return the session instance once it has connected.
  */
-declare const createSession: <State extends Record<string, unknown> = SessionState>(req: import("http").IncomingMessage, res: import("http").ServerResponse, options?: import("./Session").SessionOptions | undefined) => Promise<Session<State>>;
+declare const createSession: <State extends Record<string, unknown> = SessionState>(req: import("http").IncomingMessage | import("http2").Http2ServerRequest, res: import("http").ServerResponse | import("http2").Http2ServerResponse, options?: import("./Session").SessionOptions | undefined) => Promise<Session<State>>;
 export { createSession };

package/build/index.js

@@ -1,2 +1,2 @@
-!function(e,t){if("object"==typeof exports&&"object"==typeof module)module.exports=t();else if("function"==typeof define&&define.amd)define([],t);else{var s=t();for(var i in s)("object"==typeof exports?exports:e)[i]=s[i]}}(global,(function(){return(()=>{"use strict";var e={n:t=>{var s=t&&t.__esModule?()=>t.default:()=>t;return e.d(s,{a:s}),s},d:(t,s)=>{for(var i in s)e.o(s,i)&&!e.o(t,i)&&Object.defineProperty(t,i,{enumerable:!0,get:s[i]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},t={};e.r(t),e.d(t,{Channel:()=>d,Session:()=>a,createChannel:()=>c,createSession:()=>l});const s=require("crypto"),i=require("events");var n=e.n(i);class r extends(n()){addListener(e,t){return super.addListener(e,t)}prependListener(e,t){return super.prependListener(e,t)}prependOnceListener(e,t){return super.prependOnceListener(e,t)}on(e,t){return super.on(e,t)}once(e,t){return super.once(e,t)}emit(e,...t){return super.emit(e,...t)}off(e,t){return super.off(e,t)}removeListener(e,t){return super.removeListener(e,t)}}const o=e=>JSON.stringify(e),h=e=>{let t=e;return t=t.replace(/(\r\n|\r|\n)/g,"\n"),t=t.replace(/\n+$/g,""),t};class a extends r{constructor(e,t,i={}){var n,r,a,l,d,c,u;super(),this.lastId="",this.isConnected=!1,this.state={},this.onConnected=()=>{var e,t,s;const i=`http://${this.req.headers.host}${this.req.url}`,n=new URL(i).searchParams;if(this.trustClientEventId){const i=null!==(s=null!==(t=null!==(e=this.req.headers["last-event-id"])&&void 0!==e?e:n.get("lastEventId"))&&void 0!==t?t:n.get("evs_last_event_id"))&&void 0!==s?s:"";this.lastId=i}Object.entries(this.headers).forEach((([e,t])=>{this.res.setHeader(e,null!=t?t:"")})),this.res.statusCode=this.statusCode,this.res.setHeader("Content-Type","text/event-stream"),this.res.setHeader("Cache-Control","no-cache, no-transform"),this.res.setHeader("Connection","keep-alive"),this.res.flushHeaders(),n.has("padding")&&this.comment(" ".repeat(2049)).dispatch(),n.has("evs_preamble")&&this.comment(" ".repeat(2056)).dispatch(),null!==this.initialRetry&&this.retry(this.initialRetry).dispatch(),null!==this.keepAliveInterval&&(this.keepAliveTimer=setInterval(this.keepAlive,this.keepAliveInterval)),this.isConnected=!0,this.emit("connected")},this.onDisconnected=()=>{this.keepAliveTimer&&clearInterval(this.keepAliveTimer),this.isConnected=!1,this.emit("disconnected")},this.writeField=(e,t)=>{const s=`${e}:${this.sanitize(t)}\n`;return this.res.write(s),this},this.keepAlive=()=>{this.comment().dispatch()},this.dispatch=()=>(this.res.write("\n"),this),this.data=e=>{const t=this.serialize(e);return this.writeField("data",t),this},this.id=e=>{const t=e||"";return this.writeField("id",t),this.lastId=t,this},this.retry=e=>{const t=e.toString();return this.writeField("retry",t),this},this.comment=e=>(this.writeField("",null!=e?e:""),this),this.push=(e,t,i)=>(t||(t="message"),i||(i=(0,s.randomBytes)(4).toString("hex")),this.event(t).id(i).data(e).dispatch(),this.emit("push",e,t,i),this),this.stream=async(e,t={})=>{const{eventName:s="stream"}=t;return new Promise(((t,i)=>{e.on("data",(e=>{let t;t=Buffer.isBuffer(e)?e.toString():e,this.push(t,s)})),e.once("end",(()=>t(!0))),e.once("close",(()=>t(!0))),e.once("error",(e=>i(e)))}))},this.iterate=async(e,t={})=>{const{eventName:s="iteration"}=t;for await(const t of e)this.push(t,s)},this.req=e,this.res=t,this.serialize=null!==(n=i.serializer)&&void 0!==n?n:o,this.sanitize=null!==(r=i.sanitizer)&&void 0!==r?r:h,this.trustClientEventId=null===(a=i.trustClientEventId)||void 0===a||a,this.initialRetry=null===i.retry?null:null!==(l=i.retry)&&void 0!==l?l:2e3,this.keepAliveInterval=null===i.keepAlive?null:null!==(d=i.keepAlive)&&void 0!==d?d:1e4,this.statusCode=null!==(c=i.statusCode)&&void 0!==c?c:200,this.headers=null!==(u=i.headers)&&void 0!==u?u:{},this.req.on("close",this.onDisconnected),setImmediate(this.onConnected)}event(e){return this.writeField("event",e),this}}const l=(...e)=>new Promise((t=>{const s=new a(...e);s.once("connected",(()=>{t(s)}))}));class d extends r{constructor(){super(),this.state={},this.sessions=[],this.broadcast=(e,t,s={})=>{t||(t="message");const i=s.filter?this.sessions.filter(s.filter):this.sessions;for(const s of i)s.push(e,t);return this.emit("broadcast",e,t),this}}get activeSessions(){return this.sessions}get sessionCount(){return this.sessions.length}register(e){if(!e.isConnected)throw new Error("Cannot register a non-active session.");return e.once("disconnected",(()=>{this.deregister(e),this.emit("session-disconnected",e)})),this.sessions.push(e),this.emit("session-registered",e),this}deregister(e){return this.sessions=this.sessions.filter((t=>t!==e)),this.emit("session-deregistered",e),this}}const c=(...e)=>new d(...e);return t})()}));
+!function(e,t){if("object"==typeof exports&&"object"==typeof module)module.exports=t();else if("function"==typeof define&&define.amd)define([],t);else{var s=t();for(var i in s)("object"==typeof exports?exports:e)[i]=s[i]}}(global,(()=>(()=>{"use strict";var e={n:t=>{var s=t&&t.__esModule?()=>t.default:()=>t;return e.d(s,{a:s}),s},d:(t,s)=>{for(var i in s)e.o(s,i)&&!e.o(t,i)&&Object.defineProperty(t,i,{enumerable:!0,get:s[i]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},t={};e.r(t),e.d(t,{Channel:()=>f,Session:()=>u,createChannel:()=>v,createSession:()=>p});const s=require("http"),i=require("events");var r=e.n(i);class n extends(r()){addListener(e,t){return super.addListener(e,t)}prependListener(e,t){return super.prependListener(e,t)}prependOnceListener(e,t){return super.prependOnceListener(e,t)}on(e,t){return super.on(e,t)}once(e,t){return super.once(e,t)}emit(e,...t){return super.emit(e,...t)}off(e,t){return super.off(e,t)}removeListener(e,t){return super.removeListener(e,t)}}const o=e=>JSON.stringify(e),a=/(\r\n|\r|\n)/g,h=/\n+$/g,l=e=>{let t=e;return t=t.replace(a,"\n"),t=t.replace(h,""),t},d=require("crypto");let c;c=d.randomUUID?()=>(0,d.randomUUID)():()=>(0,d.randomBytes)(4).toString("hex");class u extends n{constructor(e,t,i={}){var r,n,a,h,d,u,p;super(),this.lastId="",this.isConnected=!1,this.state={},this.buffer="",this.initialize=()=>{var e,t,i;const r=`http://${this.req.headers.host}${this.req.url}`,n=new URL(r).searchParams;if(this.trustClientEventId){const s=null!==(i=null!==(t=null!==(e=this.req.headers["last-event-id"])&&void 0!==e?e:n.get("lastEventId"))&&void 0!==t?t:n.get("evs_last_event_id"))&&void 0!==i?i:"";this.lastId=s}const o={};this.res instanceof s.ServerResponse?(o["Content-Type"]="text/event-stream",o["Cache-Control"]="private, no-cache, no-store, no-transform, must-revalidate, max-age=0",o.Connection="keep-alive",o.Pragma="no-cache",o["X-Accel-Buffering"]="no"):(o["content-type"]="text/event-stream",o["cache-control"]="private, no-cache, no-store, no-transform, must-revalidate, max-age=0",o.pragma="no-cache",o["x-accel-buffering"]="no");for(const[e,t]of Object.entries(this.headers))o[e]=null!=t?t:"";this.res.writeHead(this.statusCode,o),n.has("padding")&&this.comment(" ".repeat(2049)).dispatch(),n.has("evs_preamble")&&this.comment(" ".repeat(2056)).dispatch(),null!==this.initialRetry&&this.retry(this.initialRetry).dispatch(),this.flush(),null!==this.keepAliveInterval&&(this.keepAliveTimer=setInterval(this.keepAlive,this.keepAliveInterval)),this.isConnected=!0,this.emit("connected")},this.onDisconnected=()=>{this.keepAliveTimer&&clearInterval(this.keepAliveTimer),this.isConnected=!1,this.emit("disconnected")},this.writeField=(e,t)=>{const s=this.sanitize(t);return this.buffer+=e+":"+s+"\n",this},this.keepAlive=()=>{this.comment().dispatch().flush()},this.data=e=>{const t=this.serialize(e);return this.writeField("data",t),this},this.id=(e="")=>(this.writeField("id",e),this.lastId=e,this),this.retry=e=>{const t=e.toString();return this.writeField("retry",t),this},this.comment=(e="")=>(this.writeField("",e),this),this.dispatch=()=>(this.buffer+="\n",this),this.flush=()=>(this.res.write(this.buffer),this.buffer="",this),this.push=(e,t="message",s=c())=>(this.event(t).id(s).data(e).dispatch().flush(),this.emit("push",e,t,s),this),this.stream=async(e,t={})=>{const{eventName:s="stream"}=t;return new Promise(((t,i)=>{e.on("data",(e=>{let t;t=Buffer.isBuffer(e)?e.toString():e,this.push(t,s)})),e.once("end",(()=>t(!0))),e.once("close",(()=>t(!0))),e.once("error",(e=>i(e)))}))},this.iterate=async(e,t={})=>{const{eventName:s="iteration"}=t;for await(const t of e)this.push(t,s)},this.req=e,this.res=t,this.serialize=null!==(r=i.serializer)&&void 0!==r?r:o,this.sanitize=null!==(n=i.sanitizer)&&void 0!==n?n:l,this.trustClientEventId=null===(a=i.trustClientEventId)||void 0===a||a,this.initialRetry=null===i.retry?null:null!==(h=i.retry)&&void 0!==h?h:2e3,this.keepAliveInterval=null===i.keepAlive?null:null!==(d=i.keepAlive)&&void 0!==d?d:1e4,this.statusCode=null!==(u=i.statusCode)&&void 0!==u?u:200,this.headers=null!==(p=i.headers)&&void 0!==p?p:{},this.req.once("close",this.onDisconnected),setImmediate(this.initialize)}event(e){return this.writeField("event",e),this}}const p=(...e)=>new Promise((t=>{const s=new u(...e);s.once("connected",(()=>{t(s)}))}));class f extends n{constructor(){super(),this.state={},this.sessions=new Set,this.broadcast=(e,t="message",s={})=>{const i=c();let r;r=s.filter?Array.from(this.sessions).filter(s.filter):this.sessions;for(const s of r)s.push(e,t,i);return this.emit("broadcast",e,t,i),this}}get activeSessions(){return Array.from(this.sessions)}get sessionCount(){return this.sessions.size}register(e){if(this.sessions.has(e))return this;if(!e.isConnected)throw new Error("Cannot register a non-active session.");return e.once("disconnected",(()=>{this.emit("session-disconnected",e),this.deregister(e)})),this.sessions.add(e),this.emit("session-registered",e),this}deregister(e){return this.sessions.has(e)?(this.sessions.delete(e),this.emit("session-deregistered",e),this):this}}const v=(...e)=>new f(...e);return t})()));
 //# sourceMappingURL=index.js.map

package/build/lib/generateId.d.ts

@@ -0,0 +1,2 @@
+declare let generateId: () => string;
+export { generateId };

package/build/lib/testUtils.d.ts

@@ -1,7 +1,10 @@
 import http from "http";
+import http2 from "http2";
+import net from "net";
 import { Session } from "../Session";
-declare const createServer: () => Promise<http.Server>;
-declare const closeServer: (server: http.Server) => Promise<void>;
-declare const getUrl: (server: http.Server) => string;
+declare const createHttpServer: () => Promise<http.Server>;
+declare const createHttp2Server: () => Promise<http2.Http2Server>;
+declare const closeServer: (server: net.Server) => Promise<void>;
+declare const getUrl: (server: net.Server) => string;
 declare const waitForConnect: (session: Session) => Promise<void>;
-export { createServer, closeServer, getUrl, waitForConnect };
+export { createHttpServer, createHttp2Server, closeServer, getUrl, waitForConnect, };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "better-sse",
   "description": "Dead simple, dependency-less, spec-compliant server-side events implementation for Node, written in TypeScript.",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "license": "MIT",
   "author": "Matthew W. <matthew.widdi@gmail.com>",
   "repository": "github:MatthewWid/better-sse",
-  "homepage": "https://github.com/MatthewWid/better-sse/blob/master/README.md",
+  "homepage": "https://github.com/MatthewWid/better-sse",
   "bugs": "https://github.com/MatthewWid/better-sse/issues",
   "keywords": [
     "server-sent-events",
@@ -26,25 +26,26 @@
     "pnpm": ">=6"
   },
   "devDependencies": {
+    "@jest/types": "^28.1.0",
     "@types/eventsource": "^1.1.8",
     "@types/express": "^4.17.13",
-    "@types/jest": "^26.0.14",
-    "@types/node": "^17.0.8",
-    "@typescript-eslint/eslint-plugin": "^5.9.0",
-    "@typescript-eslint/parser": "^5.9.0",
-    "eslint": "^8.6.0",
-    "eslint-plugin-tsdoc": "^0.2.14",
-    "eventsource": "^1.1.0",
+    "@types/jest": "^26.0.24",
+    "@types/node": "^17.0.36",
+    "@typescript-eslint/eslint-plugin": "^5.26.0",
+    "@typescript-eslint/parser": "^5.26.0",
+    "eslint": "^8.16.0",
+    "eslint-plugin-tsdoc": "^0.2.16",
+    "eventsource": "^1.1.1",
     "jest": "^26.6.3",
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.5.1",
+    "prettier": "^2.6.2",
     "rimraf": "^3.0.2",
     "ts-jest": "^26.5.6",
-    "ts-loader": "^9.2.6",
-    "ts-node": "^10.4.0",
-    "typescript": "^4.5.4",
-    "webpack": "^5.65.0",
-    "webpack-cli": "^4.9.1"
+    "ts-loader": "^9.3.0",
+    "ts-node": "^10.8.0",
+    "typescript": "^4.7.2",
+    "webpack": "^5.72.1",
+    "webpack-cli": "^4.9.2"
   },
   "scripts": {
     "build": "webpack --env production",
@@ -52,6 +53,5 @@
     "clean": "rimraf ./build",
     "format": "prettier --write ./src/**/*.ts",
     "lint": "eslint \"./src/**/*.ts\""
-  },
-  "readme": "# Better SSE\n\n<p>\n\t<img src=\"https://img.shields.io/npm/v/better-sse?color=blue&style=flat-square\" />\n\t<img src=\"https://img.shields.io/npm/l/better-sse?color=green&style=flat-square\" />\n\t<img src=\"https://img.shields.io/npm/dt/better-sse?color=grey&style=flat-square\" />\n\t<a href=\"https://github.com/MatthewWid/better-sse\"><img src=\"https://img.shields.io/github/stars/MatthewWid/better-sse?style=social\" /></a>\n</p>\n\nA dead simple, dependency-less, spec-compliant server-side events implementation for Node, written in TypeScript.\n\nThis package aims to be the easiest to use, most compliant and most streamlined solution to server-side events with Node that is framework agnostic and feature rich.\n\nPlease consider starring the project [on GitHub ⭐](https://github.com/MatthewWid/better-sse).\n\n## Why use Server-sent Events?\n\nServer-sent events (SSE) is a standardised protocol that allows web-servers to push data to clients without the need for alternative mechanisms such as pinging or long-polling.\n\nUsing SSE can allow for significant savings in bandwidth and battery life on portable devices, and will work with your existing infrastructure as it operates directly over the HTTP protocol without the need for the connection upgrade that [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) require.\n\nCompared 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.\n\n* [Comparison: Server-sent Events vs WebSockets vs Polling](https://medium.com/dailyjs/a-comparison-between-websockets-server-sent-events-and-polling-7a27c98cb1e3)\n* [WHATWG standards section for server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)\n* [MDN guide to server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)\n\n## Highlights\n\n* 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.)\n* Fully written in TypeScript (+ ships with types directly).\n* [Thoroughly tested](./src/Session.test.ts) (+ 100% code coverage!).\n* [Comprehensively documented](./docs) with guides and API documentation.\n* [Channels](./docs/channels.md) allow you to broadcast events to many clients at once.\n* Configurable reconnection time, message serialization and data sanitization (but with good defaults).\n* Trust or ignore the client-given last event ID.\n* Automatically send keep-alive pings to keep connections open.\n* Add or override the response status code and headers.\n* Fine-grained control by either sending [individual fields](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#fields) of events or sending full events with simple helpers.\n* 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 stream of events.\n* Support for popular EventStream polyfills [`event-source-polyfill`](https://www.npmjs.com/package/event-source-polyfill) and [`eventsource-polyfill`](https://www.npmjs.com/package/eventsource-polyfill).\n\n[See a comparison with other Node SSE libraries in the documentation.](./docs/comparison.md)\n\n# Installation\n\n```bash\n# npm\nnpm install better-sse\n\n# Yarn\nyarn add better-sse\n\n# pnpm\npnpm add better-sse\n```\n\n_Better SSE ships with types built in. No need to install from `@types` for TypeScript users!_\n\n# Usage\n\nThe 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)).\n\nSee the [Recipes](./docs/recipes.md) section of the documentation for use with other frameworks and libraries.\n\n---\n\nUse [sessions](./docs/api.md#session) to push events to clients:\n\n```typescript\n// Server\nimport {createSession} from \"better-sse\";\n\napp.get(\"/sse\", async (req, res) => {\n\tconst session = await createSession(req, res);\n\n\tsession.push(\"Hello world!\");\n});\n```\n\n```typescript\n// Client\nconst sse = new EventSource(\"/sse\");\n\nsse.addEventListener(\"message\", ({data}) => {\n\tconsole.log(data);\n});\n```\n\n---\n\nUse [channels](./docs/channels.md) to send events to many clients at once:\n\n```typescript\nimport {createSession, createChannel} from \"better-sse\";\n\nconst channel = createChannel();\n\napp.get(\"/sse\", async (req, res) => {\n\tconst session = await createSession(req, res);\n\n\tchannel.register(session);\n\n\tchannel.broadcast(\"A user has joined.\", \"join-notification\");\n});\n```\n\n---\n\nLoop over sync and async [iterables](./docs/api.md#sessioniterate-iterable-iterable--asynciterable-options-object--promisevoid) and send each value as an event:\n\n```typescript\nconst session = await createSession(req, res);\n\nconst list = [1, 2, 3];\n\nawait session.iterate(list);\n```\n\n---\n\nPipe [readable stream](#sessionstream-stream-readable-options-object--promiseboolean) data to the client as a stream of events:\n\n```typescript\nconst session = await createSession(req, res);\n\nconst stream = Readable.from([1, 2, 3]);\n\nawait session.stream(stream);\n```\n\n---\n\nCheck the [API documentation](./docs/api.md) and [live examples](https://github.com/MatthewWid/better-sse/tree/master/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!\n\n# Documentation\n\nAPI documentation, getting started guides and usage with other frameworks is [available on GitHub](https://github.com/MatthewWid/better-sse/tree/master/docs).\n\n# Contributing\n\nThis library is always open to contributions, whether it be code, bug reports, documentation or anything else.\n\nPlease submit suggestions, bugs and issues to the [GitHub issues page](https://github.com/MatthewWid/better-sse/issues).\n\nFor code or documentation changes, [submit a pull request on GitHub](https://github.com/MatthewWid/better-sse/pulls).\n\n## Local Development\n\nInstall Node:\n\n```bash\ncurl -L https://git.io/n-install | bash\nn auto\n```\n\nInstall pnpm:\n\n```bash\nnpm i -g pnpm\n```\n\nInstall dependencies:\n\n```bash\npnpm i\n```\n\nRun tests:\n\n```bash\npnpm t\n```\n\n# License\n\nThis project is licensed under the MIT license.\n"
+  }
 }