evstream 1.0.1 → 1.0.2

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm run lint-staged

package/.prettierignore

@@ -0,0 +1,15 @@
+# Ignore build outputs
+dist/
+build/
+coverage/
+
+# Ignore dependencies
+node_modules/
+
+# Ignore generated files
+*.min.js
+*.bundle.js
+
+# Ignore specific files
+package-lock.json
+yarn.lock

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+	"semi": false,
+	"singleQuote": true,
+	"tabWidth": 2,
+	"trailingComma": "es5",
+	"jsxSingleQuote": true,
+	"useTabs": true
+}

package/dist/adapters/redis.js

@@ -38,7 +38,7 @@ export class EvRedisAdapter {
                 catch (_a) {
                     return;
                 }
-                handlers.forEach(handler => handler(parsed));
+                handlers.forEach((handler) => handler(parsed));
             }
         });
     }

package/dist/state.d.ts

@@ -5,7 +5,7 @@ type EvSetState<T> = (val: T) => T;
  */
 export declare class EvState<T> {
     #private;
-    constructor({ channel, initialValue, manager, key, adapter }: EvStateOptions<T>);
+    constructor({ channel, initialValue, manager, key, adapter, }: EvStateOptions<T>);
     /**
      * Returns the current state value.
      */

package/dist/state.js

@@ -16,7 +16,7 @@ const { isEqual } = loadash;
  * EvState holds a reactive state and broadcasts updates to a channel using EvStreamManager.
  */
 export class EvState {
-    constructor({ channel, initialValue, manager, key, adapter }) {
+    constructor({ channel, initialValue, manager, key, adapter, }) {
         _EvState_instances.add(this);
         _EvState_value.set(this, void 0);
         _EvState_channel.set(this, void 0);

package/dist/utils.js

@@ -6,21 +6,21 @@
  * @returns
  */
 export function safeJsonParse(val) {
-    if (typeof val === "string") {
+    if (typeof val === 'string') {
         return val;
     }
-    if (typeof val === "object") {
+    if (typeof val === 'object') {
         try {
             return JSON.stringify(val);
         }
         catch (error) {
-            return "";
+            return '';
         }
     }
-    return "";
+    return '';
 }
 export function uid(opts) {
     const now = Date.now().toString(36);
     const rand = Math.random().toString(26).substring(2, 10);
-    return `${(opts === null || opts === void 0 ? void 0 : opts.prefix) ? `${opts === null || opts === void 0 ? void 0 : opts.prefix}-` : ""}${now}-${rand}-${opts === null || opts === void 0 ? void 0 : opts.counter}`;
+    return `${(opts === null || opts === void 0 ? void 0 : opts.prefix) ? `${opts === null || opts === void 0 ? void 0 : opts.prefix}-` : ''}${now}-${rand}-${opts === null || opts === void 0 ? void 0 : opts.counter}`;
 }

package/package.json

@@ -1,60 +1,73 @@
-{
-  "name": "evstream",
-  "version": "1.0.1",
-  "description": "A simple and easy to implement server sent event library for express.js",
-  "keywords": [
-    "sse",
-    "server-sent-events",
-    "event-source"
-  ],
-  "homepage": "https://github.com/kisshan13/evstream#readme",
-  "bugs": {
-    "url": "https://github.com/kisshan13/evstream/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kisshan13/evstream.git"
-  },
-  "license": "MIT",
-  "author": "Kishan Sharma",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./adapter/redis": {
-      "import": "./dist/adapters/redis.js",
-      "types": "./dist/adapters/redis.d.ts"
-    }
-  },
-  "scripts": {
-    "dev": "tsc --watch",
-    "clean": "rimraf ./dist",
-    "build": "rimraf ./dist && tsc --incremental false"
-  },
-  "engines": {
-    "node": ">=17.8.0"
-  },
-  "devDependencies": {
-    "@types/ioredis": "^5.0.0",
-    "@types/lodash": "^4.17.19",
-    "@types/node": "^24.0.7",
-    "@typescript-eslint/eslint-plugin": "^8.35.0",
-    "@typescript-eslint/parser": "^8.35.0",
-    "eslint": "^9.30.0",
-    "eslint-config-prettier": "^10.1.5",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-prettier": "^5.5.1",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "ioredis": "^5.5.0",
-    "prettier": "^3.6.2",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.8.3"
-  },
-  "dependencies": {
-    "lodash": "^4.17.21"
-  }
-}
+{
+	"name": "evstream",
+	"version": "1.0.2",
+	"description": "A simple and easy to implement server sent event library for express.js",
+	"keywords": [
+		"sse",
+		"server-sent-events",
+		"event-source"
+	],
+	"homepage": "https://github.com/kisshan13/evstream#readme",
+	"bugs": {
+		"url": "https://github.com/kisshan13/evstream/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kisshan13/evstream.git"
+	},
+	"license": "MIT",
+	"author": "Kishan Sharma",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./adapter/redis": {
+			"import": "./dist/adapters/redis.js",
+			"types": "./dist/adapters/redis.d.ts"
+		}
+	},
+	"lint-staged": {
+		"*.{js,jsx,ts,tsx,cjs,mjs}": [
+			"prettier --write"
+		],
+		"*.{json,md,yml,yaml}": [
+			"prettier --write"
+		]
+	},
+	"scripts": {
+		"dev": "tsc --watch",
+		"clean": "rimraf ./dist",
+		"build": "rimraf ./dist && tsc --incremental false",
+		"prepare": "husky",
+		"lint-staged": "lint-staged",
+		"format": "prettier --write \"**/*.{js,jsx,ts,tsx}\""
+	},
+	"engines": {
+		"node": ">=17.8.0"
+	},
+	"devDependencies": {
+		"@types/ioredis": "^5.0.0",
+		"@types/lodash": "^4.17.19",
+		"@types/node": "^24.0.7",
+		"@typescript-eslint/eslint-plugin": "^8.35.0",
+		"@typescript-eslint/parser": "^8.35.0",
+		"eslint": "^9.30.0",
+		"eslint-config-prettier": "^10.1.5",
+		"eslint-plugin-import": "^2.32.0",
+		"eslint-plugin-prettier": "^5.5.1",
+		"eslint-plugin-simple-import-sort": "^12.1.1",
+		"ioredis": "^5.5.0",
+		"prettier": "^3.7.4",
+		"rimraf": "^6.0.1",
+		"typescript": "^5.8.3",
+		"husky": "^9.1.7",
+		"lint-staged": "^16.2.7"
+	},
+	"dependencies": {
+		"lodash": "^4.17.21"
+	}
+}

package/src/adapters/redis.ts

@@ -0,0 +1,53 @@
+import Redis, { RedisOptions } from 'ioredis'
+
+import { EvStateAdapter } from '../types.js'
+
+export class EvRedisAdapter implements EvStateAdapter {
+	#pub: Redis
+	#sub: Redis
+	#listeners: Map<string, Set<(msg: any) => void>>
+
+	constructor(options?: RedisOptions) {
+		this.#pub = new Redis(options)
+		this.#sub = new Redis(options)
+		this.#listeners = new Map()
+
+		this.#sub.on('message', (channel, message) => {
+			const handlers = this.#listeners.get(channel)
+			if (handlers) {
+				let parsed: any
+				try {
+					parsed = JSON.parse(message)
+				} catch {
+					return
+				}
+				handlers.forEach((handler) => handler(parsed))
+			}
+		})
+	}
+
+	async publish(channel: string, message: any): Promise<void> {
+		await this.#pub.publish(channel, JSON.stringify(message))
+	}
+
+	async subscribe(
+		channel: string,
+		onMessage: (message: any) => void
+	): Promise<void> {
+		if (!this.#listeners.has(channel)) {
+			this.#listeners.set(channel, new Set())
+			await this.#sub.subscribe(channel)
+		}
+		this.#listeners.get(channel)!.add(onMessage)
+	}
+
+	async unsubscribe(channel: string): Promise<void> {
+		await this.#sub.unsubscribe(channel)
+		this.#listeners.delete(channel)
+	}
+
+	quit() {
+		this.#pub.quit()
+		this.#sub.quit()
+	}
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+/**
+ * `EvMaxConnectionsError` represents a error which occurs when `maxConnection` reached. Default `maxConnection` is 5000.
+ *
+ * To change connection limit you can set `maxConnection` while initializing `new EvStreamManager();`
+ */
+export class EvMaxConnectionsError extends Error {
+	constructor(connections: number) {
+		super()
+		this.message = `Max number of connected client reached. Total Connection : ${connections}`
+		this.name = `EvMaxConnectionsError`
+	}
+}
+
+/**
+ * `EvMaxListenerError` represents a error which occurs when `maxListeners` reached. Default `maxListeners` is 5000.
+ *
+ * To change listeners limit you can set `maxListeners` while initializing `new EvStreamManager();`
+ */
+export class EvMaxListenerError extends Error {
+	constructor(listeners: number, channel: string) {
+		super()
+		this.message = `Max number of listeners for the channle ${channel} reached (Listener: ${listeners}).`
+		this.name = `EvMaxListenerError`
+	}
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import { Evstream } from './stream.js'
+import { EvStreamManager } from './manager.js'
+import { EvState } from './state.js'
+
+import { EvMaxListenerError, EvMaxConnectionsError } from './errors.js'
+
+import {
+    EvOptions,
+    EvAuthenticationOptions,
+    EvEventsType,
+    EvManagerOptions,
+    EvMessage,
+    EvStateOptions,
+} from './types.js'
+
+export {
+    EvMaxConnectionsError,
+    EvMaxListenerError,
+    Evstream,
+    EvStreamManager,
+    EvState,
+    EvOptions,
+    EvAuthenticationOptions,
+    EvEventsType,
+    EvManagerOptions,
+    EvMessage,
+    EvStateOptions,
+}

package/src/manager.ts

@@ -0,0 +1,171 @@
+import { IncomingMessage, ServerResponse } from 'http'
+
+import { Evstream } from './stream.js'
+import { uid } from './utils.js'
+import { EvMaxConnectionsError, EvMaxListenerError } from './errors.js'
+
+import type {
+    EvManagerOptions,
+    EvMessage,
+    EvOnClose,
+    EvOptions,
+} from './types.js'
+
+/**
+ * `EvStreamManager` manages multiple SSE connections.
+ * Handles client creation, broadcasting messages, and channel-based listeners.
+ *
+ * Example :
+ *
+ * ```javascript
+ * const evManager = new EvStreamManager();
+ *
+ * const stream = evManager.createStream(req, res);
+ * ```
+ *
+ */
+export class EvStreamManager {
+    #clients: Map<string, Evstream>
+    #listeners: Map<string, Set<string>>
+    #count: number
+    #maxConnections: number
+    #maxListeners: number
+    #id?: string
+    constructor(opts?: EvManagerOptions) {
+        this.#clients = new Map()
+        this.#listeners = new Map()
+        this.#count = 0
+
+        this.#maxConnections = opts?.maxConnection || 5000
+        this.#maxListeners = opts?.maxListeners || 5000
+        this.#id = opts?.id
+    }
+
+    /**
+     * Creates a new SSE stream, tracks it, and returns control methods.
+     * Enforces max connection limit.
+     */
+    createStream(req: IncomingMessage, res: ServerResponse, opts?: EvOptions) {
+        if (this.#count >= this.#maxConnections) {
+            throw new EvMaxConnectionsError(this.#maxConnections)
+        }
+
+        const client = new Evstream(req, res, opts)
+        const id = uid({ counter: this.#count, prefix: this.#id })
+        const channel: string[] = []
+        let isClosed = false
+
+        this.#count += 1
+        this.#clients.set(id, client)
+
+        const close = (onClose?: EvOnClose) => {
+            if (isClosed) return
+
+            if (typeof onClose === 'function') {
+                onClose(channel)
+            }
+
+            isClosed = true
+
+            // Remove close event listener to prevent memory leaks
+            res.removeAllListeners('close')
+
+            // Clean up client
+            client.close()
+
+            // Decrement count
+            this.#count -= 1
+
+            // Remove from all channels
+            channel.forEach(chan => this.#unlisten(chan, id))
+
+            // Clear channel array to release references
+            channel.length = 0
+
+            // Remove client from map
+            this.#clients.delete(id)
+
+            // End response if not already ended
+            if (!res.writableEnded) {
+                res.end()
+            }
+        }
+
+        const onCloseHandler = () => {
+            if (!isClosed) {
+                close()
+            }
+        }
+
+        res.on('close', onCloseHandler)
+
+        return {
+            authenticate: client.authenticate.bind(client),
+            message: client.message.bind(client),
+            close: close,
+            listen: (name: string) => {
+                if (isClosed) return
+                channel.push(name)
+                this.#listen(name, id)
+            },
+        }
+    }
+
+    /**
+     * Sends a message to all clients listening to a specific channel.
+     */
+    send(name: string, msg: EvMessage) {
+        const listeners = this.#listeners.get(name)
+
+        if (!listeners) return
+
+        for (const [_, id] of listeners.entries()) {
+            const client = this.#clients.get(id)
+
+            if (client) {
+                client.message({
+                    ...msg,
+                    data:
+                        typeof msg.data === 'string'
+                            ? { ch: name, data: msg }
+                            : { ch: name, ...msg.data },
+                })
+            }
+        }
+    }
+
+    /**
+     * Adds a client to a specific channel.
+     * Enforces max listeners per channel.
+     */
+    #listen(name: string, id: string) {
+        let listeners = this.#listeners.get(name)
+
+        if (!listeners) {
+            listeners = new Set<string>()
+            this.#listeners.set(name, listeners)
+        }
+
+        if (listeners.size >= this.#maxListeners) {
+            throw new EvMaxListenerError(listeners.size, name)
+        }
+
+        listeners.add(id)
+    }
+
+    /**
+     * Removes a client from a specific channel.
+     * Deletes the channel if no listeners remain.
+     */
+    #unlisten(name: string, id: string) {
+        const isListenerExists = this.#listeners.get(name)
+
+        if (isListenerExists) {
+            isListenerExists.delete(id)
+
+            if (isListenerExists.size === 0) {
+                this.#listeners.delete(name)
+            }
+        }
+    }
+}

package/src/message.ts

@@ -0,0 +1,19 @@
+import { EvMessage } from './types.js'
+import { safeJsonParse } from './utils.js'
+
+/**
+ *
+ * This function convert the data to event stream compatible format.
+ *
+ * @param msg Message which you want to send to the client.
+ */
+export function message(msg: EvMessage) {
+    const event = `event:${msg.event || 'message'}\n`
+    const data = `data:${safeJsonParse(msg.data)}\n`
+
+    if (data === '') {
+        return `${msg.id ? `id:${msg.id}\n` : ''}${event}\n`
+    }
+
+    return `${msg.id ? `id:${msg.id}\n` : ''}${event}${data}\n`
+}

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
+  }
+}