tools-websocket

library1.0.6jsnpmunverified

A JavaScript WebSocket utility library that provides heartbeat, auto-reconnection, and message retransmission for browser environments. Current stable version is 1.0.6. It was extracted from the tools-vue3 library to be used standalone in plain HTML/JS or any JavaScript project. Key differentiators: built-in heartbeat mechanism to detect stale connections, automatic reconnection with customizable intervals, and reliable message retransmission ensuring messages are not lost during disconnection. It ships with TypeScript type definitions and is ESM-only.

messaging

npm install tools-websocket

package ↗homepage ↗

INSTALL

IMPORT

SIG · TOOLS-WEBSOCKET

tools-websocket

messagingjavascriptv1.0.6

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.

WebSocketTool

✓ import { WebSocketTool } from 'tools-websocket'

✗ const WebSocketTool = require('tools-websocket')

ESM-only package; CommonJS require will fail.

createWebSocket

✓ import { createWebSocket } from 'tools-websocket'

Factory function to create a WebSocket instance with default options.

WebSocketOptions

✓ import type { WebSocketOptions } from 'tools-websocket'

TypeScript type for configuration options.

Shows how to create a WebSocket connection with heartbeat, auto-reconnect, and a message handler.

import { createWebSocket } from 'tools-websocket'; const ws = createWebSocket('wss://example.com/socket', { heartbeatInterval: 30000, reconnectInterval: 5000, maxReconnectAttempts: 10, onMessage: (data) => { console.log('Received:', data); }, onReconnect: (attempt) => { console.log(`Reconnecting attempt ${attempt}`); } }); ws.send('Hello server!'); // Later: close connection ws.close();

Debug

Known issues

breakingThe package is ESM-only starting from v1.0.0. CommonJS require() will throw an error.

fix

Use import syntax or configure your project to handle ESM (e.g., type: 'module' in package.json, or use dynamic import()).

affects: >=1.0.0

gotchaThe heartbeat feature requires the server to respond to a ping/pong mechanism. If the server does not support WebSocket ping/pong frames, you must disable heartbeat or provide a custom heartbeat message.

fix

Set heartbeatInterval: 0 to disable, or configure heartbeatMessage to send a custom message and listen for a response.

affects: >=1.0.0

gotchaMessage retransmission may cause duplicate messages if the server processes the same message twice on reconnection.

fix

Implement idempotency keys on the server side or limit retransmission count.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Trying to use import in a CommonJS file without proper configuration.

fix

Add "type": "module" to your package.json or rename file to .mjs, or use dynamic import().

ReferenceError: WebSocket is not defined

In Node.js environments where the native WebSocket API is not available.

fix

Use a WebSocket polyfill like 'ws' and set global.WebSocket before importing tools-websocket.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

packagetools-websocket ↗

homepagehttps://gitee.com/veigarchen ↗