@hfunlabs/hyperliquid 0.27.1-hfunlabs.5 → 0.29.1-hfunlabs.1

package/src/src/transport/websocket/_hyperliquidEventTarget.ts

@@ -0,0 +1,131 @@
+import * as v from "valibot";
+import { CustomEvent_ } from "../_polyfills.js";
+
+interface SubscribeUnsubscribeResponse {
+  method: "subscribe" | "unsubscribe";
+  /** Original subscription request payload. */
+  subscription: unknown;
+}
+
+interface PostResponse {
+  id: number;
+  response:
+    | {
+      type: "info";
+      payload: { type: string; data: unknown };
+    }
+    | {
+      type: "action";
+      payload: {
+        status: "ok" | "err";
+        response:
+          | { type: string; data?: unknown }
+          | string;
+      };
+    }
+    | {
+      type: "error";
+      /** Error message, e.g. "Cannot track more than 10 total users." */
+      payload: string;
+    };
+}
+
+interface BlockDetails {
+  blockTime: number;
+  hash: string;
+  height: number;
+  numTxs: number;
+  proposer: string;
+}
+
+interface TxDetails {
+  action: {
+    type: string;
+    [key: string]: unknown;
+  };
+  block: number;
+  error: string | null;
+  hash: string;
+  time: number;
+  user: string;
+}
+
+/** Base system events and dynamic channel events for Hyperliquid WebSocket API. */
+interface HyperliquidEventMap {
+  subscriptionResponse: CustomEvent<SubscribeUnsubscribeResponse>;
+  post: CustomEvent<PostResponse>;
+  error: CustomEvent<string>;
+  pong: CustomEvent<undefined>;
+  _explorerBlock: CustomEvent<BlockDetails[]>;
+  _explorerTxs: CustomEvent<TxDetails[]>;
+  // deno-lint-ignore no-explicit-any
+  [key: string]: CustomEvent<any>;
+}
+
+const BlockDetailsSchema = /* @__PURE__ */ (() => {
+  return v.looseObject({
+    blockTime: v.unknown(),
+    hash: v.unknown(),
+    height: v.unknown(),
+    numTxs: v.unknown(),
+    proposer: v.unknown(),
+  });
+})();
+const TxDetailsSchema = /* @__PURE__ */ (() => {
+  return v.looseObject({
+    action: v.unknown(),
+    block: v.unknown(),
+    error: v.unknown(),
+    hash: v.unknown(),
+    time: v.unknown(),
+    user: v.unknown(),
+  });
+})();
+const HyperliquidEventSchema = /* @__PURE__ */ (() => {
+  return v.object({ channel: v.string(), data: v.unknown() });
+})();
+const PongEventSchema = /* @__PURE__ */ (() => {
+  return v.object({ channel: v.literal("pong") });
+})();
+const ExplorerBlockEventSchema = /* @__PURE__ */ (() => {
+  return v.pipe(v.array(BlockDetailsSchema), v.minLength(1));
+})();
+const ExplorerTxsEventSchema = /* @__PURE__ */ (() => {
+  return v.pipe(v.array(TxDetailsSchema), v.minLength(1));
+})();
+
+/** Listens for WebSocket messages and sends them as Hyperliquid typed events. */
+export interface HyperliquidEventTarget {
+  addEventListener<K extends keyof HyperliquidEventMap>(
+    type: K,
+    listener: ((event: HyperliquidEventMap[K]) => void) | EventListenerObject | null,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  removeEventListener<K extends keyof HyperliquidEventMap>(
+    type: K,
+    listener: ((event: HyperliquidEventMap[K]) => void) | EventListenerObject | null,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  dispatchEvent(event: HyperliquidEventMap[keyof HyperliquidEventMap]): boolean;
+}
+export class HyperliquidEventTarget extends EventTarget {
+  constructor(socket: WebSocket) {
+    super();
+    socket.addEventListener("message", (event) => {
+      try {
+        const msg = JSON.parse(event.data);
+        if (v.is(HyperliquidEventSchema, msg)) {
+          this.dispatchEvent(new CustomEvent_(msg.channel, { detail: msg.data }));
+        } else if (v.is(PongEventSchema, msg)) {
+          this.dispatchEvent(new CustomEvent_("pong", { detail: undefined }));
+        } else if (v.is(ExplorerBlockEventSchema, msg)) {
+          this.dispatchEvent(new CustomEvent_("_explorerBlock", { detail: msg }));
+        } else if (v.is(ExplorerTxsEventSchema, msg)) {
+          this.dispatchEvent(new CustomEvent_("_explorerTxs", { detail: msg }));
+        }
+      } catch {
+        // Ignore JSON parsing errors
+      }
+    });
+  }
+}

package/src/src/transport/websocket/_postRequest.ts

@@ -0,0 +1,272 @@
+import { TransportError } from "../../_errors.js";
+import { Promise_ } from "../_polyfills.js";
+import type { ReconnectingWebSocket } from "@nktkas/rews";
+import type { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
+
+interface PostRequest {
+  method: "post";
+  id: number;
+  request: unknown;
+}
+interface SubscribeUnsubscribeRequest {
+  method: "subscribe" | "unsubscribe";
+  subscription: unknown;
+}
+interface PingRequest {
+  method: "ping";
+}
+
+interface PendingRequest {
+  id: number | string;
+  // deno-lint-ignore no-explicit-any
+  resolve: (value?: any) => void;
+  // deno-lint-ignore no-explicit-any
+  reject: (reason?: any) => void;
+}
+
+/** Error thrown when a WebSocket request fails. */
+export class WebSocketRequestError extends TransportError {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "WebSocketRequestError";
+  }
+}
+
+/**
+ * Manages WebSocket requests to the Hyperliquid API.
+ * Handles request creation, sending, and mapping responses to their corresponding requests.
+ */
+export class WebSocketAsyncRequest {
+  protected socket: ReconnectingWebSocket;
+  protected lastId = 0;
+  protected queue: PendingRequest[] = [];
+
+  /**
+   * Creates a new WebSocket async request handler.
+   * @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: ReconnectingWebSocket, hlEvents: HyperliquidEventTarget) {
+    this.socket = socket;
+
+    // Monitor responses and match the pending request
+    hlEvents.addEventListener("subscriptionResponse", (event) => {
+      this.queue
+        // NOTE: API may add new fields over time, so perform a loose check of the payload.
+        .find((x) => typeof x.id === "string" && isSubset(JSON.parse(x.id), event.detail))
+        ?.resolve(event.detail);
+    });
+    hlEvents.addEventListener("post", (event) => {
+      if (event.detail.response.type === "error") {
+        this.queue
+          .find((x) => x.id === event.detail.id)
+          ?.reject(new WebSocketRequestError(event.detail.response.payload));
+        return;
+      }
+      const data = event.detail.response.type === "info"
+        ? event.detail.response.payload.data
+        : event.detail.response.payload;
+      this.queue.find((x) => x.id === event.detail.id)?.resolve(data);
+    });
+    hlEvents.addEventListener("pong", () => {
+      this.queue.find((x) => x.id === "ping")?.resolve();
+    });
+    hlEvents.addEventListener("error", (event) => {
+      try {
+        // For errors with `id=` suffix (e.g., `too many pending post requests id=1234`)
+        const idMatch = event.detail.match(/id=(\d+)$/);
+        if (idMatch) {
+          const id = parseInt(idMatch[1], 10);
+          this.queue.find((x) => x.id === id)
+            ?.reject(new WebSocketRequestError(event.detail));
+          return;
+        }
+
+        // Error event doesn't have an id, use original request to match
+        const request = event.detail.match(/{.*}/)?.[0];
+        if (!request) return;
+
+        const parsedRequest = JSON.parse(request);
+
+        // For `post` requests
+        if ("id" in parsedRequest && typeof parsedRequest.id === "number") {
+          this.queue.find((x) => x.id === parsedRequest.id)
+            ?.reject(new WebSocketRequestError(event.detail));
+          return;
+        }
+
+        // For `subscribe` and `unsubscribe` requests
+        if (
+          "subscription" in parsedRequest &&
+          typeof parsedRequest.subscription === "object" && parsedRequest.subscription !== null
+        ) {
+          const id = WebSocketAsyncRequest.requestToId(parsedRequest);
+          this.queue.find((x) => x.id === id)
+            ?.reject(new WebSocketRequestError(event.detail));
+          return;
+        }
+
+        // For `Already subscribed` and `Invalid subscription` requests
+        if (
+          event.detail.startsWith("Already subscribed") ||
+          event.detail.startsWith("Invalid subscription")
+        ) {
+          const id = WebSocketAsyncRequest.requestToId({
+            method: "subscribe",
+            subscription: parsedRequest,
+          });
+          this.queue.find((x) => x.id === id)
+            ?.reject(new WebSocketRequestError(event.detail));
+          return;
+        }
+
+        // For `Already unsubscribed` requests
+        if (event.detail.startsWith("Already unsubscribed")) {
+          const id = WebSocketAsyncRequest.requestToId({
+            method: "unsubscribe",
+            subscription: parsedRequest,
+          });
+          this.queue.find((x) => x.id === id)
+            ?.reject(new WebSocketRequestError(event.detail));
+          return;
+        }
+
+        // For unknown requests
+        const id = WebSocketAsyncRequest.requestToId(parsedRequest);
+        this.queue.find((x) => x.id === id)
+          ?.reject(new WebSocketRequestError(event.detail));
+      } catch {
+        // Ignore JSON parsing errors
+      }
+    });
+
+    // Throws all pending requests if the connection is dropped
+    const handleClose = () => {
+      this.queue.forEach(({ reject }) => {
+        reject(new WebSocketRequestError("WebSocket connection closed."));
+      });
+      this.queue = [];
+    };
+    socket.addEventListener("close", handleClose);
+    socket.addEventListener("error", handleClose);
+  }
+
+  /**
+   * Sends a request to the Hyperliquid API.
+   * @returns A promise that resolves with the parsed JSON response body.
+   */
+  async request(method: "ping", signal?: AbortSignal): Promise<void>;
+  async request<T>(method: "post" | "subscribe" | "unsubscribe", payload: unknown, signal?: AbortSignal): Promise<T>;
+  async request<T>(
+    method: "post" | "subscribe" | "unsubscribe" | "ping",
+    payloadOrSignal?: unknown | AbortSignal,
+    maybeSignal?: AbortSignal,
+  ): Promise<T> {
+    const payload = payloadOrSignal instanceof AbortSignal ? undefined : payloadOrSignal;
+    const signal = payloadOrSignal instanceof AbortSignal ? payloadOrSignal : maybeSignal;
+
+    // Reject the request if the signal is aborted
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    // or if the WebSocket connection is permanently closed
+    if (this.socket.terminationSignal.aborted) {
+      return Promise.reject(this.socket.terminationSignal.reason);
+    }
+
+    // Create a request
+    let id: string | number;
+    let request: SubscribeUnsubscribeRequest | PostRequest | PingRequest;
+    if (method === "post") {
+      id = ++this.lastId;
+      request = { method, id, request: payload };
+    } else if (method === "ping") {
+      id = "ping";
+      request = { method };
+    } else {
+      request = { method, subscription: payload };
+      id = WebSocketAsyncRequest.requestToId(request);
+    }
+
+    // Send the request
+    this.socket.send(JSON.stringify(request));
+
+    // Wait for a response
+    const { promise, resolve, reject } = Promise_.withResolvers<T>();
+    this.queue.push({ id, resolve, reject });
+
+    const onAbort = () => reject(signal?.reason);
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    return await promise.finally(() => {
+      const index = this.queue.findIndex((item) => item.id === id);
+      if (index !== -1) this.queue.splice(index, 1);
+
+      signal?.removeEventListener("abort", onAbort);
+    });
+  }
+
+  /** Normalizes an object and then converts it to a string. */
+  static requestToId(value: unknown): string {
+    const sortedKeys = recursiveSortObjectKeys(value);
+    const lowercasedHex = recursiveHexToLowercase(sortedKeys);
+    return JSON.stringify(lowercasedHex);
+  }
+}
+
+function recursiveSortObjectKeys<T>(obj: T): T {
+  if (Array.isArray(obj)) {
+    return obj.map(recursiveSortObjectKeys) as T;
+  }
+  if (typeof obj === "object" && obj !== null) {
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      result[key] = recursiveSortObjectKeys((obj as Record<string, unknown>)[key]);
+    }
+    return result as T;
+  }
+  return obj;
+}
+
+function recursiveHexToLowercase(value: unknown): unknown {
+  if (typeof value === "string" && /^0[xX][0-9a-fA-F]+$/.test(value)) {
+    return value.toLowerCase();
+  }
+  if (Array.isArray(value)) {
+    return value.map(recursiveHexToLowercase);
+  }
+  if (typeof value === "object" && value !== null) {
+    const result: Record<string, unknown> = {};
+    for (const k in value) {
+      result[k] = recursiveHexToLowercase((value as Record<string, unknown>)[k]);
+    }
+    return result;
+  }
+  return value;
+}
+
+/** Checks if `subset` is a subset of `superset` (all fields in subset exist in superset with same values). */
+function isSubset(subset: unknown, superset: unknown): boolean {
+  // Strings: compare hex addresses case-insensitively, others strictly
+  if (typeof subset === "string" && typeof superset === "string") {
+    const hexRegex = /^0x[0-9a-f]+$/i;
+    return hexRegex.test(subset) && hexRegex.test(superset)
+      ? subset.toLowerCase() === superset.toLowerCase()
+      : subset === superset;
+  }
+
+  // Primitives or type mismatch
+  if (typeof subset !== "object" || typeof superset !== "object" || subset === null || superset === null) {
+    return subset === superset;
+  }
+
+  // Arrays: must match element by element
+  if (Array.isArray(subset)) {
+    return Array.isArray(superset) &&
+      subset.length === superset.length &&
+      subset.every((item, i) => isSubset(item, superset[i]));
+  }
+
+  // Objects: all keys in subset must exist in superset with matching values
+  const sub = subset as Record<string, unknown>;
+  const sup = superset as Record<string, unknown>;
+  return Object.keys(sub).every((key) => key in sup && isSubset(sub[key], sup[key]));
+}

package/src/src/transport/websocket/_subscriptionManager.ts

@@ -0,0 +1,203 @@
+import type { ReconnectingWebSocket } from "@nktkas/rews";
+import type { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
+import { WebSocketAsyncRequest, WebSocketRequestError } from "./_postRequest.js";
+
+/** Maximum number of subscriptions allowed by Hyperliquid. */
+const MAX_SUBSCRIPTIONS = 1000;
+
+/** Maximum number of unique user subscriptions allowed by Hyperliquid. */
+const MAX_UNIQUE_USER_SUBSCRIPTIONS = 10;
+
+/** WebSocket subscription with failure signal. */
+export interface WebSocketSubscription {
+  /** Removes the event listener and unsubscribes from the event channel. */
+  unsubscribe(): Promise<void>;
+
+  /** [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that is aborted if the subscription fails to restore after reconnection. */
+  failureSignal: AbortSignal;
+}
+
+/** Internal state for managing a subscription. */
+interface SubscriptionState {
+  /** Map of event listeners to their unsubscribe functions. */
+  listeners: Map<(data: CustomEvent) => void, () => Promise<void>>;
+  /** Promise tracking the subscription request. */
+  promise: Promise<unknown>;
+  /** Whether the subscription request has completed. */
+  promiseFinished: boolean;
+  /** Controller to signal subscription failure. */
+  failureController: AbortController;
+}
+
+/**
+ * Manages WebSocket subscriptions to Hyperliquid event channels.
+ * Handles subscription lifecycle, resubscription on reconnect, and cleanup.
+ */
+export class WebSocketSubscriptionManager {
+  /** Enable automatic re-subscription to Hyperliquid subscription after reconnection. */
+  resubscribe: boolean;
+
+  protected _socket: ReconnectingWebSocket;
+  protected _wsRequester: WebSocketAsyncRequest;
+  protected _hlEvents: HyperliquidEventTarget;
+  protected _subscriptions: Map<string, SubscriptionState> = new Map();
+
+  constructor(
+    socket: ReconnectingWebSocket,
+    wsRequester: WebSocketAsyncRequest,
+    hlEvents: HyperliquidEventTarget,
+    resubscribe: boolean,
+  ) {
+    this._socket = socket;
+    this._wsRequester = wsRequester;
+    this._hlEvents = hlEvents;
+    this.resubscribe = resubscribe;
+
+    // Subscribe to socket events
+    socket.addEventListener("open", () => this._handleOpen());
+    socket.addEventListener("close", () => this._handleClose());
+    socket.addEventListener("error", () => this._handleClose());
+  }
+
+  // ============================================================
+  // Public methods
+  // ============================================================
+
+  /**
+   * 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 WebSocketSubscription} object to manage the subscription lifecycle.
+   *
+   * @throws {WebSocketRequestError} - An error that occurs when a WebSocket request fails.
+   */
+  async subscribe<T>(
+    channel: string,
+    payload: unknown,
+    listener: (data: CustomEvent<T>) => void,
+  ): Promise<WebSocketSubscription> {
+    // 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) {
+      // Check unique subscription limits
+      if (this._subscriptions.size >= MAX_SUBSCRIPTIONS) {
+        throw new WebSocketRequestError("Cannot subscribe to more than 1000 channels.");
+      }
+      // Check unique user subscription limits
+      if (this._hasUserParam(payload) && this._countUniqueUserSubscriptions() >= MAX_UNIQUE_USER_SUBSCRIPTIONS) {
+        throw new WebSocketRequestError("Cannot track more than 10 unique users.");
+      }
+
+      // Send subscription request
+      const promise = this._wsRequester.request("subscribe", payload)
+        .finally(() => subscription!.promiseFinished = true);
+
+      // Cache subscription info
+      subscription = {
+        listeners: new Map(),
+        promise,
+        promiseFinished: false,
+        failureController: 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 () => {
+        // 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 === 1) { // OPEN
+            await this._wsRequester.request("unsubscribe", payload);
+          }
+        }
+      };
+
+      // 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,
+      failureSignal: subscription.failureController.signal,
+    };
+  }
+
+  // ============================================================
+  // Socket event handlers
+  // ============================================================
+
+  /** Resubscribe to all existing subscriptions if auto-resubscribe is enabled. */
+  protected _handleOpen(): void {
+    if (this.resubscribe) {
+      for (const [id, subscription] of this._subscriptions.entries()) {
+        // reconnect only previously connected subscriptions to avoid double subscriptions due to message buffering
+        if (subscription.promiseFinished) {
+          subscription.promise = this._wsRequester.request("subscribe", JSON.parse(id))
+            .catch((error) => subscription.failureController.abort(error))
+            .finally(() => subscription.promiseFinished = true);
+          subscription.promiseFinished = false;
+        }
+      }
+    }
+  }
+
+  /** Cleanup subscriptions if resubscribe is disabled or socket is terminated. */
+  protected _handleClose(): 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
+        }
+      }
+    }
+  }
+
+  // ============================================================
+  // Subscription limit checks
+  // ============================================================
+
+  /** Checks if a payload contains a user parameter. */
+  protected _hasUserParam(payload: unknown): boolean {
+    return typeof payload === "object" && payload !== null && "user" in payload;
+  }
+
+  /** Counts the number of unique users across all active subscriptions. */
+  protected _countUniqueUserSubscriptions(): number {
+    const users = new Set<string>();
+    for (const id of this._subscriptions.keys()) {
+      try {
+        const payload = JSON.parse(id);
+        if (this._hasUserParam(payload)) {
+          users.add(payload.user);
+        }
+      } catch {
+        // Ignore parsing errors
+      }
+    }
+    return users.size;
+  }
+}