evstream 1.0.1 → 1.0.3

package/src/adapters/pub-sub.ts

@@ -0,0 +1,88 @@
+import Redis, { RedisOptions } from 'ioredis'
+import { uid } from '../utils.js'
+
+/**
+ * Configuration options for EvRedisPubSub
+ */
+interface EvRedisPubSubOptions<T> {
+	/** Redis Pub/Sub channel name */
+	subject: string
+
+	/** Redis connection options */
+	options: RedisOptions
+
+	/** Optional initial message handler */
+	onMessage?: (message: T) => void
+}
+
+/**
+ * Redis-based Pub/Sub helper for cross-process communication.
+ *
+ * - Uses separate publisher and subscriber connections
+ * - Prevents self-message delivery using instance UID
+ * - Typed message payload via generics
+ */
+export class EvRedisPubSub<T = unknown> {
+	#subject: string
+	#pub: Redis
+	#sub: Redis
+	#instanceId: string
+	#onMessage?: (message: T) => void
+
+	constructor({ options, subject, onMessage }: EvRedisPubSubOptions<T>) {
+		this.#pub = new Redis(options)
+		this.#sub = new Redis(options)
+		this.#subject = subject
+		this.#onMessage = onMessage
+		this.#instanceId = uid({ prefix: subject, counter: Math.random() })
+
+		this.init()
+	}
+
+	/**
+	 * Initializes Redis subscriptions and listeners.
+	 */
+	private async init() {
+		this.#pub.on('error', () => {})
+		this.#sub.on('error', () => {})
+
+		await this.#sub.subscribe(this.#subject)
+
+		this.#sub.on('message', (_, raw) => {
+			try {
+				const data = JSON.parse(raw)
+
+				// Ignore messages from the same instance
+				if (data?.uid !== this.#instanceId) {
+					this.#onMessage?.(data.msg as T)
+				}
+			} catch {
+				// Ignore malformed payloads
+			}
+		})
+	}
+
+	/**
+	 * Publishes a message to the Redis channel.
+	 */
+	async send(msg: T) {
+		await this.#pub.publish(
+			this.#subject,
+			JSON.stringify({ uid: this.#instanceId, msg })
+		)
+	}
+
+	/**
+	 * Registers or replaces the message handler.
+	 */
+	onMessage(callback: (msg: T) => void) {
+		this.#onMessage = callback
+	}
+
+	/**
+	 * Gracefully closes Redis connections.
+	 */
+	async close() {
+		await Promise.all([this.#pub.quit(), this.#sub.quit()])
+	}
+}

package/src/adapters/redis.ts

@@ -0,0 +1,120 @@
+import Redis, { RedisOptions } from 'ioredis'
+import { EvRedisPubSub } from './pub-sub.js'
+import { EvStateAdapter } from '../types.js'
+import { uid } from '../utils.js'
+
+/**
+ * Redis-based implementation of {@link EvStateAdapter}.
+ *
+ * This adapter enables distributed state updates using Redis Pub/Sub.
+ * It supports:
+ * - Channel-based subscriptions
+ * - Multiple listeners per channel
+ * - Self-message filtering via instance ID
+ *
+ * Designed to be used by EvState / EvStateManager for
+ * cross-process state synchronization.
+ */
+class EvRedisAdapter implements EvStateAdapter {
+	/** Publisher Redis client */
+	#pub: Redis
+
+	/** Subscriber Redis client */
+	#sub: Redis
+
+	/**
+	 * Channel → listeners mapping.
+	 * Each channel may have multiple local handlers.
+	 */
+	#listeners: Map<string, Set<(msg: any) => void>>
+
+	/** Unique identifier for this adapter instance */
+	#instanceId: string
+
+	/**
+	 * Creates a new Redis state adapter.
+	 *
+	 * @param options - Optional Redis connection options
+	 */
+	constructor(options?: RedisOptions) {
+		this.#pub = new Redis(options)
+		this.#sub = new Redis(options)
+		this.#listeners = new Map()
+		this.#instanceId = uid({ counter: Math.ceil(Math.random() * 100) })
+
+		this.#sub.on('message', (channel, message) => {
+			const handlers = this.#listeners.get(channel)
+			if (!handlers) return
+
+			let parsed: any
+			try {
+				parsed = JSON.parse(message)
+			} catch {
+				// Ignore malformed payloads
+				return
+			}
+
+			// Ignore messages published by this instance
+			if (parsed?.id === this.#instanceId) return
+
+			handlers.forEach((handler) => handler(parsed?.message))
+		})
+	}
+
+	/**
+	 * Publishes a message to a Redis channel.
+	 *
+	 * The payload is wrapped with the instance ID to
+	 * prevent self-delivery.
+	 *
+	 * @param channel - Redis channel name
+	 * @param message - Message payload
+	 */
+	async publish(channel: string, message: any): Promise<void> {
+		await this.#pub.publish(
+			channel,
+			JSON.stringify({ id: this.#instanceId, message })
+		)
+	}
+
+	/**
+	 * Subscribes to a Redis channel.
+	 *
+	 * Multiple listeners can be registered per channel.
+	 * The Redis subscription is created only once per channel.
+	 *
+	 * @param channel - Redis channel name
+	 * @param onMessage - Callback invoked on incoming messages
+	 */
+	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)
+	}
+
+	/**
+	 * Unsubscribes from a Redis channel and removes all listeners.
+	 *
+	 * @param channel - Redis channel name
+	 */
+	async unsubscribe(channel: string): Promise<void> {
+		await this.#sub.unsubscribe(channel)
+		this.#listeners.delete(channel)
+	}
+
+	/**
+	 * Gracefully closes Redis connections.
+	 */
+	quit() {
+		this.#pub.quit()
+		this.#sub.quit()
+	}
+}
+
+export { EvRedisPubSub, EvRedisAdapter }

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/extensions/state-manager.ts

