@hardlydifficult/websocket 1.0.0

package/dist/ReconnectingWebSocket.d.ts

@@ -0,0 +1,68 @@
+import type { BackoffOptions, WebSocketEvents, WebSocketOptions } from "./types.js";
+/**
+ * Calculate exponential backoff delay for a given attempt number.
+ *
+ * @param attempt - Zero-based attempt index
+ * @param options - Backoff configuration
+ * @returns Delay in milliseconds, capped at maxDelayMs
+ */
+export declare function getBackoffDelay(attempt: number, options: Required<BackoffOptions>): number;
+/**
+ * A generic WebSocket client that automatically reconnects on disconnection,
+ * sends protocol-level pings for heartbeats, and parses JSON messages.
+ *
+ * @typeParam T - The shape of messages exchanged over the socket (JSON-serializable)
+ */
+export declare class ReconnectingWebSocket<T> {
+    private ws;
+    private readonly url;
+    private readonly backoff;
+    private readonly heartbeat;
+    private reconnectAttempt;
+    private shouldReconnect;
+    private heartbeatInterval;
+    private heartbeatTimeout;
+    private reconnectTimeout;
+    private readonly eventListeners;
+    constructor(options: WebSocketOptions);
+    /**
+     * Subscribe to a WebSocket lifecycle event.
+     * Multiple listeners per event are supported.
+     * Returns an unsubscribe function.
+     */
+    on<K extends keyof WebSocketEvents<T>>(event: K, listener: WebSocketEvents<T>[K]): () => void;
+    /**
+     * Connect to the WebSocket server.
+     * Idempotent — no-op if already connected.
+     * If a reconnect timer is pending, cancels it and connects immediately,
+     * resetting the attempt counter.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the server and stop all reconnection attempts.
+     * Closes the socket with code 1000.
+     */
+    disconnect(): void;
+    /**
+     * Send a message as JSON. No-op if not currently connected.
+     */
+    send(message: T): void;
+    /**
+     * Prevent reconnection without closing the current connection.
+     * Useful for draining: deliver in-flight results but do not reconnect if the socket drops.
+     */
+    stopReconnecting(): void;
+    /** Whether the socket is currently open */
+    get connected(): boolean;
+    private onOpen;
+    private onClose;
+    private onError;
+    private onPong;
+    private onMessage;
+    private sendHeartbeat;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private emit;
+}
+//# sourceMappingURL=ReconnectingWebSocket.d.ts.map

package/dist/ReconnectingWebSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReconnectingWebSocket.d.ts","sourceRoot":"","sources":["../src/ReconnectingWebSocket.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EAEd,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAapB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,GAChC,MAAM,CAGR;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,iBAAiB,CAA+C;IACxE,OAAO,CAAC,gBAAgB,CAA8C;IACtE,OAAO,CAAC,gBAAgB,CAA8C;IAEtE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAG3B;gBAEQ,OAAO,EAAE,gBAAgB;IAMrC;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,eAAe,CAAC,CAAC,CAAC,EACnC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9B,MAAM,IAAI;IAYb;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAmCf;;;OAGG;IACH,UAAU,IAAI,IAAI;IAelB;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;IAMtB;;;OAGG;IACH,gBAAgB,IAAI,IAAI;IAIxB,2CAA2C;IAC3C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,SAAS;IAiBjB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,IAAI;CAab"}

package/dist/ReconnectingWebSocket.js

