Registry / communication / light-websocket-client-ts

light-websocket-client-ts

library0.0.22jsnpmunverified

A lightweight WebSocket client library for TypeScript with built-in keep-alive and automatic reconnection with exponential backoff. Version 0.0.22, active development. Requires a custom protocol header for heartbeat (since browser WebSocket API cannot send ping frames) and must be paired with the companion server `light-websocket-server`. Differentiates from raw WebSocket by providing reconnect management, disconnection callbacks, and a simple interface for both browser and Node.js (using the `ws` package). Ships TypeScript type definitions.

communication

npm install light-websocket-client-ts

package ↗

INSTALL

IMPORT

SIG · LIGHT-WEBSOCKET-CL

light-websocket-client-ts

communicationjavascriptv0.0.22

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.

LightWebsocketClientImpl

✓ import { LightWebsocketClientImpl } from 'light-websocket-client-ts'

✗ const LightWebsocketClientImpl = require('light-websocket-client-ts')

ESM-only package; CommonJS require will not work. TypeScript types included.

LightWebsocketCLientNodeImpl

✓ import { LightWebsocketClientImpl } from 'light-websocket-client-ts'; import * as WebSocket from 'ws'; class LightWebsocketCLientNodeImpl extends LightWebsocketClientImpl { ... }

✗ const LightWebsocketCLientNodeImpl = require('light-websocket-client-ts').LightWebsocketCLientNodeImpl

Node.js implementation is not exported; you must create a subclass that overrides createWebsocket. The example uses a class named LightWebsocketCLientNodeImpl but that's user-defined.

LightWebsocketClientImpl (default export?)

✓ import { LightWebsocketClientImpl } from 'light-websocket-client-ts'

✗ import LightWebsocketClientImpl from 'light-websocket-client-ts'

The library does not have a default export; only named exports.

methods onInstance

✓ const client = new LightWebsocketClientImpl(url); client.onConnect(cb); client.onDisconnect(cb); client.onMessage(cb); client.connect(); client.disconnect();

✗ client.onconnect(cb)

Method names are camelCase; onConnect, onDisconnect, onMessage are methods, not properties. Callback registration is via method calls, not assignment.

Creates a WebSocket client, registers lifecycle callbacks, connects, sends a message, and demonstrates disconnect.

import { LightWebsocketClientImpl } from 'light-websocket-client-ts'; const client = new LightWebsocketClientImpl('ws://localhost:8080/ws'); client.onConnect(() => { console.log('Connected'); }); client.onDisconnect((code?: number, reason?: string) => { console.log('Disconnected', code, reason); }); client.onMessage((message: string) => { console.log('Received:', message); }); client.connect(); // Send a message client.send('Hello server'); // Disconnect (disables auto-reconnect) // client.disconnect();

Debug

Known issues

gotchaThe library requires a companion server `light-websocket-server` that implements the custom protocol header (heartbeat/keep-alive). Using a standard WebSocket server will cause connection failures or unexpected behavior.

fix

Use the corresponding server `light-websocket-server` or implement the protocol as documented.

affects: >=0.0.1

gotchaIn Node.js environments, you must install the `ws` package and create a subclass of `LightWebsocketClientImpl` to override `createWebsocket` method. The library does not export a Node.js-specific class.

fix

npm install ws and then define a class extending LightWebsocketClientImpl that returns new WebSocket(url, protocols, {}) from createWebsocket.

affects: >=0.0.1

gotchaThe constructor and methods use camelCase (e.g., `onDisconnect`, `onConnect`). The README uses inconsistent naming (e.g., `onDisconnect` vs `onDisconnect`). Ensure correct capitalization.

fix

Use exactly `onConnect`, `onDisconnect`, `onMessage` as methods.

affects: >=0.0.1

deprecatedThe method `createWebsocket` returns `any` type; TypeScript strict mode may require type assertion. No official type for the WebSocket instance is provided.

fix

Override with correct type: `createWebsocket(url: string, protocols?: string[]): WebSocket { return new WebSocket(url, protocols); }`

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: LightWebsocketClientImpl is not a constructor

Using CommonJS require or default import when only named export exists.

fix

Use `import { LightWebsocketClientImpl } from 'light-websocket-client-ts'`

Error: No 'ws' module found. Please install 'ws' for Node.js usage.

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

fix

Run `npm install ws` and ensure it's available.

WebSocket connection to 'ws://...' failed: Unexpected response code: 101

The server side does not have the custom protocol implemented; standard WebSocket server returns 101 and connection appears to succeed but client will fail due to missing heartbeat.

fix

Deploy the required `light-websocket-server` or ensure your server sends the correct protocol header.

Cannot read properties of undefined (reading 'on')

Creating a LightWebsocketClientImpl without calling `connect()` first before calling `onConnect` or other methods? Actually the methods can be called before connect; this error may occur if the internal socket is not initialized.

fix

Call `client.connect()` after setting callbacks. Ensure you are not interacting before connect.

Upgrade

Version history

0.0.22latest on npm

Audit

Dependencies

wsoptionalRequired for Node.js environments to create WebSocket instances

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

packagelight-websocket-client-ts ↗