@hfunlabs/hyperliquid 0.27.1 → 0.30.0-hfunlabs.1

package/src/src/transport/websocket/mod.ts

@@ -1,12 +1,33 @@
-import { type IRequestTransport, type ISubscriptionTransport, type Subscription, TransportError } from "../base.js";
+/**
+ * WebSocket transport for {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | subscriptions} and {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests | POST requests}.
+ *
+ * Use {@link WebSocketTransport} for real-time subscriptions and for lower-latency API requests.
+ *
+ * @example Subscriptions
+ * ```ts
+ * import { SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";
+ *
+ * const transport = new WebSocketTransport();
+ * const client = new SubscriptionClient({ transport });
+ *
+ * const subscription = await client.allMids((data) => {
+ *   console.log(data.mids);
+ * });
+ *
+ * await subscription.unsubscribe();
+ * ```
+ *
+ * @module
+ */
+
+import type { IRequestTransport, ISubscription, ISubscriptionTransport } from "../_base.js";
 import { AbortSignal_ } from "../_polyfills.js";
-import { ReconnectingWebSocket, ReconnectingWebSocketError, type ReconnectingWebSocketOptions } from "@nktkas/rews";
-import { HyperliquidEventTarget } from "./_hyperliquid_event_target.js";
-import { WebSocketAsyncRequest, WebSocketRequestError } from "./_websocket_async_request.js";
+import { ReconnectingWebSocket, type ReconnectingWebSocketOptions } from "@nktkas/rews";
+import { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
+import { WebSocketPostRequest, WebSocketRequestError } from "./_postRequest.js";
+import { WebSocketSubscriptionManager } from "./_subscriptionManager.js";
 
-export { ReconnectingWebSocketError, WebSocketRequestError };
-
-type MaybePromise<T> = T | Promise<T>;
+export { WebSocketRequestError };
 
 /** Configuration options for the WebSocket transport layer. */
 export interface WebSocketTransportOptions {
@@ -27,17 +48,10 @@ export interface WebSocketTransportOptions {
    */
   url?: string | URL;
   /**
-   * Timeout for requests in ms.
-   * Set to `null` to disable.
+   * Timeout for requests in ms. Set to `null` to disable.
    * @default 10_000
    */
   timeout?: number | null;
-  /**
-   * Interval between sending ping messages in ms.
-   * Set to `null` to disable.
-   * @default 30_000
-   */
-  keepAliveInterval?: number | null;
   /** Reconnection policy configuration for closed connections. */
   reconnect?: ReconnectingWebSocketOptions;
   /**
@@ -45,275 +59,154 @@ export interface WebSocketTransportOptions {
    * @default true
    */
   resubscribe?: boolean;
-  onRequest?: (type: string, payload: unknown) => MaybePromise<unknown | void | null | undefined>;
-  onResponse?: (response: unknown) => MaybePromise<unknown | void | null | undefined>;
-  onError?: (error: unknown) => MaybePromise<Error | void | null | undefined>;
 }
 
-/** WebSocket implementation of the REST and Subscription transport interfaces. */
+/** Mainnet API WebSocket URL. */
+export const MAINNET_API_WS_URL = "wss://api.hyperliquid.xyz/ws";
+/** Testnet API WebSocket URL. */
+export const TESTNET_API_WS_URL = "wss://api.hyperliquid-testnet.xyz/ws";
+/** Mainnet RPC WebSocket URL. */
+export const MAINNET_RPC_WS_URL = "wss://rpc.hyperliquid.xyz/ws";
+/** Testnet RPC WebSocket URL. */
+export const TESTNET_RPC_WS_URL = "wss://rpc.hyperliquid-testnet.xyz/ws";
+
+/**
+ * WebSocket transport for Hyperliquid API.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests
+ */
 export class WebSocketTransport implements IRequestTransport, ISubscriptionTransport {
-  protected _wsRequester: WebSocketAsyncRequest;
-  protected _hlEvents: HyperliquidEventTarget;
-  protected _keepAliveTimeout: ReturnType<typeof setTimeout> | undefined;
-  protected _subscriptions: Map<
-    string, // Unique identifier based on the payload
-    {
-      listeners: Map<
-        (data: CustomEvent) => void, // Event listener function
-        () => Promise<void> // Unsubscribe function
-      >;
-      promise: Promise<unknown>; // Subscription request promise
-      promiseFinished: boolean;
-      resubscribeAbortController: AbortController; // To monitor reconnection errors
-    }
-  > = new Map();
-
   /** Indicates this transport uses testnet endpoint. */
   readonly isTestnet: boolean;
-  /**
-   * Timeout for requests in ms.
-   * Set to `null` to disable.
-   */
-  timeout: number | null;
-  /**
-   * Interval between sending ping messages in ms.
-   * Set to `null` to disable.
-   */
-  keepAliveInterval: number | null;
-  /** Enable automatic re-subscription to Hyperliquid subscription after reconnection. */
-  resubscribe: boolean;
-
   /** The WebSocket that is used for communication. */
   readonly socket: ReconnectingWebSocket;
+  /** Enable automatic re-subscription to Hyperliquid subscription after reconnection. */
+  get resubscribe(): boolean {
+    return this._subscriptionManager.resubscribe;
+  }
+  set resubscribe(value: boolean) {
+    this._subscriptionManager.resubscribe = value;
+  }
+  /** Timeout for requests in ms. Set to `null` to disable. */
+  get timeout(): number | null {
+    return this._postRequest.timeout;
+  }
+  set timeout(value: number | null) {
+    this._postRequest.timeout = value;
+  }
+
+  protected _postRequest: WebSocketPostRequest;
+  protected _hlEvents: HyperliquidEventTarget;
+  protected _subscriptionManager: WebSocketSubscriptionManager;
+  protected _keepAliveInterval: ReturnType<typeof setInterval> | undefined;
 
   /**
    * Creates a new WebSocket transport instance.
+   *
    * @param options - Configuration options for the WebSocket transport layer.
    */
   constructor(options?: WebSocketTransportOptions) {
     this.isTestnet = options?.isTestnet ?? false;
-    this.timeout = options?.timeout === undefined ? 10_000 : options.timeout;
-    this.keepAliveInterval = options?.keepAliveInterval ?? 30_000;
-    this.resubscribe = options?.resubscribe ?? true;
 
     this.socket = new ReconnectingWebSocket(
-      options?.url ?? (this.isTestnet ? "wss://api.hyperliquid-testnet.xyz/ws" : "wss://api.hyperliquid.xyz/ws"),
+      options?.url ?? (this.isTestnet ? TESTNET_API_WS_URL : MAINNET_API_WS_URL),
       options?.reconnect,
     );
 
     this._hlEvents = new HyperliquidEventTarget(this.socket);
-    this._wsRequester = new WebSocketAsyncRequest(this.socket, this._hlEvents);
-
-    // Initialize listeners
-    this.socket.addEventListener("open", () => {
-      this._keepAliveRun();
-      this._resubscribeRun();
-    });
-    const handleClose = () => {
-      this._keepAliveStop();
-      this._resubscribeStop();
-    };
-    this.socket.addEventListener("close", handleClose);
-    this.socket.addEventListener("error", handleClose);
-  }
-
-  /**
-   * Keep the connection alive.
-   * Sends ping only when no other requests were sent within the keep-alive interval.
-   */
-  protected _keepAliveRun(): void {
-    if (this.keepAliveInterval === null || this._keepAliveTimeout) return;
-
-    const tick = async () => {
-      if (
-        this.socket.readyState !== ReconnectingWebSocket.OPEN || !this._keepAliveTimeout ||
-        this.keepAliveInterval === null
-      ) return;
-
-      // Check if the last request was sent more than the keep-alive interval ago
-      if (Date.now() - this._wsRequester.lastRequestTime >= this.keepAliveInterval) {
-        const timeoutSignal = this.timeout ? AbortSignal_.timeout(this.keepAliveInterval) : undefined;
-        await this._wsRequester.request("ping", timeoutSignal)
-          .catch(() => undefined); // Ignore errors
-      }
-
-      // Schedule the next ping
-      if (
-        this.socket.readyState === ReconnectingWebSocket.OPEN && this._keepAliveTimeout &&
-        this.keepAliveInterval !== null
-      ) {
-        const nextDelay = this.keepAliveInterval - (Date.now() - this._wsRequester.lastRequestTime);
-        this._keepAliveTimeout = setTimeout(tick, nextDelay);
-      }
-    };
+    this._postRequest = new WebSocketPostRequest(
+      this.socket,
+      this._hlEvents,
+      options?.timeout === undefined ? 10_000 : options.timeout,
+    );
+    this._subscriptionManager = new WebSocketSubscriptionManager(
+      this.socket,
+      this._postRequest,
+      this._hlEvents,
+      options?.resubscribe ?? true,
+    );
 
-    this._keepAliveTimeout = setTimeout(tick, this.keepAliveInterval);
-  }
-  protected _keepAliveStop(): void {
-    clearTimeout(this._keepAliveTimeout);
-    this._keepAliveTimeout = undefined;
+    this._initKeepAlive();
   }
 
-  /** Resubscribe to all existing subscriptions if auto-resubscribe is enabled. */
-  protected _resubscribeRun(): void {
-    if (this.resubscribe) {
-      for (const [id, subscription] of this._subscriptions.entries()) {
-        if (subscription.promiseFinished) { // reconnect only previously connected subscriptions to avoid double subscriptions due to message buffering.
-          subscription.promise = this._wsRequester.request("subscribe", JSON.parse(id))
-            .catch((error) => subscription.resubscribeAbortController.abort(error))
-            .finally(() => subscription.promiseFinished = true);
-          subscription.promiseFinished = false;
-        }
-      }
-    }
-  }
-  protected _resubscribeStop(): void {
-    if (!this.resubscribe || this.socket.terminationSignal.aborted) {
-      for (const subscriptionInfo of this._subscriptions.values()) {
-        for (const [_, unsubscribe] of subscriptionInfo.listeners) {
-          unsubscribe(); // does not cause an error if used when the connection is closed
-        }
-      }
-    }
-  }
+  // ============================================================
+  // Public methods
+  // ============================================================
 
   /**
    * Sends a request to the Hyperliquid API via WebSocket.
+   *
    * @param endpoint - The API endpoint to send the request to.
    * @param payload - The payload to send with the request.
-   * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+   *
    * @returns A promise that resolves with parsed JSON response body.
+   *
    * @throws {WebSocketRequestError} - An error that occurs when a WebSocket request fails.
    */
-  async request<T>(type: "info" | "exchange", payload: unknown, signal?: AbortSignal): Promise<T> {
-    try {
-      const timeoutSignal = this.timeout ? AbortSignal_.timeout(this.timeout) : undefined;
-      const combinedSignal = signal && timeoutSignal
-        ? AbortSignal_.any([signal, timeoutSignal])
-        : signal ?? timeoutSignal;
-
-      return await this._wsRequester.request(
-        "post",
-        { type: type === "exchange" ? "action" : type, payload },
-        combinedSignal,
-      );
-    } catch (error) {
-      if (error instanceof TransportError) throw error; // Re-throw known errors
-      throw new WebSocketRequestError(
-        `Unknown error while making a WebSocket request: ${error}`,
-        { cause: error },
-      );
-    }
+  async request<T>(endpoint: "info" | "exchange", payload: unknown, signal?: AbortSignal): Promise<T> {
+    const payload_ = { type: endpoint === "exchange" ? "action" : endpoint, payload };
+    return await this._postRequest.request<T>("post", payload_, signal);
   }
 
   /**
    * Subscribes to a Hyperliquid event channel.
    * Sends a subscription request to the server and listens for events.
+   *
    * @param channel - The event channel to listen to.
    * @param payload - A payload to send with the subscription request.
    * @param listener - A function to call when the event is dispatched.
-   * @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+   *
+   * @returns A promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+   *
    * @throws {WebSocketRequestError} - An error that occurs when a WebSocket request fails.
    */
-  async subscribe<T>(
+  subscribe<T>(
     channel: string,
     payload: unknown,
     listener: (data: CustomEvent<T>) => void,
-  ): Promise<Subscription> {
-    try {
-      // Create a unique identifier for the subscription
-      const id = WebSocketAsyncRequest.requestToId(payload);
-
-      // Initialize new subscription, if it doesn't exist
-      let subscription = this._subscriptions.get(id);
-      if (!subscription) {
-        // Send subscription request
-        const promise = this._wsRequester.request("subscribe", payload)
-          .finally(() => subscription!.promiseFinished = true);
-
-        // Cache subscription info
-        subscription = {
-          listeners: new Map(),
-          promise,
-          promiseFinished: false,
-          resubscribeAbortController: new AbortController(),
-        };
-        this._subscriptions.set(id, subscription);
-      }
-
-      // Initialize new listener, if it doesn't exist
-      let unsubscribe = subscription.listeners.get(listener);
-      if (!unsubscribe) {
-        // Create new unsubscribe function
-        unsubscribe = async () => {
-          try {
-            // Remove listener and cleanup
-            this._hlEvents.removeEventListener(channel, listener);
-            const subscription = this._subscriptions.get(id);
-            subscription?.listeners.delete(listener);
-
-            // If no listeners remain, remove subscription entirely
-            if (subscription?.listeners.size === 0) {
-              // Cleanup subscription
-              this._subscriptions.delete(id);
-
-              // If the socket is open, send unsubscription request
-              if (this.socket.readyState === ReconnectingWebSocket.OPEN) {
-                await this._wsRequester.request("unsubscribe", payload);
-              }
-            }
-          } catch (error) {
-            if (error instanceof TransportError) throw error; // Re-throw known errors
-            throw new WebSocketRequestError(
-              `Unknown error while unsubscribing from a WebSocket channel: ${error}`,
-              { cause: error },
-            );
-          }
-        };
-
-        // Add listener and cache unsubscribe function
-        this._hlEvents.addEventListener(channel, listener);
-        subscription.listeners.set(listener, unsubscribe);
-      }
-
-      // Wait for the initial subscription request to complete
-      await subscription.promise;
-
-      // Return subscription control object
-      return {
-        unsubscribe,
-        resubscribeSignal: subscription.resubscribeAbortController.signal,
-      };
-    } catch (error) {
-      if (error instanceof TransportError) throw error; // Re-throw known errors
-      throw new WebSocketRequestError(
-        `Unknown error while subscribing to a WebSocket channel: ${error}`,
-        { cause: error },
-      );
-    }
+  ): Promise<ISubscription> {
+    return this._subscriptionManager.subscribe(channel, payload, listener);
   }
 
   /**
    * Waits until the WebSocket connection is ready.
-   * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the promise by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+   *
+   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the promise.
+   *
    * @returns A promise that resolves when the connection is ready.
+   *
+   * @throws {WebSocketRequestError} When the connection cannot be established.
    */
   ready(signal?: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
+      // Combine the provided signal with the socket's termination signal
       const combinedSignal = signal
         ? AbortSignal_.any([this.socket.terminationSignal, signal])
         : this.socket.terminationSignal;
 
-      if (combinedSignal.aborted) return reject(combinedSignal.reason);
+      // Check if already aborted
+      if (combinedSignal.aborted) {
+        return reject(
+          new WebSocketRequestError("Failed to establish WebSocket connection", { cause: combinedSignal.reason }),
+        );
+      }
+
+      // Check if already open
       if (this.socket.readyState === ReconnectingWebSocket.OPEN) return resolve();
 
+      // Set up event listeners
       const handleOpen = () => {
         combinedSignal.removeEventListener("abort", handleAbort);
         resolve();
       };
       const handleAbort = () => {
         this.socket.removeEventListener("open", handleOpen);
-        reject(combinedSignal.reason);
+        return reject(
+          new WebSocketRequestError("Failed to establish WebSocket connection", { cause: combinedSignal.reason }),
+        );
       };
 
       this.socket.addEventListener("open", handleOpen, { once: true });
@@ -323,27 +216,63 @@ export class WebSocketTransport implements IRequestTransport, ISubscriptionTrans
 
   /**
    * Closes the WebSocket connection and waits until it is fully closed.
-   * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the promise by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+   *
+   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the promise.
+   *
    * @returns A promise that resolves when the connection is fully closed.
+   *
+   * @throws {WebSocketRequestError} When the connection cannot be closed.
    */
   close(signal?: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
-      if (signal?.aborted) return reject(signal.reason);
+      // Check if already aborted
+      if (signal?.aborted) {
+        return reject(
+          new WebSocketRequestError("Failed to close WebSocket connection", { cause: signal.reason }),
+        );
+      }
+
+      // Check if already closed
       if (this.socket.readyState === ReconnectingWebSocket.CLOSED) return resolve();
 
+      // Set up event listeners
       const handleClose = () => {
         signal?.removeEventListener("abort", handleAbort);
         resolve();
       };
       const handleAbort = () => {
-        reject(signal?.reason);
+        return reject(
+          new WebSocketRequestError("Failed to close WebSocket connection", { cause: signal?.reason }),
+        );
       };
 
       this.socket.addEventListener("close", handleClose, { once: true, signal });
       this.socket.addEventListener("error", handleClose, { once: true, signal });
       signal?.addEventListener("abort", handleAbort, { once: true });
 
+      // Initiate close
       this.socket.close();
     });
   }
+
+  // ============================================================
+  // Keep-Alive Logic
+  // ============================================================
+
+  protected _initKeepAlive(): void {
+    const start = () => {
+      if (this._keepAliveInterval) return;
+      this._keepAliveInterval = setInterval(() => {
+        this.socket.send('{"method":"ping"}');
+      }, 30_000);
+    };
+    const stop = () => {
+      clearInterval(this._keepAliveInterval);
+      this._keepAliveInterval = undefined;
+    };
+
+    this.socket.addEventListener("open", start);
+    this.socket.addEventListener("close", stop);
+    this.socket.addEventListener("error", stop);
+  }
 }

package/src/src/utils/_format.ts

@@ -3,42 +3,55 @@
  * - Maximum 5 significant figures
  * - Maximum 6 (for perp) or 8 (for spot) - `szDecimals` decimal places
  * - Integer prices are always allowed regardless of significant figures
+ *
+ * @param price - The price to format (as string or number).
+ * @param szDecimals - The size decimals of the asset.
+ * @param type - The market type: "perp" for perpetuals or "spot" for spot markets. Default is "perp".
+ *
+ * @throws {RangeError} If the formatted price is 0
+ *
  * @example
  * ```ts
  * import { formatPrice } from "@nktkas/hyperliquid/utils";
- *
- * //        `true` for perp (default), `false` for spot
- * //                                              ⌄⌄⌄⌄⌄
- * const price = formatPrice("0.0000123456789", 0, false); // → "0.00001234"
+ * const price = formatPrice("0.0000123456789", 0, "spot"); // → "0.00001234"
  * ```
  */
-export function formatPrice(price: string | number, szDecimals: number, isPerp: boolean = true): string {
+export function formatPrice(price: string | number, szDecimals: number, type: "perp" | "spot" = "perp"): string {
   price = price.toString().trim();
   assertNumberString(price);
 
   // Integer prices are always allowed
-  if (/^-?\d+$/.test(price)) return trimZeros(price);
+  if (/^-?\d+$/.test(price)) return formatDecimalString(price);
 
   // Apply decimal limit: max 6 (perp) or 8 (spot) - szDecimals
-  const maxDecimals = Math.max((isPerp ? 6 : 8) - szDecimals, 0);
+  const maxDecimals = Math.max((type === "perp" ? 6 : 8) - szDecimals, 0);
   price = StringMath.toFixedTruncate(price, maxDecimals);
 
   // Apply sig figs limit: max 5 significant figures
   price = StringMath.toPrecisionTruncate(price, 5);
 
+  if (price === "0") {
+    throw new RangeError("Price is too small and was truncated to 0");
+  }
+
   return price;
 }
 
 /**
  * Format size according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
  * - Truncate decimal places to `szDecimals`
+ *
+ * @param size - The size to format (as string or number).
+ * @param szDecimals - The size decimals of the asset.
+ *
+ * @throws {RangeError} If the formatted size is 0
+ *
  * @example
  * ```ts
  * import { formatSize } from "@nktkas/hyperliquid/utils";
  *
  * const size = formatSize("1.23456789", 5); // → "1.23456"
  * ```
- * @note May return 0 if the value is not suitable, but when closing a position, a size of 0 means the full size.
  */
 export function formatSize(size: string | number, szDecimals: number): string {
   size = size.toString().trim();
@@ -47,6 +60,10 @@ export function formatSize(size: string | number, szDecimals: number): string {
   // Apply decimal limit: szDecimals
   size = StringMath.toFixedTruncate(size, szDecimals);
 
+  if (size === "0") {
+    throw new RangeError("Size is too small and was truncated to 0");
+  }
+
   return size;
 }
 
@@ -76,7 +93,7 @@ const StringMath = {
   /** Multiply by 10^exp: shift decimal point left (negative) or right (positive) */
   multiplyByPow10(value: string, exp: number): string {
     if (!Number.isInteger(exp)) throw new RangeError("Exponent must be an integer");
-    if (exp === 0) return trimZeros(value);
+    if (exp === 0) return formatDecimalString(value);
 
     const neg = value[0] === "-";
     const abs = neg ? value.slice(1) : value;
@@ -103,7 +120,7 @@ const StringMath = {
       }
     }
 
-    return trimZeros((neg ? "-" : "") + result);
+    return formatDecimalString((neg ? "-" : "") + result);
   },
 
   /** Returns the integer part of a number by removing any fractional digits */
@@ -131,7 +148,7 @@ const StringMath = {
     const result = StringMath.multiplyByPow10(truncated, -shiftAmount);
 
     // build final result and trim zeros
-    return trimZeros(neg ? "-" + result : result);
+    return formatDecimalString(neg ? "-" + result : result);
   },
 
   /** Truncate to a certain number of decimal places */
@@ -148,12 +165,14 @@ const StringMath = {
     }
 
     // Trim zeros after truncation
-    return trimZeros(result);
+    return formatDecimalString(result);
   },
 };
 
-function trimZeros(value: string): string {
+function formatDecimalString(value: string): string {
   return value
+    // remove leading/trailing whitespace
+    .trim() // "  123.45  " → "123.45"
     // remove leading zeros
     .replace(/^(-?)0+(?=\d)/, "$1") // "00123" → "123", "-00.5" → "-0.5"
     // remove trailing zeros