@nevuamarkets/poly-websockets 0.3.0 → 1.0.0-beta.0

package/README.md

@@ -14,10 +14,11 @@ npm install @nevuamarkets/poly-websockets
 
 - 📊 **Real-time Market Updates**: Get `book` , `price_change`, `tick_size_change` and `last_trade_price` real-time market events from Polymarket WSS
 - 🎯 **Derived Future Price Event**: Implements Polymarket's [price calculation logic](https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated#future-price) (midpoint vs last trade price based on spread)
-- 🔗 **Group Management**: Efficiently manages multiple asset subscriptions across connection groups **without losing events** when subscribing / unsubscribing assets.
-- 🔄 **Automatic Connection Management**: Handles WebSocket connections, reconnections, and cleanup for grouped assetId (i.e. clobTokenId) subscriptions
+- 🔗 **Dynamic Subscriptions**: Subscribe and unsubscribe to assets on existing WebSocket connections without reconnecting
+- 🔄 **Automatic Connection Management**: Handles WebSocket connections, reconnections, and cleanup
 - 🚦 **Rate Limiting**: Built-in rate limiting to respect Polymarket API limits
 - 💪 **TypeScript Support**: Full TypeScript definitions for all events and handlers
+- ♾️ **Unlimited Assets**: By default, all subscriptions go through a single WebSocket connection (Polymarket now supports unlimited assets per connection)
 
 ## Quick Start
 
