evstream 1.0.0

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,31 @@
+name: Publish NPM Package
+
+on:
+    push:
+        tags:
+            - "v*"
+
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout Code
+              uses: actions/checkout@v4
+              
+            - name: Set up Node.js
+              uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+                registry-url: "https://registry.npmjs/org/"
+
+            - name: Install Dependencies
+              run: npm install
+
+            - name: Build Package
+              run: npm run build
+
+            - name: Publish to NPM
+              env:
+                NODE_AUTH_TOKEN: $${{ secrets.NPM_TOKEN }}
+              run: npm publish

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 kisshan13
+
+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/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `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 declare class EvMaxConnectionsError extends Error {
+    constructor(connections: number);
+}
+/**
+ * `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 declare class EvMaxListenerError extends Error {
+    constructor(listeners: number, channel: string);
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/**
+ * `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) {
+        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, channel) {
+        super();
+        this.message = `Max number of listeners for the channle ${channel} reached (Listener: ${listeners}).`;
+        this.name = `EvMaxListenerError`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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/dist/index.js

@@ -0,0 +1,5 @@
+import { Evstream } from './stream.js';
+import { EvStreamManager } from './manager.js';
+import { EvState } from './state.js';
+import { EvMaxListenerError, EvMaxConnectionsError } from './errors.js';
+export { EvMaxConnectionsError, EvMaxListenerError, Evstream, EvStreamManager, EvState, };

package/dist/manager.d.ts

@@ -0,0 +1,33 @@
+import { IncomingMessage, ServerResponse } from 'http';
+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 declare class EvStreamManager {
+    #private;
+    constructor(opts?: EvManagerOptions);
+    /**
+     * Creates a new SSE stream, tracks it, and returns control methods.
+     * Enforces max connection limit.
+     */
+    createStream(req: IncomingMessage, res: ServerResponse, opts?: EvOptions): {
+        authenticate: any;
+        message: any;
+        close: (onClose?: EvOnClose) => void;
+        listen: (name: string) => void;
+    };
+    /**
+     * Sends a message to all clients listening to a specific channel.
+     */
+    send(name: string, msg: EvMessage): void;
+}

package/dist/manager.js

