ws-wrapper

library4.3.1jsnpmunverified

Lightweight, isomorphic WebSocket wrapper that adds named events, Promise-based request/response, channels, streaming, and cancellation on top of native WebSockets. Version 4.3.1 supports Node.js >=14, browsers, and Go. Unlike Socket.IO, it uses the native WebSocket protocol with no HTTP polling fallback, keeping the wire protocol simple and interoperable. Ships TypeScript types. Under 4 KB min+gzip.

communication

npm install ws-wrapper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WS-WRAPPER

ws-wrapper

communicationjavascriptv4.3.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.

SocketWrapper

✓ import { SocketWrapper } from 'ws-wrapper'

✗ import SocketWrapper from 'ws-wrapper'

SocketWrapper is a named export, not the default. Common mistake: trying default import.

Channel

✓ import { Channel } from 'ws-wrapper'

✗ const { Channel } = require('ws-wrapper')

Named export. TypeScript types included. CommonJS require is supported but not recommended.

createServer

✓ import { createServer } from 'ws-wrapper'

✗ import { Server } from 'ws-wrapper'

No Server export; use createServer function. ESM only for this symbol.

Creates a WebSocket server and client using SocketWrapper for request/response with named events.

import { SocketWrapper } from 'ws-wrapper'; import WebSocket from 'ws'; // Server const server = new WebSocket.Server({ port: 8080 }); server.on('connection', (ws) => { const wrapper = new SocketWrapper(ws); wrapper.on('greet', (name) => { console.log('Received:', name); return `Hello, ${name}!`; }); }); // Client const ws = new WebSocket('ws://localhost:8080'); const client = new SocketWrapper(ws); ws.on('open', async () => { const response = await client.request('greet', 'World'); console.log(response); // 'Hello, World!' });

Debug

Known issues

breakingIn v4, the 'channel' method was removed; use 'channel' property instead.

fix

Use wrapper.channel instead of wrapper.channel()

affects: >=4.0.0

breakingSocketWrapper constructor no longer accepts options object; wrap WebSocket directly.

fix

new SocketWrapper(ws) instead of new SocketWrapper(ws, options)

affects: >=4.0.0

deprecatedThe 'request' method's third argument (timeout) is deprecated; use AbortSignal instead.

fix

client.request('event', data, { signal })

affects: >=4.0.0

gotchaWhen using with Node.js 'ws' library, ensure the WebSocket is open before calling request().

fix

Wrap in ws.on('open', ...) or check readyState

affects: >=4.0.0

deprecatedThe 'wrapper.request' signature with a callback is deprecated; use Promises.

fix

Use wrapper.request(event, data).then(handler) instead of wrapper.request(event, data, callback)

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: SocketWrapper is not a constructor

Attempted to use default import instead of named import.

fix

Use import { SocketWrapper } from 'ws-wrapper'

Error: The 'channel' method has been removed. Use the 'channel' property instead.

v4 breaking change: channel() method replaced by channel property.

fix

Use wrapper.channel instead of wrapper.channel()

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

SocketWrapper created before WebSocket connection is open.

fix

Ensure WebSocket is open before using SocketWrapper, e.g., ws.on('open', () => { ... })

Upgrade

Version history

4.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

37 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bminer/ws-wrapper ↗

packagews-wrapper ↗

homepagehttps://github.com/bminer/ws-wrapper#readme ↗