@culpeo/async-ws 0.1.0

package/dist/iife/index.js

@@ -0,0 +1,277 @@
+var AsyncWS = (function (exports) {
+    'use strict';
+
+    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;
+        }
+    }
+
+    exports.WebSocketClient = WebSocketClient;
+
+    return exports;
+
+})({});

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+/** Options for connecting to a WebSocket server. */
+interface ConnectOptions {
+    /** Subprotocols to request. */
+    protocols?: string | string[];
+    /** HTTP headers to send during the handshake (Node.js only). */
+    headers?: Record<string, string>;
+}
+/** Represents a received WebSocket message. */
+interface WebSocketMessage {
+    /** The message payload. */
+    data: string | ArrayBuffer;
+    /** Whether the payload is binary data. */
+    binary: boolean;
+}
+/** Information about a WebSocket close event. */
+interface WebSocketCloseInfo {
+    /** The close code. */
+    code: number;
+    /** The close reason string. */
+    reason: string;
+    /** Whether the close handshake completed cleanly. */
+    wasClean: boolean;
+}
+/** Options for the WebSocketClient constructor. */
+interface ClientOptions {
+    /**
+     * Maximum number of messages to buffer before a consumer calls `receive()`.
+     * When the buffer is full, the oldest message is dropped.
+     * Set to 0 for unlimited. Defaults to 0 (unlimited).
+     */
+    maxBufferSize?: number;
+}
+type WebSocketState = "idle" | "connecting" | "open" | "closing" | "closed" | "errored";
+
+/**
+ * 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.
+ */
+declare class WebSocketClient {
+    private socket;
+    private state;
+    private buffer;
+    private waiters;
+    private terminalError;
+    private closeInfo;
+    private removeListeners;
+    private readonly maxBufferSize;
+    constructor(options?: ClientOptions);
+    /** Current connection state. */
+    get readyState(): WebSocketState;
+    /** Close info from the last close event, if any. */
+    get lastCloseInfo(): WebSocketCloseInfo | null;
+    /**
+     * Connect to a WebSocket server.
+     * Resolves when the connection is open. Rejects on error.
+     */
+    connect(url: string | URL, options?: ConnectOptions): Promise<void>;
+    /**
+     * Send data over the WebSocket.
+     * Resolves when the data has been accepted by the socket.
+     */
+    send(data: string | ArrayBuffer | ArrayBufferView): Promise<void>;
+    /**
+     * 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(): Promise<WebSocketMessage>;
+    /**
+     * Close the WebSocket connection.
+     * Resolves when the close handshake completes.
+     */
+    close(code?: number, reason?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<WebSocketMessage>;
+    private enqueueMessage;
+    private rejectAllWaiters;
+    private cleanup;
+    private reset;
+}
+
+export { WebSocketClient };
+export type { ClientOptions, ConnectOptions, WebSocketCloseInfo, WebSocketMessage, WebSocketState };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@culpeo/async-ws",
+  "version": "0.1.0",
+  "description": "Promise-first WebSocket client for Node.js and browsers",
+  "author": "Gerardo Lecaros",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "keywords": [
+    "websocket",
+    "ws",
+    "async",
+    "promise",
+    "browser",
+    "node",
+    "client",
+    "async-iterator",
+    "cross-platform"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/culpeo-labs/async-ws.git"
+  },
+  "homepage": "https://github.com/culpeo-labs/async-ws#readme",
+  "bugs": {
+    "url": "https://github.com/culpeo-labs/async-ws/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/browser/index.js",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs",
+      "default": "./dist/esm/index.js"
+    },
+    "./iife": {
+      "default": "./dist/iife/index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:browser": "xvfb-run vitest run --config vitest.config.browser.mts",
+    "build": "rollup -c",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run build && npm test"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "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-typescript": "^12.1.0",
+    "@types/ws": "^8.5.12",
+    "@vitest/browser-playwright": "^4.1.8",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.24.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "tslib": "^2.8.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.8"
+  }
+}