@nevuamarkets/poly-websockets 0.2.2 → 0.3.1

package/README.md

@@ -90,6 +90,12 @@ Clears all subscriptions and state:
 - Closes all WebSocket connections
 - Clears the internal order book cache
 
+##### `getStatistics(): { openWebSockets: number; subscribedAssetIds: number }`
+
+Returns statistics about the current state of the subscription manager:
+- `openWebSockets`: The number of websockets that are currently in OPEN state
+- `subscribedAssetIds`: The number of unique asset IDs that are currently subscribed
+
 ### WebSocketHandlers
 
 Interface defining event handlers for different WebSocket events.

package/dist/WSSubscriptionManager.d.ts

@@ -8,11 +8,57 @@ declare class WSSubscriptionManager {
     private reconnectAndCleanupIntervalMs;
     private maxMarketsPerWS;
     constructor(userHandlers: WebSocketHandlers, options?: SubscriptionManagerOptions);
+    /**
+     * Clears all WebSocket subscriptions and state.
+     *
+     * This will:
+     *
+     * 1. Remove all subscriptions and groups
+     * 2. Close all WebSocket connections
+     * 3. Clear the order book cache
+     */
     clearState(): Promise<void>;
+    /**
+     * This function is called when:
+     * - a websocket event is received from the Polymarket WS
+     * - a price update event detected, either by after a 'last_trade_price' event or a 'price_change' event
+     * depending on the current bid-ask spread (see https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated)
+     *
+     * The user handlers will be called **ONLY** for assets that are actively subscribed to by any groups.
+     *
+     * @param events - The events to process.
+     * @param action - The action to perform on the filtered events.
+     */
     private actOnSubscribedEvents;
+    /**
+     * Edits wsGroups: Adds new subscriptions.
+     *
+     * - Filters out assets that are already subscribed
+     * - Finds a group with capacity or creates a new one
+     * - Creates a new WebSocket client and adds it to the group
+     *
+     * @param assetIdsToAdd - The asset IDs to add subscriptions for.
+     */
     addSubscriptions(assetIdsToAdd: string[]): Promise<void>;
+    /**
+     * Edits wsGroups: Removes subscriptions.
+     * The group will use the updated subscriptions when it reconnects.
+     * We do that because we don't want to miss events by reconnecting.
+     *
+     * @param assetIdsToRemove - The asset IDs to remove subscriptions for.
+     */
     removeSubscriptions(assetIdsToRemove: string[]): Promise<void>;
+    /**
+     * This function runs periodically and:
+     *
+     * - Tries to reconnect groups that have assets and are disconnected
+     * - Cleans up groups that have no assets
+     */
     private reconnectAndCleanupGroups;
+    getStatistics(): {
+        openWebSockets: number;
+        subscribedAssetIds: number;
+    };
     private createWebSocketClient;
 }
 export { WSSubscriptionManager, WebSocketHandlers };

package/dist/WSSubscriptionManager.js

@@ -58,15 +58,15 @@ class WSSubscriptionManager {
             this.reconnectAndCleanupGroups();
         }, this.reconnectAndCleanupIntervalMs);
     }
