promise-ws

library1.0.0-1jsnpmunverified

A promise-based WebSocket implementation for Node.js, version 1.0.0-1. Built on top of the popular ws library, it provides promise-returning methods for common WebSocket operations such as send, ping, and pong, as well as factory methods for creating client and server instances. This package offers a cleaner async/await style compared to ws, which uses callbacks and events. It is maintained as a thin wrapper, inheriting the full ws API while adding promise support. Equivalent to using ws with promisify or wrapping manually, but integrated directly.

devops

npm install promise-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROMISE-WS

promise-ws

devopsjavascriptv1.0.0-1

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.

WebSocket

✓ import WebSocket from 'promise-ws'

✗ import { WebSocket } from 'promise-ws'

The main export is a default import (an object with static methods like create and Server). Named exports are not available.

WebSocket.Server.create

✓ const wss = await WebSocket.Server.create({ port: 8080 })

✗ const wss = await WebSocket.createServer({ port: 8080 })

Use WebSocket.Server.create, not WebSocket.createServer. WebSocket.create is for client connections only.

WebSocket.create

✓ const ws = await WebSocket.create('ws://example.com')

✗ const ws = await new WebSocket('ws://example.com')

WebSocket.create returns a promise that resolves to an open WebSocket instance. Do not use new WebSocket; the constructor does not return a promise.

Shows both a client and server WebSocket using promise-ws. Client connects, sends a message, and logs response. Server listens on port 8080 and echoes a welcome message. Demonstrates async/await usage and promise-returning methods.

import WebSocket from 'promise-ws'; async function clientExample() { const ws = await WebSocket.create('ws://echo.websocket.org'); ws.on('message', (data) => { console.log('received:', data); }); await ws.send('Hello'); console.log('Message sent'); // cleanup ws.close(); } async function serverExample() { const wss = await WebSocket.Server.create({ port: 8080 }); wss.on('connection', async (ws) => { ws.on('message', (msg) => console.log('received:', msg)); await ws.send('Welcome'); }); } // Run one of them clientExample().catch(console.error);

Debug

Known issues

deprecatedVersion 1.0.0-1 is a pre-release (beta) and may contain breaking changes before stable 1.0.0.

fix

Monitor for stable release; pin exact version in production.

affects: <1.0.0

gotchaWebSocket.create and WebSocket.Server.create are static methods on the default export, not constructors. Calling new WebSocket() or new WebSocket.Server() will not work as expected and will throw an error.

fix

Use await WebSocket.create(url) for client and await WebSocket.Server.create(options) for server.

affects: *

gotchaThe promise-returning methods (send, ping, pong) resolve before the underlying ws operation completes. For send, the promise resolves when the data is buffered, not when it is actually transmitted.

fix

For reliable delivery, listen to the 'error' event and consider using the callback version from ws directly if needed.

affects: *

breakingThe promise-ws package does not export types; TypeScript users may need to supply their own typings or use @types/ws.

fix

Install @types/ws and import ws types separately, or augment the module.

affects: *

gotchaThe package is ESM-only (import statements); it does not support require() in Node.js versions < v12 or without --experimental-modules.

fix

Use import syntax or configure your bundler/transpiler to handle ESM.

affects: *

Errors

Common errors & fixes

TypeError: WebSocket is not a constructor

Using new WebSocket() instead of WebSocket.create()

fix

Replace new WebSocket(url) with await WebSocket.create(url)

Cannot find module 'promise-ws'

Package not installed or import path incorrect

fix

Run npm install promise-ws and ensure import 'promise-ws' is correct (no subpath)

WebSocket.Server is not a function

Using WebSocket.Server() directly instead of WebSocket.Server.create()

fix

Use await WebSocket.Server.create(options) to get a server instance

Upgrade

Version history

1.0.0-1latest on npm

Audit

Dependencies

wsrequiredCore WebSocket implementation; promise-ws wraps ws with Promise-based methods.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/cantonjs/promise-ws ↗

packagepromise-ws ↗

homepagehttps://github.com/cantonjs/promise-ws#readme ↗