@@ -0,0 +1,186 @@
+import type { EvStreamManager } from '../manager.js'
+import type { EvRedisAdapter } from '../adapters/redis.js'
+import type { EvRedisPubSub } from '../adapters/pub-sub.js'
+import { EvState } from '../state.js'
+
+/**
+ * Options for creating an {@link EvStateManager}.
+ */
+interface EvStateManagerOptions {
+	/**
+	 * Stream manager responsible for managing client connections
+	 * and broadcasting state updates.
+	 */
+	manager: EvStreamManager
+
+	/**
+	 * Optional distributed state adapter (e.g. Redis).
+	 * Enables cross-process state propagation.
+	 */
+	adapter?: EvRedisAdapter
+
+	/**
+	 * Optional Pub/Sub instance used to synchronize
+	 * state creation and removal across instances.
+	 */
+	pubsub?: EvRedisPubSub
+}
+
+/**
+ * Manages a collection of named {@link EvState} instances.
+ *
+ * Responsibilities:
+ * - Create and cache state objects locally
+ * - Synchronize state lifecycle (create/remove) across processes
+ * - Bridge EvState with stream manager and adapters
+ *
+ * Internally, all state keys are converted to strings to remain
+ * Redis-safe and transport-friendly.
+ *
+ * @typeParam S - Mapping of state keys to their value types
+ */
+export class EvStateManager<S extends Record<string, any>> {
+	/**
+	 * Internal state registry.
+	 * Keyed by string channel name.
+	 */
+	#states = new Map<string, EvState<any>>()
+
+	/** Stream manager used by all states */
+	#manager: EvStreamManager
+
+	/** Optional distributed adapter */
+	#adapter?: EvRedisAdapter
+
+	/** Optional Pub/Sub synchronizer */
+	#pubsub?: EvRedisPubSub
+
+	/**
+	 * Creates a new state manager.
+	 *
+	 * @param options - Initialization options
+	 */
+	constructor({ manager, adapter, pubsub }: EvStateManagerOptions) {
+		this.#manager = manager
+		this.#adapter = adapter
+		this.#pubsub = pubsub
+
+		this.pubSubCallback = this.pubSubCallback.bind(this)
+
+		if (this.#pubsub) {
+			this.#pubsub.onMessage(this.pubSubCallback)
+		}
+	}
+
+	/**
+	 * Creates a state locally without emitting Pub/Sub events.
+	 *
+	 * @param channel - State channel name
+	 * @param initialValue - Initial state value
+	 */
+	private createLocalState(channel: string, initialValue: any): EvState<any> {
+		const state = new EvState({
+			channel,
+			initialValue,
+			manager: this.#manager,
+			adapter: this.#adapter,
+		})
+
+		this.#states.set(channel, state)
+		return state
+	}
+
+	/**
+	 * Removes a state locally without emitting Pub/Sub events.
+	 *
+	 * @param channel - State channel name
+	 */
+	private removeLocalState(channel: string) {
+		this.#states.delete(channel)
+	}
+
+	/**
+	 * Creates or returns an existing state.
+	 *
+	 * If Pub/Sub is enabled, the creation is broadcast
+	 * to other instances.
+	 *
+	 * @param key - State key
+	 * @param initialValue - Initial state value
+	 */
+	createState<K extends keyof S>(key: K, initialValue: S[K]): EvState<S[K]> {
+		const channel = String(key)
+
+		if (this.#states.has(channel)) {
+			return this.#states.get(channel)! as EvState<S[K]>
+		}
+
+		const state = this.createLocalState(channel, initialValue)
+
+		this.#pubsub?.send({
+			type: 'create',
+			channel,
+			initialValue,
+		})
+
+		return state as EvState<S[K]>
+	}
+
+	/**
+	 * Retrieves an existing state.
+	 *
+	 * @param key - State key
+	 */
+	getState<K extends keyof S>(key: K): EvState<S[K]> | undefined {
+		return this.#states.get(String(key)) as EvState<S[K]> | undefined
+	}
+
+	/**
+	 * Checks whether a state exists.
+	 *
+	 * @param key - State key
+	 */
+	hasState<K extends keyof S>(key: K): boolean {
+		return this.#states.has(String(key))
+	}
+
+	/**
+	 * Removes a state locally and propagates the removal
+	 * to other instances via Pub/Sub.
+	 *
+	 * @param key - State key
+	 */
+	removeState<K extends keyof S>(key: K) {
+		const channel = String(key)
+
+		this.removeLocalState(channel)
+
+		this.#pubsub?.send({
+			type: 'remove',
+			channel,
+		})
+	}
+
+	/**
+	 * Handles incoming Pub/Sub lifecycle events.
+	 *
+	 * @param msg - Pub/Sub message payload
+	 */
+	private pubSubCallback(msg: any) {
+		if (!msg || typeof msg.channel !== 'string') return
+
+		switch (msg.type) {
+			case 'create': {
+				if (!this.#states.has(msg.channel)) {
+					this.createLocalState(msg.channel, msg.initialValue)
+				}
+				break
+			}
+
+			case 'remove': {
+				this.removeLocalState(msg.channel)
+				break
+			}
+		}
+	}
+}

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