@@ -66,7 +67,7 @@ new WSSubscriptionManager(handlers: WebSocketHandlers, options?: SubscriptionMan
 **Parameters:**
 - `handlers` - Event handlers for different WebSocket events
 - `options` - Optional configuration object:
-  - `maxMarketsPerWS?: number` - Maximum assets per WebSocket connection (default: 100)
+  - `maxMarketsPerWS?: number` - Maximum assets per WebSocket connection (default: `Infinity` - unlimited, single connection for all assets)
   - `reconnectAndCleanupIntervalMs?: number` - Interval for reconnection attempts (default: 10s)
   - `burstLimiter?: Bottleneck` - Custom rate limiter instance. If none is provided, one will be created and used internally in the component.
 
@@ -76,12 +77,15 @@ new WSSubscriptionManager(handlers: WebSocketHandlers, options?: SubscriptionMan
 
 Adds new asset subscriptions. The manager will:
 - Filter out already subscribed assets
-- Find available connection groups or create new ones
-- Establish WebSocket connections as needed
+- If an active WebSocket connection exists with capacity, send a subscribe message on that connection
+- Otherwise, create a new WebSocket connection
 
 ##### `removeSubscriptions(assetIds: string[]): Promise<void>`
 
-Removes asset subscriptions. **Connections are kept alive to avoid missing events**, and unused groups are cleaned up during the next reconnection cycle.
+Removes asset subscriptions. The manager will:
+- Send an unsubscribe message on the active connection
+- Clear the internal order book cache for removed assets
+- Connections are kept alive to avoid missing events for other subscribed assets
 
 ##### `clearState(): Promise<void>`
 

package/dist/WSSubscriptionManager.d.ts

@@ -7,11 +7,54 @@ declare class WSSubscriptionManager {
     private bookCache;
     private reconnectAndCleanupIntervalMs;
     private maxMarketsPerWS;
+    private reconnectInterval?;
     constructor(userHandlers: WebSocketHandlers, options?: SubscriptionManagerOptions);
+    /**
+     * Clears all WebSocket subscriptions and state.
+     *
+     * This will:
+     *
+     * 1. Stop the reconnection interval
+     * 2. Remove all subscriptions and groups (including GroupSockets)
+     * 3. Close all WebSocket connections
+     * 4. 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;
+    /**
+     * Adds new subscriptions.
+     *
+     * - Filters out assets that are already subscribed
+     * - If an ALIVE group exists with capacity, sends subscribe message on that connection
+     * - Otherwise creates a new group and WebSocket connection
+     *
+     * @param assetIdsToAdd - The asset IDs to add subscriptions for.
+     */
     addSubscriptions(assetIdsToAdd: string[]): Promise<void>;
+    /**
+     * Removes subscriptions.
+     * Sends unsubscribe messages to ALIVE connections.
+     *
+     * @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;

package/dist/WSSubscriptionManager.js

@@ -5,7 +5,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WSSubscriptionManager = void 0;
 const ms_1 = __importDefault(require("ms"));
-const lodash_1 = __importDefault(require("lodash"));
 const bottleneck_1 = __importDefault(require("bottleneck"));
 const PolymarketWebSocket_1 = require("./types/PolymarketWebSocket");
 const GroupRegistry_1 = require("./modules/GroupRegistry");
@@ -16,7 +15,9 @@ const logger_1 = require("./logger");
 // See https://docs.polymarket.com/quickstart/introduction/rate-limits#api-rate-limits
 const BURST_LIMIT_PER_SECOND = 5;
 const DEFAULT_RECONNECT_AND_CLEANUP_INTERVAL_MS = (0, ms_1.default)('10s');
-const DEFAULT_MAX_MARKETS_PER_WS = 100;
+// Default to Infinity - no limit on assets per WebSocket (single connection)
+// Polymarket now supports unlimited asset subscriptions per connection
+const DEFAULT_MAX_MARKETS_PER_WS = Infinity;
 class WSSubscriptionManager {
     constructor(userHandlers, options) {
         this.groupRegistry = new GroupRegistry_1.GroupRegistry();
@@ -54,20 +55,26 @@ class WSSubscriptionManager {
             (_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, err);
         });
         // Check for dead groups every 10s and reconnect them if needed
-        setInterval(() => {
+        this.reconnectInterval = setInterval(() => {
             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. Stop the reconnection interval
+     * 2. Remove all subscriptions and groups (including GroupSockets)
+     * 3. Close all WebSocket connections
+     * 4. Clear the order book cache
+     */
     async clearState() {
+        // Stop the reconnection interval to prevent zombie behavior
+        if (this.reconnectInterval) {
+            clearInterval(this.reconnectInterval);
+            this.reconnectInterval = undefined;
+        }
         const previousGroups = await this.groupRegistry.clearAllGroups();
         // Close sockets outside the lock
         for (const group of previousGroups) {
@@ -76,17 +83,20 @@ 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) => {
+        events = events.filter((event) => {
             // Handle PriceChangeEvent which doesn't have asset_id at root
             if ((0, PolymarketWebSocket_1.isPriceChangeEvent)(event)) {
                 // Check if any of the price_changes are subscribed
@@ -118,17 +128,20 @@ 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
-    */
+    /**
+     * Adds new subscriptions.
+     *
+     * - Filters out assets that are already subscribed
+     * - If an ALIVE group exists with capacity, sends subscribe message on that connection
+     * - Otherwise creates a new group and WebSocket connection
+     *
+     * @param assetIdsToAdd - The asset IDs to add subscriptions for.
+     */
     async addSubscriptions(assetIdsToAdd) {
         var _a, _b;
         try {
             const groupIdsToConnect = await this.groupRegistry.addAssets(assetIdsToAdd, this.maxMarketsPerWS);
+            // Create new connections for any new groups
             for (const groupId of groupIdsToConnect) {
                 await this.createWebSocketClient(groupId, this.handlers);
             }
@@ -138,11 +151,12 @@ 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.
-    */
+    /**
+     * Removes subscriptions.
+     * Sends unsubscribe messages to ALIVE connections.
+     *
+     * @param assetIdsToRemove - The asset IDs to remove subscriptions for.
+     */
     async removeSubscriptions(assetIdsToRemove) {
         var _a, _b;
         try {
@@ -153,12 +167,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 {
@@ -192,6 +206,8 @@ class WSSubscriptionManager {
             return;
         }
         const groupSocket = new GroupSocket_1.GroupSocket(group, this.burstLimiter, this.bookCache, handlers);
+        // Store the groupSocket in the registry for later subscribe/unsubscribe operations
+        this.groupRegistry.setGroupSocket(groupId, groupSocket);
         try {
             await groupSocket.connect();
         }

package/dist/modules/GroupRegistry.d.ts

@@ -1,6 +1,46 @@
 import { WebSocketGroup } from '../types/WebSocketSubscriptions';
 import { OrderBookCache } from './OrderBookCache';
+import { GroupSocket } from './GroupSocket';
+/**
+ * WebSocketStatus State Transitions:
+ *
+ *   ┌─────────┐
+ *   │ PENDING │ ──── connect() succeeds ────► ALIVE
+ *   └────┬────┘                                 │
+ *        │                                      │
+ *   assets removed                         error/close
+ *   before connect                              │
+ *        │                                      ▼
+ *        │                               ┌──────────┐
+ *        └────────────────────────────►  │   DEAD   │
+ *                                        └────┬─────┘
+ *                                             │
+ *                                     reconnect attempt
+ *                                             │
+ *                                             ▼
+ *                                        ┌─────────┐
+ *                                        │ PENDING │
+ *                                        └─────────┘
+ *
+ *   Any state ──── all assets removed ────► CLEANUP ────► removed from registry
+ *
+ * Valid transitions:
+ *   PENDING -> ALIVE    (on successful connection)
+ *   PENDING -> CLEANUP  (if all assets removed before connect)
+ *   ALIVE   -> DEAD     (on error or connection close)
+ *   ALIVE   -> CLEANUP  (if all assets removed while connected)
+ *   DEAD    -> PENDING  (on reconnection attempt - status reset)
+ *   DEAD    -> CLEANUP  (if all assets removed while dead)
+ *   CLEANUP -> removed  (group removed from registry)
+ *
+ * Note: If a subscribe/unsubscribe message fails to send (e.g., WebSocket closing),
+ * there may be a brief window where local state and server state diverge and events
+ * are missed. This self-heals on reconnection when the full asset list is re-sent.
+ */
 export declare class GroupRegistry {
+    private wsGroups;
+    private wsGroupsMutex;
+    private groupSockets;
     /**
      * Atomic mutate helper.
      *
@@ -14,31 +54,41 @@ export declare class GroupRegistry {
      * Only to be used in test suite.
      */
     snapshot(): WebSocketGroup[];
-    /**
-     * Find the first group with capacity to hold new assets.
-     *
-     * 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.
+     * Note: This read operation does not acquire the mutex for performance reasons.
+     * It provides eventual consistency - the result may be slightly stale if a
+     * concurrent mutation is in progress. This is acceptable given the self-healing
+     * nature of the system (see note at top of file).
+     *
+     * @param assetId - The tokenId of a market.
+     * @returns An array of indices.
      */
     getGroupIndicesForAsset(assetId: string): number[];
     /**
      * Check if any group contains the asset.
+     *
+     * Note: This read operation provides eventual consistency (see getGroupIndicesForAsset).
+     *
+     * @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.
+     * Note: This read operation provides eventual consistency (see getGroupIndicesForAsset).
+     *
+     * @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.
      *
+     * Note: This read operation provides eventual consistency (see getGroupIndicesForAsset).
+     *
      * 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
@@ -47,40 +97,71 @@ export declare class GroupRegistry {
         openWebSockets: number;
         subscribedAssetIds: number;
     };
+    /**
+     * Set the GroupSocket for a group.
+     * Disposes the old socket if one exists to prevent interval leaks.
+     *
+     * @param groupId - The group UUID.
+     * @param socket - The GroupSocket instance.
+     */
+    setGroupSocket(groupId: string, socket: GroupSocket): void;
+    /**
+     * Get the GroupSocket for a group.
+     *
+     * @param groupId - The group UUID.
+     * @returns The GroupSocket if found, otherwise undefined.
+     */
+    getGroupSocket(groupId: string): GroupSocket | undefined;
+    /**
+     * Remove the GroupSocket for a group.
+     * Disposes the socket to prevent interval leaks.
+     *
+     * @param groupId - The group UUID.
+     */
+    removeGroupSocket(groupId: string): void;
+    /**
+     * Clear all GroupSockets.
+     * Disposes all sockets to prevent interval leaks.
+     */
+    clearAllGroupSockets(): void;
     /**
      * Atomically remove **all** groups from the registry and return them so the
      * caller can perform any asynchronous cleanup (closing sockets, etc.)
-     * outside the lock.
+     * outside the lock. Also clears all GroupSockets.
      *
-     * Returns the removed groups.
+     * @returns The removed groups.
      */
     clearAllGroups(): Promise<WebSocketGroup[]>;
     /**
      * Add new asset subscriptions.
      *
      * – Ignores assets that are already subscribed.
-     * – Either reuses an existing group with capacity or creates new groups (size ≤ maxPerWS).
-     * – If appending to a group:
-     *  - A new group is created with the updated assetIds.
-     *  - The old group is marked for cleanup.
-     *  - The group is added to the list of groups to connect.
+     * – If there's an existing non-CLEANUP group with capacity, adds assets to it.
+     *   - ALIVE groups: sends subscribe message immediately
+     *   - PENDING/DEAD groups: assets included when connection is (re)established
+     * – Otherwise creates new groups (size ≤ maxPerWS).
      *
      * @param assetIds - The assetIds to add.
      * @param maxPerWS - The maximum number of assets per WebSocket group.
-     * @returns An array of *new* groupIds that need websocket connections.
+     * @returns An array of groupIds that need new websocket connections.
      */
     addAssets(assetIds: string[], maxPerWS: number): Promise<string[]>;
     /**
      * Remove asset subscriptions from every group that contains the asset.
+     * Sends unsubscribe messages on ALIVE connections.
      *
-     * 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 (deduplicated).
      */
     removeAssets(assetIds: string[], bookCache: OrderBookCache): Promise<string[]>;
     /**
-     * Disconnect a group.
+     * Disconnect a group and reset its status for reconnection.
+     *
+     * @param group - The group to disconnect.
      */
     disconnectGroup(group: WebSocketGroup): void;
     /**
@@ -90,7 +171,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[]>;
 }