evstream 1.0.1 → 1.0.3

package/src/state.ts

@@ -0,0 +1,84 @@
+import loadash from 'lodash'
+
+import { EvStreamManager } from './manager.js'
+import { EvStateAdapter, EvStateOptions } from './types.js'
+
+const { isEqual } = loadash
+
+type EvSetState<T> = (val: T) => T
+
+/**
+ * EvState holds a reactive state and broadcasts updates to a channel using EvStreamManager.
+ */
+export class EvState<T> {
+	#value: T
+	#channel: string
+	#manager: EvStreamManager
+	#key: string
+	#adapter?: EvStateAdapter
+
+	constructor({
+		channel,
+		initialValue,
+		manager,
+		key,
+		adapter,
+	}: EvStateOptions<T>) {
+		this.#value = initialValue
+		this.#channel = channel
+		this.#manager = manager
+		this.#key = key || 'value'
+		this.#adapter = adapter
+
+		if (this.#adapter) {
+			this.#adapter.subscribe(this.#channel, (data) => {
+				this.#handleRemoteUpdate(data)
+			})
+		}
+	}
+
+	#handleRemoteUpdate(data: any) {
+		if (data && typeof data === 'object' && this.#key in data) {
+			const newValue = data[this.#key]
+
+			if (!isEqual(newValue, this.#value)) {
+				this.#value = newValue
+				this.#manager.send(this.#channel, {
+					event: this.#channel,
+					data: {
+						[this.#key]: newValue,
+					},
+				})
+			}
+		}
+	}
+
+	/**
+	 * Returns the current state value.
+	 */
+	get() {
+		return this.#value
+	}
+
+	/**
+	 * Updates the state using a callback.
+	 * Broadcasts the new value if it has changed.
+	 */
+	set(callback: EvSetState<T>) {
+		const newValue = callback(this.#value)
+
+		if (!isEqual(newValue, this.#value)) {
+			this.#value = newValue
+			this.#manager.send(this.#channel, {
+				event: this.#channel,
+				data: {
+					[this.#key]: newValue,
+				},
+			})
+
+			if (this.#adapter) {
+				this.#adapter.publish(this.#channel, { [this.#key]: newValue })
+			}
+		}
+	}
+}

package/src/stream.ts

