@nktkas/hyperliquid 0.25.0-beta.2 → 0.25.0-beta.4

package/src/src/transports/websocket/_hyperliquid_event_target.ts

@@ -1,18 +1,13 @@
-import type { BlockDetails, TxDetails } from "../../schemas/mod.js";
-
-/** Represents a message from the Hyperliquid WebSocket API. */
-interface HyperliquidMsg {
-    /** Event channel name. */
-    channel: string;
-    /** Channel-specific data. */
-    data: unknown;
-}
+import { TypedEventTarget } from "typescript-event-target";
+import * as v from "valibot";
+import { CustomEvent_ } from "../_polyfills.js";
+import { BlockDetails, TxDetails } from "../../schemas/mod.js";
 
 /** Response to subscribe to or unsubscribe from an event. */
-interface SubscriptionResponse {
-    /** Type of subscription operation. */
+interface SubscribeUnsubscribeResponse {
+    /** Type of response */
     method: "subscribe" | "unsubscribe";
-    /** Original subscription request. */
+    /** Original request. */
     subscription: unknown;
 }
 
@@ -56,8 +51,8 @@ interface PostResponse {
 }
 
 /** Base system events and dynamic channel events for Hyperliquid WebSocket API. */
-export interface HyperliquidEventMap {
-    subscriptionResponse: CustomEvent<SubscriptionResponse>;
+interface HyperliquidEventMap {
+    subscriptionResponse: CustomEvent<SubscribeUnsubscribeResponse>;
     post: CustomEvent<PostResponse>;
     error: CustomEvent<string>;
     pong: CustomEvent<undefined>;
@@ -67,19 +62,26 @@ export interface HyperliquidEventMap {
     [key: string]: CustomEvent<any>;
 }
 
+const HyperliquidEventSchema = v.object({ channel: v.string(), data: v.unknown() });
+const ExplorerBlockEventSchema = v.pipe(
+    v.array(v.omit(v.object({ ...BlockDetails.entries }), ["txs"])),
+    v.minLength(1),
+);
+const ExplorerTxsEventSchema = v.pipe(v.array(TxDetails), v.minLength(1));
+
 /** Listens for WebSocket messages and sends them as Hyperliquid typed events. */
-export class HyperliquidEventTarget extends EventTarget {
+export class HyperliquidEventTarget extends TypedEventTarget<HyperliquidEventMap> {
     constructor(socket: WebSocket) {
         super();
         socket.addEventListener("message", (event) => {
             try {
-                const msg = JSON.parse(event.data) as unknown;
-                if (isHyperliquidMsg(msg)) {
-                    this.dispatchEvent(new CustomEvent(msg.channel, { detail: msg.data }));
-                } else if (isExplorerBlockMsg(msg)) {
-                    this.dispatchEvent(new CustomEvent("_explorerBlock", { detail: msg }));
-                } else if (isExplorerTxsMsg(msg)) {
-                    this.dispatchEvent(new CustomEvent("_explorerTxs", { detail: msg }));
+                const msg = JSON.parse(event.data);
+                if (v.is(HyperliquidEventSchema, msg)) {
+                    this.dispatchEvent(new CustomEvent_(msg.channel, { detail: msg.data }));
+                } 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
@@ -87,32 +89,3 @@ export class HyperliquidEventTarget extends EventTarget {
         });
     }
 }
-
-/** Type guard for Hyperliquid messages. */
-function isHyperliquidMsg(value: unknown): value is HyperliquidMsg {
-    return typeof value === "object" && value !== null &&
-        "channel" in value && typeof value.channel === "string";
-}
-
-/** Type guard for explorer block messages. */
-function isExplorerBlockMsg(value: unknown): value is Omit<BlockDetails, "txs">[] {
-    return Array.isArray(value) && value.length > 0 &&
-        (typeof value[0] === "object" && value[0] !== null && !Array.isArray(value[0]) &&
-            "height" in value[0] && typeof value[0].height === "number" &&
-            "blockTime" in value[0] && typeof value[0].blockTime === "number" &&
-            "hash" in value[0] && typeof value[0].hash === "string" &&
-            "proposer" in value[0] && typeof value[0].proposer === "string" &&
-            "numTxs" in value[0] && typeof value[0].numTxs === "number");
-}
-
-/** Type guard for explorer transactions messages. */
-function isExplorerTxsMsg(value: unknown): value is TxDetails[] {
-    return Array.isArray(value) && value.length > 0 &&
-        (typeof value[0] === "object" && value[0] !== null && !Array.isArray(value[0]) &&
-            "action" in value[0] && typeof value[0].action === "object" && value[0].action !== null &&
-            "block" in value[0] && typeof value[0].block === "number" &&
-            "error" in value[0] && (typeof value[0].error === "string" || value[0].error === null) &&
-            "hash" in value[0] && typeof value[0].hash === "string" &&
-            "time" in value[0] && typeof value[0].time === "number" &&
-            "user" in value[0] && typeof value[0].user === "string");
-}

package/src/src/transports/websocket/_reconnecting_websocket.ts

@@ -1,79 +1,42 @@
 // deno-lint-ignore-file no-explicit-any
 import { TransportError } from "../base.js";
-
-type MaybePromise<T> = T | Promise<T>;
+import { AbortSignal_ } from "../_polyfills.js";
 
 /** Configuration options for the `ReconnectingWebSocket`. */
 export interface ReconnectingWebSocketOptions {
+    /**
+     * Custom WebSocket constructor.
+     * @defaultValue The global `WebSocket` constructor.
+     */
+    WebSocket?: new (url: string | URL, protocols?: string | string[]) => WebSocket;
     /**
      * Maximum number of reconnection attempts.
      * @defaultValue `3`
      */
     maxRetries?: number;
-
     /**
      * Maximum time in ms to wait for a connection to open.
      * Set to `null` to disable.
      * @defaultValue `10_000`
      */
     connectionTimeout?: number | null;
-
     /**
-     * Delay between reconnection attempts in ms.
+     * Delay before reconnection in ms.
      * May be a number or a function that returns a number.
      * @param attempt - The current attempt number.
      * @defaultValue `(attempt) => Math.min(~~(1 << attempt) * 150, 10_000)` - Exponential backoff (max 10s)
      */
-    connectionDelay?: number | ((attempt: number, signal: AbortSignal) => MaybePromise<number>);
-
-    /**
-     * Custom logic to determine if reconnection is required.
-     * @param event - The close event that occurred during the connection.
-     * @returns A boolean indicating if reconnection should be attempted.
-     * @defaultValue `() => true` - Always reconnect
-     */
-    shouldReconnect?: (event: CloseEvent, signal: AbortSignal) => MaybePromise<boolean>;
-
-    /**
-     * Message buffering strategy between reconnection attempts.
-     * @defaultValue `new FIFOMessageBuffer()`
-     */
-    messageBuffer?: MessageBufferStrategy;
+    reconnectionDelay?: number | ((attempt: number) => number);
 }
 
-/** Message buffer strategy interface. */
-export interface MessageBufferStrategy {
-    push(data: string | ArrayBufferLike | Blob | ArrayBufferView, signal?: AbortSignal): void;
-    [Symbol.iterator](): Iterator<string | ArrayBufferLike | Blob | ArrayBufferView>;
-}
-
-/** Simple FIFO (First In, First Out) buffer implementation. */
-class FIFOMessageBuffer implements MessageBufferStrategy {
-    queue: {
-        data: string | ArrayBufferLike | Blob | ArrayBufferView;
-        signal?: AbortSignal;
-    }[] = [];
-
-    push(data: string | ArrayBufferLike | Blob | ArrayBufferView, signal?: AbortSignal): void {
-        this.queue.push({ data, signal });
-    }
-
-    *[Symbol.iterator](): Iterator<string | ArrayBufferLike | Blob | ArrayBufferView> {
-        while (this.queue.length > 0) {
-            const { data, signal } = this.queue.shift()!;
-            if (signal?.aborted) continue;
-            yield data;
-        }
-    }
-}
+type WebSocketSendData = string | ArrayBufferLike | Blob | ArrayBufferView;
 
 /** Error thrown when reconnection problems occur. */
 export class ReconnectingWebSocketError extends TransportError {
     constructor(
         public code:
-            | "RECONNECTION_LIMIT_REACHED"
-            | "RECONNECTION_STOPPED_BY_USER"
-            | "USER_INITIATED_CLOSE"
+            | "RECONNECTION_LIMIT"
+            | "TERMINATED_BY_USER"
             | "UNKNOWN_ERROR",
         cause?: unknown,
     ) {
@@ -84,8 +47,12 @@ export class ReconnectingWebSocketError extends TransportError {
 }
 
 /**
- * A WebSocket that automatically reconnects when disconnected.
+ * A WebSocket that automatically reconnects and restores event listeners after disconnection.
  * Fully compatible with standard WebSocket API.
+ *
+ * Additions:
+ * - `reconnectOptions` property: The options used to configure the reconnection behavior.
+ * - `terminateSignal` property: An `AbortSignal` that is aborted when the instance is permanently closed.
  */
 export class ReconnectingWebSocket implements WebSocket {
     protected _socket: WebSocket;
@@ -97,107 +64,135 @@ export class ReconnectingWebSocket implements WebSocket {
         listenerProxy: EventListenerOrEventListenerObject;
     }[] = [];
     protected _attempt = 0;
+    protected _messageBuffer: { data: WebSocketSendData; signal?: AbortSignal }[] = [];
+    protected _abortController = new AbortController();
+
     reconnectOptions: Required<ReconnectingWebSocketOptions>;
-    readonly reconnectAbortController: AbortController = new AbortController();
+    readonly terminateSignal = this._abortController.signal;
+
+    constructor(url: string | URL, options?: ReconnectingWebSocketOptions);
+    constructor(url: string | URL, protocols?: string | string[], options?: ReconnectingWebSocketOptions);
+    constructor(
+        url: string | URL,
+        protocolsOrOptions?: (string | string[]) | ReconnectingWebSocketOptions,
+        maybeOptions?: ReconnectingWebSocketOptions,
+    ) {
+        const protocols = typeof protocolsOrOptions === "string" || Array.isArray(protocolsOrOptions)
+            ? protocolsOrOptions
+            : undefined;
+        const options = typeof protocolsOrOptions === "object" && !Array.isArray(protocolsOrOptions)
+            ? protocolsOrOptions
+            : maybeOptions;
+
+        if (!globalThis.WebSocket && !options?.WebSocket) {
+            throw new Error(
+                "No WebSocket implementation found. Please provide a custom WebSocket constructor in the options.",
+            );
+        }
 
-    constructor(url: string | URL, protocols?: string | string[], options?: ReconnectingWebSocketOptions) {
         this.reconnectOptions = {
+            WebSocket: options?.WebSocket ?? WebSocket,
             maxRetries: options?.maxRetries ?? 3,
             connectionTimeout: options?.connectionTimeout === undefined ? 10_000 : options.connectionTimeout,
-            connectionDelay: options?.connectionDelay ?? ((n) => Math.min(~~(1 << n) * 150, 10_000)),
-            shouldReconnect: options?.shouldReconnect ?? (() => true),
-            messageBuffer: options?.messageBuffer ?? new FIFOMessageBuffer(),
+            reconnectionDelay: options?.reconnectionDelay ?? ((n) => Math.min(~~(1 << n) * 150, 10_000)),
         };
 
         this._socket = this._createSocket(url, protocols);
         this._protocols = protocols;
-        this._setupEventListeners();
+
+        this._initInternalListeners();
     }
 
     protected _createSocket(url: string | URL, protocols?: string | string[]): WebSocket {
-        const socket = new WebSocket(url, protocols);
+        const socket = new this.reconnectOptions.WebSocket(url, protocols);
         if (this.reconnectOptions.connectionTimeout === null) return socket;
 
-        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
-        }, this.reconnectOptions.connectionTimeout);
-
-        const openHandler = () => {
-            socket.removeEventListener("close", closeHandler);
-            clearTimeout(timeoutId);
+        const handleOpen = () => {
+            socket.removeEventListener("close", handleClose);
+            socket.removeEventListener("error", handleError);
+            signal.removeEventListener("abort", handleAbort);
         };
-        const closeHandler = () => {
-            socket.removeEventListener("open", openHandler);
-            clearTimeout(timeoutId);
+        const handleClose = () => {
+            socket.removeEventListener("open", handleOpen);
+            socket.removeEventListener("error", handleError);
+            signal.removeEventListener("abort", handleAbort);
         };
+        const handleError = () => {
+            socket.removeEventListener("open", handleOpen);
+            socket.removeEventListener("close", handleClose);
+            signal.removeEventListener("abort", handleAbort);
+        };
+        const handleAbort = () => {
+            socket.close(3008, "Timeout"); // https://www.iana.org/assignments/websocket/websocket.xml#close-code-number
+        };
+
+        const signal = AbortSignal_.timeout(this.reconnectOptions.connectionTimeout);
 
-        socket.addEventListener("open", openHandler, { once: true });
-        socket.addEventListener("close", closeHandler, { once: true });
+        socket.addEventListener("open", handleOpen, { once: true, signal });
+        socket.addEventListener("close", handleClose, { once: true, signal });
+        socket.addEventListener("error", handleError, { once: true, signal });
+        signal.addEventListener("abort", handleAbort, { once: true });
 
         return socket;
     }
 
+    protected _cleanup(code: ConstructorParameters<typeof ReconnectingWebSocketError>[0], cause?: unknown) {
+        const error = new ReconnectingWebSocketError(code, cause);
+        this._abortController.abort(error);
+        this._listeners = [];
+        this._socket.close();
+    }
+
     /** Initializes the internal event listeners for the socket. */
-    protected _setupEventListeners() {
+    protected _initInternalListeners() {
+        const handleClose = () => {
+            this._socket.removeEventListener("error", handleError);
+            this._close();
+        };
+        const handleError = () => {
+            this._socket.removeEventListener("close", handleClose);
+            this._close();
+        };
         this._socket.addEventListener("open", this._open, { once: true });
-        this._socket.addEventListener("close", this._close, { once: true });
+        this._socket.addEventListener("close", handleClose, { once: true });
+        this._socket.addEventListener("error", handleError, { once: true });
     }
     protected _open: () => void = () => {
         // Reset the attempt counter
         this._attempt = 0;
 
         // Send all buffered messages
-        for (const message of this.reconnectOptions.messageBuffer) {
-            this._socket.send(message);
+        while (this._messageBuffer.length > 0) {
+            const item = this._messageBuffer.shift()!;
+            if (item.signal?.aborted) continue;
+            this._socket.send(item.data);
         }
     };
-    protected _close = async (event: CloseEvent) => {
+    protected _close = async () => {
         try {
-            // If the event was triggered but the socket is not closing, ignore it
-            if (
-                this._socket.readyState !== ReconnectingWebSocket.CLOSING &&
-                this._socket.readyState !== ReconnectingWebSocket.CLOSED
-            ) return;
-
             // If the instance is terminated, do not attempt to reconnect
-            if (this.reconnectAbortController.signal.aborted) return;
+            if (this._abortController.signal.aborted) return;
 
             // Check if reconnection should be attempted
             if (++this._attempt > this.reconnectOptions.maxRetries) {
-                this._cleanup("RECONNECTION_LIMIT_REACHED");
-                return;
-            }
-
-            const userDecision = await this.reconnectOptions.shouldReconnect(
-                event,
-                this.reconnectAbortController.signal,
-            );
-            if (this.reconnectAbortController.signal.aborted) return;
-            if (!userDecision) {
-                this._cleanup("RECONNECTION_STOPPED_BY_USER");
+                this._cleanup("RECONNECTION_LIMIT");
                 return;
             }
 
             // Delay before reconnecting
-            const reconnectDelay = typeof this.reconnectOptions.connectionDelay === "number"
-                ? this.reconnectOptions.connectionDelay
-                : await this.reconnectOptions.connectionDelay(this._attempt, this.reconnectAbortController.signal);
-            if (this.reconnectAbortController.signal.aborted) return;
-            await delay(reconnectDelay, this.reconnectAbortController.signal);
-
-            // Create a new WebSocket instance
-            const { onclose, onerror, onmessage, onopen } = this._socket;
-            this._socket = this._createSocket(this._socket.url, this._protocols);
+            const delay = typeof this.reconnectOptions.reconnectionDelay === "number"
+                ? this.reconnectOptions.reconnectionDelay
+                : this.reconnectOptions.reconnectionDelay(this._attempt);
+            await sleep(delay, this._abortController.signal);
 
-            // Reconnect all listeners
-            this._setupEventListeners();
+            // Create a new WebSocket instance and re-apply event listeners
+            const { onclose, onerror, onmessage, onopen } = this._socket; // preserve event handlers
+            this._socket = this._createSocket(this._socket.url, this._protocols);
 
+            this._initInternalListeners();
             this._listeners.forEach(({ type, listenerProxy, options }) => {
                 this._socket.addEventListener(type, listenerProxy, options);
             });
-
             this._socket.onclose = onclose;
             this._socket.onerror = onerror;
             this._socket.onmessage = onmessage;
@@ -207,13 +202,6 @@ export class ReconnectingWebSocket implements WebSocket {
         }
     };
 
-    /** Clean up internal resources. */
-    protected _cleanup(code: ConstructorParameters<typeof ReconnectingWebSocketError>[0], cause?: unknown) {
-        this.reconnectAbortController.abort(new ReconnectingWebSocketError(code, cause));
-        this._listeners = [];
-        this._socket.close();
-    }
-
     // WebSocket property implementations
     get url(): string {
         return this._socket.url;
@@ -280,17 +268,17 @@ export class ReconnectingWebSocket implements WebSocket {
      */
     close(code?: number, reason?: string, permanently: boolean = true): void {
         this._socket.close(code, reason);
-        if (permanently) this._cleanup("USER_INITIATED_CLOSE");
+        if (permanently) this._cleanup("TERMINATED_BY_USER");
     }
 
     /**
      * @param signal - `AbortSignal` to cancel sending a message if it was in the buffer.
      * @note If the connection is not open, the data will be buffered and sent when the connection is established.
      */
-    send(data: string | ArrayBufferLike | Blob | ArrayBufferView, signal?: AbortSignal): void {
+    send(data: WebSocketSendData, signal?: AbortSignal): void {
         if (signal?.aborted) return;
-        if (this._socket.readyState !== ReconnectingWebSocket.OPEN && !this.reconnectAbortController.signal.aborted) {
-            this.reconnectOptions.messageBuffer.push(data, signal);
+        if (this._socket.readyState !== ReconnectingWebSocket.OPEN && !this._abortController.signal.aborted) {
+            this._messageBuffer.push({ data, signal });
         } else {
             this._socket.send(data);
         }
@@ -310,7 +298,7 @@ export class ReconnectingWebSocket implements WebSocket {
     ): void {
         // Wrap the listener to handle reconnection
         let listenerProxy: EventListenerOrEventListenerObject;
-        if (this.reconnectAbortController.signal.aborted) {
+        if (this._abortController.signal.aborted) {
             // If the instance is terminated, use the original listener
             listenerProxy = listener;
         } else {
@@ -381,13 +369,13 @@ function listenersMatch(
     a: { type: string; listener: EventListenerOrEventListenerObject; options?: boolean | AddEventListenerOptions },
     b: { type: string; listener: EventListenerOrEventListenerObject; options?: boolean | AddEventListenerOptions },
 ): boolean {
-    // EventTarget only compares capture in options, even if one is an object and the other is boolean
+    // `EventTarget` only compares `capture` in options, even if one is an object and the other is boolean
     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;
 }
 
-function delay(ms: number, signal?: AbortSignal): Promise<void> {
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
     if (signal?.aborted) return Promise.reject(signal.reason);
     return new Promise((resolve, reject) => {
         const onAbort = () => {