@@ -0,0 +1,220 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReconnectingWebSocket = void 0;
+exports.getBackoffDelay = getBackoffDelay;
+const ws_1 = __importDefault(require("ws"));
+const BACKOFF_DEFAULTS = {
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    multiplier: 2,
+};
+const HEARTBEAT_DEFAULTS = {
+    intervalMs: 30000,
+    timeoutMs: 10000,
+};
+/**
+ * Calculate exponential backoff delay for a given attempt number.
+ *
+ * @param attempt - Zero-based attempt index
+ * @param options - Backoff configuration
+ * @returns Delay in milliseconds, capped at maxDelayMs
+ */
+function getBackoffDelay(attempt, options) {
+    const delay = options.initialDelayMs * Math.pow(options.multiplier, attempt);
+    return Math.min(delay, options.maxDelayMs);
+}
+/**
+ * A generic WebSocket client that automatically reconnects on disconnection,
+ * sends protocol-level pings for heartbeats, and parses JSON messages.
+ *
+ * @typeParam T - The shape of messages exchanged over the socket (JSON-serializable)
+ */
+class ReconnectingWebSocket {
+    ws = null;
+    url;
+    backoff;
+    heartbeat;
+    reconnectAttempt = 0;
+    shouldReconnect = true;
+    heartbeatInterval = null;
+    heartbeatTimeout = null;
+    reconnectTimeout = null;
+    eventListeners = new Map();
+    constructor(options) {
+        this.url = options.url;
+        this.backoff = { ...BACKOFF_DEFAULTS, ...options.backoff };
+        this.heartbeat = { ...HEARTBEAT_DEFAULTS, ...options.heartbeat };
+    }
+    /**
+     * Subscribe to a WebSocket lifecycle event.
+     * Multiple listeners per event are supported.
+     * Returns an unsubscribe function.
+     */
+    on(event, listener) {
+        let set = this.eventListeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.eventListeners.set(event, set);
+        }
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+        };
+    }
+    /**
+     * Connect to the WebSocket server.
+     * Idempotent — no-op if already connected.
+     * If a reconnect timer is pending, cancels it and connects immediately,
+     * resetting the attempt counter.
+     */
+    connect() {
+        if (this.ws) {
+            return;
+        }
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+            this.reconnectAttempt = 0;
+        }
+        this.shouldReconnect = true;
+        this.ws = new ws_1.default(this.url);
+        this.ws.on("open", () => {
+            this.onOpen();
+        });
+        this.ws.on("message", (data) => {
+            this.onMessage(data);
+        });
+        this.ws.on("close", (code, reason) => {
+            this.onClose(code, reason.toString());
+        });
+        this.ws.on("error", (error) => {
+            this.onError(error);
+        });
+        this.ws.on("pong", () => {
+            this.onPong();
+        });
+    }
+    /**
+     * Disconnect from the server and stop all reconnection attempts.
+     * Closes the socket with code 1000.
+     */
+    disconnect() {
+        this.shouldReconnect = false;
+        this.stopHeartbeat();
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.ws) {
+            this.ws.close(1000, "Client disconnecting");
+            this.ws = null;
+        }
+    }
+    /**
+     * Send a message as JSON. No-op if not currently connected.
+     */
+    send(message) {
+        if (this.ws?.readyState === ws_1.default.OPEN) {
+            this.ws.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Prevent reconnection without closing the current connection.
+     * Useful for draining: deliver in-flight results but do not reconnect if the socket drops.
+     */
+    stopReconnecting() {
+        this.shouldReconnect = false;
+    }
+    /** Whether the socket is currently open */
+    get connected() {
+        return this.ws?.readyState === ws_1.default.OPEN;
+    }
+    onOpen() {
+        this.reconnectAttempt = 0;
+        this.startHeartbeat();
+        this.emit("open");
+    }
+    onClose(code, reason) {
+        this.ws = null;
+        this.stopHeartbeat();
+        this.emit("close", code, reason);
+        if (this.shouldReconnect) {
+            this.scheduleReconnect();
+        }
+    }
+    onError(error) {
+        this.emit("error", error);
+    }
+    onPong() {
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = null;
+        }
+    }
+    onMessage(data) {
+        try {
+            let raw;
+            if (Buffer.isBuffer(data)) {
+                raw = data.toString("utf8");
+            }
+            else if (Array.isArray(data)) {
+                raw = Buffer.concat(data).toString("utf8");
+            }
+            else {
+                raw = Buffer.from(data).toString("utf8");
+            }
+            const parsed = JSON.parse(raw);
+            this.emit("message", parsed);
+        }
+        catch (err) {
+            this.emit("error", err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    sendHeartbeat() {
+        if (this.ws?.readyState === ws_1.default.OPEN) {
+            this.ws.ping();
+            this.heartbeatTimeout = setTimeout(() => {
+                this.ws?.terminate();
+            }, this.heartbeat.timeoutMs);
+        }
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatInterval = setInterval(() => {
+            this.sendHeartbeat();
+        }, this.heartbeat.intervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = null;
+        }
+    }
+    scheduleReconnect() {
+        const delay = getBackoffDelay(this.reconnectAttempt, this.backoff);
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectAttempt++;
+            this.reconnectTimeout = null;
+            this.ws = null;
+            this.connect();
+        }, delay);
+    }
+    emit(event, ...args) {
+        const set = this.eventListeners.get(event);
+        if (!set) {
+            return;
+        }
+        for (const listener of set) {
+            listener(...args);
+        }
+    }
+}
+exports.ReconnectingWebSocket = ReconnectingWebSocket;
+//# sourceMappingURL=ReconnectingWebSocket.js.map

package/dist/ReconnectingWebSocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReconnectingWebSocket.js","sourceRoot":"","sources":["../src/ReconnectingWebSocket.ts"],"names":[],"mappings":";;;;;;AA2BA,0CAMC;AAjCD,4CAA2B;AAS3B,MAAM,gBAAgB,GAA6B;IACjD,cAAc,EAAE,IAAI;IACpB,UAAU,EAAE,KAAK;IACjB,UAAU,EAAE,CAAC;CACd,CAAC;AAEF,MAAM,kBAAkB,GAA+B;IACrD,UAAU,EAAE,KAAK;IACjB,SAAS,EAAE,KAAK;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,eAAe,CAC7B,OAAe,EACf,OAAiC;IAEjC,MAAM,KAAK,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC7E,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAa,qBAAqB;IACxB,EAAE,GAAqB,IAAI,CAAC;IACnB,GAAG,CAAS;IACZ,OAAO,CAA2B;IAClC,SAAS,CAA6B;IAC/C,gBAAgB,GAAG,CAAC,CAAC;IACrB,eAAe,GAAG,IAAI,CAAC;IACvB,iBAAiB,GAA0C,IAAI,CAAC;IAChE,gBAAgB,GAAyC,IAAI,CAAC;IAC9D,gBAAgB,GAAyC,IAAI,CAAC;IAErD,cAAc,GAAG,IAAI,GAAG,EAGtC,CAAC;IAEJ,YAAY,OAAyB;QACnC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3D,IAAI,CAAC,SAAS,GAAG,EAAE,GAAG,kBAAkB,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IACnE,CAAC;IAED;;;;OAIG;IACH,EAAE,CACA,KAAQ,EACR,QAA+B;QAE/B,IAAI,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClB,OAAO,GAAG,EAAE;YACV,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACZ,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACpC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;YAC7B,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,EAAE,GAAG,IAAI,YAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAuB,EAAE,EAAE;YAChD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAY,EAAE,MAAc,EAAE,EAAE;YACnD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;YACnC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;QAC7B,IAAI,CAAC,aAAa,EAAE,CAAC;QAErB,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACpC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC;QAED,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;YAC5C,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,OAAU;QACb,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,YAAS,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;IAC/B,CAAC;IAED,2CAA2C;IAC3C,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,YAAS,CAAC,IAAI,CAAC;IAChD,CAAC;IAEO,MAAM;QACZ,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IAEO,OAAO,CAAC,IAAY,EAAE,MAAc;QAC1C,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;QACf,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAEjC,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IAEO,OAAO,CAAC,KAAY;QAC1B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAEO,MAAM;QACZ,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACpC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC;IACH,CAAC;IAEO,SAAS,CAAC,IAAuB;QACvC,IAAI,CAAC;YACH,IAAI,GAAW,CAAC;YAChB,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC9B,CAAC;iBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC7C,CAAC;iBAAM,CAAC;gBACN,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;YACpC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAEO,aAAa;QACnB,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,YAAS,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YACf,IAAI,CAAC,gBAAgB,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC;YACvB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAEO,cAAc;QACpB,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC,iBAAiB,GAAG,WAAW,CAAC,GAAG,EAAE;YACxC,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAChC,CAAC;IAEO,aAAa;QACnB,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC3B,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YACtC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;QAChC,CAAC;QACD,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACpC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC;IACH,CAAC;IAEO,iBAAiB;QACvB,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACnE,IAAI,CAAC,gBAAgB,GAAG,UAAU,CAAC,GAAG,EAAE;YACtC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACxB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;YAC7B,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;YACf,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;IAMO,IAAI,CAAC,KAA+B,EAAE,GAAG,IAAe;QAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;YAC1B,QAAsC,CAAC,GAAG,IAAI,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;CACF;AA1ND,sDA0NC"}

package/dist/RequestTracker.d.ts

@@ -0,0 +1,40 @@
+import type { RequestTrackerEvents } from "./types.js";
+/**
+ * Tracks active requests and manages draining state.
+ *
+ * Centralizes the pattern of rejecting new work during drain
+ * and notifying listeners when the last request completes.
+ */
+export declare class RequestTracker {
+    private _active;
+    private _draining;
+    private readonly listeners;
+    /**
+     * Subscribe to a RequestTracker event.
+     * Returns an unsubscribe function.
+     */
+    on<K extends keyof RequestTrackerEvents>(event: K, listener: RequestTrackerEvents[K]): () => void;
+    /**
+     * Try to accept a new request.
+     * Returns false if draining — caller should send a rejection response.
+     */
+    tryAccept(): boolean;
+    /**
+     * Mark a request as complete.
+     * Decrements the active count and emits drained when the last
+     * request finishes during a drain.
+     */
+    complete(): void;
+    /**
+     * Enter draining mode — no new requests will be accepted.
+     * Idempotent: subsequent calls are ignored.
+     * Emits draining immediately and drained when active reaches zero.
+     */
+    startDraining(reason: string): void;
+    /** Whether the tracker is in draining mode */
+    get draining(): boolean;
+    /** Number of currently active requests */
+    get active(): number;
+    private emit;
+}
+//# sourceMappingURL=RequestTracker.d.ts.map

package/dist/RequestTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestTracker.d.ts","sourceRoot":"","sources":["../src/RequestTracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGtB;IAEJ;;;OAGG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,EACrC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAChC,MAAM,IAAI;IAYb;;;OAGG;IACH,SAAS,IAAI,OAAO;IAQpB;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAOhB;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAWnC,8CAA8C;IAC9C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,0CAA0C;IAC1C,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,CAAC,IAAI;CAWb"}

package/dist/RequestTracker.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestTracker = void 0;
+/**
+ * Tracks active requests and manages draining state.
+ *
+ * Centralizes the pattern of rejecting new work during drain
+ * and notifying listeners when the last request completes.
+ */
+class RequestTracker {
+    _active = 0;
+    _draining = false;
+    listeners = new Map();
+    /**
+     * Subscribe to a RequestTracker event.
+     * Returns an unsubscribe function.
+     */
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+        };
+    }
+    /**
+     * Try to accept a new request.
+     * Returns false if draining — caller should send a rejection response.
+     */
+    tryAccept() {
+        if (this._draining) {
+            return false;
+        }
+        this._active++;
+        return true;
+    }
+    /**
+     * Mark a request as complete.
+     * Decrements the active count and emits drained when the last
+     * request finishes during a drain.
+     */
+    complete() {
+        this._active--;
+        if (this._draining && this._active === 0) {
+            this.emit("drained");
+        }
+    }
+    /**
+     * Enter draining mode — no new requests will be accepted.
+     * Idempotent: subsequent calls are ignored.
+     * Emits draining immediately and drained when active reaches zero.
+     */
+    startDraining(reason) {
+        if (this._draining) {
+            return;
+        }
+        this._draining = true;
+        this.emit("draining", reason);
+        if (this._active === 0) {
+            this.emit("drained");
+        }
+    }
+    /** Whether the tracker is in draining mode */
+    get draining() {
+        return this._draining;
+    }
+    /** Number of currently active requests */
+    get active() {
+        return this._active;
+    }
+    emit(event, ...args) {
+        const set = this.listeners.get(event);
+        if (!set) {
+            return;
+        }
+        for (const listener of set) {
+            listener(...args);
+        }
+    }
+}
+exports.RequestTracker = RequestTracker;
+//# sourceMappingURL=RequestTracker.js.map

