@pythnetwork/pyth-lazer-sdk 5.2.0 → 5.2.1

package/dist/cjs/emitter/index.cjs

@@ -0,0 +1,53 @@
+/**
+ * T defines the "Event Map".
+ * Example: `{ 'data': (payload: string) => void; 'error': (err: Error) => void; }`
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "IsomorphicEventEmitter", {
+    enumerable: true,
+    get: function() {
+        return IsomorphicEventEmitter;
+    }
+});
+class IsomorphicEventEmitter {
+    listeners = new Map();
+    /**
+   * Register a callback for a specific event.
+   */ on(eventName, callback) {
+        const currentListeners = this.listeners.get(eventName) ?? [];
+        this.listeners.set(eventName, [
+            ...currentListeners,
+            callback
+        ]);
+    }
+    /**
+   * Registers a callback for a specific event that
+   * will only be executed a single time i.e. the first occurence.
+   * After this, the handler will be automatically removed and cleaned up.
+   */ once(eventName, callback) {
+        const wrappedCallback = (...args)=>{
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            callback(...args);
+            this.off(eventName, wrappedCallback);
+        };
+        this.on(eventName, wrappedCallback);
+    }
+    /**
+   * Remove a callback from a specific event.
+   * If no specific callback is specified when off() is called,
+   * ALL event handler callbacks for the given eventName will be removed
+   * at once.
+   */ off(eventName, callback) {
+        const cbIsFunc = typeof callback === "function";
+        const currentListeners = this.listeners.get(eventName) ?? [];
+        this.listeners.set(eventName, currentListeners.filter((cb)=>cbIsFunc && cb !== callback));
+    }
+    /**
+   * Protected method to retrieve listeners for internal triggering.
+   * This allows the child class to decide how/when to execute them.
+   */ getListeners(eventName) {
+        return this.listeners.get(eventName) ?? [];
+    }
+}

package/dist/cjs/emitter/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * T defines the "Event Map".
+ * Example: `{ 'data': (payload: string) => void; 'error': (err: Error) => void; }`
+ */
+export declare abstract class IsomorphicEventEmitter<T extends Record<string, (...args: any[]) => void>> {
+    private listeners;
+    /**
+     * Register a callback for a specific event.
+     */
+    on<K extends keyof T>(eventName: K, callback: T[K]): void;
+    /**
+     * Registers a callback for a specific event that
+     * will only be executed a single time i.e. the first occurence.
+     * After this, the handler will be automatically removed and cleaned up.
+     */
+    once<K extends keyof T>(eventName: K, callback: T[K]): void;
+    /**
+     * Remove a callback from a specific event.
+     * If no specific callback is specified when off() is called,
+     * ALL event handler callbacks for the given eventName will be removed
+     * at once.
+     */
+    off<K extends keyof T>(eventName: K, callback?: T[K]): void;
+    /**
+     * Protected method to retrieve listeners for internal triggering.
+     * This allows the child class to decide how/when to execute them.
+     */
+    protected getListeners<K extends keyof T>(eventName: K): T[K][];
+}

package/dist/cjs/socket/websocket-pool.cjs

@@ -12,14 +12,15 @@ const _ttlcache = /*#__PURE__*/ _interop_require_default(require("@isaacs/ttlcac
 const _tslog = require("ts-log");
 const _resilientwebsocket = require("./resilient-websocket.cjs");
 const _constants = require("../constants.cjs");
-const _index = require("../util/index.cjs");
+const _index = require("../emitter/index.cjs");
+const _index1 = require("../util/index.cjs");
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
     };
 }
 const DEFAULT_NUM_CONNECTIONS = 4;