@@ -0,0 +1,122 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _EvStreamManager_instances, _EvStreamManager_clients, _EvStreamManager_listeners, _EvStreamManager_count, _EvStreamManager_maxConnections, _EvStreamManager_maxListeners, _EvStreamManager_id, _EvStreamManager_listen, _EvStreamManager_unlisten;
+import { Evstream } from './stream.js';
+import { uid } from './utils.js';
+import { EvMaxConnectionsError, EvMaxListenerError } from './errors.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 {
+    constructor(opts) {
+        _EvStreamManager_instances.add(this);
+        _EvStreamManager_clients.set(this, void 0);
+        _EvStreamManager_listeners.set(this, void 0);
+        _EvStreamManager_count.set(this, void 0);
+        _EvStreamManager_maxConnections.set(this, void 0);
+        _EvStreamManager_maxListeners.set(this, void 0);
+        _EvStreamManager_id.set(this, void 0);
+        __classPrivateFieldSet(this, _EvStreamManager_clients, new Map(), "f");
+        __classPrivateFieldSet(this, _EvStreamManager_listeners, new Map(), "f");
+        __classPrivateFieldSet(this, _EvStreamManager_count, 0, "f");
+        __classPrivateFieldSet(this, _EvStreamManager_maxConnections, (opts === null || opts === void 0 ? void 0 : opts.maxConnection) || 5000, "f");
+        __classPrivateFieldSet(this, _EvStreamManager_maxListeners, (opts === null || opts === void 0 ? void 0 : opts.maxListeners) || 5000, "f");
+        __classPrivateFieldSet(this, _EvStreamManager_id, opts === null || opts === void 0 ? void 0 : opts.id, "f");
+    }
+    /**
+     * Creates a new SSE stream, tracks it, and returns control methods.
+     * Enforces max connection limit.
+     */
+    createStream(req, res, opts) {
+        if (__classPrivateFieldGet(this, _EvStreamManager_count, "f") >= __classPrivateFieldGet(this, _EvStreamManager_maxConnections, "f")) {
+            throw new EvMaxConnectionsError(__classPrivateFieldGet(this, _EvStreamManager_maxConnections, "f"));
+        }
+        const client = new Evstream(req, res, opts);
+        const id = uid({ counter: __classPrivateFieldGet(this, _EvStreamManager_count, "f"), prefix: __classPrivateFieldGet(this, _EvStreamManager_id, "f") });
+        const channel = [];
+        let isClosed = false;
+        __classPrivateFieldSet(this, _EvStreamManager_count, __classPrivateFieldGet(this, _EvStreamManager_count, "f") + 1, "f");
+        __classPrivateFieldGet(this, _EvStreamManager_clients, "f").set(id, client);
+        const close = (onClose) => {
+            if (isClosed)
+                return;
+            if (typeof onClose === 'function') {
+                onClose(channel);
+            }
+            isClosed = true;
+            client.close();
+            __classPrivateFieldSet(this, _EvStreamManager_count, __classPrivateFieldGet(this, _EvStreamManager_count, "f") - 1, "f");
+            channel.forEach(chan => __classPrivateFieldGet(this, _EvStreamManager_instances, "m", _EvStreamManager_unlisten).call(this, chan, id));
+            __classPrivateFieldGet(this, _EvStreamManager_clients, "f").delete(id);
+            res.end();
+        };
+        res.on('close', () => {
+            if (!isClosed) {
+                close();
+            }
+        });
+        return {
+            authenticate: client.authenticate.bind(client),
+            message: client.message.bind(client),
+            close: close,
+            listen: (name) => {
+                if (isClosed)
+                    return;
+                channel.push(name);
+                __classPrivateFieldGet(this, _EvStreamManager_instances, "m", _EvStreamManager_listen).call(this, name, id);
+            },
+        };
+    }
+    /**
+     * Sends a message to all clients listening to a specific channel.
+     */
+    send(name, msg) {
+        const listeners = __classPrivateFieldGet(this, _EvStreamManager_listeners, "f").get(name);
+        for (const [_, id] of listeners.entries()) {
+            const client = __classPrivateFieldGet(this, _EvStreamManager_clients, "f").get(id);
+            if (client) {
+                client.message(Object.assign(Object.assign({}, msg), { data: typeof msg.data === 'string'
+                        ? { ch: name, data: msg }
+                        : Object.assign({ ch: name }, msg.data) }));
+            }
+        }
+    }
+}
+_EvStreamManager_clients = new WeakMap(), _EvStreamManager_listeners = new WeakMap(), _EvStreamManager_count = new WeakMap(), _EvStreamManager_maxConnections = new WeakMap(), _EvStreamManager_maxListeners = new WeakMap(), _EvStreamManager_id = new WeakMap(), _EvStreamManager_instances = new WeakSet(), _EvStreamManager_listen = function _EvStreamManager_listen(name, id) {
+    var _a;
+    if (!__classPrivateFieldGet(this, _EvStreamManager_listeners, "f").has(name)) {
+        const size = (_a = __classPrivateFieldGet(this, _EvStreamManager_listeners, "f").get(name)) === null || _a === void 0 ? void 0 : _a.size;
+        if (size >= __classPrivateFieldGet(this, _EvStreamManager_maxListeners, "f")) {
+            throw new EvMaxListenerError(size, name);
+        }
+        __classPrivateFieldGet(this, _EvStreamManager_listeners, "f").set(name, new Set());
+    }
+    __classPrivateFieldGet(this, _EvStreamManager_listeners, "f").get(name).add(id);
+}, _EvStreamManager_unlisten = function _EvStreamManager_unlisten(name, id) {
+    const isListenerExists = __classPrivateFieldGet(this, _EvStreamManager_listeners, "f").get(name);
+    if (isListenerExists) {
+        isListenerExists.delete(id);
+        if (isListenerExists.size === 0) {
+            __classPrivateFieldGet(this, _EvStreamManager_listeners, "f").delete(name);
+        }
+    }
+};

