@nktkas/hyperliquid 0.13.0

package/script/src/transports/websocket/reconnecting_websocket.js

@@ -0,0 +1,374 @@
+"use strict";
+// deno-lint-ignore-file no-explicit-any
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReconnectingWebSocket = void 0;
+/**
+ * Simple FIFO (First In, First Out) buffer implementation.
+ */
+class FIFOMessageBuffer {
+    constructor() {
+        Object.defineProperty(this, "messages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+    }
+    push(data) {
+        this.messages.push(data);
+    }
+    shift() {
+        return this.messages.shift();
+    }
+    clear() {
+        this.messages = [];
+    }
+}
+/**
+ * A WebSocket that automatically reconnects when disconnected.
+ * Fully compatible with standard WebSocket API.
+ */
+class ReconnectingWebSocket {
+    /**
+     * Creates a new reconnecting WebSocket.
+     * @param url - The WebSocket URL to connect to.
+     * @param protocols - The WebSocket protocols to use.
+     * @param options - The configuration options.
+     */
+    constructor(url, protocols, options) {
+        /** Controller for handling connection termination */
+        Object.defineProperty(this, "terminationController", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new AbortController()
+        });
+        /** WebSocket protocols */
+        Object.defineProperty(this, "protocols", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The underlying WebSocket instance */
+        Object.defineProperty(this, "socket", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Current number of reconnection attempts */
+        Object.defineProperty(this, "reconnectCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /** Array of registered event listeners */
+        Object.defineProperty(this, "eventListeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        /** Configuration options */
+        Object.defineProperty(this, "reconnectOptions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** An AbortSignal that is triggered when the connection is permanently closed */
+        Object.defineProperty(this, "terminationSignal", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: this.terminationController.signal
+        });
+        Object.defineProperty(this, "CLOSED", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: WebSocket.CLOSED
+        });
+        Object.defineProperty(this, "CLOSING", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: WebSocket.CLOSING
+        });
+        Object.defineProperty(this, "CONNECTING", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: WebSocket.CONNECTING
+        });
+        Object.defineProperty(this, "OPEN", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: WebSocket.OPEN
+        });
+        this.reconnectOptions = {
+            maxRetries: options?.maxRetries ?? 3,
+            connectionTimeout: options?.connectionTimeout === undefined ? 10_000 : options.connectionTimeout,
+            connectionDelay: options?.connectionDelay ?? ((attempt) => Math.min(~~(1 << attempt) * 150, 10_000)),
+            shouldReconnect: options?.shouldReconnect ?? (() => true),
+            messageBuffer: options?.messageBuffer ?? new FIFOMessageBuffer(),
+            WebSocketConstructor: options?.WebSocketConstructor ?? WebSocket,
+        };
+        this.protocols = protocols;
+        this.socket = this.reconnectOptions.connectionTimeout
+            ? this.connectWithTimeout(url, this.protocols, this.reconnectOptions.connectionTimeout)
+            : new this.reconnectOptions.WebSocketConstructor(url, this.protocols);
+        this.initEventListeners();
+    }
+    /**
+     * Creates a WebSocket connection with timeout.
+     * @param url - The WebSocket URL to connect to.
+     * @param protocols - The WebSocket protocols to use.
+     * @param timeout - The connection timeout in ms.
+     * @returns A new WebSocket instance.
+     */
+    connectWithTimeout(url, protocols, timeout) {
+        const socket = new this.reconnectOptions.WebSocketConstructor(url, protocols);
+        const timeoutId = setTimeout(() => {
+            socket.removeEventListener("open", openHandler);
+            socket.removeEventListener("close", closeHandler);
+            socket.close(3008, "Timeout"); // https://www.iana.org/assignments/websocket/websocket.xml#close-code-number
+        }, timeout);
+        const openHandler = () => {
+            socket.removeEventListener("close", closeHandler);
+            clearTimeout(timeoutId);
+        };
+        const closeHandler = () => {
+            socket.removeEventListener("open", openHandler);
+            clearTimeout(timeoutId);
+        };
+        socket.addEventListener("open", openHandler, { once: true });
+        socket.addEventListener("close", closeHandler, { once: true });
+        return socket;
+    }
+    /**
+     * Initializes the internal event listeners for the WebSocket.
+     */
+    initEventListeners() {
+        this.socket.addEventListener("open", () => {
+            // Reset reconnection count
+            this.reconnectCount = 0;
+            // Send all buffered messages
+            let message;
+            while ((message = this.reconnectOptions.messageBuffer.shift()) !== undefined) {
+                this.socket.send(message);
+            }
+        }, { once: true });
+        this.socket.addEventListener("close", async (event) => {
+            try {
+                // If the termination signal is already aborted, do not attempt to reconnect
+                if (this.terminationSignal.aborted)
+                    return;
+                // Check if reconnection should be attempted
+                if (++this.reconnectCount > this.reconnectOptions.maxRetries) {
+                    this.cleanup(new Error("RECONNECTION_LIMIT_REACHED", { cause: event }));
+                    return;
+                }
+                const userDecision = await this.reconnectOptions.shouldReconnect(event);
+                if (this.terminationSignal.aborted)
+                    return; // Check again after the await
+                if (!userDecision) {
+                    this.cleanup(new Error("RECONNECTION_STOPPED_BY_USER", { cause: event }));
+                    return;
+                }
+                // Delay before reconnecting
+                const delay = typeof this.reconnectOptions.connectionDelay === "number"
+                    ? this.reconnectOptions.connectionDelay
+                    : await this.reconnectOptions.connectionDelay(this.reconnectCount);
+                if (this.terminationSignal.aborted)
+                    return; // Check again after the await
+                await sleep(delay, this.terminationSignal);
+                // Reconnect the socket
+                this.socket = this.reconnectOptions.connectionTimeout
+                    ? this.connectWithTimeout(this.url, this.protocols, this.reconnectOptions.connectionTimeout)
+                    : new this.reconnectOptions.WebSocketConstructor(this.url, this.protocols);
+                // Reconnect all listeners
+                this.initEventListeners();
+                this.eventListeners.forEach(({ type, listenerProxy, options }) => {
+                    this.socket.addEventListener(type, listenerProxy, options);
+                });
+            }
+            catch (error) {
+                this.cleanup(new Error("RECONNECTION_ERROR", { cause: { error, event } }));
+            }
+        }, { once: true });
+    }
+    /**
+     * Clean up internal resources.
+     * @param reason - The reason for cleanup.
+     */
+    cleanup(reason) {
+        this.terminationController.abort(reason);
+        this.reconnectOptions.messageBuffer.clear();
+        this.eventListeners = [];
+    }
+    /**
+     * Check if two event listeners are the same (just like EventTarget).
+     * @param a - First event listener configuration.
+     * @param b - Second event listener configuration.
+     * @returns True if the listeners match.
+     */
+    isListenerMatch(a, b) {
+        const aCapture = Boolean(typeof a.options === "object" ? a.options.capture : a.options);
+        const bCapture = Boolean(typeof b.options === "object" ? b.options.capture : b.options);
+        return a.type === b.type && a.listener === b.listener && aCapture === bCapture;
+    }
+    // WebSocket property implementations
+    get url() {
+        return this.socket.url;
+    }
+    get readyState() {
+        return this.socket.readyState;
+    }
+    get bufferedAmount() {
+        return this.socket.bufferedAmount;
+    }
+    get extensions() {
+        return this.socket.extensions;
+    }
+    get protocol() {
+        return this.socket.protocol;
+    }
+    get binaryType() {
+        return this.socket.binaryType;
+    }
+    set binaryType(value) {
+        this.socket.binaryType = value;
+    }
+    get onclose() {
+        return this.socket.onclose;
+    }
+    set onclose(value) {
+        this.socket.onclose = value;
+    }
+    get onerror() {
+        return this.socket.onerror;
+    }
+    set onerror(value) {
+        this.socket.onerror = value;
+    }
+    get onmessage() {
+        return this.socket.onmessage;
+    }
+    set onmessage(value) {
+        this.socket.onmessage = value;
+    }
+    get onopen() {
+        return this.socket.onopen;
+    }
+    set onopen(value) {
+        this.socket.onopen = value;
+    }
+    /**
+     * @param permanently - If true, the connection will be permanently closed. Default is true.
+     */
+    close(code, reason, permanently = true) {
+        if (permanently)
+            this.cleanup(new Error("USER_INITIATED_CLOSE"));
+        this.socket.close(code, reason);
+    }
+    /**
+     * @note If the connection is not open, the data will be buffered and sent when the connection is established.
+     */
+    send(data) {
+        if (this.socket.readyState !== WebSocket.OPEN && !this.terminationSignal.aborted) {
+            this.reconnectOptions.messageBuffer.push(data);
+        }
+        else {
+            this.socket.send(data);
+        }
+    }
+    addEventListener(type, listener, options) {
+        // Check if the listener is already added
+        const exists = this.eventListeners.some((e) => this.isListenerMatch(e, { type, listener, options }));
+        if (exists)
+            return;
+        // Wrap the original listener to follow the once option when reconnecting
+        const listenerProxy = (event) => {
+            try {
+                if (typeof listener === "function") {
+                    listener.call(this, event);
+                }
+                else {
+                    listener.handleEvent(event);
+                }
+            }
+            finally {
+                if (typeof options === "object" && options.once === true) {
+                    const index = this.eventListeners.findIndex((e) => this.isListenerMatch(e, { type, listener, options }));
+                    if (index !== -1)
+                        this.eventListeners.splice(index, 1);
+                }
+            }
+        };
+        this.eventListeners.push({ type, listener, options, listenerProxy });
+        this.socket.addEventListener(type, listenerProxy, options);
+    }
+    removeEventListener(type, listener, options) {
+        const index = this.eventListeners.findIndex((e) => this.isListenerMatch(e, { type, listener, options }));
+        if (index !== -1) {
+            const { listenerProxy } = this.eventListeners[index];
+            this.socket.removeEventListener(type, listenerProxy, options);
+            this.eventListeners.splice(index, 1);
+        }
+    }
+    dispatchEvent(event) {
+        return this.socket.dispatchEvent(event);
+    }
+}
+exports.ReconnectingWebSocket = ReconnectingWebSocket;
+Object.defineProperty(ReconnectingWebSocket, "CLOSED", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: WebSocket.CLOSED
+});
+Object.defineProperty(ReconnectingWebSocket, "CLOSING", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: WebSocket.CLOSING
+});
+Object.defineProperty(ReconnectingWebSocket, "CONNECTING", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: WebSocket.CONNECTING
+});
+Object.defineProperty(ReconnectingWebSocket, "OPEN", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: WebSocket.OPEN
+});
+/**
+ * Returns a promise that resolves after the specified number of ms,
+ * or rejects as soon as the given signal is aborted.
+ * @param ms - The number of ms to sleep.
+ * @param signal - An optional abort signal.
+ * @returns A promise that resolves after the specified delay.
+ */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            return reject(signal.reason);
+        }
+        const onAbort = function () {
+            clearTimeout(timer);
+            reject(this.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/script/src/transports/websocket/websocket_request_dispatcher.d.ts

@@ -0,0 +1,63 @@
+import { TransportError } from "../base.js";
+import type { HyperliquidEventTarget } from "./hyperliquid_event_target.js";
+/**
+ * Error thrown when a WebSocket request fails:
+ * - When the WebSocket connection is closed
+ * - When the server responds with an error message
+ */
+export declare class WebSocketRequestError extends TransportError {
+    /**
+     * Creates a new WebSocket request error.
+     * @param message - The error message.
+     */
+    constructor(message: string);
+}
+/**
+ * Manages WebSocket requests to the Hyperliquid API.
+ * Handles request creation, sending, and mapping responses to their corresponding requests.
+ */
+export declare class WebSocketRequestDispatcher {
+    protected socket: WebSocket;
+    /** Last used request ID */
+    protected lastId: number;
+    /** Map of pending requests waiting for responses */
+    protected pending: Map<number | string, {
+        resolve: (value: unknown) => void;
+        reject: (reason: unknown) => void;
+    }>;
+    /**
+     * Creates a new WebSocket request dispatcher.
+     * @param socket - WebSocket connection instance for sending requests to the Hyperliquid WebSocket API
+     * @param hlEvents - Used to recognize Hyperliquid responses and match them with sent requests
+     */
+    constructor(socket: WebSocket, hlEvents: HyperliquidEventTarget);
+    /** Gets the next request ID */
+    protected get nextId(): number;
+    /**
+     * Sends a request to the Hyperliquid API.
+     * @param method - The method of websocket request.
+     * @param payload - The payload to send with the request.
+     * @param signal - An optional abort signal.
+     * @returns A promise that resolves with the parsed JSON response body.
+     */
+    request(method: "post" | "subscribe" | "unsubscribe", payload: unknown, signal?: AbortSignal): Promise<unknown>;
+    /**
+     * Resolves a pending request.
+     * @param id - A request ID or a stringified request.
+     * @param value - A resolution value.
+     */
+    protected resolve(id: number | string, value: unknown): void;
+    /**
+     * Rejects a pending request.
+     * @param id - A request ID or a stringified request.
+     * @param reason - A rejection reason.
+     */
+    protected reject(id: number | string, reason: unknown): void;
+    /**
+     * Normalizes a request object to an ID.
+     * @param value - A request object.
+     * @returns A stringified request.
+     */
+    static requestToId(value: unknown): string;
+}
+//# sourceMappingURL=websocket_request_dispatcher.d.ts.map

package/script/src/transports/websocket/websocket_request_dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_request_dispatcher.d.ts","sourceRoot":"","sources":["../../../../src/src/transports/websocket/websocket_request_dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,cAAc;IACrD;;;OAGG;gBACS,OAAO,EAAE,MAAM;CAI9B;AAED;;;GAGG;AACH,qBAAa,0BAA0B;IAevB,SAAS,CAAC,MAAM,EAAE,SAAS;IAdvC,2BAA2B;IAC3B,SAAS,CAAC,MAAM,EAAE,MAAM,CAAK;IAE7B,oDAAoD;IACpD,SAAS,CAAC,OAAO,EAAE,GAAG,CAClB,MAAM,GAAG,MAAM,EACf;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAC3E,CAAa;IAEd;;;;OAIG;gBACmB,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,sBAAsB;IAkDzE,+BAA+B;IAC/B,SAAS,KAAK,MAAM,IAAI,MAAM,CAE7B;IAED;;;;;;OAMG;IACH,OAAO,CACH,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,aAAa,EAC5C,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,OAAO,CAAC;IAkCnB;;;;OAIG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAK5D;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAK5D;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;CAK7C"}

package/script/src/transports/websocket/websocket_request_dispatcher.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketRequestDispatcher = exports.WebSocketRequestError = void 0;
+const base_js_1 = require("../base.js");
+/**
+ * Error thrown when a WebSocket request fails:
+ * - When the WebSocket connection is closed
+ * - When the server responds with an error message
+ */
+class WebSocketRequestError extends base_js_1.TransportError {
+    /**
+     * Creates a new WebSocket request error.
+     * @param message - The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "WebSocketRequestError";
+    }
+}
+exports.WebSocketRequestError = WebSocketRequestError;
+/**
+ * Manages WebSocket requests to the Hyperliquid API.
+ * Handles request creation, sending, and mapping responses to their corresponding requests.
+ */
+class WebSocketRequestDispatcher {
+    /**
+     * Creates a new WebSocket request dispatcher.
+     * @param socket - WebSocket connection instance for sending requests to the Hyperliquid WebSocket API
+     * @param hlEvents - Used to recognize Hyperliquid responses and match them with sent requests
+     */
+    constructor(socket, hlEvents) {
+        Object.defineProperty(this, "socket", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: socket
+        });
+        /** Last used request ID */
+        Object.defineProperty(this, "lastId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /** Map of pending requests waiting for responses */
+        Object.defineProperty(this, "pending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        // Monitor responses and match the pending request
+        hlEvents.addEventListener("subscriptionResponse", (event) => {
+            // Use a stringified request as an id
+            const id = WebSocketRequestDispatcher.requestToId(event.detail.subscription);
+            this.resolve(id, event.detail);
+        });
+        hlEvents.addEventListener("post", (event) => {
+            const data = event.detail.response.type === "info"
+                ? event.detail.response.payload.data
+                : event.detail.response.payload;
+            this.resolve(event.detail.id, data);
+        });
+        hlEvents.addEventListener("error", (event) => {
+            try {
+                // Error event doesn't have an id, use original request to match
+                const request = event.detail.match(/{.*}/)?.[0];
+                if (request) {
+                    const parsedRequest = JSON.parse(request);
+                    if ("id" in parsedRequest && typeof parsedRequest.id === "number") {
+                        // If a post request was sent, it is possible to get the id from the request
+                        this.reject(parsedRequest.id, new WebSocketRequestError(event.detail));
+                    }
+                    else if ("subscription" in parsedRequest &&
+                        typeof parsedRequest.subscription === "object" &&
+                        parsedRequest.subscription !== null) {
+                        // If a subscription/unsubscribe request was sent, use the request as an id
+                        const id = WebSocketRequestDispatcher.requestToId(parsedRequest.subscription);
+                        this.reject(id, new WebSocketRequestError(event.detail));
+                    }
+                    else {
+                        // If the request is not recognized, use the parsed request as an id
+                        const id = WebSocketRequestDispatcher.requestToId(parsedRequest);
+                        this.reject(id, new WebSocketRequestError(event.detail));
+                    }
+                }
+            }
+            catch {
+                // Ignore JSON parsing errors
+            }
+        });
+        // Throws all pending requests if the connection is dropped
+        socket.addEventListener("close", () => {
+            this.pending.forEach(({ reject }) => {
+                reject(new WebSocketRequestError("The WebSocket connection has been closed."));
+            });
+            this.pending.clear();
+        });
+    }
+    /** Gets the next request ID */
+    get nextId() {
+        return ++this.lastId;
+    }
+    /**
+     * Sends a request to the Hyperliquid API.
+     * @param method - The method of websocket request.
+     * @param payload - The payload to send with the request.
+     * @param signal - An optional abort signal.
+     * @returns A promise that resolves with the parsed JSON response body.
+     */
+    request(method, payload, signal) {
+        signal?.throwIfAborted();
+        // Create a request object
+        let id;
+        let request;
+        if (method === "post") {
+            id = this.nextId;
+            request = { method, id, request: payload };
+        }
+        else {
+            id = WebSocketRequestDispatcher.requestToId(payload);
+            request = { method, subscription: payload };
+        }
+        // Send the request
+        this.socket.send(JSON.stringify(request));
+        // Wait for a response
+        let onAbort;
+        return new Promise((resolve, reject) => {
+            // Add an abort listener
+            onAbort = () => reject(signal?.reason);
+            signal?.addEventListener("abort", onAbort, { once: true });
+            // Add the promise to the pending list
+            this.pending.set(id, { resolve, reject });
+        }).finally(() => {
+            // Remove the abort listener when the promise is settled
+            signal?.removeEventListener("abort", onAbort);
+        });
+    }
+    /**
+     * Resolves a pending request.
+     * @param id - A request ID or a stringified request.
+     * @param value - A resolution value.
+     */
+    resolve(id, value) {
+        this.pending.get(id)?.resolve(value);
+        this.pending.delete(id);
+    }
+    /**
+     * Rejects a pending request.
+     * @param id - A request ID or a stringified request.
+     * @param reason - A rejection reason.
+     */
+    reject(id, reason) {
+        this.pending.get(id)?.reject(reason);
+        this.pending.delete(id);
+    }
+    /**
+     * Normalizes a request object to an ID.
+     * @param value - A request object.
+     * @returns A stringified request.
+     */
+    static requestToId(value) {
+        const lowerHex = deepLowerHex(value);
+        const sorted = deepSortKeys(lowerHex);
+        return JSON.stringify(sorted);
+    }
+}
+exports.WebSocketRequestDispatcher = WebSocketRequestDispatcher;
+/**
+ * Convert all hexadecimal strings to lowercase in an object/array.
+ * @param obj - The object/array to convert hexadecimal strings to lowercase.
+ * @returns A new object/array with hexadecimal strings converted to lowercase.
+ */
+function deepLowerHex(obj) {
+    if (Array.isArray(obj)) {
+        return obj.map(deepLowerHex);
+    }
+    else if (obj && typeof obj === "object") {
+        return Object.entries(obj).reduce((acc, [key, val]) => ({
+            ...acc,
+            [key]: deepLowerHex(val),
+        }), {});
+    }
+    else if (typeof obj === "string" && /^0x[0-9A-Fa-f]+$/.test(obj)) {
+        return obj.toLowerCase();
+    }
+    else {
+        return obj;
+    }
+}
+/**
+ * Deeply sort the keys of an object.
+ * @param obj - An object to sort the keys of.
+ * @returns A new object with sorted keys.
+ */
+function deepSortKeys(obj) {
+    if (obj === null || typeof obj !== "object") {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(deepSortKeys);
+    }
+    return Object.fromEntries(Object.entries(obj)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => [k, deepSortKeys(v)]));
+}