-class WebSocketPool {
+class WebSocketPool extends _index.IsomorphicEventEmitter {
     logger;
     rwsPool;
     cache;
@@ -29,7 +30,7 @@ class WebSocketPool {
     wasAllDown = true;
     checkConnectionStatesInterval;
     constructor(logger){
-        this.logger = logger;
+        super(), this.logger = logger;
         this.rwsPool = [];
         this.cache = new _ttlcache.default({
             ttl: 1000 * 10
@@ -57,10 +58,19 @@ class WebSocketPool {
         const log = logger ?? _tslog.dummyLogger;
         const pool = new WebSocketPool(log);
         const numConnections = config.numConnections ?? DEFAULT_NUM_CONNECTIONS;
+        // bind a handler to capture any emitted errors and send them to the user-provided
+        // onWebSocketPoolError callback (if it is present)
+        if (typeof config.onWebSocketPoolError === "function") {
+            pool.on("error", config.onWebSocketPoolError);
+            pool.once("shutdown", ()=>{
+                // unbind all error handlers so we don't leak memory
+                pool.off("error");
+            });
+        }
         for(let i = 0; i < numConnections; i++){
             const baseUrl = urls[i % urls.length];
-            const isBrowser = (0, _index.envIsBrowserOrWorker)();
-            const url = isBrowser ? (0, _index.addAuthTokenToWebSocketUrl)(baseUrl, token) : baseUrl;
+            const isBrowser = (0, _index1.envIsBrowserOrWorker)();
+            const url = isBrowser ? (0, _index1.addAuthTokenToWebSocketUrl)(baseUrl, token) : baseUrl;
             if (!url) {
                 throw new Error(`URLs must not be null or empty`);
             }
@@ -90,14 +100,15 @@ class WebSocketPool {
                     }
                 }
             };
-            if (config.onError) {
-                rws.onError = config.onError;
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            const onErrorHandler = config.onWebSocketError ?? config.onError;
+            if (typeof onErrorHandler === "function") {
+                rws.onError = onErrorHandler;
             }
             // Handle all client messages ourselves. Dedupe before sending to registered message handlers.
             rws.onMessage = (data)=>{
                 pool.dedupeHandler(data).catch((error)=>{
-                    const errMsg = `An error occurred in the WebSocket pool's dedupeHandler: ${error instanceof Error ? error.message : String(error)}`;
-                    throw new Error(errMsg);
+                    pool.emitPoolError(error, "Error in WebSocketPool dedupeHandler");
                 });
             };
             pool.rwsPool.push(rws);
@@ -110,6 +121,21 @@ class WebSocketPool {
         pool.logger.info(`At least one WebSocket connection is established. WebSocketPool is ready.`);
         return pool;
     }
+    emitPoolError(error, context) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (context) {
+            this.logger.error(context, err);
+        } else {
+            this.logger.error("WebSocketPool error", err);
+        }
+        for (const errHandler of this.getListeners("error")){
+            try {
+                errHandler(err);
+            } catch (handlerError) {
+                this.logger.error("WebSocketPool error handler threw", handlerError);
+            }
+        }
+    }
     /**
    * Checks for error responses in JSON messages and throws appropriate errors
    */ handleErrorMessages(data) {
@@ -122,7 +148,7 @@ class WebSocketPool {
     }
     async constructCacheKeyFromWebsocketData(data) {
         if (typeof data === "string") return data;
-        const buff = await (0, _index.bufferFromWebsocketData)(data);
+        const buff = await (0, _index1.bufferFromWebsocketData)(data);
         return buff.toString("hex");
     }
     /**
@@ -138,16 +164,25 @@ class WebSocketPool {
         if (typeof data === "string") {
             this.handleErrorMessages(data);
         }
-        await Promise.all(this.messageListeners.map((handler)=>handler(data)));
+        try {
+            await Promise.all(this.messageListeners.map((handler)=>handler(data)));
+        } catch (error) {
+            this.emitPoolError(error, "Error in WebSocketPool message handler");
+        }
     };
     sendRequest(request) {
         for (const rws of this.rwsPool){
-            rws.send(JSON.stringify(request));
+            try {
+                rws.send(JSON.stringify(request));
+            } catch (error) {
+                this.emitPoolError(error, "Failed to send WebSocket request");
+            }
         }
     }
     addSubscription(request) {
         if (request.type !== "subscribe") {
-            throw new Error("Request must be a subscribe request");
+            this.emitPoolError(new Error("Request must be a subscribe request"));
+            return;
         }
         this.subscriptions.set(request.subscriptionId, request);
         this.sendRequest(request);
@@ -183,7 +218,11 @@ class WebSocketPool {
             this.logger.error("All WebSocket connections are down or reconnecting");
             // Notify all listeners
             for (const listener of this.allConnectionsDownListeners){
-                listener();
+                try {
+                    listener();
+                } catch (error) {
+                    this.emitPoolError(error, "All-connections-down listener threw");
+                }
             }
         }
         // If at least one connection was restored
@@ -200,5 +239,15 @@ class WebSocketPool {
         this.messageListeners = [];
         this.allConnectionsDownListeners = [];
         clearInterval(this.checkConnectionStatesInterval);
+        // execute all bound shutdown handlers
+        for (const shutdownHandler of this.getListeners("shutdown")){
+            try {
+                shutdownHandler();
+            } catch (error) {
+                this.emitPoolError(error, "Shutdown handler threw");
+            }
+        }
+        // ensure any error handlers are removed to avoid leaks
+        this.off("error");
     }
 }

package/dist/cjs/socket/websocket-pool.d.ts

@@ -4,14 +4,47 @@ import type { Logger } from "ts-log";
 import type { Request } from "../protocol.js";
 import type { ResilientWebSocketConfig } from "./resilient-websocket.js";
 import { ResilientWebSocket } from "./resilient-websocket.js";
+import { IsomorphicEventEmitter } from "../emitter/index.js";
 type WebSocketOnMessageCallback = (data: WebSocket.Data) => void | Promise<void>;
 export type WebSocketPoolConfig = {
-    urls?: string[];
+    /**
+     * Maximum number of open, parallel websocket connections
+     * @defaultValue 3
+     */
     numConnections?: number;
-    rwsConfig?: Omit<ResilientWebSocketConfig, "logger" | "endpoint">;
+    /**
+     * Callback that will be executed whenever an error
+     * message or an error event occurs on an individual WebSocket connection
+     *
+     * @deprecated use onWebSocketError() instead
+     */
     onError?: (error: ErrorEvent) => void;
+    /**
+     * Callback that will be executed whenever an error
+     * message or an error event occurs on an individual WebSocket connection
+     */
+    onWebSocketError?: (error: ErrorEvent) => void;
+    /**
+     * Callback that will be executed whenever an error occurs
+     * directly within the WebSocket pool. These can typically
+     * be errors that would normally manifest as "unhandledRejection" or "uncaughtException"
+     * errors.
+     */
+    onWebSocketPoolError?: (error: Error) => void;
+    /**
+     * Additional websocket configuration
+     */
+    rwsConfig?: Omit<ResilientWebSocketConfig, "logger" | "endpoint">;
+    /**
+     * Pyth URLs to use when creating a connection
+     */
+    urls?: string[];
+};
+export type WebSocketPoolEvents = {
+    error: (error: Error) => void;
+    shutdown: () => void;
 };
-export declare class WebSocketPool {
+export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolEvents> {
     private readonly logger;
     rwsPool: ResilientWebSocket[];
     private cache;
@@ -30,6 +63,7 @@ export declare class WebSocketPool {
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
     static create(config: WebSocketPoolConfig, token: string, logger?: Logger): Promise<WebSocketPool>;
+    private emitPoolError;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
      */

package/dist/cjs/util/env-util.cjs

@@ -1,5 +1,3 @@
-// we create this local-only type, which has assertions made to indicate
-// that we do not know and cannot guarantee which JS environment we are in
 "use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
@@ -21,6 +19,8 @@ _export(exports, {
         return envIsServiceOrWebWorker;
     }
 });
+// we create this local-only type, which has assertions made to indicate
+// that we do not know and cannot guarantee which JS environment we are in
 const g = globalThis;
 function envIsServiceOrWebWorker() {
     return typeof WorkerGlobalScope !== "undefined" && g.self instanceof WorkerGlobalScope;

package/dist/esm/emitter/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * T defines the "Event Map".
+ * Example: `{ 'data': (payload: string) => void; 'error': (err: Error) => void; }`
+ */
+export declare abstract class IsomorphicEventEmitter<T extends Record<string, (...args: any[]) => void>> {
+    private listeners;
+    /**
+     * Register a callback for a specific event.
+     */
+    on<K extends keyof T>(eventName: K, callback: T[K]): void;
+    /**
+     * Registers a callback for a specific event that
+     * will only be executed a single time i.e. the first occurence.
+     * After this, the handler will be automatically removed and cleaned up.
+     */
+    once<K extends keyof T>(eventName: K, callback: T[K]): void;
+    /**
+     * Remove a callback from a specific event.
+     * If no specific callback is specified when off() is called,
+     * ALL event handler callbacks for the given eventName will be removed
+     * at once.
+     */
+    off<K extends keyof T>(eventName: K, callback?: T[K]): void;
+    /**
+     * Protected method to retrieve listeners for internal triggering.
+     * This allows the child class to decide how/when to execute them.
+     */
+    protected getListeners<K extends keyof T>(eventName: K): T[K][];
+}

package/dist/esm/emitter/index.mjs

@@ -0,0 +1,43 @@
+/**
+ * T defines the "Event Map".
+ * Example: `{ 'data': (payload: string) => void; 'error': (err: Error) => void; }`
+ */ export class IsomorphicEventEmitter {
+    listeners = new Map();
+    /**
+   * Register a callback for a specific event.
+   */ on(eventName, callback) {
+        const currentListeners = this.listeners.get(eventName) ?? [];
+        this.listeners.set(eventName, [
+            ...currentListeners,
+            callback
+        ]);
+    }
+    /**
+   * Registers a callback for a specific event that
+   * will only be executed a single time i.e. the first occurence.
+   * After this, the handler will be automatically removed and cleaned up.
+   */ once(eventName, callback) {
+        const wrappedCallback = (...args)=>{
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            callback(...args);
+            this.off(eventName, wrappedCallback);
+        };
+        this.on(eventName, wrappedCallback);
+    }
+    /**
+   * Remove a callback from a specific event.
+   * If no specific callback is specified when off() is called,
+   * ALL event handler callbacks for the given eventName will be removed
+   * at once.
+   */ off(eventName, callback) {
+        const cbIsFunc = typeof callback === "function";
+        const currentListeners = this.listeners.get(eventName) ?? [];
+        this.listeners.set(eventName, currentListeners.filter((cb)=>cbIsFunc && cb !== callback));
+    }
+    /**
+   * Protected method to retrieve listeners for internal triggering.
+   * This allows the child class to decide how/when to execute them.
+   */ getListeners(eventName) {
+        return this.listeners.get(eventName) ?? [];
+    }
+}

package/dist/esm/socket/websocket-pool.d.ts

@@ -4,14 +4,47 @@ import type { Logger } from "ts-log";
 import type { Request } from "../protocol.js";
 import type { ResilientWebSocketConfig } from "./resilient-websocket.js";
 import { ResilientWebSocket } from "./resilient-websocket.js";
+import { IsomorphicEventEmitter } from "../emitter/index.js";
 type WebSocketOnMessageCallback = (data: WebSocket.Data) => void | Promise<void>;
 export type WebSocketPoolConfig = {
-    urls?: string[];
+    /**
+     * Maximum number of open, parallel websocket connections
+     * @defaultValue 3
+     */
     numConnections?: number;
-    rwsConfig?: Omit<ResilientWebSocketConfig, "logger" | "endpoint">;
+    /**
+     * Callback that will be executed whenever an error
+     * message or an error event occurs on an individual WebSocket connection
+     *
+     * @deprecated use onWebSocketError() instead
+     */
     onError?: (error: ErrorEvent) => void;
+    /**
+     * Callback that will be executed whenever an error
+     * message or an error event occurs on an individual WebSocket connection
+     */
+    onWebSocketError?: (error: ErrorEvent) => void;
+    /**
+     * Callback that will be executed whenever an error occurs
+     * directly within the WebSocket pool. These can typically
+     * be errors that would normally manifest as "unhandledRejection" or "uncaughtException"
+     * errors.
+     */
+    onWebSocketPoolError?: (error: Error) => void;
+    /**
+     * Additional websocket configuration
+     */
+    rwsConfig?: Omit<ResilientWebSocketConfig, "logger" | "endpoint">;
+    /**
+     * Pyth URLs to use when creating a connection
+     */
+    urls?: string[];
+};
+export type WebSocketPoolEvents = {
+    error: (error: Error) => void;
+    shutdown: () => void;
 };
-export declare class WebSocketPool {
+export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolEvents> {
     private readonly logger;
     rwsPool: ResilientWebSocket[];
     private cache;
@@ -30,6 +63,7 @@ export declare class WebSocketPool {
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
     static create(config: WebSocketPoolConfig, token: string, logger?: Logger): Promise<WebSocketPool>;
+    private emitPoolError;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
      */

package/dist/esm/socket/websocket-pool.mjs

@@ -2,9 +2,10 @@ import TTLCache from "@isaacs/ttlcache";
 import { dummyLogger } from "ts-log";
 import { ResilientWebSocket } from "./resilient-websocket.mjs";
 import { DEFAULT_STREAM_SERVICE_0_URL, DEFAULT_STREAM_SERVICE_1_URL } from "../constants.mjs";
+import { IsomorphicEventEmitter } from "../emitter/index.mjs";
 import { addAuthTokenToWebSocketUrl, bufferFromWebsocketData, envIsBrowserOrWorker } from "../util/index.mjs";
 const DEFAULT_NUM_CONNECTIONS = 4;
-export class WebSocketPool {
+export class WebSocketPool extends IsomorphicEventEmitter {
     logger;
     rwsPool;
     cache;
@@ -14,7 +15,7 @@ export class WebSocketPool {
     wasAllDown = true;
     checkConnectionStatesInterval;
     constructor(logger){
-        this.logger = logger;
+        super(), this.logger = logger;
         this.rwsPool = [];
         this.cache = new TTLCache({
             ttl: 1000 * 10
@@ -42,6 +43,15 @@ export class WebSocketPool {
         const log = logger ?? dummyLogger;
         const pool = new WebSocketPool(log);
         const numConnections = config.numConnections ?? DEFAULT_NUM_CONNECTIONS;
+        // bind a handler to capture any emitted errors and send them to the user-provided
+        // onWebSocketPoolError callback (if it is present)
+        if (typeof config.onWebSocketPoolError === "function") {
+            pool.on("error", config.onWebSocketPoolError);
+            pool.once("shutdown", ()=>{
+                // unbind all error handlers so we don't leak memory
+                pool.off("error");
+            });
+        }
         for(let i = 0; i < numConnections; i++){
             const baseUrl = urls[i % urls.length];
             const isBrowser = envIsBrowserOrWorker();
@@ -75,14 +85,15 @@ export class WebSocketPool {
                     }
                 }
             };
-            if (config.onError) {
-                rws.onError = config.onError;
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            const onErrorHandler = config.onWebSocketError ?? config.onError;
+            if (typeof onErrorHandler === "function") {
+                rws.onError = onErrorHandler;
             }
             // Handle all client messages ourselves. Dedupe before sending to registered message handlers.
             rws.onMessage = (data)=>{
                 pool.dedupeHandler(data).catch((error)=>{
-                    const errMsg = `An error occurred in the WebSocket pool's dedupeHandler: ${error instanceof Error ? error.message : String(error)}`;
-                    throw new Error(errMsg);
+                    pool.emitPoolError(error, "Error in WebSocketPool dedupeHandler");
                 });
             };
             pool.rwsPool.push(rws);
@@ -95,6 +106,21 @@ export class WebSocketPool {
         pool.logger.info(`At least one WebSocket connection is established. WebSocketPool is ready.`);
         return pool;
     }
+    emitPoolError(error, context) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (context) {
+            this.logger.error(context, err);
+        } else {
+            this.logger.error("WebSocketPool error", err);
+        }
+        for (const errHandler of this.getListeners("error")){
+            try {
+                errHandler(err);
+            } catch (handlerError) {
+                this.logger.error("WebSocketPool error handler threw", handlerError);
+            }
+        }
+    }
     /**
    * Checks for error responses in JSON messages and throws appropriate errors
    */ handleErrorMessages(data) {
@@ -123,16 +149,25 @@ export class WebSocketPool {
         if (typeof data === "string") {
             this.handleErrorMessages(data);
         }
-        await Promise.all(this.messageListeners.map((handler)=>handler(data)));
+        try {
+            await Promise.all(this.messageListeners.map((handler)=>handler(data)));
+        } catch (error) {
+            this.emitPoolError(error, "Error in WebSocketPool message handler");
+        }
     };
     sendRequest(request) {
         for (const rws of this.rwsPool){
-            rws.send(JSON.stringify(request));
+            try {
+                rws.send(JSON.stringify(request));
+            } catch (error) {
+                this.emitPoolError(error, "Failed to send WebSocket request");
+            }
         }
     }
     addSubscription(request) {
         if (request.type !== "subscribe") {
-            throw new Error("Request must be a subscribe request");
+            this.emitPoolError(new Error("Request must be a subscribe request"));
+            return;
         }
         this.subscriptions.set(request.subscriptionId, request);
         this.sendRequest(request);
@@ -168,7 +203,11 @@ export class WebSocketPool {
             this.logger.error("All WebSocket connections are down or reconnecting");
             // Notify all listeners
             for (const listener of this.allConnectionsDownListeners){
-                listener();
+                try {
+                    listener();
+                } catch (error) {
+                    this.emitPoolError(error, "All-connections-down listener threw");
+                }
             }
         }
         // If at least one connection was restored
@@ -185,5 +224,15 @@ export class WebSocketPool {
         this.messageListeners = [];
         this.allConnectionsDownListeners = [];
         clearInterval(this.checkConnectionStatesInterval);
+        // execute all bound shutdown handlers
+        for (const shutdownHandler of this.getListeners("shutdown")){
+            try {
+                shutdownHandler();
+            } catch (error) {
+                this.emitPoolError(error, "Shutdown handler threw");
+            }
+        }
+        // ensure any error handlers are removed to avoid leaks
+        this.off("error");
     }
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@pythnetwork/pyth-lazer-sdk",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "description": "Pyth Lazer SDK",
   "engines": {
-    "node": ">=22.14.0"
+    "node": "^24.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -34,6 +34,16 @@
         "default": "./dist/esm/constants.mjs"
       }
     },
+    "./emitter": {
+      "require": {
+        "types": "./dist/cjs/emitter/index.d.ts",
+        "default": "./dist/cjs/emitter/index.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/emitter/index.d.ts",
+        "default": "./dist/esm/emitter/index.mjs"
+      }
+    },
     ".": {
       "require": {
         "types": "./dist/cjs/index.d.ts",
@@ -119,6 +129,7 @@
   "devDependencies": {
     "@cprussin/eslint-config": "^4.0.2",
     "@cprussin/tsconfig": "^3.1.2",
+    "@types/jest": "^29.5.14",
     "@types/node": "^18.19.54",
     "@types/ws": "^8.5.12",
     "eslint": "^9.23.0",