@pythnetwork/pyth-lazer-sdk 5.0.0 → 5.2.1

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

@@ -0,0 +1,238 @@
+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 extends IsomorphicEventEmitter {
+    logger;
+    rwsPool;
+    cache;
+    subscriptions;
+    messageListeners;
+    allConnectionsDownListeners;
+    wasAllDown = true;
+    checkConnectionStatesInterval;
+    constructor(logger){
+        super(), this.logger = logger;
+        this.rwsPool = [];
+        this.cache = new TTLCache({
+            ttl: 1000 * 10
+        }); // TTL of 10 seconds
+        this.subscriptions = new Map();
+        this.messageListeners = [];
+        this.allConnectionsDownListeners = [];
+        // Start monitoring connection states
+        this.checkConnectionStatesInterval = setInterval(()=>{
+            this.checkConnectionStates();
+        }, 100);
+    }
+    /**
+   * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
+   * Usage semantics are similar to using a regular WebSocket client.
+   * @param urls - List of WebSocket URLs to connect to
+   * @param token - Authentication token to use for the connections
+   * @param numConnections - Number of parallel WebSocket connections to maintain (default: 3)
+   * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
+   */ static async create(config, token, logger) {
+        const urls = config.urls ?? [
+            DEFAULT_STREAM_SERVICE_0_URL,
+            DEFAULT_STREAM_SERVICE_1_URL
+        ];
+        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();
+            const url = isBrowser ? addAuthTokenToWebSocketUrl(baseUrl, token) : baseUrl;
+            if (!url) {
+                throw new Error(`URLs must not be null or empty`);
+            }
+            const wsOptions = {
+                ...config.rwsConfig?.wsOptions,
+                headers: isBrowser ? undefined : {
+                    Authorization: `Bearer ${token}`
+                }
+            };
+            const rws = new ResilientWebSocket({
+                ...config.rwsConfig,
+                endpoint: url,
+                wsOptions,
+                logger: log
+            });
+            // If a websocket client unexpectedly disconnects, ResilientWebSocket will reestablish
+            // the connection and call the onReconnect callback.
+            rws.onReconnect = ()=>{
+                if (rws.wsUserClosed) {
+                    return;
+                }
+                for (const [, request] of pool.subscriptions){
+                    try {
+                        rws.send(JSON.stringify(request));
+                    } catch (error) {
+                        pool.logger.error("Failed to resend subscription on reconnect:", error);
+                    }
+                }
+            };
+            // 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)=>{
+                    pool.emitPoolError(error, "Error in WebSocketPool dedupeHandler");
+                });
+            };
+            pool.rwsPool.push(rws);
+            rws.startWebSocket();
+        }
+        pool.logger.info(`Started WebSocketPool with ${numConnections.toString()} connections. Waiting for at least one to connect...`);
+        while(!pool.isAnyConnectionEstablished()){
+            await new Promise((resolve)=>setTimeout(resolve, 100));
+        }
+        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) {
+        const message = JSON.parse(data);
+        if (message.type === "subscriptionError") {
+            throw new Error(`Error occurred for subscription ID ${String(message.subscriptionId)}: ${message.error}`);
+        } else if (message.type === "error") {
+            throw new Error(`Error: ${message.error}`);
+        }
+    }
+    async constructCacheKeyFromWebsocketData(data) {
+        if (typeof data === "string") return data;
+        const buff = await bufferFromWebsocketData(data);
+        return buff.toString("hex");
+    }
+    /**
+   * Handles incoming websocket messages by deduplicating identical messages received across
+   * multiple connections before forwarding to registered handlers
+   */ dedupeHandler = async (data)=>{
+        const cacheKey = await this.constructCacheKeyFromWebsocketData(data);
+        if (this.cache.has(cacheKey)) {
+            this.logger.debug("Dropping duplicate message");
+            return;
+        }
+        this.cache.set(cacheKey, true);
+        if (typeof data === "string") {
+            this.handleErrorMessages(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){
+            try {
+                rws.send(JSON.stringify(request));
+            } catch (error) {
+                this.emitPoolError(error, "Failed to send WebSocket request");
+            }
+        }
+    }
+    addSubscription(request) {
+        if (request.type !== "subscribe") {
+            this.emitPoolError(new Error("Request must be a subscribe request"));
+            return;
+        }
+        this.subscriptions.set(request.subscriptionId, request);
+        this.sendRequest(request);
+    }
+    removeSubscription(subscriptionId) {
+        this.subscriptions.delete(subscriptionId);
+        const request = {
+            type: "unsubscribe",
+            subscriptionId
+        };
+        this.sendRequest(request);
+    }
+    addMessageListener(handler) {
+        this.messageListeners.push(handler);
+    }
+    /**
+   * Calls the handler if all websocket connections are currently down or in reconnecting state.
+   * The connections may still try to reconnect in the background.
+   */ addAllConnectionsDownListener(handler) {
+        this.allConnectionsDownListeners.push(handler);
+    }
+    areAllConnectionsDown() {
+        return this.rwsPool.every((ws)=>!ws.isConnected() || ws.isReconnecting());
+    }
+    isAnyConnectionEstablished() {
+        return this.rwsPool.some((ws)=>ws.isConnected());
+    }
+    checkConnectionStates() {
+        const allDown = this.areAllConnectionsDown();
+        // If all connections just went down
+        if (allDown && !this.wasAllDown) {
+            this.wasAllDown = true;
+            this.logger.error("All WebSocket connections are down or reconnecting");
+            // Notify all listeners
+            for (const listener of this.allConnectionsDownListeners){
+                try {
+                    listener();
+                } catch (error) {
+                    this.emitPoolError(error, "All-connections-down listener threw");
+                }
+            }
+        }
+        // If at least one connection was restored
+        if (!allDown && this.wasAllDown) {
+            this.wasAllDown = false;
+        }
+    }
+    shutdown() {
+        for (const rws of this.rwsPool){
+            rws.closeWebSocket();
+        }
+        this.rwsPool = [];
+        this.subscriptions.clear();
+        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/esm/util/{buffer-util.js → buffer-util.mjs}

@@ -8,19 +8,16 @@ const BufferClassToUse = "Buffer" in globalThis ? globalThis.Buffer : BrowserBuf
  * given a relatively unknown websocket frame data object,
  * returns a valid Buffer instance that is safe to use
  * isomorphically in any JS runtime environment
- */
-export async function bufferFromWebsocketData(data) {
+ */ export async function bufferFromWebsocketData(data) {
     if (typeof data === "string") {
         return BufferClassToUse.from(new TextEncoder().encode(data).buffer);
     }
-    if (data instanceof BufferClassToUse)
-        return data;
+    if (data instanceof BufferClassToUse) return data;
     if (data instanceof Blob) {
         // let the uncaught promise exception bubble up if there's an issue
         return BufferClassToUse.from(await data.arrayBuffer());
     }
-    if (data instanceof ArrayBuffer)
-        return BufferClassToUse.from(data);
+    if (data instanceof ArrayBuffer) return BufferClassToUse.from(data);
     if (Array.isArray(data)) {
         // an array of buffers is highly unlikely, but it is a possibility
         // indicated by the WebSocket Data interface

package/dist/esm/util/{env-util.js → env-util.mjs}

@@ -4,16 +4,13 @@ const g = globalThis;
 /**
  * Detects if this code is running within any Service or WebWorker context.
  * @returns true if in a worker of some kind, false if otherwise
- */
-export function envIsServiceOrWebWorker() {
-    return (typeof WorkerGlobalScope !== "undefined" &&
-        g.self instanceof WorkerGlobalScope);
+ */ export function envIsServiceOrWebWorker() {
+    return typeof WorkerGlobalScope !== "undefined" && g.self instanceof WorkerGlobalScope;
 }
 /**
  * Detects if the code is running in a regular DOM or Web Worker context.
  * @returns true if running in a DOM or Web Worker context, false if running in Node.js
- */
-export function envIsBrowser() {
+ */ export function envIsBrowser() {
     return g.window !== undefined;
 }
 /**
@@ -21,7 +18,6 @@ export function envIsBrowser() {
  * this code is executing in some type of browser-centric environment
  *
  * @returns true if in the browser's main UI thread or in a worker, false if otherwise
- */
-export function envIsBrowserOrWorker() {
+ */ export function envIsBrowserOrWorker() {
     return envIsServiceOrWebWorker() || envIsBrowser();
 }

package/dist/esm/util/index.mjs

@@ -0,0 +1,3 @@
+export * from "./buffer-util.mjs";
+export * from "./env-util.mjs";
+export * from "./url-util.mjs";

package/dist/esm/util/{url-util.js → url-util.mjs}

@@ -5,10 +5,8 @@ const ACCESS_TOKEN_QUERY_PARAM_KEY = "ACCESS_TOKEN";
  * contained within.
  * If the URL provided is nullish, it is returned as-is (in the same nullish format).
  * If the token is nullish, the baseUrl given is returned, instead.
- */
-export function addAuthTokenToWebSocketUrl(baseUrl, authToken) {
-    if (!baseUrl || !authToken)
-        return baseUrl;
+ */ export function addAuthTokenToWebSocketUrl(baseUrl, authToken) {
+    if (!baseUrl || !authToken) return baseUrl;
     const parsedUrl = new URL(baseUrl);
     parsedUrl.searchParams.set(ACCESS_TOKEN_QUERY_PARAM_KEY, authToken);
     return parsedUrl.toString();

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@pythnetwork/pyth-lazer-sdk",
-  "version": "5.0.0",
+  "version": "5.2.1",
   "description": "Pyth Lazer SDK",
   "engines": {
-    "node": ">=22"
+    "node": "^24.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -11,28 +11,131 @@
   "files": [
     "dist/**/*"
   ],
-  "main": "./dist/cjs/index.js",
+  "main": "./dist/cjs/index.cjs",
   "types": "./dist/cjs/index.d.ts",
   "exports": {
-    "import": {
-      "types": "./dist/esm/index.d.ts",
-      "default": "./dist/esm/index.js"
+    "./client": {
+      "require": {
+        "types": "./dist/cjs/client.d.ts",
+        "default": "./dist/cjs/client.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/client.d.ts",
+        "default": "./dist/esm/client.mjs"
+      }
     },
-    "require": {
-      "types": "./dist/cjs/index.d.ts",
-      "default": "./dist/cjs/index.js"
-    }
+    "./constants": {
+      "require": {
+        "types": "./dist/cjs/constants.d.ts",
+        "default": "./dist/cjs/constants.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/constants.d.ts",
+        "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",
+        "default": "./dist/cjs/index.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.mjs"
+      }
+    },
+    "./protocol": {
+      "require": {
+        "types": "./dist/cjs/protocol.d.ts",
+        "default": "./dist/cjs/protocol.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/protocol.d.ts",
+        "default": "./dist/esm/protocol.mjs"
+      }
+    },
+    "./socket/resilient-websocket": {
+      "require": {
+        "types": "./dist/cjs/socket/resilient-websocket.d.ts",
+        "default": "./dist/cjs/socket/resilient-websocket.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/socket/resilient-websocket.d.ts",
+        "default": "./dist/esm/socket/resilient-websocket.mjs"
+      }
+    },
+    "./socket/websocket-pool": {
+      "require": {
+        "types": "./dist/cjs/socket/websocket-pool.d.ts",
+        "default": "./dist/cjs/socket/websocket-pool.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/socket/websocket-pool.d.ts",
+        "default": "./dist/esm/socket/websocket-pool.mjs"
+      }
+    },
+    "./util/buffer-util": {
+      "require": {
+        "types": "./dist/cjs/util/buffer-util.d.ts",
+        "default": "./dist/cjs/util/buffer-util.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/util/buffer-util.d.ts",
+        "default": "./dist/esm/util/buffer-util.mjs"
+      }
+    },
+    "./util/env-util": {
+      "require": {
+        "types": "./dist/cjs/util/env-util.d.ts",
+        "default": "./dist/cjs/util/env-util.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/util/env-util.d.ts",
+        "default": "./dist/esm/util/env-util.mjs"
+      }
+    },
+    "./util": {
+      "require": {
+        "types": "./dist/cjs/util/index.d.ts",
+        "default": "./dist/cjs/util/index.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/util/index.d.ts",
+        "default": "./dist/esm/util/index.mjs"
+      }
+    },
+    "./util/url-util": {
+      "require": {
+        "types": "./dist/cjs/util/url-util.d.ts",
+        "default": "./dist/cjs/util/url-util.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/util/url-util.d.ts",
+        "default": "./dist/esm/util/url-util.mjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "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",
     "prettier": "^3.5.3",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.26.8",
-    "typescript": "^5.8.2"
+    "typedoc": "^0.26.8"
   },
   "bugs": {
     "url": "https://github.com/pyth-network/pyth-crosschain/issues"
@@ -56,9 +159,9 @@
     "ts-log": "^2.2.7",
     "ws": "^8.18.0"
   },
+  "module": "./dist/esm/index.mjs",
   "scripts": {
-    "build:cjs": "tsc --project tsconfig.build.json --verbatimModuleSyntax false --module commonjs --outDir ./dist/cjs && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
-    "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "build": "ts-duality --clean",
     "fix:lint": "eslint --fix . --max-warnings 0",
     "test:lint": "eslint . --max-warnings 0",
     "test:types": "tsc",
@@ -67,6 +170,7 @@
     "example:streaming": "node --loader ts-node/esm examples/streaming.js",
     "example:history": "node --loader ts-node/esm examples/history.js",
     "example:symbols": "node --loader ts-node/esm examples/symbols.js",
-    "doc": "typedoc --out docs/typedoc src"
+    "doc": "typedoc --out docs/typedoc src",
+    "clean": "rm -rf ./dist"
   }
 }

package/dist/cjs/constants.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_STREAM_SERVICE_1_URL = exports.DEFAULT_STREAM_SERVICE_0_URL = exports.DEFAULT_PRICE_SERVICE_URL = exports.DEFAULT_METADATA_SERVICE_URL = exports.SOLANA_LAZER_STORAGE_ID = exports.SOLANA_LAZER_PROGRAM_ID = void 0;
-exports.SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt";
-exports.SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
-exports.DEFAULT_METADATA_SERVICE_URL = "https://history.pyth-lazer.dourolabs.app/history";
-exports.DEFAULT_PRICE_SERVICE_URL = "https://pyth-lazer-0.dourolabs.app";
-exports.DEFAULT_STREAM_SERVICE_0_URL = "wss://pyth-lazer-0.dourolabs.app/v1/stream";
-exports.DEFAULT_STREAM_SERVICE_1_URL = "wss://pyth-lazer-1.dourolabs.app/v1/stream";

package/dist/cjs/index.js

@@ -1,19 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./client.js"), exports);
-__exportStar(require("./protocol.js"), exports);
-__exportStar(require("./constants.js"), exports);

package/dist/cjs/protocol.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CustomSocketClosureCodes = exports.FORMAT_MAGICS_LE = exports.BINARY_UPDATE_FORMAT_MAGIC_LE = void 0;
-exports.BINARY_UPDATE_FORMAT_MAGIC_LE = 461_928_307;
-exports.FORMAT_MAGICS_LE = {
-    JSON: 3_302_625_434,
-    EVM: 2_593_727_018,
-    SOLANA: 2_182_742_457,
-    LE_ECDSA: 1_296_547_300,
-    LE_UNSIGNED: 1_499_680_012,
-};
-var CustomSocketClosureCodes;
-(function (CustomSocketClosureCodes) {
-    CustomSocketClosureCodes[CustomSocketClosureCodes["CLIENT_TIMEOUT_BUT_RECONNECTING"] = 4000] = "CLIENT_TIMEOUT_BUT_RECONNECTING";
-})(CustomSocketClosureCodes || (exports.CustomSocketClosureCodes = CustomSocketClosureCodes = {}));