websocket-ts

library2.3.0jsnpmunverified

A lightweight, standalone WebSocket client library for browsers written in TypeScript, offering optional auto-reconnect and message buffering. Current stable version is 2.3.0, with frequent updates. Key differentiators: zero dependencies, 2.5 kB min+gzip, uses native WebSocket API, provides a builder pattern for easy configuration, and supports both CommonJS and ES modules. It is well-tested with high coverage and includes comprehensive API documentation.

networking

npm install websocket-ts

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSOCKET-TS

websocket-ts

networkingjavascriptv2.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.

WebsocketBuilder

✓ import { WebsocketBuilder } from 'websocket-ts'

✗ const WebsocketBuilder = require('websocket-ts').WebsocketBuilder;

ESM import is preferred; CJS also supported.

WebsocketEvent

✓ import { WebsocketEvent } from 'websocket-ts'

Use named import for event enum.

ArrayQueue

✓ import { ArrayQueue } from 'websocket-ts'

Used as buffer; not exported in v1.x (breaking change).

ConstantBackoff

✓ import { ConstantBackoff } from 'websocket-ts'

One of several backoff strategies.

Creates a WebSocket with message buffering and auto-reconnect (1s delay), logs events, and echoes received messages.

import { ArrayQueue, ConstantBackoff, WebsocketBuilder, WebsocketEvent } from 'websocket-ts'; const ws = new WebsocketBuilder('ws://localhost:8080') .withBuffer(new ArrayQueue()) .withBackoff(new ConstantBackoff(1000)) .build(); ws.addEventListener(WebsocketEvent.open, () => console.log('opened!')); ws.addEventListener(WebsocketEvent.close, () => console.log('closed!')); ws.addEventListener(WebsocketEvent.message, (i, ev) => { console.log('received:', ev.data); i.send('echo: ' + ev.data); });

Debug

Known issues

breakingVersion 2.0.0 changed the builder API: .withBuffer() now requires a Queue instance instead of a boolean.

fix

Replace .withBuffer(true) with .withBuffer(new ArrayQueue()).

affects: >=1.0.0 <2.0.0

breakingIn version 2.0.0, the listen method was removed; use addEventListener instead.

fix

Replace ws.listen('open', cb) with ws.addEventListener(WebsocketEvent.open, cb).

affects: >=1.0.0 <2.0.0

deprecatedThe 'onOpen', 'onClose', etc. callback properties are deprecated since version 2.0.0.

fix

Use addEventListener or the on() method.

affects: >=1.0.0 <2.0.0

gotchaWebsocketEvent enum values are strings (e.g., 'open'), not numbers. Attempting to compare with numbers will fail.

fix

Use WebsocketEvent.open === 'open' or compare with the enum.

affects: >=2.0.0

Errors

Common errors & fixes

Error: WebsocketBuilder is not a constructor

Forgetting to import WebsocketBuilder or using wrong import (e.g., default import).

fix

Use named import: import { WebsocketBuilder } from 'websocket-ts'

Property 'withBuffer' does not exist on type 'WebsocketBuilder'.

Trying to call .withBuffer() after .build() or on a non-builder instance.

fix

Chain .withBuffer() before .build() on the builder.

Cannot read property 'send' of undefined

Calling ws.send() before the WebSocket is fully initialized (before 'open' event).

fix

Use buffering (ArrayQueue) to queue messages and send after connection.

TS2339: Property 'WebsocketEvent' does not exist on type 'typeof import('...')'

Using an older version (v1.x) that doesn't export WebsocketEvent.

fix

Upgrade to v2.0.0+ or use string literals like 'open' instead of enum.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

websocket-tsrequiredZero dependencies; this is the only package needed.

Agent activity

22 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/jjxxs/websocket-ts ↗

packagewebsocket-ts ↗

homepagehttps://github.com/jjxxs/websocket-ts#readme ↗