websocket-async

library1.3.0jsnpmunverified

An async/await WebSocket client for browsers. Version 1.3.0 provides a simple, promise-based interface for WebSocket connections using ES2017 async/await. The library wraps the native WebSocket API and offers methods like connect, send, receive, and disconnect. Unlike raw WebSocket, it queues incoming messages and allows asynchronous reading via receive() without event listeners. It supports reconnection and sends data synchronously while receiving asynchronously. The library is browser-only, has no dependencies, and is ESM-compatible.

messaging

npm install websocket-async

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSOCKET-ASYNC

websocket-async

messagingjavascriptv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebSocketClient

✓ import { WebSocketClient } from 'websocket-async'

✗ const WebSocketClient = require('websocket-async')

Package is ESM-only; CommonJS require will fail.

default import

✓ import { WebSocketClient } from 'websocket-async'

✗ import WebSocketClient from 'websocket-async'

No default export exported; must use named import.

dynamic import

✓ const { WebSocketClient } = await import('websocket-async')

✗ const WebSocketClient = (await import('websocket-async')).default

Dynamic import returns module with named exports only.

Shows basic usage of WebSocketClient: connect, send, receive, and disconnect using async/await.

import { WebSocketClient } from 'websocket-async'; async function demo() { const client = new WebSocketClient(); await client.connect('wss://echo.websocket.org'); client.send('Hello, WebSocket!'); const response = await client.receive(); console.log('Received:', response); await client.disconnect(); } demo().catch(console.error);

Debug

Known issues

gotchasend() is synchronous and will throw if not connected. Always check client.connected or call after a successful connect().

fix

Ensure client.connected is true before calling send().

affects: >=1.0.0

gotchareceive() returns pending promise if no data available. If connection closes while waiting, the promise rejects. Wrap in try/catch or use dataAvailable to check.

fix

Check client.dataAvailable > 0 before calling receive() to avoid waiting.

affects: >=1.0.0

gotchadisconnect() never rejects but may return undefined if no connection. Always await but be aware it might resolve immediately.

fix

Use await client.disconnect() and handle potential undefined.

affects: >=1.0.0

gotchaOnly works in browser environment. Node.js native 'ws' module is not supported.

fix

Use for browser apps only; for Node.js use the 'ws' library with async wrappers.

affects: >=1.0.0

gotchaNo built-in reconnection or heartbeat. Connection loss is not automatically handled.

fix

Implement custom reconnection logic using connect/disconnect loop.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'WebSocketClient')

Using default import instead of named import.

fix

Use `import { WebSocketClient } from 'websocket-async'`

ReferenceError: WebSocket is not defined

Running in Node.js environment where native WebSocket is not available.

fix

Use in browser or provide a polyfill like `globalThis.WebSocket = require('ws')`

TypeError: client.send is not a function

Attempted to call send before client was properly initialized or after destruction.

fix

Ensure you created an instance: `const client = new WebSocketClient()`

Uncaught (in promise) Error: Connection closed before receiving data

Called receive() after the WebSocket closed, with no queued messages.

fix

Check `client.connected` and `client.dataAvailable` before calling receive.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/jcao219/websocket-async ↗

packagewebsocket-async ↗

homepagehttps://github.com/jcao219/websocket-async ↗