@nktkas/hyperliquid 0.13.0

package/esm/src/transports/base.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Interface representing a REST transport.
+ * Handles communication with Hyperliquid API endpoints.
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint | Info endpoint}
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint | Exchange endpoint}
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests | Websocket post requests}
+ */
+export interface IRequestTransport {
+    /**
+     * Sends a request to the Hyperliquid API.
+     * @param endpoint - The API endpoint to send the request to.
+     * @param payload - The payload to send with the request.
+     * @param signal - An ptional abort signal.
+     * @returns A promise that resolves with parsed JSON response body.
+     */
+    request(endpoint: "info" | "action" | "explorer", payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/**
+ * Interface representing an event subscription transport.
+ * Handles WebSocket subscriptions for real-time updates.
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | Websocket subscriptions}
+ */
+export interface ISubscriptionTransport {
+    /**
+     * Subscribes to a Hyperliquid event channel.
+     * @param channel - The event channel to listen to.
+     * @param payload - The payload to send with the subscription request.
+     * @param listener - The function to call when the event is dispatched.
+     * @param signal - An optional abort signal for canceling the subscription request.
+     * @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+     */
+    subscribe(channel: string, payload: unknown, listener: (data: CustomEvent) => void, signal?: AbortSignal): Promise<Subscription>;
+}
+/**
+ * Controls event subscription lifecycle.
+ */
+export interface Subscription {
+    /**
+     * Unsubscribes from the event and sends an unsubscribe request to the server.
+     * @param signal - An optional abort signal for canceling the unsubscribe request.
+     */
+    unsubscribe(signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Base class for all transport-related errors.
+ */
+export declare class TransportError extends Error {
+    /**
+     * Creates a new transport error.
+     * @param message - The error message.
+     * @param options - Additional error options.
+     */
+    constructor(message?: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=base.d.ts.map

package/esm/src/transports/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/src/transports/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/G;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACnC;;;;;;;OAOG;IACH,SAAS,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,EACrC,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACrC;;;;OAIG;gBACS,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIvD"}

package/esm/src/transports/base.js

@@ -0,0 +1,14 @@
+/**
+ * Base class for all transport-related errors.
+ */
+export class TransportError extends Error {
+    /**
+     * Creates a new transport error.
+     * @param message - The error message.
+     * @param options - Additional error options.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TransportError";
+    }
+}

package/esm/src/transports/http/http_transport.d.ts

@@ -0,0 +1,78 @@
+import { type IRequestTransport, TransportError } from "../base.js";
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Error thrown when an HTTP response is deemed invalid:
+ * - Non-200 status code
+ * - Unexpected content type
+ */
+export declare class HttpRequestError extends TransportError {
+    response: Response;
+    responseBody?: string | undefined;
+    /**
+     * Creates a new HTTP request error.
+     * @param response - The failed HTTP response.
+     * @param responseBody - The raw response body content, if available.
+     */
+    constructor(response: Response, responseBody?: string | undefined);
+}
+/**
+ * Configuration options for the HTTP transport layer.
+ */
+export interface HttpTransportOptions {
+    /**
+     * Base URL for API endpoints.
+     * - Mainnet: `https://api.hyperliquid.xyz`
+     * - Testnet: `https://api.hyperliquid-testnet.xyz`
+     * @defaultValue `https://api.hyperliquid.xyz`
+     */
+    url?: string | URL;
+    /**
+     * Request timeout in ms.
+     * Set to `null` to disable.
+     * @defaultValue `10_000`
+     */
+    timeout?: number | null;
+    /** A custom {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | RequestInit} that is merged with a fetch request. */
+    fetchOptions?: Omit<RequestInit, "body" | "method">;
+    /**
+     * A callback function that is called before the request is sent.
+     * @param request - An original request to send.
+     * @returns If returned a {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/Request/Request | Request}, it will replace the original request.
+     */
+    onRequest?: (request: Request) => MaybePromise<Request | void | null | undefined>;
+    /**
+     * A callback function that is called after the response is received.
+     * @param response - An original response to process.
+     * @returns If returned a {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/Response/Response | Response}, it will replace the original response.
+     */
+    onResponse?: (response: Response) => MaybePromise<Response | void | null | undefined>;
+}
+/**
+ * HTTP implementation of the REST transport interface.
+ */
+export declare class HttpTransport implements IRequestTransport, HttpTransportOptions {
+    url: string | URL;
+    timeout: number | null;
+    fetchOptions: Omit<RequestInit, "body" | "method">;
+    onRequest?: (request: Request) => MaybePromise<Request | void | null | undefined>;
+    onResponse?: (response: Response) => MaybePromise<Response | void | null | undefined>;
+    /** Mapping of endpoint types to their API paths. */
+    protected _endpointPaths: Record<"info" | "action" | "explorer", string>;
+    /**
+     * Creates a new HTTP transport instance.
+     * @param options - Configuration options for the HTTP transport layer.
+     */
+    constructor(options?: HttpTransportOptions);
+    /**
+     * Sends a request to the Hyperliquid API via fetch.
+     * @param endpoint - The API endpoint to send the request to.
+     * @param payload - The payload to send with the request.
+     * @param signal - An optional abort signal.
+     * @returns A promise that resolves with parsed JSON response body.
+     * @throws {HttpRequestError} - Thrown when an HTTP response is deemed invalid.
+     * @throws May throw {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch#exceptions | fetch errors}.
+     */
+    request(endpoint: "info" | "action" | "explorer", payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+export {};
+//# sourceMappingURL=http_transport.d.ts.map

package/esm/src/transports/http/http_transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_transport.d.ts","sourceRoot":"","sources":["../../../../src/src/transports/http/http_transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEpE,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,cAAc;IAM7B,QAAQ,EAAE,QAAQ;IAAS,YAAY,CAAC,EAAE,MAAM;IALnE;;;;OAIG;gBACgB,QAAQ,EAAE,QAAQ,EAAS,YAAY,CAAC,EAAE,MAAM,YAAA;CAItE;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,2IAA2I;IAC3I,YAAY,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;IAEpD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,YAAY,CAAC,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAElF;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,YAAY,CAAC,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACzF;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,iBAAiB,EAAE,oBAAoB;IACzE,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;IACnD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,YAAY,CAAC,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAClF,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,YAAY,CAAC,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAEtF,oDAAoD;IACpD,SAAS,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,GAAG,QAAQ,GAAG,UAAU,EAAE,MAAM,CAAC,CAItE;IAEF;;;OAGG;gBACS,OAAO,CAAC,EAAE,oBAAoB;IAQ1C;;;;;;;;OAQG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CA6CpH"}

package/esm/src/transports/http/http_transport.js

@@ -0,0 +1,170 @@
+import { TransportError } from "../base.js";
+/**
+ * Error thrown when an HTTP response is deemed invalid:
+ * - Non-200 status code
+ * - Unexpected content type
+ */
+export class HttpRequestError extends TransportError {
+    /**
+     * Creates a new HTTP request error.
+     * @param response - The failed HTTP response.
+     * @param responseBody - The raw response body content, if available.
+     */
+    constructor(response, responseBody) {
+        super(`HTTP request failed. Status: ${response.status}. Body: ${responseBody}`);
+        Object.defineProperty(this, "response", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: response
+        });
+        Object.defineProperty(this, "responseBody", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: responseBody
+        });
+        this.name = "HttpRequestError";
+    }
+}
+/**
+ * HTTP implementation of the REST transport interface.
+ */
+export class HttpTransport {
+    /**
+     * Creates a new HTTP transport instance.
+     * @param options - Configuration options for the HTTP transport layer.
+     */
+    constructor(options) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "timeout", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fetchOptions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onRequest", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onResponse", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Mapping of endpoint types to their API paths. */
+        Object.defineProperty(this, "_endpointPaths", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                info: "/info",
+                action: "/exchange",
+                explorer: "/explorer",
+            }
+        });
+        this.url = options?.url ?? "https://api.hyperliquid.xyz";
+        this.timeout = options?.timeout === undefined ? 10_000 : options.timeout;
+        this.fetchOptions = options?.fetchOptions ?? {};
+        this.onRequest = options?.onRequest;
+        this.onResponse = options?.onResponse;
+    }
+    /**
+     * Sends a request to the Hyperliquid API via fetch.
+     * @param endpoint - The API endpoint to send the request to.
+     * @param payload - The payload to send with the request.
+     * @param signal - An optional abort signal.
+     * @returns A promise that resolves with parsed JSON response body.
+     * @throws {HttpRequestError} - Thrown when an HTTP response is deemed invalid.
+     * @throws May throw {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch#exceptions | fetch errors}.
+     */
+    async request(endpoint, payload, signal) {
+        // Construct a Request
+        const url = new URL(this._endpointPaths[endpoint], this.url);
+        const init = mergeRequestInit({
+            body: JSON.stringify(payload),
+            headers: {
+                "Accept-Encoding": "gzip, deflate, br, zstd",
+                "Connection": "keep-alive",
+                "Content-Type": "application/json",
+            },
+            keepalive: true,
+            method: "POST",
+            signal: this.timeout ? AbortSignal.timeout(this.timeout) : undefined,
+        }, this.fetchOptions, { signal });
+        let request = new Request(url, init);
+        // Call the onRequest callback, if provided
+        if (this.onRequest) {
+            const customRequest = await this.onRequest(request);
+            if (customRequest instanceof Request)
+                request = customRequest;
+        }
+        // Send the Request and wait for a Response
+        let response = await fetch(request);
+        // Call the onResponse callback, if provided
+        if (this.onResponse) {
+            const customResponse = await this.onResponse(response);
+            if (customResponse instanceof Response)
+                response = customResponse;
+        }
+        // Validate the Response
+        if (!response.ok || !response.headers.get("Content-Type")?.includes("application/json")) {
+            // Unload the response body to prevent memory leaks
+            const body = await response.text().catch(() => undefined);
+            throw new HttpRequestError(response, body);
+        }
+        // Parse and return the response body
+        return await response.json();
+    }
+}
+/**
+ * Merges multiple `HeadersInit` objects into one.
+ * @param inits - A list of `HeadersInit` objects to merge.
+ * @returns A new `Headers` object that contains all headers from the input objects.
+ */
+function mergeHeadersInit(...inits) {
+    if (inits.length === 0 || inits.length === 1) {
+        return new Headers(inits[0]);
+    }
+    const merged = new Headers();
+    for (const headers of inits) {
+        const entries = Symbol.iterator in headers ? headers : Object.entries(headers);
+        for (const [key, value] of entries) {
+            merged.set(key, value);
+        }
+    }
+    return merged;
+}
+/**
+ * Merges multiple `RequestInit` objects into one.
+ * @param inits - A list of `RequestInit` objects to merge.
+ * @returns A new `RequestInit` object that contains all properties from the input objects.
+ */
+function mergeRequestInit(...inits) {
+    const merged = inits.reduce((acc, init) => ({ ...acc, ...init }), {});
+    const headersList = inits.map((init) => init.headers)
+        .filter((headers) => typeof headers === "object");
+    if (headersList.length > 0) {
+        merged.headers = mergeHeadersInit(...headersList);
+    }
+    const signals = inits.map((init) => init.signal)
+        .filter((signal) => signal instanceof AbortSignal);
+    if (signals.length > 0) {
+        merged.signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+    }
+    return merged;
+}

package/esm/src/transports/websocket/hyperliquid_event_target.d.ts

@@ -0,0 +1,66 @@
+import { TypedEventTarget } from "../../../deps/jsr.io/@derzade/typescript-event-target/1.1.1/mod.js";
+/**
+ * Base system events and dynamic channel events for Hyperliquid WebSocket API.
+ */
+export interface HyperliquidEventMap {
+    /** Subscription created/removed event */
+    subscriptionResponse: CustomEvent<{
+        /** Type of subscription operation */
+        method: "subscribe" | "unsubscribe";
+        /** Original subscription request */
+        subscription: unknown;
+    }>;
+    /** Response to post request event */
+    post: CustomEvent<{
+        /** Unique request identifier */
+        id: number;
+        /** Server response */
+        response: 
+        /** Response containing requested information */
+        {
+            /** Indicates that this is an informational response */
+            type: "info";
+            /** Contains the information data */
+            payload: {
+                /** Type of information being returned */
+                type: string;
+                /** Information specific data */
+                data: unknown;
+            };
+        }
+        /** Response containing action result */
+         | {
+            /** Indicates that this is an action response */
+            type: "action";
+            /** Contains the action result data */
+            payload: {
+                /** Response status indicating success or failure of the action */
+                status: "ok" | "err";
+                /** Success data or error message */
+                response: {
+                    /** Type of operation */
+                    type: string;
+                    /** Specific data for the operation */
+                    data?: unknown;
+                } | string;
+            };
+        };
+    }>;
+    /** Error response for message event */
+    error: CustomEvent<string>;
+    /** Pong response event */
+    pong: CustomEvent<undefined>;
+    /** Subscribed channel events */
+    [key: string]: CustomEvent<unknown>;
+}
+/**
+ * A class that listens to WebSocket messages and dispatches them as Hyperliquid typed events.
+ */
+export declare class HyperliquidEventTarget extends TypedEventTarget<HyperliquidEventMap> {
+    /**
+     * Creates a new Hyperliquid event target.
+     * @param socket - The WebSocket to listen to.
+     */
+    constructor(socket: WebSocket);
+}
+//# sourceMappingURL=hyperliquid_event_target.d.ts.map

package/esm/src/transports/websocket/hyperliquid_event_target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperliquid_event_target.d.ts","sourceRoot":"","sources":["../../../../src/src/transports/websocket/hyperliquid_event_target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oEAAoE,CAAC;AAYtG;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,yCAAyC;IACzC,oBAAoB,EAAE,WAAW,CAAC;QAC9B,qCAAqC;QACrC,MAAM,EAAE,WAAW,GAAG,aAAa,CAAC;QACpC,oCAAoC;QACpC,YAAY,EAAE,OAAO,CAAC;KACzB,CAAC,CAAC;IAEH,qCAAqC;IACrC,IAAI,EAAE,WAAW,CAAC;QACd,gCAAgC;QAChC,EAAE,EAAE,MAAM,CAAC;QACX,sBAAsB;QACtB,QAAQ;QACJ,gDAAgD;QAC9C;YACE,uDAAuD;YACvD,IAAI,EAAE,MAAM,CAAC;YACb,oCAAoC;YACpC,OAAO,EAAE;gBACL,yCAAyC;gBACzC,IAAI,EAAE,MAAM,CAAC;gBACb,gCAAgC;gBAChC,IAAI,EAAE,OAAO,CAAC;aACjB,CAAC;SACL;QACD,wCAAwC;WACtC;YACE,gDAAgD;YAChD,IAAI,EAAE,QAAQ,CAAC;YACf,sCAAsC;YACtC,OAAO,EAAE;gBACL,kEAAkE;gBAClE,MAAM,EAAE,IAAI,GAAG,KAAK,CAAC;gBACrB,oCAAoC;gBACpC,QAAQ,EACF;oBACE,wBAAwB;oBACxB,IAAI,EAAE,MAAM,CAAC;oBACb,sCAAsC;oBACtC,IAAI,CAAC,EAAE,OAAO,CAAC;iBAClB,GACC,MAAM,CAAC;aAChB,CAAC;SACL,CAAC;KACT,CAAC,CAAC;IAEH,uCAAuC;IACvC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAE3B,0BAA0B;IAC1B,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAE7B,gCAAgC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,gBAAgB,CAAC,mBAAmB,CAAC;IAC7E;;;OAGG;gBACS,MAAM,EAAE,SAAS;CAahC"}

package/esm/src/transports/websocket/hyperliquid_event_target.js

@@ -0,0 +1,33 @@
+import { TypedEventTarget } from "../../../deps/jsr.io/@derzade/typescript-event-target/1.1.1/mod.js";
+/**
+ * A class that listens to WebSocket messages and dispatches them as Hyperliquid typed events.
+ */
+export class HyperliquidEventTarget extends TypedEventTarget {
+    /**
+     * Creates a new Hyperliquid event target.
+     * @param socket - The WebSocket to listen to.
+     */
+    constructor(socket) {
+        super();
+        socket.addEventListener("message", (event) => {
+            try {
+                const msg = JSON.parse(event.data);
+                if (isHyperliquidMsg(msg)) {
+                    this.dispatchEvent(new CustomEvent(msg.channel, { detail: msg.data }));
+                }
+            }
+            catch {
+                // Ignore JSON parsing errors
+            }
+        });
+    }
+}
+/**
+ * Type guard for Hyperliquid messages.
+ * @param value - The value to check.
+ * @returns True if the value is a Hyperliquid message.
+ */
+function isHyperliquidMsg(value) {
+    return typeof value === "object" && value !== null &&
+        "channel" in value && typeof value.channel === "string";
+}

package/esm/src/transports/websocket/reconnecting_websocket.d.ts

@@ -0,0 +1,160 @@
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Configuration options for the `ReconnectingWebSocket`.
+ */
+export interface ReconnectingWebSocketOptions {
+    /**
+     * 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.
+     * 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) => 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) => MaybePromise<boolean>;
+    /**
+     * Message buffering strategy between reconnection attempts.
+     * @defaultValue `new FIFOMessageBuffer()`
+     */
+    messageBuffer?: MessageBufferStrategy;
+    /**
+     * Custom WebSocket constructor to use.
+     * @defaultValue `new WebSocket(url, protocols)`
+     */
+    WebSocketConstructor?: typeof WebSocket;
+}
+/**
+ * Message buffer strategy interface.
+ */
+export interface MessageBufferStrategy {
+    /** Array of buffered messages. */
+    messages: (string | ArrayBufferLike | Blob | ArrayBufferView)[];
+    /**
+     * Add a message to the buffer.
+     * @param data - The message to buffer.
+     */
+    push(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    /**
+     * Get and remove the next message from the buffer.
+     * @returns The next message or `undefined` if no more messages are available.
+     */
+    shift(): (string | ArrayBufferLike | Blob | ArrayBufferView) | undefined;
+    /** Clear all buffered messages. */
+    clear(): void;
+}
+/**
+ * A WebSocket that automatically reconnects when disconnected.
+ * Fully compatible with standard WebSocket API.
+ */
+export declare class ReconnectingWebSocket implements WebSocket {
+    /** Controller for handling connection termination */
+    protected terminationController: AbortController;
+    /** WebSocket protocols */
+    protected protocols?: string | string[];
+    /** The underlying WebSocket instance */
+    protected socket: WebSocket;
+    /** Current number of reconnection attempts */
+    protected reconnectCount: number;
+    /** Array of registered event listeners */
+    protected eventListeners: {
+        type: string;
+        listener: EventListenerOrEventListenerObject;
+        options?: boolean | AddEventListenerOptions;
+        listenerProxy: EventListenerOrEventListenerObject;
+    }[];
+    /** Configuration options */
+    reconnectOptions: Required<ReconnectingWebSocketOptions>;
+    /** An AbortSignal that is triggered when the connection is permanently closed */
+    readonly terminationSignal: AbortSignal;
+    /**
+     * 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: string | URL, protocols?: string | string[], options?: ReconnectingWebSocketOptions);
+    /**
+     * 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.
+     */
+    protected connectWithTimeout(url: string | URL, protocols: string | string[] | undefined, timeout: number): WebSocket;
+    /**
+     * Initializes the internal event listeners for the WebSocket.
+     */
+    protected initEventListeners(): void;
+    /**
+     * Clean up internal resources.
+     * @param reason - The reason for cleanup.
+     */
+    protected cleanup(reason: unknown): void;
+    /**
+     * 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.
+     */
+    protected isListenerMatch(a: {
+        type: string;
+        listener: EventListenerOrEventListenerObject;
+        options?: boolean | AddEventListenerOptions;
+    }, b: {
+        type: string;
+        listener: EventListenerOrEventListenerObject;
+        options?: boolean | AddEventListenerOptions;
+    }): boolean;
+    get url(): string;
+    get readyState(): number;
+    get bufferedAmount(): number;
+    get extensions(): string;
+    get protocol(): string;
+    get binaryType(): BinaryType;
+    set binaryType(value: BinaryType);
+    readonly CLOSED: 3;
+    readonly CLOSING: 2;
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    static readonly CLOSED: 3;
+    static readonly CLOSING: 2;
+    static readonly CONNECTING: 0;
+    static readonly OPEN: 1;
+    get onclose(): ((this: WebSocket, ev: CloseEvent) => any) | null;
+    set onclose(value: ((this: WebSocket, ev: CloseEvent) => any) | null);
+    get onerror(): ((this: WebSocket, ev: Event) => any) | null;
+    set onerror(value: ((this: WebSocket, ev: Event) => any) | null);
+    get onmessage(): ((this: WebSocket, ev: MessageEvent<any>) => any) | null;
+    set onmessage(value: ((this: WebSocket, ev: MessageEvent<any>) => any) | null);
+    get onopen(): ((this: WebSocket, ev: Event) => any) | null;
+    set onopen(value: ((this: WebSocket, ev: Event) => any) | null);
+    /**
+     * @param permanently - If true, the connection will be permanently closed. Default is true.
+     */
+    close(code?: number, reason?: string, permanently?: boolean): void;
+    /**
+     * @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): void;
+    addEventListener<K extends keyof WebSocketEventMap>(type: K, listener: (this: ReconnectingWebSocket, ev: WebSocketEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof WebSocketEventMap>(type: K, listener: (this: ReconnectingWebSocket, ev: WebSocketEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+    dispatchEvent(event: Event): boolean;
+}
+export {};
+//# sourceMappingURL=reconnecting_websocket.d.ts.map

package/esm/src/transports/websocket/reconnecting_websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnecting_websocket.d.ts","sourceRoot":"","sources":["../../../../src/src/transports/websocket/reconnecting_websocket.ts"],"names":[],"mappings":"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"}