package/dist/RequestTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestTracker.js","sourceRoot":"","sources":["../src/RequestTracker.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,MAAa,cAAc;IACjB,OAAO,GAAG,CAAC,CAAC;IACZ,SAAS,GAAG,KAAK,CAAC;IACT,SAAS,GAAG,IAAI,GAAG,EAGjC,CAAC;IAEJ;;;OAGG;IACH,EAAE,CACA,KAAQ,EACR,QAAiC;QAEjC,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClB,OAAO,GAAG,EAAE;YACV,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,SAAS;QACP,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACN,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,MAAc;QAC1B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,0CAA0C;IAC1C,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAIO,IAAI,CAAC,KAAiC,EAAE,GAAG,IAAe;QAChE,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;YAC1B,QAAsC,CAAC,GAAG,IAAI,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;CACF;AAxFD,wCAwFC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ReconnectingWebSocket } from "./ReconnectingWebSocket.js";
+export { RequestTracker } from "./RequestTracker.js";
+export type { BackoffOptions, HeartbeatOptions, WebSocketOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestTracker = exports.ReconnectingWebSocket = void 0;
+var ReconnectingWebSocket_js_1 = require("./ReconnectingWebSocket.js");
+Object.defineProperty(exports, "ReconnectingWebSocket", { enumerable: true, get: function () { return ReconnectingWebSocket_js_1.ReconnectingWebSocket; } });
+var RequestTracker_js_1 = require("./RequestTracker.js");
+Object.defineProperty(exports, "RequestTracker", { enumerable: true, get: function () { return RequestTracker_js_1.RequestTracker; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAC9B,yDAAqD;AAA5C,mHAAA,cAAc,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Backoff configuration for reconnection delays.
+ */
+export interface BackoffOptions {
+    /** Initial delay in milliseconds. Default: 1000 */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds. Default: 30000 */
+    maxDelayMs?: number;
+    /** Multiplier applied per attempt. Default: 2 */
+    multiplier?: number;
+}
+/**
+ * Heartbeat configuration for detecting dead connections.
+ */
+export interface HeartbeatOptions {
+    /** Interval between pings in milliseconds. Default: 30000 */
+    intervalMs?: number;
+    /** Time to wait for pong before terminating. Default: 10000 */
+    timeoutMs?: number;
+}
+/**
+ * Configuration options for ReconnectingWebSocket.
+ */
+export interface WebSocketOptions {
+    /** WebSocket server URL */
+    url: string;
+    /** Backoff configuration for reconnection */
+    backoff?: BackoffOptions;
+    /** Heartbeat configuration */
+    heartbeat?: HeartbeatOptions;
+}
+/**
+ * Event callbacks for ReconnectingWebSocket.
+ */
+export interface WebSocketEvents<T> {
+    /** Fired when the connection is established */
+    open: () => void;
+    /** Fired when the connection is closed */
+    close: (code: number, reason: string) => void;
+    /** Fired on connection or parse errors */
+    error: (error: Error) => void;
+    /** Fired when a message is received and parsed */
+    message: (data: T) => void;
+}
+/**
+ * Event callbacks for RequestTracker.
+ */
+export interface RequestTrackerEvents {
+    /** Fired when draining mode is entered */
+    draining: (reason: string) => void;
+    /** Fired when all active requests complete during drain */
+    drained: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,0CAA0C;IAC1C,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,0CAA0C;IAC1C,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,kDAAkD;IAClD,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hardlydifficult/websocket",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "ws": "8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.2.3",
+    "@types/ws": "8.18.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}