@culpeo/async-ws 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+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`
+- Close info tracking via `lastCloseInfo`
+- TypeScript-first with bundled type definitions
+- Node.js build uses `ws`; browser build uses native WebSocket

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gerardo Lecaros
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,358 @@
+# @culpeo/async-ws
+
+> Promise-first WebSocket client for Node.js and browsers.
+>
+> [![npm version](https://img.shields.io/npm/v/%40culpeo/async-ws)](https://www.npmjs.com/package/@culpeo/async-ws)
+> [![license](https://img.shields.io/npm/l/%40culpeo/async-ws)](./LICENSE)
+> [![bundle size](https://img.shields.io/bundlephobia/minzip/%40culpeo/async-ws)](https://bundlephobia.com/package/@culpeo/async-ws)
+
+`@culpeo/async-ws` is a cross-platform WebSocket client that turns the event-driven WebSocket API into a small, imperative, promise-based interface.
+
+## Features
+
+- Works in both Node.js and browsers from one package
+- Promise-based `connect()`, `send()`, `receive()`, and `close()` APIs
+- 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
+- Clean close information via `lastCloseInfo`
+- TypeScript-first with bundled type definitions
+- Binary and text message support
+- Browser build uses the native `WebSocket`; Node build uses `ws`
+
+## Install
+
+```bash
+npm install @culpeo/async-ws
+```
+
+```bash
+yarn add @culpeo/async-ws
+```
+
+```bash
+pnpm add @culpeo/async-ws
+```
+
+## Quick Start
+
+```ts
+import { WebSocketClient } from "@culpeo/async-ws";
+
+const client = new WebSocketClient();
+
+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.binary); // boolean
+
+await client.close();
+```
+
+## API Reference
+
+### `WebSocketClient`
+
+#### Constructor
+
+```ts
+new WebSocketClient(options?: ClientOptions)
+```
+
+Creates a new client instance.
+
+#### Constructor options
+
+- `maxBufferSize?: number`
+  - 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
+
+#### Properties
+
+#### `client.readyState`
+
+```ts
+readonly readyState: WebSocketState
+```
+
+Returns the current client state:
+
+- `"idle"`
+- `"connecting"`
+- `"open"`
+- `"closing"`
+- `"closed"`
+- `"errored"`
+
+#### `client.lastCloseInfo`
+
+```ts
+readonly lastCloseInfo: WebSocketCloseInfo | null
+```
+
+Returns close metadata from the most recent close event, or `null` if the socket has not closed yet.
+
+#### Methods
+
+#### `connect()`
+
+```ts
+connect(url: string | URL, options?: ConnectOptions): Promise<void>
+```
+
+Opens a WebSocket connection and resolves when the connection is established.
+
+Rejects when:
+
+- the client is already connecting, open, or closing
+- the socket constructor throws
+- the connection errors before opening
+- the socket closes before opening
+
+##### `ConnectOptions`
+
+- `protocols?: string | string[]` — WebSocket subprotocols to request
+- `headers?: Record<string, string>` — custom handshake headers in Node.js
+
+> In browsers, passing `headers` throws because the native WebSocket API does not support custom headers.
+
+#### `send()`
+
+```ts
+send(data: string | ArrayBuffer | ArrayBufferView): Promise<void>
+```
+
+Sends text or binary data.
+
+Resolves when the underlying socket accepts the payload. Rejects if the client is not open or if the underlying adapter reports an error.
+
+#### `receive()`
+
+```ts
+receive(): Promise<WebSocketMessage>
+```
+
+Resolves with the next incoming message.
+
+Behavior:
+
+- If buffered messages exist, returns the oldest buffered message immediately
+- If no buffered message exists, waits for the next incoming message
+- If the socket closes after buffering messages, buffered messages are still drained first
+- Rejects when the client is not open and no buffered messages remain
+
+#### `close()`
+
+```ts
+close(code?: number, reason?: string): Promise<void>
+```
+
+Starts the close handshake and resolves when the socket closes.
+
+Behavior:
+
+- Resolves immediately if the client is idle, already closed, or errored
+- If a close is already in progress, waits for the close event
+- Validates custom close codes before calling the underlying socket
+- Accepts `1000` or values in the range `3000-4999`
+
+#### Async iterator
+
+```ts
+client[Symbol.asyncIterator](): AsyncGenerator<WebSocketMessage>
+```
+
+Allows consumption with `for await...of`.
+
+Behavior:
+
+- Yields incoming messages as they arrive
+- Ends iteration on a clean close
+- Throws on unexpected or error-driven termination
+- Does not automatically close the socket if you `break` out of the loop
+
+## Types
+
+### `ConnectOptions`
+
+```ts
+interface ConnectOptions {
+  protocols?: string | string[];
+  headers?: Record<string, string>;
+}
+```
+
+Connection-time options.
+
+### `ClientOptions`
+
+```ts
+interface ClientOptions {
+  maxBufferSize?: number;
+}
+```
+
+Client-level configuration.
+
+### `WebSocketMessage`
+
+```ts
+interface WebSocketMessage {
+  data: string | ArrayBuffer;
+  binary: boolean;
+}
+```
+
+Represents a received message payload.
+
+### `WebSocketCloseInfo`
+
+```ts
+interface WebSocketCloseInfo {
+  code: number;
+  reason: string;
+  wasClean: boolean;
+}
+```
+
+Represents close metadata captured from the underlying socket.
+
+### `WebSocketState`
+
+```ts
+type WebSocketState =
+  | "idle"
+  | "connecting"
+  | "open"
+  | "closing"
+  | "closed"
+  | "errored";
+```
+
+Represents the client lifecycle state.
+
+## Browser vs Node
+
+`@culpeo/async-ws` ships one API for both environments:
+
+- **Node.js build** uses the `ws` package internally
+- **Browser build** uses the native `WebSocket` implementation
+
+This is handled at build time with Rollup. The browser bundle aliases the Node adapter module to a browser-specific adapter, so application code does not need environment checks or separate imports.
+
+In practice, that means you write this once:
+
+```ts
+import { WebSocketClient } from "@culpeo/async-ws";
+```
+
+…and the appropriate adapter is selected by the published package exports and browser build.
+
+## Async Iterator
+
+```ts
+import { WebSocketClient } from "@culpeo/async-ws";
+
+const client = new WebSocketClient();
+await client.connect("wss://example.com/ws");
+
+try {
+  for await (const message of client) {
+    if (!message.binary) {
+      console.log("text:", message.data);
+    }
+  }
+} finally {
+  await client.close();
+}
+```
+
+This is useful when you want a stream-like consumer loop without manually calling `receive()` each time.
+
+## Error Handling
+
+All core operations are async and communicate failure by rejecting:
+
+- `connect()` rejects on invalid state, connection failure, or early close
+- `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
+
+Additional notes:
+
+- Connection errors are treated as terminal for pending receivers
+- A socket error is typically followed by a close event; close metadata is exposed through `lastCloseInfo`
+- If buffered messages exist when a close happens, those messages are still delivered before `receive()` starts rejecting
+
+A simple pattern:
+
+```ts
+try {
+  await client.connect("wss://example.com/ws");
+  await client.send("ping");
+  const reply = await client.receive();
+  console.log(reply);
+} catch (error) {
+  console.error("WebSocket operation failed", error);
+  console.error("Last close info:", client.lastCloseInfo);
+}
+```
+
+## Message Buffering
+
+Incoming messages are buffered when they arrive before a consumer calls `receive()`.
+
+By default, buffering is unlimited:
+
+```ts
+const client = new WebSocketClient();
+```
+
+To cap memory usage, set `maxBufferSize`:
+
+```ts
+const client = new WebSocketClient({ maxBufferSize: 100 });
+```
+
+When the buffer is full:
+
+- the oldest message is removed
+- the newest message is stored
+
+This makes buffering predictable for bursty message streams while keeping the public API simple.
+
+## Building from Source
+
+```bash
+git clone <your-fork-or-repo-url>
+cd <repo-directory>
+npm install
+```
+
+Run tests:
+
+```bash
+npm test
+npm run test:browser
+```
+
+Build the package:
+
+```bash
+npm run build
+```
+
+Current build outputs include:
+
+- CommonJS for Node.js
+- ESM for Node.js
+- Browser ESM
+- Browser IIFE bundle
+- Bundled TypeScript declarations
+
+## License
+
+MIT

