@culpeo/async-ws 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.0.0
+
+### Major Changes
+
+- 6b68e4c: ### Connect timeout and abort signal
+
+  `connect()` now accepts `timeout` (milliseconds) and `signal` (AbortSignal) options to cancel connection attempts.
+
+  ### Keep-alive ping/pong (Node.js)
+
+  New `keepAlive` constructor option sends periodic pings and terminates the connection if no pong is received. Not available in browsers.
+
+  ### Exposed WebSocket properties
+
+  Added read-only `protocol`, `url`, `bufferedAmount`, and `extensions` properties that delegate to the underlying socket.
+
+## 0.2.0
+
+### Minor Changes
+
+- 9453a7c: Initial release
+  - Cross-platform WebSocket client for Node.js and browsers
+  - Promise-based `connect()`, `send()`, `receive()`, `close()` API
+  - Async iteration with `for await...of`
+  - Message buffering with configurable `maxBufferSize`
+  - Clean close info tracking via `lastCloseInfo`
+  - TypeScript-first with bundled type definitions
+
 ## 0.1.0
 
 Initial release.

package/README.md

@@ -15,6 +15,9 @@
 - Async iteration support with `for await...of`
 - Message buffering for messages that arrive before `receive()` is called
 - Configurable `maxBufferSize` with oldest-message eviction when full
+- Connect timeout and `AbortSignal` support
+- Keep-alive with automatic ping/pong (Node.js)
+- Exposed WebSocket properties (`protocol`, `url`, `bufferedAmount`, `extensions`)
 - Clean close information via `lastCloseInfo`
 - TypeScript-first with bundled type definitions
 - Binary and text message support
@@ -45,7 +48,7 @@ await client.connect("wss://echo.websocket.events");
 await client.send("hello");
 
 const message = await client.receive();
-console.log(message.data);   // string | ArrayBuffer
+console.log(message.data); // string | ArrayBuffer
 console.log(message.binary); // boolean
 
 await client.close();
@@ -69,6 +72,9 @@ Creates a new client instance.
   - Maximum number of incoming messages to keep buffered before they are consumed
   - Default: `0` (unlimited)
   - When the limit is reached, the oldest buffered message is dropped
+- `keepAlive?: KeepAliveOptions`
+  - Enables automatic ping/pong keep-alive (Node.js only)
+  - Throws if used in a browser environment
 
 #### Properties
 
@@ -87,6 +93,38 @@ Returns the current client state:
 - `"closed"`
 - `"errored"`
 
+#### `client.protocol`
+
+```ts
+readonly protocol: string
+```
+
+Returns the negotiated subprotocol, or `""` when not connected.
+
+#### `client.url`
+
+```ts
+readonly url: string
+```
+
+Returns the URL of the WebSocket connection, or `""` when not connected.
+
+#### `client.bufferedAmount`
+
+```ts
+readonly bufferedAmount: number
+```
+
+Returns the number of bytes queued for transmission, or `0` when not connected.
+
+#### `client.extensions`
+
+```ts
+readonly extensions: string
+```
+
+Returns the negotiated extensions, or `""` when not connected.
+
 #### `client.lastCloseInfo`
 
 ```ts
@@ -116,6 +154,8 @@ Rejects when:
 
 - `protocols?: string | string[]` — WebSocket subprotocols to request
 - `headers?: Record<string, string>` — custom handshake headers in Node.js
+- `timeout?: number` — connection timeout in milliseconds; rejects if the connection is not established within this time
+- `signal?: AbortSignal` — an abort signal to cancel the connection attempt
 
 > In browsers, passing `headers` throws because the native WebSocket API does not support custom headers.
 
@@ -182,6 +222,8 @@ Behavior:
 interface ConnectOptions {
   protocols?: string | string[];
   headers?: Record<string, string>;
+  timeout?: number;
+  signal?: AbortSignal;
 }
 ```
 
@@ -192,11 +234,24 @@ Connection-time options.
 ```ts
 interface ClientOptions {
   maxBufferSize?: number;
+  keepAlive?: KeepAliveOptions;
 }
 ```
 
 Client-level configuration.
 
+### `KeepAliveOptions`
+
+```ts
+interface KeepAliveOptions {
+  interval: number;
+  timeout?: number;
+}
+```
+
+- `interval` — milliseconds between pings
+- `timeout` — milliseconds to wait for a pong before terminating the connection (default: `interval`)
+
 ### `WebSocketMessage`
 
 ```ts
@@ -276,7 +331,7 @@ This is useful when you want a stream-like consumer loop without manually callin
 
 All core operations are async and communicate failure by rejecting:
 
-- `connect()` rejects on invalid state, connection failure, or early close
+- `connect()` rejects on invalid state, connection failure, early close, timeout, or abort
 - `send()` rejects when called before the socket is open or when the adapter fails to send
 - `receive()` rejects when the client is not in a receivable state and no buffered messages remain
 - `close()` rejects for invalid close codes
@@ -324,6 +379,49 @@ When the buffer is full:
 
 This makes buffering predictable for bursty message streams while keeping the public API simple.
 
+## Connection Timeout and Abort
+
+Use `timeout` to reject if the connection isn't established within a deadline:
+
+```ts
+await client.connect("wss://example.com/ws", { timeout: 5000 });
+```
+
+Use `signal` to cancel a connection attempt at any time:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 3000);
+
+await client.connect("wss://example.com/ws", { signal: controller.signal });
+```
+
+Both can be combined:
+
+```ts
+await client.connect("wss://example.com/ws", {
+  timeout: 10000,
+  signal: controller.signal,
+});
+```
+
+## Keep-Alive (Node.js)
+
+Enable automatic ping/pong to detect dead connections:
+
+```ts
+const client = new WebSocketClient({
+  keepAlive: { interval: 30000, timeout: 5000 },
+});
+
+await client.connect("wss://example.com/ws");
+```
+
+- Sends a ping every `interval` milliseconds
+- If no pong is received within `timeout` milliseconds, the connection is terminated
+- `timeout` defaults to `interval` if omitted
+- **Not available in browsers** — the constructor throws if `keepAlive` is configured in a browser environment
+
 ## Building from Source
 
 ```bash

package/dist/browser/index.js

@@ -10,7 +10,17 @@ function socketSend(socket, data) {
         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) {
@@ -42,6 +52,15 @@ function attachListeners(socket, onOpen, onMessage, onClose, onError) {
 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 () => { };
+}
 
 /**
  * Imperative WebSocket client that works in both browser and Node.js.
@@ -62,7 +81,17 @@ 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) {
+            {
+                throw new Error("keepAlive is not supported in browsers. " +
+                    "The browser handles WebSocket ping/pong at the protocol level automatically.");
+            }
+        }
     }
     /** Current connection state. */
     get readyState() {
@@ -72,16 +101,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);
@@ -89,19 +143,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) => {
@@ -109,14 +207,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})`));
@@ -124,11 +224,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
@@ -176,7 +278,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) {
@@ -186,7 +290,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();
@@ -251,11 +357,50 @@ 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);
+        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;
@@ -264,6 +409,7 @@ class WebSocketClient {
         this.terminalError = null;
         this.closeInfo = null;
         this.removeListeners = null;
+        this.stopKeepAlive();
     }
 }