@@ -0,0 +1,122 @@
+import { IncomingMessage, ServerResponse } from 'http'
+import { EvMessage, EvOptions } from './types.js'
+import { message } from './message.js'
+
+/**
+ * Evstream manages a Server-Sent Events (SSE) connection.
+ * Sets necessary headers, handles heartbeat, authentication, sending messages, and closing the stream.
+ * Example :
+ *
+ * ```javascript
+ * const ev = new Evstream(req, res);
+ *
+ * ev.message({event: "message", data: {message: "a message"}, id: "event_id_1"})
+ * ```
+ */
+export class Evstream {
+	#res: ServerResponse
+	#opts?: EvOptions
+	#url: URL
+	#heartbeatInterval?: NodeJS.Timeout
+	#onCloseHandler?: () => void
+	constructor(req: IncomingMessage, res: ServerResponse, opts?: EvOptions) {
+		this.#res = res
+		this.#opts = opts
+		this.#url = new URL(req.url!, `http://${req.headers.host}`)
+
+		this.#res.setHeader('Content-Type', 'text/event-stream')
+		this.#res.setHeader('Cache-Control', 'no-cache')
+		this.#res.setHeader('Connection', 'keep-alive')
+		this.#res.flushHeaders()
+
+		if (opts?.heartbeat) {
+			this.#heartbeatInterval = setInterval(() => {
+				this.#res.write(message({ event: 'heartbeat', data: '' }))
+			}, this.#opts.heartbeat)
+
+			this.#onCloseHandler = () => {
+				this.#clearHeartbeat()
+			}
+
+			this.#res.on('close', this.#onCloseHandler)
+		}
+	}
+
+	/**
+	 * Clears the heartbeat interval if it exists.
+	 * Prevents memory leaks by ensuring the interval is properly cleaned up.
+	 */
+	#clearHeartbeat() {
+		if (this.#heartbeatInterval) {
+			clearInterval(this.#heartbeatInterval)
+			this.#heartbeatInterval = undefined
+		}
+	}
+
+	/**
+	 * Removes the close event listener to prevent memory leaks.
+	 */
+	#removeCloseListener() {
+		if (this.#onCloseHandler) {
+			this.#res.removeListener('close', this.#onCloseHandler)
+			this.#onCloseHandler = undefined
+		}
+	}
+
+	/**
+	 * Handles optional authentication using provided token verification.
+	 * Sends error message and closes connection if authentication fails.
+	 */
+	async authenticate() {
+		if (this.#opts.authentication) {
+			const token = this.#url.searchParams.get(this.#opts.authentication.param)
+
+			const isAuthenticated = await this.#opts.authentication.verify(token)
+
+			if (typeof isAuthenticated === 'boolean') {
+				if (!isAuthenticated) {
+					this.#clearHeartbeat()
+					this.message({
+						data: { message: 'authentication failed' },
+						event: 'error',
+					})
+					this.#res.end()
+					return false
+				}
+
+				return true
+			}
+
+			if (typeof isAuthenticated === 'object') {
+				this.message(isAuthenticated)
+				return true
+			}
+
+			return false
+		}
+	}
+
+	/**
+	 * Sends an SSE message to the client.
+	 * Accepts an `EvMessage` object.
+	 */
+	message(msg: EvMessage) {
+		this.#res.write(message(msg))
+	}
+
+	/**
+	 * Sends an "end" event and closes the SSE connection.
+	 * Cleans up heartbeat interval and event listeners to prevent memory leaks.
+	 */
+	close() {
+		this.#clearHeartbeat()
+		this.#removeCloseListener()
+
+		this.message({
+			event: 'end',
+			data: '',
+		})
+
+		this.#res.end()
+	}
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+import type { EvStreamManager } from './manager.js'
+
+// Built-in event types.
+export type EvEventsType = 'data' | 'error' | 'end'
+
+// Represents a message sent to the client over SSE.
+export interface EvMessage {
+    // Optional event name.
+    event?: string | EvEventsType
+    // Data to send; can be a string or object.
+    data: string | object
+    // Optional ID of the event.
+    id?: string
+}
+
+// Options for token-based authentication from query parameters.
+export interface EvAuthenticationOptions {
+    method: 'query'
+    param: string
+    verify: (token: string) => Promise<EvMessage> | undefined | null | boolean
+}
+
+// Options for configuring a single SSE stream.
+export interface EvOptions {
+    authentication?: EvAuthenticationOptions
+    heartbeat?: number
+}
+
+// Configuration options for EvStreamManager.
+export interface EvManagerOptions {
+    // Unique ID for the manager
+    id?: string
+
+    // Max Connection which a manager can handle. If this limit exceeds it throws `EvMaxConnectionsError`
+    maxConnection?: number
+
+    // Max Listeners which a listener can broadcast a message to. If this limit exceeds it throw `EvMaxListenerError`
+    maxListeners?: number
+}
+
+// Options for initializing EvState.
+export interface EvStateAdapter {
+    publish(channel: string, message: any): Promise<void>
+    subscribe(channel: string, onMessage: (message: any) => void): Promise<void>
+    unsubscribe(channel: string): Promise<void>
+}
+
+export interface EvStateOptions<T> {
+    initialValue: T
+    channel: string
+    manager: EvStreamManager
+    key?: string
+    adapter?: EvStateAdapter
+}
+
+export type EvOnClose = (channels: string[]) => Promise<void>

package/src/utils.ts

@@ -0,0 +1,29 @@
+/**
+ *
+ * This function takes a value which can be string or an object and returns a string for that value. If value cannot be convertable to string then it will return a empty string.
+ *
+ * @param val Data which needs to be serialize to JSON string format
+ * @returns
+ */
+export function safeJsonParse(val: any) {
+	if (typeof val === 'string') {
+		return val
+	}
+
+	if (typeof val === 'object') {
+		try {
+			return JSON.stringify(val)
+		} catch (error) {
+			return ''
+		}
+	}
+
+	return ''
+}
+
+export function uid(opts?: { prefix?: string; counter?: number }) {
+	const now = Date.now().toString(36)
+	const rand = Math.random().toString(26).substring(2, 10)
+
+	return `${opts?.prefix ? `${opts?.prefix}-` : ''}${now}-${rand}-${opts?.counter}`
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compileOnSave": true,
+  "compilerOptions": {
+    "newLine": "LF",
+    "rootDir": "src/",
+    "outDir": "dist/",
+    "module": "ESNext",
+    "target": "ES2015",
+    "declaration": true,
+    "incremental": true,
+    "alwaysStrict": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "preserveConstEnums": true
+  }
+}