Registry / messaging / typed-websocket-client

typed-websocket-client

library1.3.2jsnpmunverified

Typed WebSocket client for browsers and Node.js with automatic reconnection, heartbeat/keepalive, send buffer, and exponential backoff. The current stable version is 1.3.2. Release cadence is irregular. Key differentiators: full TypeScript generics for send/receive types, event-driven API (on/off), AbortSignal support, and pluggable encoding/decoding. Inspired by the Phoenix Framework Socket.

messaging

npm install typed-websocket-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TYPED-WEBSOCKET-CL

typed-websocket-client

messagingjavascriptv1.3.2

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 'typed-websocket-client'

✗ const WebSocketClient = require('typed-websocket-client')

ESM-only, no CommonJS default export. Named import is required.

WebSocketClient

✓ import { WebSocketClient as WSClient } from 'typed-websocket-client'

✗ import WebSocketClient from 'typed-websocket-client'

Not a default export; use named import with optional alias.

default

✓ N/A – no default export

✗ import WebSocketClient from 'typed-websocket-client'

Package only exports named export WebSocketClient.

Create a typed WebSocket client with generic send/receive types, connect to a server, and handle messages.

import { WebSocketClient } from 'typed-websocket-client'; interface UserMessage { type: 'message'; payload: { text: string; timestamp: number }; } interface ServerEvent { type: 'event'; payload: { name: 'user_joined' | 'user_left'; userId: string }; } type SendType = UserMessage; type ReceiveType = UserMessage | ServerEvent; const client = new WebSocketClient<SendType, ReceiveType>('ws://localhost:8080/socket'); client.on('open', () => { client.push({ type: 'message', payload: { text: 'Hello!', timestamp: Date.now() } }); }); client.on('message', (data) => { console.log(data.payload.text); }); client.connect();

Debug

Known issues

gotchaEnsure your WebSocket server sends heartbeat replies; otherwise client may disconnect prematurely.

fix

Configure heartbeatReply detection: new WebSocketClient(url, { heartbeat: { replyPayload: 'pong' } })

affects: >=1.0.0

gotchaIn Node.js, you must install the 'ws' package as it's not included. Browser usage is built-in.

fix

npm install ws

affects: >=1.0.0

deprecatedUsing default import (import WebSocketClient from 'typed-websocket-client') is deprecated; use named import instead.

fix

Use import { WebSocketClient } from 'typed-websocket-client'

affects: >=1.0.0

gotchaThe connect() method does not return a promise; use events to know when connected.

fix

Use client.on('open', callback) or client.on('close', callback) to handle connection state.

affects: >=1.0.0

gotchaMessages pushed before connection are buffered; ensure client.connect() is called after push? The buffer sends on reconnect.

fix

Call client.connect() before or after push; buffer will send when connected.

affects: >=1.0.0

gotchaThe 'ws' constructor option is required for Node.js environments; otherwise native WebSocket is used (only in browsers).

fix

Provide wsConstructor: require('ws') in options.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: WebSocket is not defined

Trying to use the package in Node.js without 'ws' installed.

fix

Install ws: npm install ws or provide custom constructor.

Uncaught TypeError: client.push is not a function

Using default import instead of named import.

fix

Use import { WebSocketClient } from 'typed-websocket-client'.

'WebSocketClient' cannot be used as a value because it is imported using a type-only import

Importing WebSocketClient as a type (import type { WebSocketClient }) when used as value.

fix

Remove 'type' keyword: import { WebSocketClient } from 'typed-websocket-client'.

Cannot find module 'ws' or its corresponding type declarations

TypeScript missing type definitions for 'ws'.

fix

Install @types/ws as dev dependency: npm install --save-dev @types/ws

Upgrade

Version history

1.3.2latest on npm

Audit

Dependencies

wsoptionalRequired in Node.js environments; browser uses native WebSocket.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/arumi-s/typed-websocket-client ↗

packagetyped-websocket-client ↗

homepagehttps://github.com/arumi-s/typed-websocket-client#readme ↗