@culpeo/async-ws 0.2.0 → 1.1.0

package/dist/cjs/index.cjs

@@ -64,6 +64,33 @@ function attachListeners(socket, onOpen, onMessage, onClose, onError) {
 function socketClose(socket, code, reason) {
     socket.close(code, reason);
 }
+function socketTerminate(socket) {
+    socket.terminate();
+}
+function socketPing(socket) {
+    socket.ping();
+}
+function attachPongListener(socket, onPong) {
+    const handler = () => onPong();
+    socket.on("pong", handler);
+    return () => socket.off("pong", handler);
+}
+function adoptSocket(rawSocket) {
+    const s = rawSocket;
+    if (!s ||
+        typeof s !== "object" ||
+        typeof s.send !== "function" ||
+        typeof s.close !== "function" ||
+        typeof s.addEventListener !== "function" ||
+        typeof s.removeEventListener !== "function") {
+        throw new Error("Expected a WebSocket-compatible object (must have send, close, addEventListener, removeEventListener).");
+    }
+    if (s.readyState !== ws.WebSocket.OPEN) {
+        throw new Error("Socket must be in the OPEN state to be adopted. " +
+            "Call fromSocket() immediately in the server's connection handler.");
+    }
+    return rawSocket;
+}
 ws.WebSocket.OPEN;
 
 /**
@@ -85,7 +112,75 @@ class WebSocketClient {
         this.terminalError = null;
         this.closeInfo = null;
         this.removeListeners = null;
+        this.keepAliveTimer = null;
+        this.pongTimer = null;
+        this.removePongListener = null;
+        this.connectionId = 0;
         this.maxBufferSize = options?.maxBufferSize ?? 0;
+        if (options?.keepAlive) {
+            if (options.keepAlive.interval <= 0) {
+                throw new Error("keepAlive.interval must be greater than 0.");
+            }
+            if (options.keepAlive.timeout !== undefined &&
+                options.keepAlive.timeout <= 0) {
+                throw new Error("keepAlive.timeout must be greater than 0.");
+            }
+            this.keepAliveConfig = options.keepAlive;
+        }
+    }
+    /**
+     * Adopt an already-open WebSocket (e.g. from a `WebSocketServer` connection event).
+     *
+     * Returns a `WebSocketClient` in the "open" state, ready to send/receive.
+     * The client takes ownership of the socket lifecycle: calling `close()`
+     * will close the underlying socket.
+     *
+     * **Node.js only.** Throws in browser builds.
+     *
+     * Call this immediately in the server's `connection` handler to avoid
+     * missing messages:
+     *
+     * ```ts
+     * wss.on("connection", (socket) => {
+     *   const client = WebSocketClient.fromSocket(socket);
+     *   const msg = await client.receive();
+     * });
+     * ```
+     */
+    static fromSocket(rawSocket, options) {
+        const client = new WebSocketClient(options);
+        const socket = adoptSocket(rawSocket);
+        client.socket = socket;
+        setBinaryType(socket);
+        client.state = "open";
+        const currentConnectionId = ++client.connectionId;
+        client.removeListeners = attachListeners(socket, 
+        // onOpen — already open, won't fire
+        () => { }, 
+        // onMessage
+        (data, binary) => {
+            client.enqueueMessage({ data, binary });
+        }, 
+        // onClose
+        (code, reason, wasClean) => {
+            if (currentConnectionId !== client.connectionId)
+                return;
+            client.closeInfo = { code, reason, wasClean };
+            client.state = "closed";
+            client.cleanup();
+            if (client.buffer.length === 0) {
+                client.rejectAllWaiters(new Error(`WebSocket closed (code: ${code}, reason: ${reason})`));
+            }
+        }, 
+        // onError
+        (error) => {
+            if (currentConnectionId !== client.connectionId)
+                return;
+            client.terminalError = error;
+            client.rejectAllWaiters(error);
+        });
+        client.startKeepAlive();
+        return client;
     }
     /** Current connection state. */
     get readyState() {
@@ -95,16 +190,41 @@ class WebSocketClient {
     get lastCloseInfo() {
         return this.closeInfo;
     }
+    /** The negotiated subprotocol, or empty string if none. */
+    get protocol() {
+        return this.socket?.protocol ?? "";
+    }
+    /** The URL of the WebSocket connection. */
+    get url() {
+        return this.socket?.url ?? "";
+    }
+    /** The number of bytes of data queued for sending. */
+    get bufferedAmount() {
+        return this.socket?.bufferedAmount ?? 0;
+    }
+    /** The extensions negotiated by the server. */
+    get extensions() {
+        return this.socket?.extensions ?? "";
+    }
     /**
      * Connect to a WebSocket server.
      * Resolves when the connection is open. Rejects on error.
      */
     connect(url, options) {
-        if (this.state !== "idle" && this.state !== "closed" && this.state !== "errored") {
+        if (this.state !== "idle" &&
+            this.state !== "closed" &&
+            this.state !== "errored") {
             return Promise.reject(new Error(`Cannot connect: client is in "${this.state}" state`));
         }
+        if (options?.timeout !== undefined && options.timeout <= 0) {
+            return Promise.reject(new Error("timeout must be greater than 0."));
+        }
+        if (options?.signal?.aborted) {
+            return Promise.reject(new Error("Connection aborted."));
+        }
         this.reset();
         this.state = "connecting";
+        const currentConnectionId = ++this.connectionId;
         return new Promise((resolve, reject) => {
             try {
                 this.socket = createWebSocket(url, options);
@@ -112,19 +232,63 @@ class WebSocketClient {
             }
             catch (err) {
                 this.state = "errored";
-                this.terminalError = err instanceof Error ? err : new Error(String(err));
+                this.terminalError =
+                    err instanceof Error ? err : new Error(String(err));
                 reject(this.terminalError);
                 return;
             }
             let settled = false;
+            let timeoutId = null;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutId !== null) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                if (options?.signal) {
+                    options.signal.removeEventListener("abort", onAbort);
+                }
+                fn();
+            };
+            const onAbort = () => {
+                settle(() => {
+                    this.state = "closed";
+                    this.terminalError = new Error("Connection aborted.");
+                    if (this.socket) {
+                        socketTerminate(this.socket);
+                    }
+                    // Don't call cleanup() here — socketTerminate() emits
+                    // error/close asynchronously; let onClose handle cleanup.
+                    reject(this.terminalError);
+                });
+            };
+            if (options?.timeout !== undefined) {
+                timeoutId = setTimeout(() => {
+                    settle(() => {
+                        this.state = "closed";
+                        this.terminalError = new Error(`Connection timed out after ${options.timeout}ms.`);
+                        if (this.socket) {
+                            socketTerminate(this.socket);
+                        }
+                        // Don't call cleanup() here — socketTerminate() emits
+                        // error/close asynchronously; let onClose handle cleanup.
+                        reject(this.terminalError);
+                    });
+                }, options.timeout);
+            }
+            if (options?.signal) {
+                options.signal.addEventListener("abort", onAbort, { once: true });
+            }
             this.removeListeners = attachListeners(this.socket, 
             // onOpen
             () => {
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     this.state = "open";
+                    this.startKeepAlive();
                     resolve();
-                }
+                });
             }, 
             // onMessage
             (data, binary) => {
@@ -132,14 +296,16 @@ class WebSocketClient {
             }, 
             // onClose
             (code, reason, wasClean) => {
+                // Ignore close events from a stale connection (e.g., after
+                // timeout/abort triggered a reconnect on the same client).
+                if (currentConnectionId !== this.connectionId)
+                    return;
                 this.closeInfo = { code, reason, wasClean };
-                this.state;
                 this.state = "closed";
                 this.cleanup();
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     reject(new Error(`WebSocket closed before opening (code: ${code}, reason: ${reason})`));
-                }
+                });
                 // Only reject pending waiters once buffer is drained
                 if (this.buffer.length === 0) {
                     this.rejectAllWaiters(new Error(`WebSocket closed (code: ${code}, reason: ${reason})`));
@@ -147,11 +313,13 @@ class WebSocketClient {
             }, 
             // onError
             (error) => {
+                // Ignore error events from a stale connection.
+                if (currentConnectionId !== this.connectionId)
+                    return;
                 this.terminalError = error;
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     reject(error);
-                }
+                });
                 // Reject any pending receive() waiters immediately
                 this.rejectAllWaiters(error);
                 // Don't call cleanup() here — per spec, a close event always
@@ -199,7 +367,9 @@ class WebSocketClient {
      * Resolves when the close handshake completes.
      */
     close(code, reason) {
-        if (this.state === "closed" || this.state === "idle" || this.state === "errored") {
+        if (this.state === "closed" ||
+            this.state === "idle" ||
+            this.state === "errored") {
             return Promise.resolve();
         }
         if (!this.socket) {
@@ -209,7 +379,9 @@ class WebSocketClient {
             // Already closing — wait for the close event via a one-shot listener
             return new Promise((resolve) => {
                 if (this.socket) {
-                    this.socket.addEventListener("close", () => resolve(), { once: true });
+                    this.socket.addEventListener("close", () => resolve(), {
+                        once: true,
+                    });
                 }
                 else {
                     resolve();
@@ -274,11 +446,55 @@ class WebSocketClient {
             waiter.reject(error);
         }
     }
+    startKeepAlive() {
+        if (!this.keepAliveConfig || !this.socket)
+            return;
+        const { interval, timeout } = this.keepAliveConfig;
+        const pongTimeout = timeout ?? interval;
+        this.removePongListener = attachPongListener(this.socket, () => {
+            if (this.pongTimer !== null) {
+                clearTimeout(this.pongTimer);
+                this.pongTimer = null;
+            }
+        });
+        this.keepAliveTimer = setInterval(() => {
+            if (this.state !== "open" || !this.socket)
+                return;
+            socketPing(this.socket);
+            // Clear any existing pong watchdog before starting a new one
+            // to prevent multiple timers when timeout > interval.
+            if (this.pongTimer !== null) {
+                clearTimeout(this.pongTimer);
+            }
+            this.pongTimer = setTimeout(() => {
+                if (this.state === "open" && this.socket) {
+                    this.terminalError = new Error(`Keep-alive timeout: no pong received within ${pongTimeout}ms.`);
+                    socketTerminate(this.socket);
+                }
+            }, pongTimeout);
+        }, interval);
+    }
+    stopKeepAlive() {
+        if (this.keepAliveTimer !== null) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = null;
+        }
+        if (this.pongTimer !== null) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+        if (this.removePongListener) {
+            this.removePongListener();
+            this.removePongListener = null;
+        }
+    }
     cleanup() {
+        this.stopKeepAlive();
         if (this.removeListeners) {
             this.removeListeners();
             this.removeListeners = null;
         }
+        this.socket = null;
     }
     reset() {
         this.socket = null;
@@ -287,6 +503,7 @@ class WebSocketClient {
         this.terminalError = null;
         this.closeInfo = null;
         this.removeListeners = null;
+        this.stopKeepAlive();
     }
 }
 

package/dist/esm/index.js

@@ -62,6 +62,33 @@ function attachListeners(socket, onOpen, onMessage, onClose, onError) {
 function socketClose(socket, code, reason) {
     socket.close(code, reason);
 }
+function socketTerminate(socket) {
+    socket.terminate();
+}
+function socketPing(socket) {
+    socket.ping();
+}
+function attachPongListener(socket, onPong) {
+    const handler = () => onPong();
+    socket.on("pong", handler);
+    return () => socket.off("pong", handler);
+}
+function adoptSocket(rawSocket) {
+    const s = rawSocket;
+    if (!s ||
+        typeof s !== "object" ||
+        typeof s.send !== "function" ||
+        typeof s.close !== "function" ||
+        typeof s.addEventListener !== "function" ||
+        typeof s.removeEventListener !== "function") {
+        throw new Error("Expected a WebSocket-compatible object (must have send, close, addEventListener, removeEventListener).");
+    }
+    if (s.readyState !== WebSocket.OPEN) {
+        throw new Error("Socket must be in the OPEN state to be adopted. " +
+            "Call fromSocket() immediately in the server's connection handler.");
+    }
+    return rawSocket;
+}
 WebSocket.OPEN;
 
 /**
@@ -83,7 +110,75 @@ class WebSocketClient {
         this.terminalError = null;
         this.closeInfo = null;
         this.removeListeners = null;
+        this.keepAliveTimer = null;
+        this.pongTimer = null;
+        this.removePongListener = null;
+        this.connectionId = 0;
         this.maxBufferSize = options?.maxBufferSize ?? 0;
+        if (options?.keepAlive) {
+            if (options.keepAlive.interval <= 0) {
+                throw new Error("keepAlive.interval must be greater than 0.");
+            }
+            if (options.keepAlive.timeout !== undefined &&
+                options.keepAlive.timeout <= 0) {
+                throw new Error("keepAlive.timeout must be greater than 0.");
+            }
+            this.keepAliveConfig = options.keepAlive;
+        }
+    }
+    /**
+     * Adopt an already-open WebSocket (e.g. from a `WebSocketServer` connection event).
+     *
+     * Returns a `WebSocketClient` in the "open" state, ready to send/receive.
+     * The client takes ownership of the socket lifecycle: calling `close()`
+     * will close the underlying socket.
+     *
+     * **Node.js only.** Throws in browser builds.
+     *
+     * Call this immediately in the server's `connection` handler to avoid
+     * missing messages:
+     *
+     * ```ts
+     * wss.on("connection", (socket) => {
+     *   const client = WebSocketClient.fromSocket(socket);
+     *   const msg = await client.receive();
+     * });
+     * ```
+     */
+    static fromSocket(rawSocket, options) {
+        const client = new WebSocketClient(options);
+        const socket = adoptSocket(rawSocket);
+        client.socket = socket;
+        setBinaryType(socket);
+        client.state = "open";
+        const currentConnectionId = ++client.connectionId;
+        client.removeListeners = attachListeners(socket, 
+        // onOpen — already open, won't fire
+        () => { }, 
+        // onMessage
+        (data, binary) => {
+            client.enqueueMessage({ data, binary });
+        }, 
+        // onClose
+        (code, reason, wasClean) => {
+            if (currentConnectionId !== client.connectionId)
+                return;
+            client.closeInfo = { code, reason, wasClean };
+            client.state = "closed";
+            client.cleanup();
+            if (client.buffer.length === 0) {
+                client.rejectAllWaiters(new Error(`WebSocket closed (code: ${code}, reason: ${reason})`));
+            }
+        }, 
+        // onError
+        (error) => {
+            if (currentConnectionId !== client.connectionId)
+                return;
+            client.terminalError = error;
+            client.rejectAllWaiters(error);
+        });
+        client.startKeepAlive();
+        return client;
     }
     /** Current connection state. */
     get readyState() {
@@ -93,16 +188,41 @@ class WebSocketClient {
     get lastCloseInfo() {
         return this.closeInfo;
     }
+    /** The negotiated subprotocol, or empty string if none. */
+    get protocol() {
+        return this.socket?.protocol ?? "";
+    }
+    /** The URL of the WebSocket connection. */
+    get url() {
+        return this.socket?.url ?? "";
+    }
+    /** The number of bytes of data queued for sending. */
+    get bufferedAmount() {
+        return this.socket?.bufferedAmount ?? 0;
+    }
+    /** The extensions negotiated by the server. */
+    get extensions() {
+        return this.socket?.extensions ?? "";
+    }
     /**
      * Connect to a WebSocket server.
      * Resolves when the connection is open. Rejects on error.
      */
     connect(url, options) {
-        if (this.state !== "idle" && this.state !== "closed" && this.state !== "errored") {
+        if (this.state !== "idle" &&
+            this.state !== "closed" &&
+            this.state !== "errored") {
             return Promise.reject(new Error(`Cannot connect: client is in "${this.state}" state`));
         }
+        if (options?.timeout !== undefined && options.timeout <= 0) {
+            return Promise.reject(new Error("timeout must be greater than 0."));
+        }
+        if (options?.signal?.aborted) {
+            return Promise.reject(new Error("Connection aborted."));
+        }
         this.reset();
         this.state = "connecting";
+        const currentConnectionId = ++this.connectionId;
         return new Promise((resolve, reject) => {
             try {
                 this.socket = createWebSocket(url, options);
@@ -110,19 +230,63 @@ class WebSocketClient {
             }
             catch (err) {
                 this.state = "errored";
-                this.terminalError = err instanceof Error ? err : new Error(String(err));
+                this.terminalError =
+                    err instanceof Error ? err : new Error(String(err));
                 reject(this.terminalError);
                 return;
             }
             let settled = false;
+            let timeoutId = null;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutId !== null) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                if (options?.signal) {
+                    options.signal.removeEventListener("abort", onAbort);
+                }
+                fn();
+            };
+            const onAbort = () => {
+                settle(() => {
+                    this.state = "closed";
+                    this.terminalError = new Error("Connection aborted.");
+                    if (this.socket) {
+                        socketTerminate(this.socket);
+                    }
+                    // Don't call cleanup() here — socketTerminate() emits
+                    // error/close asynchronously; let onClose handle cleanup.
+                    reject(this.terminalError);
+                });
+            };
+            if (options?.timeout !== undefined) {
+                timeoutId = setTimeout(() => {
+                    settle(() => {
+                        this.state = "closed";
+                        this.terminalError = new Error(`Connection timed out after ${options.timeout}ms.`);
+                        if (this.socket) {
+                            socketTerminate(this.socket);
+                        }
+                        // Don't call cleanup() here — socketTerminate() emits
+                        // error/close asynchronously; let onClose handle cleanup.
+                        reject(this.terminalError);
+                    });
+                }, options.timeout);
+            }
+            if (options?.signal) {
+                options.signal.addEventListener("abort", onAbort, { once: true });
+            }
             this.removeListeners = attachListeners(this.socket, 
             // onOpen
             () => {
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     this.state = "open";
+                    this.startKeepAlive();
                     resolve();
-                }
+                });
             }, 
             // onMessage
             (data, binary) => {
@@ -130,14 +294,16 @@ class WebSocketClient {
             }, 
             // onClose
             (code, reason, wasClean) => {
+                // Ignore close events from a stale connection (e.g., after
+                // timeout/abort triggered a reconnect on the same client).
+                if (currentConnectionId !== this.connectionId)
+                    return;
                 this.closeInfo = { code, reason, wasClean };
-                this.state;
                 this.state = "closed";
                 this.cleanup();
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     reject(new Error(`WebSocket closed before opening (code: ${code}, reason: ${reason})`));
-                }
+                });
                 // Only reject pending waiters once buffer is drained
                 if (this.buffer.length === 0) {
                     this.rejectAllWaiters(new Error(`WebSocket closed (code: ${code}, reason: ${reason})`));
@@ -145,11 +311,13 @@ class WebSocketClient {
             }, 
             // onError
             (error) => {
+                // Ignore error events from a stale connection.
+                if (currentConnectionId !== this.connectionId)
+                    return;
                 this.terminalError = error;
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     reject(error);
-                }
+                });
                 // Reject any pending receive() waiters immediately
                 this.rejectAllWaiters(error);
                 // Don't call cleanup() here — per spec, a close event always
@@ -197,7 +365,9 @@ class WebSocketClient {
      * Resolves when the close handshake completes.
      */
     close(code, reason) {
-        if (this.state === "closed" || this.state === "idle" || this.state === "errored") {
+        if (this.state === "closed" ||
+            this.state === "idle" ||
+            this.state === "errored") {
             return Promise.resolve();
         }
         if (!this.socket) {
@@ -207,7 +377,9 @@ class WebSocketClient {
             // Already closing — wait for the close event via a one-shot listener
             return new Promise((resolve) => {
                 if (this.socket) {
-                    this.socket.addEventListener("close", () => resolve(), { once: true });
+                    this.socket.addEventListener("close", () => resolve(), {
+                        once: true,
+                    });
                 }
                 else {
                     resolve();
@@ -272,11 +444,55 @@ class WebSocketClient {
             waiter.reject(error);
         }
     }
+    startKeepAlive() {
+        if (!this.keepAliveConfig || !this.socket)
+            return;
+        const { interval, timeout } = this.keepAliveConfig;
+        const pongTimeout = timeout ?? interval;
+        this.removePongListener = attachPongListener(this.socket, () => {
+            if (this.pongTimer !== null) {
+                clearTimeout(this.pongTimer);
+                this.pongTimer = null;
+            }
+        });
+        this.keepAliveTimer = setInterval(() => {
+            if (this.state !== "open" || !this.socket)
+                return;
+            socketPing(this.socket);
+            // Clear any existing pong watchdog before starting a new one
+            // to prevent multiple timers when timeout > interval.
+            if (this.pongTimer !== null) {
+                clearTimeout(this.pongTimer);
+            }
+            this.pongTimer = setTimeout(() => {
+                if (this.state === "open" && this.socket) {
+                    this.terminalError = new Error(`Keep-alive timeout: no pong received within ${pongTimeout}ms.`);
+                    socketTerminate(this.socket);
+                }
+            }, pongTimeout);
+        }, interval);
+    }
+    stopKeepAlive() {
+        if (this.keepAliveTimer !== null) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = null;
+        }
+        if (this.pongTimer !== null) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+        if (this.removePongListener) {
+            this.removePongListener();
+            this.removePongListener = null;
+        }
+    }
     cleanup() {
+        this.stopKeepAlive();
         if (this.removeListeners) {
             this.removeListeners();
             this.removeListeners = null;
         }
+        this.socket = null;
     }
     reset() {
         this.socket = null;
@@ -285,6 +501,7 @@ class WebSocketClient {
         this.terminalError = null;
         this.closeInfo = null;
         this.removeListeners = null;
+        this.stopKeepAlive();
     }
 }