package/dist/message.d.ts

@@ -0,0 +1,8 @@
+import { EvMessage } from './types.js';
+/**
+ *
+ * This function convert the data to event stream compatible format.
+ *
+ * @param msg Message which you want to send to the client.
+ */
+export declare function message(msg: EvMessage): string;

package/dist/message.js

@@ -0,0 +1,15 @@
+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) {
+    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/dist/state.d.ts

@@ -0,0 +1,19 @@
+import { EvStateOptions } from './types.js';
+type EvSetState<T> = (val: T) => T;
+/**
+ * EvState holds a reactive state and broadcasts updates to a channel using EvStreamManager.
+ */
+export declare class EvState<T> {
+    #private;
+    constructor({ channel, initialValue, manager, key }: EvStateOptions<T>);
+    /**
+     * Returns the current state value.
+     */
+    get(): T;
+    /**
+     * Updates the state using a callback.
+     * Broadcasts the new value if it has changed.
+     */
+    set(callback: EvSetState<T>): void;
+}
+export {};

package/dist/state.js

@@ -0,0 +1,52 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _EvState_value, _EvState_channel, _EvState_manager, _EvState_key;
+import loadash from 'lodash';
+const { isEqual } = loadash;
+/**
+ * EvState holds a reactive state and broadcasts updates to a channel using EvStreamManager.
+ */
+export class EvState {
+    constructor({ channel, initialValue, manager, key }) {
+        _EvState_value.set(this, void 0);
+        _EvState_channel.set(this, void 0);
+        _EvState_manager.set(this, void 0);
+        _EvState_key.set(this, void 0);
+        __classPrivateFieldSet(this, _EvState_value, initialValue, "f");
+        __classPrivateFieldSet(this, _EvState_channel, channel, "f");
+        __classPrivateFieldSet(this, _EvState_manager, manager, "f");
+        __classPrivateFieldSet(this, _EvState_key, key || 'value', "f");
+    }
+    /**
+     * Returns the current state value.
+     */
+    get() {
+        return __classPrivateFieldGet(this, _EvState_value, "f");
+    }
+    /**
+     * Updates the state using a callback.
+     * Broadcasts the new value if it has changed.
+     */
+    set(callback) {
+        const newValue = callback(__classPrivateFieldGet(this, _EvState_value, "f"));
+        if (!isEqual(newValue, __classPrivateFieldGet(this, _EvState_value, "f"))) {
+            __classPrivateFieldSet(this, _EvState_value, newValue, "f");
+            __classPrivateFieldGet(this, _EvState_manager, "f").send(__classPrivateFieldGet(this, _EvState_channel, "f"), {
+                event: __classPrivateFieldGet(this, _EvState_channel, "f"),
+                data: {
+                    [__classPrivateFieldGet(this, _EvState_key, "f")]: newValue,
+                },
+            });
+        }
+    }
+}
+_EvState_value = new WeakMap(), _EvState_channel = new WeakMap(), _EvState_manager = new WeakMap(), _EvState_key = new WeakMap();

package/dist/stream.d.ts

@@ -0,0 +1,31 @@
+import { IncomingMessage, ServerResponse } from 'http';
+import { EvMessage, EvOptions } from './types.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 declare class Evstream {
+    #private;
+    constructor(req: IncomingMessage, res: ServerResponse, opts?: EvOptions);
+    /**
+     * Handles optional authentication using provided token verification.
+     * Sends error message and closes connection if authentication fails.
+     */
+    authenticate(): Promise<boolean>;
+    /**
+     * Sends an SSE message to the client.
+     * Accepts an `EvMessage` object.
+     */
+    message(msg: EvMessage): void;
+    /**
+     * Sends an "end" event and closes the SSE connection.
+     */
+    close(): void;
+}

package/dist/stream.js

