@culpeo/async-ws 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- 89a662e: ### Adopt existing WebSocket connections
+
+  New static method `WebSocketClient.fromSocket(socket, options?)` wraps an already-open WebSocket (e.g. from a `WebSocketServer` connection event) into a ready-to-use `WebSocketClient`. Node.js only.
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -17,6 +17,7 @@
 - Configurable `maxBufferSize` with oldest-message eviction when full
 - Connect timeout and `AbortSignal` support
 - Keep-alive with automatic ping/pong (Node.js)
+- Server-side socket adoption with `fromSocket()` (Node.js)
 - Exposed WebSocket properties (`protocol`, `url`, `bufferedAmount`, `extensions`)
 - Clean close information via `lastCloseInfo`
 - TypeScript-first with bundled type definitions
@@ -133,7 +134,39 @@ readonly lastCloseInfo: WebSocketCloseInfo | null
 
 Returns close metadata from the most recent close event, or `null` if the socket has not closed yet.
 
-#### Methods
+#### Static Methods
+
+#### `fromSocket()`
+
+```ts
+static fromSocket(rawSocket: unknown, options?: ClientOptions): WebSocketClient
+```
+
+Wraps an already-open WebSocket into a `WebSocketClient` in the `"open"` state, ready to send and receive. Intended for server scenarios where a `WebSocketServer` hands you an established connection.
+
+**Node.js only.** Throws in browser builds.
+
+```ts
+import { WebSocketServer } from "ws";
+import { WebSocketClient } from "@culpeo/async-ws";
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", async (socket) => {
+  const client = WebSocketClient.fromSocket(socket);
+
+  for await (const msg of client) {
+    console.log("received:", msg.data);
+    await client.send("echo: " + msg.data);
+  }
+});
+```
+
+The client takes ownership of the socket lifecycle — calling `close()` will close the underlying socket. Call `fromSocket()` immediately in the `connection` handler to avoid missing messages.
+
+Accepts any WebSocket-compatible object (validated structurally, not via `instanceof`), so it works even when multiple copies of the `ws` package are installed.
+
+#### Instance Methods
 
 #### `connect()`
 
@@ -405,6 +438,34 @@ await client.connect("wss://example.com/ws", {
 });
 ```
 
+## Server-Side Socket Adoption (Node.js)
+
+Use `fromSocket()` to wrap connections from a `WebSocketServer`:
+
+```ts
+import { WebSocketServer } from "ws";
+import { WebSocketClient } from "@culpeo/async-ws";
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", async (socket) => {
+  const client = WebSocketClient.fromSocket(socket);
+
+  const msg = await client.receive();
+  await client.send("got: " + msg.data);
+  await client.close();
+});
+```
+
+The same `ClientOptions` are supported:
+
+```ts
+const client = WebSocketClient.fromSocket(socket, {
+  maxBufferSize: 100,
+  keepAlive: { interval: 30000 },
+});
+```
+
 ## Keep-Alive (Node.js)
 
 Enable automatic ping/pong to detect dead connections:

package/dist/browser/index.js

@@ -61,6 +61,10 @@ function socketPing(_socket) {
 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.
@@ -93,6 +97,60 @@ class WebSocketClient {
             }
         }
     }
+    /**
+     * 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() {
         return this.state;

package/dist/cjs/index.cjs

@@ -75,6 +75,22 @@ function attachPongListener(socket, 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;
 
 /**
@@ -112,6 +128,60 @@ class WebSocketClient {
             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() {
         return this.state;

package/dist/esm/index.js

@@ -73,6 +73,22 @@ function attachPongListener(socket, 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;
 
 /**
@@ -110,6 +126,60 @@ class WebSocketClient {
             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() {
         return this.state;

package/dist/iife/index.js

@@ -64,6 +64,10 @@ var AsyncWS = (function (exports) {
     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.
@@ -96,6 +100,60 @@ var AsyncWS = (function (exports) {
                 }
             }
         }
+        /**
+         * 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() {
             return this.state;

package/dist/index.d.ts

@@ -84,6 +84,26 @@ declare class WebSocketClient {
     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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@culpeo/async-ws",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Promise-first WebSocket client for Node.js and browsers",
   "author": "Gerardo Lecaros",
   "license": "MIT",