ltws

library1.0.9jsnpmunverified

ltws is a lightweight WebSocket library that provides automatic reconnection and promise-based async connection. It wraps the native WebSocket API and adds event-driven communication, automatic ping/pong keep-alive, and customizable retry logic. Version 1.0.9 is stable. It offers a simple API with connect, send, sendJson, and event listeners for connect, disconnect, message, json, and errors. Key differentiators: built-in reconnection with configurable delays and retries, support for both callback and async/await patterns, and TypeScript-like type definitions.

messaging

npm install ltws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LTWS

ltws

messagingjavascriptv1.0.9

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.

default

✓ import ltws from 'ltws'

✗ const ltws = require('ltws')

Since v1, the package is ESM-only. The default export is a module with connect and createInstance methods.

connect

✓ import ltws from 'ltws'; const ws = ltws.connect('ws://...');

✗ const ltws = require('ltws').connect('ws://...');

connect is a method on the default export, not a named export.

createInstance

✓ import ltws from 'ltws'; const ws = ltws.createInstance();

✗ const { createInstance } = require('ltws');

createInstance is a method on the default export, not a named export.

Connects to an echo WebSocket server, sends a text message and a JSON message, logs incoming messages, and disconnects after 5 seconds.

import ltws from 'ltws'; const ws = ltws.connect('wss://echo.websocket.org'); ws.on('connect', () => { ws.send('Hello from ltws!'); ws.sendJson({ msg: 'Hello JSON!' }); }); ws.on('message', (data) => { console.log('Message:', data); }); ws.on('json', (data) => { console.log('JSON:', data); }); ws.on('error', (err) => { console.error('WebSocket error:', err); }); setTimeout(() => { ws.disconnect(); console.log('Disconnected'); }, 5000);

Debug

Known issues

breakingDefault export no longer is a constructor; use ltws.connect() or ltws.createInstance() instead.

fix

Replace new ltws() with ltws.connect(url) or ltws.createInstance().

affects: >=1.0.0

deprecatedThe useReconnectEvent option is deprecated and may be removed in a future version.

fix

Set useReconnectEvent to false (default) and listen for 'reconnect' event directly.

affects: >=1.0.0

gotchasendJson does not clone the object; mutations after send may affect data in transit.

fix

Call JSON.parse(JSON.stringify(obj)) before passing to sendJson if you need to preserve immutability.

affects: >=1.0.0

gotchaIn Node.js, you must install the 'ws' package as a dependency; the library does not include it.

fix

Run npm install ws alongside ltws.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ws'

The 'ws' package is required in Node.js environments but is not automatically installed.

fix

npm install ws

TypeError: ltws is not a constructor

Importing ltws and trying to use it as a constructor (e.g., new ltws()).

fix

Use ltws.connect(url) or ltws.createInstance() instead.

TypeError: ws.send is not a function

Calling send before the connection is established.

fix

Wrap send calls inside the 'connect' event listener, or use connectAsync and await.

Error: connect ETIMEDOUT

Connection attempt timed out, possibly due to network or server issues.

fix

Increase connectTimeout option or check server availability.

Upgrade

Version history

1.0.9latest on npm

Audit

Dependencies

wsoptionalWebSocket implementation for Node.js environments; required for server-side usage

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ltmin/ltws ↗

packageltws ↗

homepagehttps://github.com/ltmin/ltws#readme ↗