@@ -0,0 +1,101 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Evstream_res, _Evstream_opts, _Evstream_url;
+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 {
+    constructor(req, res, opts) {
+        _Evstream_res.set(this, void 0);
+        _Evstream_opts.set(this, void 0);
+        _Evstream_url.set(this, void 0);
+        __classPrivateFieldSet(this, _Evstream_res, res, "f");
+        __classPrivateFieldSet(this, _Evstream_opts, opts, "f");
+        __classPrivateFieldSet(this, _Evstream_url, new URL(req.url, `http://${req.headers.host}`), "f");
+        __classPrivateFieldGet(this, _Evstream_res, "f").setHeader('Content-Type', 'text/event-stream');
+        __classPrivateFieldGet(this, _Evstream_res, "f").setHeader('Cache-Control', 'no-cache');
+        __classPrivateFieldGet(this, _Evstream_res, "f").setHeader('Connection', 'keep-alive');
+        __classPrivateFieldGet(this, _Evstream_res, "f").flushHeaders();
+        if (opts === null || opts === void 0 ? void 0 : opts.heartbeat) {
+            const timeout = setInterval(() => {
+                __classPrivateFieldGet(this, _Evstream_res, "f").write(message({ event: 'heartbeat', data: '' }));
+            }, __classPrivateFieldGet(this, _Evstream_opts, "f").heartbeat);
+            __classPrivateFieldGet(this, _Evstream_res, "f").on('close', () => {
+                clearTimeout(timeout);
+            });
+        }
+    }
+    /**
+     * Handles optional authentication using provided token verification.
+     * Sends error message and closes connection if authentication fails.
+     */
+    authenticate() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (__classPrivateFieldGet(this, _Evstream_opts, "f").authentication) {
+                const token = __classPrivateFieldGet(this, _Evstream_url, "f").searchParams.get(__classPrivateFieldGet(this, _Evstream_opts, "f").authentication.param);
+                const isAuthenticated = yield __classPrivateFieldGet(this, _Evstream_opts, "f").authentication.verify(token);
+                if (typeof isAuthenticated === 'boolean') {
+                    if (!isAuthenticated) {
+                        this.message({
+                            data: { message: 'authentication failed' },
+                            event: 'error',
+                        });
+                        __classPrivateFieldGet(this, _Evstream_res, "f").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) {
+        __classPrivateFieldGet(this, _Evstream_res, "f").write(message(msg));
+    }
+    /**
+     * Sends an "end" event and closes the SSE connection.
+     */
+    close() {
+        this.message({
+            event: 'end',
+            data: '',
+        });
+        __classPrivateFieldGet(this, _Evstream_res, "f").end();
+    }
+}
+_Evstream_res = new WeakMap(), _Evstream_opts = new WeakMap(), _Evstream_url = new WeakMap();

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import type { EvStreamManager } from './manager.js';
+export type EvEventsType = 'data' | 'error' | 'end';
+export interface EvMessage {
+    event?: string | EvEventsType;
+    data: string | object;
+    id?: string;
+}
+export interface EvAuthenticationOptions {
+    method: 'query';
+    param: string;
+    verify: (token: string) => Promise<EvMessage> | undefined | null | boolean;
+}
+export interface EvOptions {
+    authentication?: EvAuthenticationOptions;
+    heartbeat?: number;
+}
+export interface EvManagerOptions {
+    id?: string;
+    maxConnection?: number;
+    maxListeners?: number;
+}
+export interface EvStateOptions<T> {
+    initialValue: T;
+    channel: string;
+    manager: EvStreamManager;
+    key?: string;
+}
+export type EvOnClose = (channels: string[]) => Promise<void>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ *
+ * 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 declare function safeJsonParse(val: any): string;
+export declare function uid(opts?: {
+    prefix?: string;
+    counter?: number;
+}): string;

package/dist/utils.js

@@ -0,0 +1,26 @@
+/**
+ *
+ * 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) {
+    if (typeof val === "string") {
+        return val;
+    }
+    if (typeof val === "object") {
+        try {
+            return JSON.stringify(val);
+        }
+        catch (error) {
+            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}`;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "evstream",
+  "version": "1.0.0",
+  "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",
+  "scripts": {
+    "dev": "tsc --watch",
+    "clean": "rimraf ./dist",
+    "build": "rimraf ./dist && tsc --incremental false"
+  },
+  "engines": {
+    "node": ">=17.8.0"
+  },
+  "devDependencies": {
+    "@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",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  }
+}

package/readme.md

@@ -0,0 +1,625 @@
+# `evstream`
+
+A simple, easy, and lightweight Server-Sent Events (SSE) library for Node.js that simplifies managing SSE connections, broadcasting events, and maintaining reactive state. It works out of the box with any backend library that supports native `IncomingMessage` and `ServerResponse` objects for IO.
+
+## Features
+
+- Manage multiple SSE connections with centralized control.
+- Broadcast events to channels (event names).
+- Built-in support for connection and listener limits.
+- Optional token-based authentication per connection.
+- Heartbeat support to keep connections alive.
+- Reactive state management with automatic broadcasting.
+
+## Installation
+
+```bash
+npm install evstream
+```
+
+## Usage
+
+We used `express.js` to show you the usage. However you can use the library with any backend library or framework supporting `IncomingMessage` and `ServerResponse` objects for IO. 
+
+### 1. Creating a base SSE Connection
+
+```javascript
+import { Evstream } from 'evstream'
+
+app.get("/", (req, res) => {
+    const stream = new Evstream(req, res, { heartbeat: 5000 })
+
+    stream.message({ event: "connected", data: { userId: "a-user-id" } })
+
+    setTimeout(() => {
+        stream.close();
+    }, 5000)
+})
+```
+
+Client Recieves :
+```
+event:connected
+data:{"userId":"a-user-id"}
+
+event:heartbeat
+data:
+
+event:end
+data:
+```
+
+### 2. Creating a SSE Connection with query based authentication
+
+```javascript
+app.get("/", async (req, res) => {
+    const stream = new Evstream(req, res, {
+        heartbeat: 5000, authentication: {
+            method: "query",
+            param: "token",
+            verify: async (token) => false
+        }
+    })
+
+    const isAuthenticated = await stream.authenticate();
+
+    if (!isAuthenticated) {
+        return;
+    }
+
+    stream.message({ event: "connected", data: { userId: "a-user-id" } })
+
+    setTimeout(() => {
+        stream.close();
+    }, 5000)
+})
+```
+
+To test this out URL should be `/?token=<auth-token>`.
+
+You'll get the query parameter value one the callback function's parameter passed to `verify` field.
+You can either return boolean values or `EvMessage`.
+
+#### Authentication
+
+To authenticate the incoming request there is a built-in support in `evstream`. You can verify the query based token verification which is generally not recommended.
+
+- Options :
+  - `method` : Authentication method to use (`"query"`).
+  - `param` : Field or parameter in `query` which holds the authentication token.
+  - `verify` : A callback function to check the token. If `false` returned req will get close.
+
+`evstream` by default doesn't authenticate the request. You have to call the `authenticate` function from `Evstream` class to verify. If false returned you have to stop processing the request and return immediately.
+
+```javascript
+const isAuthenticated = await stream.authenticate()
+```
+
+
+### 3. Creating a stream manager
+
+Using `EvStreamManager` you can broadcast messages, create channels and manage connections in a much better way.
+
+```javascript
+const manager = new EvStreamManager();
+
+app.get("/", (req, res) => {
+    const stream = manager.createStream(req, res)
+
+    const i = setInterval(() => {
+        stream.message({ data: { hello: "hii" } })
+    }, 2000)
+
+    stream.message({ data: { why: "hii" }, event: "hello" })
+
+    setTimeout(() => {
+        clearTimeout(i);
+        stream.close();
+    }, 10000)
+})
+```
+
+### 4. Using Reactive State
+
+Reactive states are data which you can shared across multiple clients within the same server. Whenever the data gets updated each client listening to that data get notified with an SSE message.
+
+- #### Creating a reactive States
+
+  ```javascript
+  import { EvState, EvStreamManager } from "evstream"
+
+  const manager = new EvStreamManager();
+  const userCount = new EvState({ channel: "user-count", initialValue: 0, manager: manager })
+  ```
+
+  To create a reactive value you can use `EvState` class which takes a `channel` which is then listened by the connected client for any update.
+
+  - `channel` : A unique name to which client will listen to for state changes.
+  - `initialValue` : Default value for the state.
+  - `manager` : Connection manager for the connected clients.
+
+  **Getting the state data**
+
+  ```javascript
+  userCount.get();
+  ```
+
+  **Updating State data**
+
+  ```javascript
+  userCount.set((prev) => prev += 1);
+  ```
+  This will update the values and send the data to all clients which are listening for the state changes.
+
+
+- #### Listening for a reactive state
+  ```javascript
+  import { EvState, EvStreamManager } from "evstream"
+
+
+  const manager = new EvStreamManager();
+  const userCount = new EvState({ channel: "user-count", initialValue: 0, manager: manager })
+
+
+  app.get("/", (req, res) => {
+      const stream = manager.createStream(req, res)
+      stream.listen("user-count")
+      userCount.set((user) => user + 1);
+
+      const i = setInterval(() => {
+          stream.message({ data: { hello: "hii" } })
+      }, 2000)
+
+      stream.message({ data: { why: "hii" }, event: "hello" })
+
+      setTimeout(() => {
+          clearTimeout(i);
+          stream.close((channels) => {
+
+              userCount.set((user) => user - 1)
+
+              console.log(channels)
+          });
+      }, 10000)
+  })
+  ```
+
+  This will now listen for a state change in `userCount` variables and push the update to all the connected client listening for that state.
+
+  **See** `channel` **and the value pass to the** `listen()` **must be the same**
+
+### 5. Sending data to a channel
+
+To send data to a channel you can use `send()` method from `EvStreamManager` class.
+
+Example :
+
+```javascript
+import { EvStreamManager } from "evstream"
+
+const manager = new EvStreamManager();
+
+manager.send("<channel-name>", {event: "custom-event", data: {"foo": "bar"}})
+```
+
+### 6. Listening for channels
+
+To listen for data from any channel you can use `listen()` function from `Evstream` class.
+
+```javascript
+client.listen("<channel-name>")
+```
+
+## API Reference
+
+## `Evstream`
+
+Manages a Server-Sent Events (SSE) connection. Handles headers, heartbeat intervals, authentication, sending messages, and closing the stream.
+
+### Constructor
+
+```js
+new Evstream(req: IncomingMessage, res: ServerResponse, opts?: EvOptions)
+```
+
+#### Parameters:
+
+* `req`: `IncomingMessage` – The incoming HTTP request.
+* `res`: `ServerResponse` – The HTTP response to write SSE messages to.
+* `opts` *(optional)*: `EvOptions` – Optional configuration including heartbeat interval and authentication.
+
+---
+
+### Methods
+
+#### `authenticate(): Promise<boolean | undefined>`
+
+Performs optional token-based authentication if `opts.authentication` is provided.
+
+* If authentication fails, sends an error message and closes the connection.
+* Returns `true` if authenticated, `false` if rejected, or `undefined` if no authentication is configured.
+
+---
+
+#### `message(msg: EvMessage): void`
+
+Sends an SSE message to the connected client.
+
+##### Parameters:
+
+* `msg`: `EvMessage` – Object containing `event`, `data`, and optionally `id`.
+
+---
+
+#### `close(): void`
+
+Sends a final `end` event and closes the SSE connection.
+
+---
+
+### Example
+
+```js
+const ev = new Evstream(req, res, {
+  heartbeat: 30000,
+  authentication: {
+    param: 'token',
+    verify: async (token) => token === 'valid_token'
+  }
+})
+
+await ev.authenticate()
+ev.message({ event: 'message', data: { text: 'Hello world' }, id: '1' })
+ev.close()
+```
+
+---
+
+## `EvStreamManager`
+
+Manages multiple Server-Sent Events (SSE) client streams. Supports connection tracking, message broadcasting, and channel-based listeners.
+
+### Constructor
+
+```js
+new EvStreamManager(opts?: EvManagerOptions)
+```
+
+#### Parameters:
+
+* `opts` *(optional)*: `EvManagerOptions`
+
+  * `maxConnection`: Maximum allowed active connections (default: `5000`)
+  * `maxListeners`: Maximum listeners per channel (default: `5000`)
+  * `id`: Optional prefix for client IDs
+
+---
+
+### Methods
+
+#### `createStream(req: IncomingMessage, res: ServerResponse, opts?: EvOptions): { authenticate, message, close, listen }`
+
+Creates and tracks a new SSE stream.
+
+#### Parameters:
+
+* `req`: `IncomingMessage` – Incoming HTTP request
+* `res`: `ServerResponse` – HTTP response for the SSE connection
+* `opts` *(optional)*: `EvOptions` – Optional stream config (heartbeat, authentication, etc.)
+
+#### Returns:
+
+An object with methods:
+
+* `authenticate(): Promise<boolean | undefined>` – Authenticates the stream (delegates to `Evstream`)
+* `message(msg: EvMessage): void` – Sends a message to the stream
+* `close(onClose?: EvOnClose): void` – Closes the stream and cleans up listeners
+* `listen(name: string): void` – Subscribes the stream to a named channel
+
+---
+
+#### `send(name: string, msg: EvMessage): void`
+
+Broadcasts a message to all clients listening on the specified `name` (channel).
+
+##### Parameters:
+
+* `name`: `string` – Channel name
+* `msg`: `EvMessage` – The message to broadcast
+
+---
+
+### Private Methods
+
+#### `#listen(name: string, id: string): void`
+
+Adds a client (by ID) to a named channel. Throws `EvMaxListenerError` if channel exceeds max listeners.
+
+---
+
+#### `#unlisten(name: string, id: string): void`
+
+Removes a client from a channel. Deletes the channel if no listeners remain.
+
+---
+
+### Example
+
+```js
+const manager = new EvStreamManager()
+
+const stream = manager.createStream(req, res)
+
+await stream.authenticate()
+stream.listen('news')
+stream.message({ event: 'hello', data: 'welcome' })
+
+manager.send('news', { event: 'news', data: 'breaking update' })
+```
+
+## `EvState<T>`
+
+Reactive state holder that broadcasts updates to a specified channel via an `EvStreamManager`. Designed for real-time state syncing over Server-Sent Events (SSE).
+
+### Constructor
+
+```ts
+new EvState<T>({
+  channel,
+  initialValue,
+  manager,
+  key
+}: EvStateOptions<T>)
+```
+
+#### Parameters:
+
+* `channel`: `string` – The name of the channel to broadcast updates to.
+* `initialValue`: `T` – The initial state value.
+* `manager`: `EvStreamManager` – The SSE manager instance used for broadcasting.
+* `key` *(optional)*: `string` – The key used in the broadcasted data object (default: `'value'`).
+
+---
+
+### Methods
+
+#### `get(): T`
+
+Returns the current value of the state.
+
+---
+
+#### `set(callback: (val: T) => T): void`
+
+Updates the internal state based on a callback function. If the new value is different (deep comparison), it broadcasts the updated value to the channel.
+
+##### Parameters:
+
+* `callback`: `(val: T) => T` – A function that receives the current state and returns the new state.
+
+---
+
+### Example
+
+```ts
+const state = new EvState({
+  channel: 'counter',
+  initialValue: 0,
+  manager: evManager,
+  key: 'count'
+})
+
+state.set(prev => prev + 1)
+// Will broadcast: { event: 'counter', data: { count: 1 } }
+
+const current = state.get()
+// current === 1
+```
+
+---
+
+## `EvMaxConnectionsError`
+
+Represents an error thrown when the number of active SSE connections exceeds the allowed `maxConnection` limit (default: `5000`).
+
+### Constructor
+
+```ts
+new EvMaxConnectionsError(connections: number)
+```
+
+#### Parameters:
+
+- `connections`: `number` – The current number of active connections when the limit is exceeded.
+
+#### Example
+
+```ts
+const manager = new EvStreamManager({ maxConnection: 100 });
+if (tooManyConnections) {
+  throw new EvMaxConnectionsError(100)
+}
+```
+
+---
+
+## `EvMaxListenerError`
+
+Represents an error thrown when the number of listeners on a given channel exceeds the allowed `maxListeners` limit (default: `5000`).
+
+### Constructor
+
+```ts
+new EvMaxListenerError(listeners: number, channel: string)
+```
+
+#### Parameters:
+
+- `listeners`: `number` – The current number of listeners on the channel.
+- `channel`: `string` – The name of the channel that exceeded the listener limit.
+
+#### Example
+
+```ts
+if (tooManyListenersOnChannel) {
+  throw new EvMaxListenerError(5000, 'news')
+}
+```
+
+---
+
+## Type Definitions
+
+---
+
+### `EvEventsType`
+
+```ts
+type EvEventsType = 'data' | 'error' | 'end'
+```
+
+Represents built-in event types commonly used in Server-Sent Events.
+
+---
+
+### `EvMessage`
+
+```ts
+interface EvMessage {
+  event?: string | EvEventsType
+  data: string | object
+  id?: string
+}
+```
+
+Represents a message sent to the client via SSE.
+
+- `event` *(optional)*: Name of the event.
+- `data`: The payload to send. Can be a string or an object.
+- `id` *(optional)*: Event ID for reconnection tracking.
+
+---
+
+### `EvAuthenticationOptions`
+
+```ts
+interface EvAuthenticationOptions {
+  method: 'query'
+  param: string
+  verify: (token: string) => Promise<EvMessage> | undefined | null | boolean
+}
+```
+
+Options for enabling query-based token authentication.
+
+- `method`: Always `'query'`
+- `param`: Name of the query parameter containing the token.
+- `verify`: Async verification function. Can return:
+  - `true` (authenticated)
+  - `false` (rejected)
+  - `EvMessage` (custom response)
+  - `undefined` / `null` (unauthenticated)
+
+---
+
+### `EvOptions`
+
+```ts
+interface EvOptions {
+  authentication?: EvAuthenticationOptions
+  heartbeat?: number
+}
+```
+
+Optional config for an individual SSE stream.
+
+- `authentication`: Auth configuration (see `EvAuthenticationOptions`)
+- `heartbeat`: Interval in milliseconds for sending heartbeat events
+
+---
+
+### `EvManagerOptions`
+
+```ts
+interface EvManagerOptions {
+  id?: string
+  maxConnection?: number
+  maxListeners?: number
+}
+```
+
+Configuration for `EvStreamManager`.
+
+- `id`: Optional prefix for client IDs
+- `maxConnection`: Max allowed connections (default: `5000`)
+- `maxListeners`: Max listeners per channel (default: `5000`)
+
+---
+
+### `EvStateOptions<T>`
+
+```ts
+interface EvStateOptions<T> {
+  initialValue: T
+  channel: string
+  manager: EvStreamManager
+  key?: string
+}
+```
+
+Options for initializing a reactive state with `EvState`.
+
+- `initialValue`: Initial state value
+- `channel`: Channel name for broadcasting
+- `manager`: Instance of `EvStreamManager`
+- `key` *(optional)*: Key for wrapping state in the broadcast (default: `'value'`)
+
+---
+
+### `EvOnClose`
+
+```ts
+type EvOnClose = (channels: string[]) => Promise<void>
+```
+
+Callback triggered when a client connection is closed. Receives a list of channels the client was subscribed to.
+
+---
+
+## 🤝 Contribution
+
+Contributions are welcome! Whether it's a bug fix, feature request, or improvement to documentation, your help is appreciated.
+
+### How to Contribute:
+
+1. **Fork** the repository.
+2. **Create a branch** for your feature or fix:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. **Commit your changes** with a clear message.
+4. **Push to your fork**:
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+5. **Open a Pull Request** and describe your changes.
+
+### Guidelines:
+
+* Keep your code clean and consistent with the project's existing style.
+* Include relevant tests and documentation updates.
+* Make sure the project builds and passes all existing checks.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**.
+
+You are free to use, modify, distribute, and sublicense this software for both personal and commercial use — provided that the original license and copyright notice are included in all copies.
+
+> See the [LICENSE](./LICENSE) file for full details.
+
+---