Merge pull request #68 from MatthewWid/infer-state-type

Allow passing initial session and channel state in constructor

Author: MatthewWid

docs/api.md

@@ -41,6 +41,7 @@ Note that creating a new session will immediately send the initial status code a
 |`keepAlive`|`number` \| `null`|`10000`|Time in milliseconds interval for the session to send a comment to keep the connection alive.<br><br>Give as `null` to disable the keep-alive mechanism.|
 |`statusCode`|`number`|`200`|Status code to be sent to the client.<br><br>Event stream requests can be redirected using HTTP 301 and 307 status codes. Make sure to set `Location` header when using these status codes (301/307) using the `headers` property.<br><br>A client can be asked to stop reconnecting by send a 204 status code.|
 |`headers`|`object`|`{}`|Additional headers to be sent along with the response.|
+|`state`|`object`|`{}`|Initial custom state for the session.<br><br>Accessed via the [`state`](#sessionstate-state) property.<br><br>When using TypeScript, providing the initial state structure allows the type of the `state` property to be automatically inferred.|
 
 #### `Session#lastId`: `string`
 
@@ -60,6 +61,8 @@ Custom state for this session.
 
 Use this object to safely store information related to the session and user.
 
+You may set an initial value for this property using the `state` property in the [constructor `options` object](#new-sessionstate--defaultsessionstatereq-incomingmessage--http2serverrequest-res-serverresponse--http2serverresponse-options--), allowing its type to be automatically inferred.
+
 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.
 
 #### `Session#push`: `(data: unknown[, eventName: string[, eventId: string]]) => this`
@@ -174,14 +177,24 @@ A `Channel` is used to broadcast events to many sessions at once.
 You may use the second generic argument `SessionState` to enforce that only sessions
 with the same state type may be registered with this channel.
 
-#### `new Channel<State, SessionState>()`
+#### `new Channel<State, SessionState>([options = {}])`
+
+`options` is an object with the following properties:
+
+|Property|Type|Default|Description|
+|-|-|-|-|
+|`state`|`object`|`{}`|Initial custom state for the channel.<br><br>Accessed via the [`state`](#channelstate-state) property.<br><br>When using TypeScript, providing the initial state structure allows the type of the `state` property to be automatically inferred.|
 
 #### `Channel#state`: `State`
 
 Custom state for this channel.
 
 Use this object to safely store information related to the channel.
 
+You may set an initial value for this property using the `state` property in the [constructor `options` object](#new-channelstate-sessionstate), allowing its type to be automatically inferred.
+
+Use [module augmentation and declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to safely add new properties to the `DefaultChannelState` interface.
+
 #### `Channel#activeSessions`: `ReadonlyArray<Session>`
 
 List of the currently active sessions subscribed to this channel.

examples/create-keys.ts

@@ -0,0 +1,10 @@
+import {createCertificate} from "pem";
+
+createCertificate({days: 1, selfSigned: true}, (error, result) => {
+	if (error) {
+		console.error(error);
+		return;
+	}
+
+	console.log(result);
+});

examples/getting-started/pubsub.ts

@@ -0,0 +1,42 @@
+import {Session, Channel, createChannel} from "better-sse";
+
+class PubSub {
+	private events = new Map<string, Channel>();
+
+	subscribe(session: Session, event: string): void {
+		if (!this.events.has(event)) {
+			const newChannel = createChannel();
+
+			this.events.set(event, newChannel);
+
+			// Clean up channel if no more subscribers
+			newChannel.on("session-deregistered", () => {
+				if (newChannel.sessionCount === 0) {
+					this.events.delete(event);
+				}
+			});
+		}
+
+		const channel = this.events.get(event) as Channel;
+
+		channel.register(session);
+	}
+
+	unsubscribe(session: Session, event: string): void {
+		const channel = this.events.get(event);
+
+		if (channel) {
+			channel.deregister(session);
+		}
+	}
+
+	publish(data: unknown, event: string): void {
+		const channel = this.events.get(event);
+
+		if (channel) {
+			channel.broadcast(data, event);
+		}
+	}
+}
+
+export {PubSub};

src/Channel.test.ts

@@ -45,6 +45,16 @@ describe("construction", () => {
 	});
 });
 
+describe("state", () => {
+	const givenState = {id: "123"};
+
+	it("can set the initial state in options", () => {
+		const channel = new Channel({state: givenState});
+
+		expect(channel.state.id).toBe(givenState.id);
+	});
+});
+
 describe("registering", () => {
 	it("can register and store an active session", () =>
 		new Promise<void>((done) => {

src/Channel.ts

@@ -3,6 +3,17 @@ import {TypedEmitter, EventMap} from "./lib/TypedEmitter";
 import {generateId} from "./lib/generateId";
 import {SseError} from "./lib/SseError";
 
+interface ChannelOptions<
+	State extends Record<string, unknown> = DefaultChannelState
+> {
+	/**
+	 * Custom state for this channel.
+	 *
+	 * Use this object to safely store information related to the channel.
+	 */
+	state?: State;
+}
+
 interface BroadcastOptions<
 	SessionState extends Record<string, unknown> = DefaultSessionState
 > {
@@ -49,12 +60,14 @@ class Channel<
 	 *
 	 * Use this object to safely store information related to the channel.
 	 */
-	state = {} as State;
+	state: State;
 
 	private sessions = new Set<Session<SessionState>>();
 
-	constructor() {
+	constructor(options: ChannelOptions<State> = {}) {
 		super();
+
+		this.state = options.state ?? ({} as State);
 	}
 
 	/**

src/Session.test.ts

@@ -265,6 +265,25 @@ describe("connection", () => {
 		}));
 });
 
+describe("state", () => {
+	const givenState = {id: "123"};
+
+	it("can set the initial state in options", () =>
+		new Promise<void>((done) => {
+			server.on("request", async (req, res) => {
+				const session = new Session(req, res, {state: givenState});
+
+				await waitForConnect(session);
+
+				expect(session.state.id).toBe(givenState.id);
+
+				done();
+			});
+
+			eventsource = new EventSource(url);
+		}));
+});
+
 describe("retry", () => {
 	it("writes an initial retry field by default", () =>
 		new Promise<void>((done) => {

src/Session.ts

@@ -13,8 +13,9 @@ import {serialize, SerializerFunction} from "./lib/serialize";
 import {sanitize, SanitizerFunction} from "./lib/sanitize";
 import {SseError} from "./lib/SseError";
 
-interface SessionOptions
-	extends Pick<EventBufferOptions, "serializer" | "sanitizer"> {
+interface SessionOptions<
+	State extends Record<string, unknown> = 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.
 	 *
@@ -64,6 +65,13 @@ interface SessionOptions
 	 * Additional headers to be sent along with the response.
 	 */
 	headers?: OutgoingHttpHeaders;
+
+	/**
+	 * Custom state for this session.
+	 *
+	 * Use this object to safely store information related to the session and user.
+	 */
+	state?: State;
 }
 
 interface DefaultSessionState {
@@ -120,7 +128,7 @@ class Session<
 	 * 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 = {} as State;
+	state: State;
 
 	private buffer: EventBuffer;
 
@@ -151,12 +159,11 @@ class Session<
 	constructor(
 		req: Http1ServerRequest | Http2ServerRequest,
 		res: Http1ServerResponse | Http2ServerResponse,
-		options: SessionOptions = {}
+		options: SessionOptions<State> = {}
 	) {
 		super();
 
 		this.req = req;
-
 		this.res = res;
 
 		const serializer = options.serializer ?? serialize;
@@ -179,6 +186,8 @@ class Session<
 
 		this.headers = options.headers ?? {};
 
+		this.state = options.state ?? ({} as State);
+
 		this.req.once("close", this.onDisconnected);
 		this.res.once("close", this.onDisconnected);