-    /*
-        Clears all WebSocket subscriptions and state.
-
-        This will:
-
-        1. Remove all subscriptions and groups
-        2. Close all WebSocket connections
-        3. Clear the order book cache
-    */
+    /**
+     * Clears all WebSocket subscriptions and state.
+     *
+     * This will:
+     *
+     * 1. Remove all subscriptions and groups
+     * 2. Close all WebSocket connections
+     * 3. Clear the order book cache
+     */
     async clearState() {
         const previousGroups = await this.groupRegistry.clearAllGroups();
         // Close sockets outside the lock
@@ -76,14 +76,17 @@ class WSSubscriptionManager {
         // Also clear the order book cache
         this.bookCache.clear();
     }
-    /*
-        This function is called when:
-        - a websocket event is received from the Polymarket WS
-        - a price update event detected, either by after a 'last_trade_price' event or a 'price_change' event
-        depending on the current bid-ask spread (see https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated)
-
-        The user handlers will be called **ONLY** for assets that are actively subscribed to by any groups.
-    */
+    /**
+     * This function is called when:
+     * - a websocket event is received from the Polymarket WS
+     * - a price update event detected, either by after a 'last_trade_price' event or a 'price_change' event
+     * depending on the current bid-ask spread (see https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated)
+     *
+     * The user handlers will be called **ONLY** for assets that are actively subscribed to by any groups.
+     *
+     * @param events - The events to process.
+     * @param action - The action to perform on the filtered events.
+     */
     async actOnSubscribedEvents(events, action) {
         // Filter out events that are not subscribed to by any groups
         events = lodash_1.default.filter(events, (event) => {
@@ -118,13 +121,15 @@ class WSSubscriptionManager {
         });
         await (action === null || action === void 0 ? void 0 : action(events));
     }
-    /*
-        Edits wsGroups: Adds new subscriptions.
-
-        - Filters out assets that are already subscribed
-        - Finds a group with capacity or creates a new one
-        - Creates a new WebSocket client and adds it to the group
-    */
+    /**
+     * Edits wsGroups: Adds new subscriptions.
+     *
+     * - Filters out assets that are already subscribed
+     * - Finds a group with capacity or creates a new one
+     * - Creates a new WebSocket client and adds it to the group
+     *
+     * @param assetIdsToAdd - The asset IDs to add subscriptions for.
+     */
     async addSubscriptions(assetIdsToAdd) {
         var _a, _b;
         try {
@@ -138,11 +143,13 @@ class WSSubscriptionManager {
             await ((_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, new Error(msg)));
         }
     }
-    /*
-        Edits wsGroups: Removes subscriptions.
-        The group will use the updated subscriptions when it reconnects.
-        We do that because we don't want to miss events by reconnecting.
-    */
+    /**
+     * Edits wsGroups: Removes subscriptions.
+     * The group will use the updated subscriptions when it reconnects.
+     * We do that because we don't want to miss events by reconnecting.
+     *
+     * @param assetIdsToRemove - The asset IDs to remove subscriptions for.
+     */
     async removeSubscriptions(assetIdsToRemove) {
         var _a, _b;
         try {
@@ -153,12 +160,12 @@ class WSSubscriptionManager {
             await ((_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, new Error(errMsg)));
         }
     }
-    /*
-        This function runs periodically and:
-
-        - Tries to reconnect groups that have assets and are disconnected
-        - Cleans up groups that have no assets
-    */
+    /**
+     * This function runs periodically and:
+     *
+     * - Tries to reconnect groups that have assets and are disconnected
+     * - Cleans up groups that have no assets
+     */
     async reconnectAndCleanupGroups() {
         var _a, _b;
         try {
@@ -171,6 +178,16 @@ class WSSubscriptionManager {
             await ((_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, err));
         }
     }
+    /*
+        Returns statistics about the current state of the subscription manager.
+
+        Returns an object with:
+        - openWebSockets: The number of websockets that are currently in OPEN state
+        - subscribedAssetIds: The number of unique asset IDs that are currently subscribed
+    */
+    getStatistics() {
+        return this.groupRegistry.getStatistics();
+    }
     async createWebSocketClient(groupId, handlers) {
         var _a, _b;
         const group = this.groupRegistry.findGroupById(groupId);

package/dist/modules/GroupRegistry.d.ts

@@ -17,31 +17,47 @@ export declare class GroupRegistry {
     /**
      * Find the first group with capacity to hold new assets.
      *
-     * Returns the groupId if found, otherwise null.
+     * @returns The groupId if found, otherwise null.
      */
     findGroupWithCapacity(newAssetLen: number, maxPerWS: number): string | null;
     /**
      * Get the indices of all groups that contain the asset.
      *
-     * Returns an array of indices.
+     * @param assetId - The tokenId of a market.
+     * @returns An array of indices.
      */
     getGroupIndicesForAsset(assetId: string): number[];
     /**
      * Check if any group contains the asset.
+     *
+     * @param assetId - The tokenId of a market.
+     * @returns True if found.
      */
     hasAsset(assetId: string): boolean;
     /**
      * Find the group by groupId.
      *
-     * Returns the group if found, otherwise undefined.
+     * @param groupId - The group UUID.
+     * @returns The group if found, otherwise undefined.
      */
     findGroupById(groupId: string): WebSocketGroup | undefined;
+    /**
+     * Get statistics about the current state of the registry.
+     *
+     * Returns an object with:
+     * - openWebSockets: The number of websockets that are currently in OPEN state
+     * - subscribedAssetIds: The number of unique asset IDs that are currently subscribed
+     */
+    getStatistics(): {
+        openWebSockets: number;
+        subscribedAssetIds: number;
+    };
     /**
      * Atomically remove **all** groups from the registry and return them so the
      * caller can perform any asynchronous cleanup (closing sockets, etc.)
      * outside the lock.
      *
-     * Returns the removed groups.
+     * @returns The removed groups.
      */
     clearAllGroups(): Promise<WebSocketGroup[]>;
     /**
@@ -62,14 +78,18 @@ export declare class GroupRegistry {
     /**
      * Remove asset subscriptions from every group that contains the asset.
      *
-     * It should be only one group that contains the asset, we search all of them
+     * It should be only one group that contains the asset, but we search all of them
      * regardless.
      *
-     * Returns the list of assetIds that were removed.
+     * @param assetIds - The tokenIds of the markets to remove.
+     * @param bookCache - The stored orderbook.
+     * @returns The list of assetIds that were removed.
      */
     removeAssets(assetIds: string[], bookCache: OrderBookCache): Promise<string[]>;
     /**
      * Disconnect a group.
+     *
+     * @param group - The group to disconnect.
      */
     disconnectGroup(group: WebSocketGroup): void;
     /**
@@ -79,7 +99,7 @@ export declare class GroupRegistry {
      * – Dead (but non-empty) groups are reset so that caller can reconnect them.
      * – Pending groups are returned so that caller can connect them.
      *
-     * Returns an array of group IDs that need to be reconnected, after cleaning up empty and cleanup-marked groups.
+     * @returns An array of group IDs that need to be reconnected, after cleaning up empty and cleanup-marked groups.
      */
     getGroupsToReconnectAndCleanup(): Promise<string[]>;
 }

package/dist/modules/GroupRegistry.js

@@ -7,6 +7,7 @@ exports.GroupRegistry = void 0;
 const async_mutex_1 = require("async-mutex");
 const lodash_1 = __importDefault(require("lodash"));
 const uuid_1 = require("uuid");
+const ws_1 = __importDefault(require("ws"));
 const WebSocketSubscriptions_1 = require("../types/WebSocketSubscriptions");
 const logger_1 = require("../logger");
 /*
@@ -46,7 +47,7 @@ class GroupRegistry {
     /**
      * Find the first group with capacity to hold new assets.
      *
-     * Returns the groupId if found, otherwise null.
+     * @returns The groupId if found, otherwise null.
      */
     findGroupWithCapacity(newAssetLen, maxPerWS) {
         for (const group of wsGroups) {
@@ -60,7 +61,8 @@ class GroupRegistry {
     /**
      * Get the indices of all groups that contain the asset.
      *
-     * Returns an array of indices.
+     * @param assetId - The tokenId of a market.
+     * @returns An array of indices.
      */
     getGroupIndicesForAsset(assetId) {
         var _a;
@@ -73,6 +75,9 @@ class GroupRegistry {
     }
     /**
      * Check if any group contains the asset.
+     *
+     * @param assetId - The tokenId of a market.
+     * @returns True if found.
      */
     hasAsset(assetId) {
         return wsGroups.some(group => group.assetIds.has(assetId));
@@ -80,17 +85,43 @@ class GroupRegistry {
     /**
      * Find the group by groupId.
      *
-     * Returns the group if found, otherwise undefined.
+     * @param groupId - The group UUID.
+     * @returns The group if found, otherwise undefined.
      */
     findGroupById(groupId) {
         return wsGroups.find(g => g.groupId === groupId);
     }
+    /**
+     * Get statistics about the current state of the registry.
+     *
+     * Returns an object with:
+     * - openWebSockets: The number of websockets that are currently in OPEN state
+     * - subscribedAssetIds: The number of unique asset IDs that are currently subscribed
+     */
+    getStatistics() {
+        let openWebSockets = 0;
+        const uniqueAssetIds = new Set();
+        for (const group of wsGroups) {
+            // Count open websockets
+            if (group.wsClient && group.wsClient.readyState === ws_1.default.OPEN) {
+                openWebSockets++;
+            }
+            // Collect unique asset IDs
+            for (const assetId of group.assetIds) {
+                uniqueAssetIds.add(assetId);
+            }
+        }
+        return {
+            openWebSockets,
+            subscribedAssetIds: uniqueAssetIds.size,
+        };
+    }
     /**
      * Atomically remove **all** groups from the registry and return them so the
      * caller can perform any asynchronous cleanup (closing sockets, etc.)
      * outside the lock.
      *
-     * Returns the removed groups.
+     * @returns The removed groups.
      */
     async clearAllGroups() {
         let removed = [];
@@ -171,10 +202,12 @@ class GroupRegistry {
     /**
      * Remove asset subscriptions from every group that contains the asset.
      *
-     * It should be only one group that contains the asset, we search all of them
+     * It should be only one group that contains the asset, but we search all of them
      * regardless.
      *
-     * Returns the list of assetIds that were removed.
+     * @param assetIds - The tokenIds of the markets to remove.
+     * @param bookCache - The stored orderbook.
+     * @returns The list of assetIds that were removed.
      */
     async removeAssets(assetIds, bookCache) {
         const removedAssetIds = [];
@@ -199,11 +232,14 @@ class GroupRegistry {
     }
     /**
      * Disconnect a group.
+     *
+     * @param group - The group to disconnect.
      */
     disconnectGroup(group) {
         var _a;
         (_a = group.wsClient) === null || _a === void 0 ? void 0 : _a.close();
         group.wsClient = null;
+        group.connecting = false;
         logger_1.logger.info({
             message: 'Disconnected group',
             groupId: group.groupId,
@@ -218,7 +254,7 @@ class GroupRegistry {
      * – Dead (but non-empty) groups are reset so that caller can reconnect them.
      * – Pending groups are returned so that caller can connect them.
      *
-     * Returns an array of group IDs that need to be reconnected, after cleaning up empty and cleanup-marked groups.
+     * @returns An array of group IDs that need to be reconnected, after cleaning up empty and cleanup-marked groups.
      */
     async getGroupsToReconnectAndCleanup() {
         const reconnectIds = [];
@@ -242,6 +278,9 @@ class GroupRegistry {
                     continue;
                 }
                 if (group.status === WebSocketSubscriptions_1.WebSocketStatus.PENDING) {
+                    if (group.connecting) {
+                        continue;
+                    }
                     reconnectIds.push(group.groupId);
                 }
             }

package/dist/modules/GroupSocket.d.ts

@@ -14,9 +14,46 @@ export declare class GroupSocket {
      *
      */
     connect(): Promise<void>;
+    /**
+     * Sets up event handlers for the WebSocket connection.
+     *
+     * Handles:
+     * - 'open': Authenticates and starts ping interval
+     * - 'message': Parses and routes events
+     * - 'pong': Handles pong responses
+     * - 'error': Handles errors
+     * - 'close': Handles connection closure
+     */
     private setupEventHandlers;
+    /**
+     * Handles book events by updating the cache and notifying listeners.
+     *
+     * @param bookEvents - The book events to process.
+     */
     private handleBookEvents;
+    /**
+     * Handles tick size change events by notifying listeners.
+     *
+     * @param tickEvents - The tick size change events to process.
+     */
     private handleTickEvents;
+    /**
+     * Handles price change events.
+     *
+     * - Updates the order book cache
+     * - Calculates derived price updates based on spread and midpoint
+     * - Notifies listeners of price changes and derived updates
+     *
+     * @param priceChangeEvents - The price change events to process.
+     */
     private handlePriceChangeEvents;
+    /**
+     * Handles last trade price events.
+     *
+     * - Notifies listeners of last trade price
+     * - Calculates derived price updates based on spread
+     *
+     * @param lastTradeEvents - The last trade price events to process.
+     */
     private handleLastTradeEvents;
 }

package/dist/modules/GroupSocket.js

@@ -24,10 +24,14 @@ class GroupSocket {
      *
      */
     async connect() {
+        if (this.group.connecting) {
+            return;
+        }
         if (this.group.assetIds.size === 0) {
             this.group.status = WebSocketSubscriptions_1.WebSocketStatus.CLEANUP;
             return;
         }
+        this.group.connecting = true;
         try {
             logger_1.logger.info({
                 message: 'Connecting to CLOB WebSocket',
@@ -54,8 +58,21 @@ class GroupSocket {
             this.group.status = WebSocketSubscriptions_1.WebSocketStatus.DEAD;
             throw err; // caller responsible for error handler
         }
+        finally {
+            this.group.connecting = false;
+        }
         this.setupEventHandlers();
     }
+    /**
+     * Sets up event handlers for the WebSocket connection.
+     *
+     * Handles:
+     * - 'open': Authenticates and starts ping interval
+     * - 'message': Parses and routes events
+     * - 'pong': Handles pong responses
+     * - 'error': Handles errors
+     * - 'close': Handles connection closure
+     */
     setupEventHandlers() {
         const group = this.group;
         const handlers = this.handlers;
@@ -220,6 +237,11 @@ class GroupSocket {
             return;
         }
     }
+    /**
+     * Handles book events by updating the cache and notifying listeners.
+     *
+     * @param bookEvents - The book events to process.
+     */
     async handleBookEvents(bookEvents) {
         var _a, _b;
         if (bookEvents.length) {
@@ -229,12 +251,26 @@ class GroupSocket {
             await ((_b = (_a = this.handlers).onBook) === null || _b === void 0 ? void 0 : _b.call(_a, bookEvents));
         }
     }
+    /**
+     * Handles tick size change events by notifying listeners.
+     *
+     * @param tickEvents - The tick size change events to process.
+     */
     async handleTickEvents(tickEvents) {
         var _a, _b;
         if (tickEvents.length) {
             await ((_b = (_a = this.handlers).onTickSizeChange) === null || _b === void 0 ? void 0 : _b.call(_a, tickEvents));
         }
     }
+    /**
+     * Handles price change events.
+     *
+     * - Updates the order book cache
+     * - Calculates derived price updates based on spread and midpoint
+     * - Notifies listeners of price changes and derived updates
+     *
+     * @param priceChangeEvents - The price change events to process.
+     */
     async handlePriceChangeEvents(priceChangeEvents) {
         var _a, _b, _c, _d;
         if (priceChangeEvents.length) {
@@ -309,6 +345,14 @@ class GroupSocket {
             }
         }
     }
+    /**
+     * Handles last trade price events.
+     *
+     * - Notifies listeners of last trade price
+     * - Calculates derived price updates based on spread
+     *
+     * @param lastTradeEvents - The last trade price events to process.
+     */
     async handleLastTradeEvents(lastTradeEvents) {
         var _a, _b, _c, _d;
         if (lastTradeEvents.length) {

package/dist/modules/OrderBookCache.d.ts

@@ -6,27 +6,27 @@ export interface BookEntry {
     midpoint: string | null;
     spread: string | null;
 }
-export declare function sortDescendingInPlace(bookSide: PriceLevel[]): void;
 export declare class OrderBookCache {
     private bookCache;
     constructor();
     /**
      * Replace full book (after a `book` event)
+     * @param event new orderbook event
      */
     replaceBook(event: BookEvent): void;
     /**
      * Update a cached book from a `price_change` event.
      *
-     * Returns true if the book was updated.
-     * Throws if the book is not found.
+     * @param event PriceChangeEvent
+     * @returns true if the book was updated.
+     * @throws if the book is not found.
      */
     upsertPriceChange(event: PriceChangeEvent): void;
     /**
-     * Return `true` if best-bid/best-ask spread exceeds `cents`.
-     *
      * Side effect: updates the book's spread
      *
-     * Throws if either side of the book is empty.
+     * @returns `true` if best-bid/best-ask spread exceeds `cents`.
+     * @throws if either side of the book is empty.
      */
     spreadOver(assetId: string, cents?: number): boolean;
     /**
@@ -39,11 +39,16 @@ export declare class OrderBookCache {
      * - the midpoint is NaN.
     */
     midpoint(assetId: string): string;
+    /**
+     * Removes a specific market from the orderbook if assetId is provided
+     * otherwise clears all orderbook
+     * @param assetId tokenId of a market
+     */
     clear(assetId?: string): void;
     /**
      * Get a book entry by asset id.
      *
-     * Return null if the book is not found.
+     * @returns book entry if found, otherwise null
      */
     getBookEntry(assetId: string): BookEntry | null;
 }

package/dist/modules/OrderBookCache.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrderBookCache = void 0;
-exports.sortDescendingInPlace = sortDescendingInPlace;
 function sortDescendingInPlace(bookSide) {
     bookSide.sort((a, b) => parseFloat(b.price) - parseFloat(a.price));
 }
@@ -14,6 +13,7 @@ class OrderBookCache {
     }
     /**
      * Replace full book (after a `book` event)
+     * @param event new orderbook event
      */
     replaceBook(event) {
         let lastPrice = null;
@@ -43,8 +43,9 @@ class OrderBookCache {
     /**
      * Update a cached book from a `price_change` event.
      *
-     * Returns true if the book was updated.
-     * Throws if the book is not found.
+     * @param event PriceChangeEvent
+     * @returns true if the book was updated.
+     * @throws if the book is not found.
      */
     upsertPriceChange(event) {
         // Iterate through price_changes array
@@ -79,11 +80,10 @@ class OrderBookCache {
         }
     }
     /**
-     * Return `true` if best-bid/best-ask spread exceeds `cents`.
-     *
      * Side effect: updates the book's spread
      *
-     * Throws if either side of the book is empty.
+     * @returns `true` if best-bid/best-ask spread exceeds `cents`.
+     * @throws if either side of the book is empty.
      */
     spreadOver(assetId, cents = 0.1) {
         const book = this.bookCache[assetId];
@@ -149,6 +149,11 @@ class OrderBookCache {
         book.midpoint = parseFloat(midpoint.toFixed(3)).toString();
         return parseFloat(midpoint.toFixed(3)).toString();
     }
+    /**
+     * Removes a specific market from the orderbook if assetId is provided
+     * otherwise clears all orderbook
+     * @param assetId tokenId of a market
+     */
     clear(assetId) {
         if (assetId) {
             delete this.bookCache[assetId];
@@ -162,7 +167,7 @@ class OrderBookCache {
     /**
      * Get a book entry by asset id.
      *
-     * Return null if the book is not found.
+     * @returns book entry if found, otherwise null
      */
     getBookEntry(assetId) {
         if (!this.bookCache[assetId]) {

package/dist/types/PolymarketWebSocket.d.ts

@@ -22,7 +22,7 @@ export type PriceChangeItem = {
 /**
  * Represents a price_change event from Polymarket WebSocket
  *
- * Schema example:
+ * @example
  * {
  *   market: "0x5f65177b394277fd294cd75650044e32ba009a95022d88a0c1d565897d72f8f1",
  *   price_changes: [

package/dist/types/WebSocketSubscriptions.d.ts

@@ -11,6 +11,7 @@ export type WebSocketGroup = {
     assetIds: Set<string>;
     wsClient: WebSocket | null;
     status: WebSocketStatus;
+    connecting?: boolean;
 };
 export type SubscriptionManagerOptions = {
     burstLimiter?: Bottleneck;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevuamarkets/poly-websockets",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Plug-and-play Polymarket WebSocket price alerts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,9 @@
   "scripts": {
     "build": "tsc",
     "prepare": "npm run build && npm run test",
-    "test": "vitest run"
+    "test": "vitest run --exclude LiveData.test.ts",
+    "test:live": "vitest run LiveData.test.ts",
+    "prepublishOnly": "npm run test:live"
   },
   "repository": {
     "type": "git",

package/src/WSSubscriptionManager.ts

@@ -79,15 +79,15 @@ class WSSubscriptionManager {
         }, this.reconnectAndCleanupIntervalMs);
     }
 
-    /*
-        Clears all WebSocket subscriptions and state.
-
-        This will:
-
-        1. Remove all subscriptions and groups
-        2. Close all WebSocket connections
-        3. Clear the order book cache
-    */
+    /**
+     * Clears all WebSocket subscriptions and state.
+     * 
+     * This will:
+     * 
+     * 1. Remove all subscriptions and groups
+     * 2. Close all WebSocket connections
+     * 3. Clear the order book cache
+     */
     public async clearState() {
         const previousGroups = await this.groupRegistry.clearAllGroups();
 
@@ -100,14 +100,17 @@ class WSSubscriptionManager {
         this.bookCache.clear();
     }
 
-    /* 
-        This function is called when:
-        - a websocket event is received from the Polymarket WS
-        - a price update event detected, either by after a 'last_trade_price' event or a 'price_change' event
-        depending on the current bid-ask spread (see https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated)
-
-        The user handlers will be called **ONLY** for assets that are actively subscribed to by any groups.
-    */
+    /** 
+     * This function is called when:
+     * - a websocket event is received from the Polymarket WS
+     * - a price update event detected, either by after a 'last_trade_price' event or a 'price_change' event
+     * depending on the current bid-ask spread (see https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated)
+     * 
+     * The user handlers will be called **ONLY** for assets that are actively subscribed to by any groups.
+     * 
+     * @param events - The events to process.
+     * @param action - The action to perform on the filtered events.
+     */
     private async actOnSubscribedEvents<T extends PolymarketWSEvent | PolymarketPriceUpdateEvent>(events: T[], action?: (events: T[]) => Promise<void>) {
 
         // Filter out events that are not subscribed to by any groups
@@ -148,13 +151,15 @@ class WSSubscriptionManager {
         await action?.(events);
     }
 
-    /*  
-        Edits wsGroups: Adds new subscriptions.
-
-        - Filters out assets that are already subscribed
-        - Finds a group with capacity or creates a new one
-        - Creates a new WebSocket client and adds it to the group
-    */
+    /**  
+     * Edits wsGroups: Adds new subscriptions.
+     * 
+     * - Filters out assets that are already subscribed
+     * - Finds a group with capacity or creates a new one
+     * - Creates a new WebSocket client and adds it to the group
+     * 
+     * @param assetIdsToAdd - The asset IDs to add subscriptions for.
+     */
     public async addSubscriptions(assetIdsToAdd: string[]) {
         try {
             const groupIdsToConnect = await this.groupRegistry.addAssets(assetIdsToAdd, this.maxMarketsPerWS);
@@ -167,11 +172,13 @@ class WSSubscriptionManager {
         }
     }
 
-    /*  
-        Edits wsGroups: Removes subscriptions.
-        The group will use the updated subscriptions when it reconnects.
-        We do that because we don't want to miss events by reconnecting.
-    */
+    /**  
+     * Edits wsGroups: Removes subscriptions.
+     * The group will use the updated subscriptions when it reconnects.
+     * We do that because we don't want to miss events by reconnecting.
+     * 
+     * @param assetIdsToRemove - The asset IDs to remove subscriptions for.
+     */
     public async removeSubscriptions(assetIdsToRemove: string[]) {
         try {
             await this.groupRegistry.removeAssets(assetIdsToRemove, this.bookCache);
@@ -181,12 +188,12 @@ class WSSubscriptionManager {
         }
     }
 
-    /*
-        This function runs periodically and:
-
-        - Tries to reconnect groups that have assets and are disconnected
-        - Cleans up groups that have no assets
-    */
+    /**
+     * This function runs periodically and:
+     * 
+     * - Tries to reconnect groups that have assets and are disconnected
+     * - Cleans up groups that have no assets
+     */
     private async reconnectAndCleanupGroups() {
         try {
             const reconnectIds = await this.groupRegistry.getGroupsToReconnectAndCleanup();
@@ -199,6 +206,20 @@ class WSSubscriptionManager {
         }
     }
 
+    /*
+        Returns statistics about the current state of the subscription manager.
+
+        Returns an object with:
+        - openWebSockets: The number of websockets that are currently in OPEN state
+        - subscribedAssetIds: The number of unique asset IDs that are currently subscribed
+    */
+    public getStatistics(): {
+        openWebSockets: number;
+        subscribedAssetIds: number;
+    } {
+        return this.groupRegistry.getStatistics();
+    }
+
     private async createWebSocketClient(groupId: string, handlers: WebSocketHandlers) {
         const group = this.groupRegistry.findGroupById(groupId);
 

package/src/modules/GroupRegistry.ts

@@ -1,6 +1,7 @@
 import { Mutex } from 'async-mutex';
 import _ from 'lodash';
 import { v4 as uuidv4 } from 'uuid';
+import WebSocket from 'ws';
 import { WebSocketGroup, WebSocketStatus } from '../types/WebSocketSubscriptions';
 import { OrderBookCache } from './OrderBookCache';
 import { logger } from '../logger';
@@ -42,7 +43,7 @@ export class GroupRegistry {
     /**
      * Find the first group with capacity to hold new assets.
      * 
-     * Returns the groupId if found, otherwise null.
+     * @returns The groupId if found, otherwise null.
      */
     public findGroupWithCapacity(newAssetLen: number, maxPerWS: number): string | null {
         for (const group of wsGroups) {
@@ -55,7 +56,8 @@ export class GroupRegistry {
     /**
      * Get the indices of all groups that contain the asset.
      * 
-     * Returns an array of indices.
+     * @param assetId - The tokenId of a market.
+     * @returns An array of indices.
      */
     public getGroupIndicesForAsset(assetId: string): number[] {
         const indices: number[] = [];
@@ -67,6 +69,9 @@ export class GroupRegistry {
 
     /**
      * Check if any group contains the asset.
+     * 
+     * @param assetId - The tokenId of a market.
+     * @returns True if found.
      */
     public hasAsset(assetId: string): boolean {
         return wsGroups.some(group => group.assetIds.has(assetId));
@@ -75,18 +80,51 @@ export class GroupRegistry {
     /**
      * Find the group by groupId.
      * 
-     * Returns the group if found, otherwise undefined.
+     * @param groupId - The group UUID.
+     * @returns The group if found, otherwise undefined.
      */
     public findGroupById(groupId: string): WebSocketGroup | undefined {
         return wsGroups.find(g => g.groupId === groupId);
     }
 
+    /**
+     * Get statistics about the current state of the registry.
+     * 
+     * Returns an object with:
+     * - openWebSockets: The number of websockets that are currently in OPEN state
+     * - subscribedAssetIds: The number of unique asset IDs that are currently subscribed
+     */
+    public getStatistics(): {
+        openWebSockets: number;
+        subscribedAssetIds: number;
+    } {
+        let openWebSockets = 0;
+        const uniqueAssetIds = new Set<string>();
+
+        for (const group of wsGroups) {
+            // Count open websockets
+            if (group.wsClient && group.wsClient.readyState === WebSocket.OPEN) {
+                openWebSockets++;
+            }
+
+            // Collect unique asset IDs
+            for (const assetId of group.assetIds) {
+                uniqueAssetIds.add(assetId);
+            }
+        }
+
+        return {
+            openWebSockets,
+            subscribedAssetIds: uniqueAssetIds.size,
+        };
+    }
+
     /**
      * Atomically remove **all** groups from the registry and return them so the
      * caller can perform any asynchronous cleanup (closing sockets, etc.)
      * outside the lock. 
      * 
-     * Returns the removed groups.
+     * @returns The removed groups.
      */
     public async clearAllGroups(): Promise<WebSocketGroup[]> {
         let removed: WebSocketGroup[] = [];
@@ -179,10 +217,12 @@ export class GroupRegistry {
     /**
      * Remove asset subscriptions from every group that contains the asset.
      * 
-     * It should be only one group that contains the asset, we search all of them
+     * It should be only one group that contains the asset, but we search all of them
      * regardless.
      * 
-     * Returns the list of assetIds that were removed.
+     * @param assetIds - The tokenIds of the markets to remove.
+     * @param bookCache - The stored orderbook.
+     * @returns The list of assetIds that were removed.
      */
     public async removeAssets(assetIds: string[], bookCache: OrderBookCache): Promise<string[]> {
         const removedAssetIds: string[] = [];
@@ -208,10 +248,13 @@ export class GroupRegistry {
 
     /**
      * Disconnect a group.
+     * 
+     * @param group - The group to disconnect.
      */
     public disconnectGroup(group: WebSocketGroup) {
         group.wsClient?.close();
         group.wsClient = null;
+        group.connecting = false;
 
         logger.info({
             message: 'Disconnected group',
@@ -227,7 +270,7 @@ export class GroupRegistry {
      * – Dead (but non-empty) groups are reset so that caller can reconnect them.
      * – Pending groups are returned so that caller can connect them.
      * 
-     * Returns an array of group IDs that need to be reconnected, after cleaning up empty and cleanup-marked groups.
+     * @returns An array of group IDs that need to be reconnected, after cleaning up empty and cleanup-marked groups.
      */
     public async getGroupsToReconnectAndCleanup(): Promise<string[]> {
         const reconnectIds: string[] = [];
@@ -254,8 +297,10 @@ export class GroupRegistry {
                     group.assetIds = new Set();
                     continue;
                 }
-
                 if (group.status === WebSocketStatus.PENDING) {
+                    if (group.connecting) {
+                        continue;
+                    }
                     reconnectIds.push(group.groupId);
                 }
             }
@@ -271,4 +316,4 @@ export class GroupRegistry {
         });
         return reconnectIds;
     }
-} 
+} 

package/src/modules/GroupSocket.ts

@@ -37,11 +37,16 @@ export class GroupSocket {
      * 
      */
     public async connect(): Promise<void> {
+        if (this.group.connecting) {
+            return;
+        }
         if (this.group.assetIds.size === 0) {
             this.group.status = WebSocketStatus.CLEANUP;
             return;
         }
 
+	    this.group.connecting = true;
+
         try {
             logger.info({
                 message: 'Connecting to CLOB WebSocket',
@@ -66,11 +71,23 @@ export class GroupSocket {
         } catch (err) {
             this.group.status = WebSocketStatus.DEAD;
             throw err; // caller responsible for error handler
+        } finally {
+            this.group.connecting = false;
         }
 
         this.setupEventHandlers();
     }
 
+    /**
+     * Sets up event handlers for the WebSocket connection.
+     * 
+     * Handles:
+     * - 'open': Authenticates and starts ping interval
+     * - 'message': Parses and routes events
+     * - 'pong': Handles pong responses
+     * - 'error': Handles errors
+     * - 'close': Handles connection closure
+     */
     private setupEventHandlers() {
         const group = this.group;
         const handlers = this.handlers;
@@ -249,6 +266,11 @@ export class GroupSocket {
         }
     }
 
+    /**
+     * Handles book events by updating the cache and notifying listeners.
+     * 
+     * @param bookEvents - The book events to process.
+     */
     private async handleBookEvents(bookEvents: BookEvent[]): Promise<void> {
         if (bookEvents.length) {
             for (const event of bookEvents) {
@@ -258,12 +280,26 @@ export class GroupSocket {
         }
     }
 
+    /**
+     * Handles tick size change events by notifying listeners.
+     * 
+     * @param tickEvents - The tick size change events to process.
+     */
     private async handleTickEvents(tickEvents: TickSizeChangeEvent[]): Promise<void> {
         if (tickEvents.length) {
             await this.handlers.onTickSizeChange?.(tickEvents);
         }
     }
 
+    /**
+     * Handles price change events.
+     * 
+     * - Updates the order book cache
+     * - Calculates derived price updates based on spread and midpoint
+     * - Notifies listeners of price changes and derived updates
+     * 
+     * @param priceChangeEvents - The price change events to process.
+     */
     private async handlePriceChangeEvents(priceChangeEvents: PriceChangeEvent[]): Promise<void> {
         if (priceChangeEvents.length) {
             await this.handlers.onPriceChange?.(priceChangeEvents);
@@ -341,6 +377,14 @@ export class GroupSocket {
         }
     }
 
+    /**
+     * Handles last trade price events.
+     * 
+     * - Notifies listeners of last trade price
+     * - Calculates derived price updates based on spread
+     * 
+     * @param lastTradeEvents - The last trade price events to process.
+     */
     private async handleLastTradeEvents(lastTradeEvents: LastTradePriceEvent[]): Promise<void> {
         if (lastTradeEvents.length) {
             /*
@@ -396,4 +440,4 @@ export class GroupSocket {
             }
         }
     }
-} 
+} 

package/src/modules/OrderBookCache.ts

@@ -16,8 +16,7 @@ export interface BookEntry {
     midpoint: string | null;
     spread: string | null;
 }
-
-export 
+ 
 
 function sortDescendingInPlace(bookSide: PriceLevel[]): void {
     bookSide.sort((a, b) => parseFloat(b.price) - parseFloat(a.price));
@@ -36,6 +35,7 @@ export class OrderBookCache {
 
     /**
      * Replace full book (after a `book` event)
+     * @param event new orderbook event
      */
     public replaceBook(event: BookEvent): void {
         let lastPrice = null;
@@ -68,8 +68,9 @@ export class OrderBookCache {
     /**
      * Update a cached book from a `price_change` event.
      * 
-     * Returns true if the book was updated.
-     * Throws if the book is not found.
+     * @param event PriceChangeEvent
+     * @returns true if the book was updated.
+     * @throws if the book is not found.
      */
     public upsertPriceChange(event: PriceChangeEvent): void {
         // Iterate through price_changes array
@@ -105,11 +106,10 @@ export class OrderBookCache {
     }
 
     /**
-     * Return `true` if best-bid/best-ask spread exceeds `cents`.
-     * 
      * Side effect: updates the book's spread
      * 
-     * Throws if either side of the book is empty.
+     * @returns `true` if best-bid/best-ask spread exceeds `cents`.
+     * @throws if either side of the book is empty.
      */
     public spreadOver(assetId: string, cents = 0.1): boolean {
         const book = this.bookCache[assetId];
@@ -183,7 +183,11 @@ export class OrderBookCache {
 
         return parseFloat(midpoint.toFixed(3)).toString();
     }
-
+    /**
+     * Removes a specific market from the orderbook if assetId is provided
+     * otherwise clears all orderbook
+     * @param assetId tokenId of a market 
+     */
     public clear(assetId?: string): void {
         if (assetId) {
             delete this.bookCache[assetId];
@@ -197,7 +201,7 @@ export class OrderBookCache {
     /**
      * Get a book entry by asset id.
      * 
-     * Return null if the book is not found.
+     * @returns book entry if found, otherwise null
      */
     public getBookEntry(assetId: string): BookEntry | null {
         if (!this.bookCache[assetId]) {

package/src/types/PolymarketWebSocket.ts

@@ -24,7 +24,7 @@ export type PriceChangeItem = {
 /**
  * Represents a price_change event from Polymarket WebSocket
  * 
- * Schema example:
+ * @example
  * {
  *   market: "0x5f65177b394277fd294cd75650044e32ba009a95022d88a0c1d565897d72f8f1",
  *   price_changes: [

package/src/types/WebSocketSubscriptions.ts

@@ -13,6 +13,7 @@ export type WebSocketGroup = {
     assetIds: Set<string>;
     wsClient: WebSocket | null;
     status: WebSocketStatus;
+    connecting?: boolean;
 };
 
 export type SubscriptionManagerOptions = {
@@ -23,4 +24,4 @@ export type SubscriptionManagerOptions = {
 
     // How many assets to allow per WebSocket
     maxMarketsPerWS?: number;
-}
+}