package/dist/browser/index.js

@@ -0,0 +1,270 @@
+const _WS = WebSocket;
+function createWebSocket(url, options) {
+    if (options?.headers != null) {
+        throw new Error("Custom headers are not supported in the browser. Use subprotocols or query parameters instead.");
+    }
+    return new _WS(url, options?.protocols);
+}
+function socketSend(socket, data) {
+    if (socket.readyState !== _WS.OPEN) {
+        return Promise.reject(new Error("WebSocket is not open"));
+    }
+    try {
+        socket.send(data);
+        return Promise.resolve();
+    }
+    catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+}
+function setBinaryType(socket) {
+    socket.binaryType = "arraybuffer";
+}
+function attachListeners(socket, onOpen, onMessage, onClose, onError) {
+    const handleOpen = () => onOpen();
+    const handleMessage = (event) => {
+        const isBinary = event.data instanceof ArrayBuffer;
+        onMessage(event.data, isBinary);
+    };
+    const handleClose = (event) => onClose(event.code, event.reason, event.wasClean);
+    const handleError = () => onError(new Error("WebSocket error"));
+    socket.addEventListener("open", handleOpen);
+    socket.addEventListener("message", handleMessage);
+    socket.addEventListener("close", handleClose);
+    socket.addEventListener("error", handleError);
+    return () => {
+        socket.removeEventListener("open", handleOpen);
+        socket.removeEventListener("message", handleMessage);
+        socket.removeEventListener("close", handleClose);
+        socket.removeEventListener("error", handleError);
+    };
+}
+function socketClose(socket, code, reason) {
+    socket.close(code, reason);
+}
+
+/**
+ * Imperative WebSocket client that works in both browser and Node.js.
+ *
+ * Turns the event-driven WebSocket API into a promise-based one:
+ * - `connect(url)` returns a promise that resolves when the connection opens.
+ * - `send(data)` returns a promise that resolves when the data is accepted.
+ * - `receive()` returns a promise that resolves with the next message.
+ * - `close()` returns a promise that resolves when the connection closes.
+ * - Supports `for await...of` iteration over incoming messages.
+ */
+class WebSocketClient {
+    constructor(options) {
+        this.socket = null;
+        this.state = "idle";
+        this.buffer = [];
+        this.waiters = [];
+        this.terminalError = null;
+        this.closeInfo = null;
+        this.removeListeners = null;
+        this.maxBufferSize = options?.maxBufferSize ?? 0;
+    }
+    /** Current connection state. */
+    get readyState() {
+        return this.state;
+    }
+    /** Close info from the last close event, if any. */
+    get lastCloseInfo() {
+        return this.closeInfo;
+    }
+    /**
+     * 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") {
+            return Promise.reject(new Error(`Cannot connect: client is in "${this.state}" state`));
+        }
+        this.reset();
+        this.state = "connecting";
+        return new Promise((resolve, reject) => {
+            try {
+                this.socket = createWebSocket(url, options);
+                setBinaryType(this.socket);
+            }
+            catch (err) {
+                this.state = "errored";
+                this.terminalError = err instanceof Error ? err : new Error(String(err));
+                reject(this.terminalError);
+                return;
+            }
+            let settled = false;
+            this.removeListeners = attachListeners(this.socket, 
+            // onOpen
+            () => {
+                if (!settled) {
+                    settled = true;
+                    this.state = "open";
+                    resolve();
+                }
+            }, 
+            // onMessage
+            (data, binary) => {
+                this.enqueueMessage({ data, binary });
+            }, 
+            // onClose
+            (code, reason, wasClean) => {
+                this.closeInfo = { code, reason, wasClean };
+                this.state;
+                this.state = "closed";
+                this.cleanup();
+                if (!settled) {
+                    settled = true;
+                    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})`));
+                }
+            }, 
+            // onError
+            (error) => {
+                this.terminalError = error;
+                if (!settled) {
+                    settled = true;
+                    reject(error);
+                }
+                // Reject any pending receive() waiters immediately
+                this.rejectAllWaiters(error);
+                // Don't call cleanup() here — per spec, a close event always
+                // follows an error event. Let onClose handle state transition
+                // and listener removal.
+            });
+        });
+    }
+    /**
+     * Send data over the WebSocket.
+     * Resolves when the data has been accepted by the socket.
+     */
+    send(data) {
+        if (this.state !== "open" || !this.socket) {
+            return Promise.reject(new Error(`Cannot send: client is in "${this.state}" state`));
+        }
+        return socketSend(this.socket, data);
+    }
+    /**
+     * Wait for and return the next incoming message.
+     *
+     * If messages have been buffered, returns the oldest one immediately.
+     * If the socket has closed cleanly and the buffer is empty, rejects.
+     */
+    receive() {
+        // Drain buffer first, even if the socket is closed
+        if (this.buffer.length > 0) {
+            return Promise.resolve(this.buffer.shift());
+        }
+        if (this.state === "errored" && this.terminalError) {
+            return Promise.reject(this.terminalError);
+        }
+        if (this.state === "closed") {
+            return Promise.reject(new Error("WebSocket is closed"));
+        }
+        if (this.state !== "open") {
+            return Promise.reject(new Error(`Cannot receive: client is in "${this.state}" state`));
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    /**
+     * Close the WebSocket connection.
+     * Resolves when the close handshake completes.
+     */
+    close(code, reason) {
+        if (this.state === "closed" || this.state === "idle" || this.state === "errored") {
+            return Promise.resolve();
+        }
+        if (!this.socket) {
+            return Promise.resolve();
+        }
+        if (this.state === "closing") {
+            // 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 });
+                }
+                else {
+                    resolve();
+                }
+            });
+        }
+        this.state = "closing";
+        // Validate close code before calling socketClose to avoid leaving the
+        // socket in a corrupt state (ws library sets readyState to CLOSING
+        // before throwing on invalid codes, making the socket unrecoverable).
+        if (code !== undefined) {
+            if (code !== 1000 && (code < 3000 || code > 4999)) {
+                this.state = "open";
+                return Promise.reject(new Error(`Invalid close code: ${code}. Must be 1000 or in range 3000-4999.`));
+            }
+        }
+        return new Promise((resolve) => {
+            if (this.socket) {
+                this.socket.addEventListener("close", () => resolve(), { once: true });
+            }
+            socketClose(this.socket, code, reason);
+        });
+    }
+    /**
+     * Async iterator over incoming messages.
+     *
+     * - Yields messages as they arrive.
+     * - Returns (ends iteration) on normal close.
+     * - Throws on error/abnormal close.
+     * - If the consumer `break`s, the socket is NOT closed automatically.
+     */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            try {
+                yield await this.receive();
+            }
+            catch {
+                // If closed cleanly, end iteration
+                if (this.state === "closed" && this.closeInfo?.wasClean) {
+                    return;
+                }
+                // Otherwise, propagate the error
+                throw this.terminalError ?? new Error("WebSocket closed unexpectedly");
+            }
+        }
+    }
+    enqueueMessage(msg) {
+        if (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter.resolve(msg);
+        }
+        else {
+            if (this.maxBufferSize > 0 && this.buffer.length >= this.maxBufferSize) {
+                this.buffer.shift(); // drop oldest
+            }
+            this.buffer.push(msg);
+        }
+    }
+    rejectAllWaiters(error) {
+        const pending = this.waiters.splice(0);
+        for (const waiter of pending) {
+            waiter.reject(error);
+        }
+    }
+    cleanup() {
+        if (this.removeListeners) {
+            this.removeListeners();
+            this.removeListeners = null;
+        }
+    }
+    reset() {
+        this.socket = null;
+        this.buffer = [];
+        this.waiters = [];
+        this.terminalError = null;
+        this.closeInfo = null;
+        this.removeListeners = null;
+    }
+}
+
+export { WebSocketClient };