@culpeo/async-ws 0.2.0 → 1.1.0

package/dist/iife/index.js

@@ -13,7 +13,17 @@ var AsyncWS = (function (exports) {
             return Promise.reject(new Error("WebSocket is not open"));
         }
         try {
-            socket.send(data);
+            if (ArrayBuffer.isView(data)) {
+                if (data.buffer instanceof SharedArrayBuffer) {
+                    throw new Error("SharedArrayBuffer-backed views are not supported. " +
+                        "Copy into a regular ArrayBuffer before sending.");
+                }
+                // Zero-copy: create a Uint8Array view over the same ArrayBuffer
+                socket.send(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+            }
+            else {
+                socket.send(data);
+            }
             return Promise.resolve();
         }
         catch (err) {
@@ -45,6 +55,19 @@ var AsyncWS = (function (exports) {
     function socketClose(socket, code, reason) {
         socket.close(code, reason);
     }
+    function socketTerminate(socket) {
+        socket.close();
+    }
+    function socketPing(_socket) {
+        throw new Error("Ping is not supported in browsers.");
+    }
+    function attachPongListener(_socket, _onPong) {
+        return () => { };
+    }
+    function adoptSocket(_rawSocket) {
+        throw new Error("fromSocket() is not supported in browsers. " +
+            "Browsers cannot accept server-side WebSocket connections.");
+    }
 
     /**
      * Imperative WebSocket client that works in both browser and Node.js.
@@ -65,7 +88,71 @@ var AsyncWS = (function (exports) {
             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) {
+                {
+                    throw new Error("keepAlive is not supported in browsers. " +
+                        "The browser handles WebSocket ping/pong at the protocol level automatically.");
+                }
+            }
+        }
+        /**
+         * 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();
+            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() {
@@ -75,16 +162,41 @@ var AsyncWS = (function (exports) {
         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);
@@ -92,19 +204,63 @@ var AsyncWS = (function (exports) {
                 }
                 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) => {
@@ -112,14 +268,16 @@ var AsyncWS = (function (exports) {
                 }, 
                 // 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})`));
@@ -127,11 +285,13 @@ var AsyncWS = (function (exports) {
                 }, 
                 // 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
@@ -179,7 +339,9 @@ var AsyncWS = (function (exports) {
          * 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) {
@@ -189,7 +351,9 @@ var AsyncWS = (function (exports) {
                 // 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();
@@ -254,11 +418,50 @@ var AsyncWS = (function (exports) {
                 waiter.reject(error);
             }
         }
+        startKeepAlive() {
+            if (!this.keepAliveConfig || !this.socket)
+                return;
+            const { interval, timeout } = this.keepAliveConfig;
+            const pongTimeout = timeout ?? interval;
+            this.removePongListener = attachPongListener(this.socket);
+            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;
@@ -267,6 +470,7 @@ var AsyncWS = (function (exports) {
             this.terminalError = null;
             this.closeInfo = null;
             this.removeListeners = null;
+            this.stopKeepAlive();
         }
     }
 

package/dist/index.d.ts

@@ -4,6 +4,17 @@ interface ConnectOptions {
     protocols?: string | string[];
     /** HTTP headers to send during the handshake (Node.js only). */
     headers?: Record<string, string>;
+    /**
+     * Connection timeout in milliseconds.
+     * If the connection is not established within this time, it is aborted.
+     * Default: no timeout.
+     */
+    timeout?: number;
+    /**
+     * An AbortSignal to cancel the connection attempt.
+     * If aborted, the connection is terminated and connect() rejects.
+     */
+    signal?: AbortSignal;
 }
 /** Represents a received WebSocket message. */
 interface WebSocketMessage {
@@ -29,6 +40,22 @@ interface ClientOptions {
      * Set to 0 for unlimited. Defaults to 0 (unlimited).
      */
     maxBufferSize?: number;
+    /**
+     * Enable automatic keep-alive pings (Node.js only).
+     * In browsers, this option throws because the browser handles
+     * ping/pong at the protocol level automatically.
+     */
+    keepAlive?: KeepAliveOptions;
+}
+/** Configuration for automatic keep-alive pings (Node.js only). */
+interface KeepAliveOptions {
+    /** Interval in milliseconds between pings. Must be > 0. */
+    interval: number;
+    /**
+     * Time in milliseconds to wait for a pong response before
+     * terminating the connection. Default: same as interval.
+     */
+    timeout?: number;
 }
 type WebSocketState = "idle" | "connecting" | "open" | "closing" | "closed" | "errored";
 
@@ -50,12 +77,45 @@ declare class WebSocketClient {
     private terminalError;
     private closeInfo;
     private removeListeners;
+    private keepAliveTimer;
+    private pongTimer;
+    private removePongListener;
+    private connectionId;
     private readonly maxBufferSize;
+    private readonly keepAliveConfig;
     constructor(options?: ClientOptions);
+    /**
+     * 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: unknown, options?: ClientOptions): WebSocketClient;
     /** Current connection state. */
     get readyState(): WebSocketState;
     /** Close info from the last close event, if any. */
     get lastCloseInfo(): WebSocketCloseInfo | null;
+    /** The negotiated subprotocol, or empty string if none. */
+    get protocol(): string;
+    /** The URL of the WebSocket connection. */
+    get url(): string;
+    /** The number of bytes of data queued for sending. */
+    get bufferedAmount(): number;
+    /** The extensions negotiated by the server. */
+    get extensions(): string;
     /**
      * Connect to a WebSocket server.
      * Resolves when the connection is open. Rejects on error.
@@ -89,9 +149,11 @@ declare class WebSocketClient {
     [Symbol.asyncIterator](): AsyncGenerator<WebSocketMessage>;
     private enqueueMessage;
     private rejectAllWaiters;
+    private startKeepAlive;
+    private stopKeepAlive;
     private cleanup;
     private reset;
 }
 
 export { WebSocketClient };
-export type { ClientOptions, ConnectOptions, WebSocketCloseInfo, WebSocketMessage, WebSocketState };
+export type { ClientOptions, ConnectOptions, KeepAliveOptions, WebSocketCloseInfo, WebSocketMessage, WebSocketState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@culpeo/async-ws",
-  "version": "0.2.0",
+  "version": "1.1.0",
   "description": "Promise-first WebSocket client for Node.js and browsers",
   "author": "Gerardo Lecaros",
   "license": "MIT",
@@ -58,6 +58,8 @@
     "build": "rollup -c",
     "clean": "rimraf dist",
     "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "changeset": "changeset",
     "version": "changeset version",
     "release": "changeset publish",
@@ -68,17 +70,18 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-commonjs": "^28.0.0",
-    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-alias": "^6.0.0",
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.1.0",
     "@types/ws": "^8.5.12",
     "@vitest/browser-playwright": "^4.1.8",
+    "prettier": "^3.8.3",
     "rimraf": "^6.0.1",
     "rollup": "^4.24.0",
     "rollup-plugin-dts": "^6.1.1",
     "tslib": "^2.8.0",
-    "typescript": "^5.6.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   }
 }