elmer-socket

library2.0.14jsnpmunverified

A lightweight WebSocket client library for Node.js built on the `ws` library (peer dependency v8.11.0+). Provides a clean, Promise-based API for WebSocket connections, message handling, and automatic reconnection. Current stable version is 2.0.14, released with TypeScript declarations included. Differentiates from raw `ws` by offering higher-level abstractions like event emitters, reconnection logic, and simpler error handling. Suitable for real-time applications, chat systems, and live data feeds.

messaging

npm install elmer-socket

package ↗

INSTALL

IMPORT

SIG · ELMER-SOCKET

elmer-socket

messagingjavascriptv2.0.14

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.

ElmerSocket

✓ import { ElmerSocket } from 'elmer-socket'

✗ const ElmerSocket = require('elmer-socket')

ESM-only; this package does not provide CommonJS. TypeScript types are included.

ElmerSocket

✓ import ElmerSocket from 'elmer-socket'

✗ import { ElmerSocket } from 'elmer-socket'

The package exports a default class. Named import `ElmerSocket` is also available but less common.

WebSocketMessage

✓ import type { WebSocketMessage } from 'elmer-socket'

✗ import { WebSocketMessage } from 'elmer-socket'

Type-only import to avoid runtime overhead.

Shows basic WebSocket connection with event handlers for open, message, close, and error.

import ElmerSocket from 'elmer-socket'; const ws = new ElmerSocket('ws://localhost:8080'); ws.on('open', () => { console.log('Connected'); ws.send('Hello server!'); }); ws.on('message', (data) => { console.log('Received:', data); }); ws.on('close', () => { console.log('Disconnected'); }); ws.on('error', (err) => { console.error('WebSocket error:', err); });

Debug

Known issues

breakingIn version 2.0.0, the default export changed from a function to a class.

fix

Update to new class-based API: use `new ElmerSocket(url, options)` instead of `ElmerSocket(url, options)`.

affects: >=1.0.0 <2.0.0

breakingPeer dependency `ws` must be version ^8.11.0; using older versions may cause runtime errors.

fix

Run `npm install ws@^8.11.0` to satisfy peer dependency.

affects: >=2.0.0

deprecatedThe `readyState` property is deprecated; use `ws.status` instead.

fix

Replace `ws.readyState` with `ws.status`.

affects: >=2.0.0

deprecatedThe `bufferedAmount` property is deprecated and will be removed in v3.

fix

Use `ws.bufferedBytes()` method instead.

affects: >=2.0.0

gotchaCalling `ws.send()` before the 'open' event may throw or silently fail.

fix

Always send messages inside the 'open' event callback or after checking `ws.readyState === ws.OPEN` (use `ws.status` in v2).

affects: >=1.0.0

gotchaThe library does not support browser environments; it requires Node.js and the `ws` package.

fix

Use a browser-compatible WebSocket library like `isomorphic-ws` if targeting the browser.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ws'

Missing peer dependency `ws`.

fix

Run `npm install ws@^8.11.0` in your project.

TypeError: Class constructor ElmerSocket cannot be invoked without 'new'

Using the package without the `new` keyword.

fix

Instantiate with `new ElmerSocket(url, options)`.

Error: send() called before connection is established

Calling `ws.send()` before the 'open' event is emitted.

fix

Call `ws.send()` only inside the 'open' event handler or after ensuring the connection is open using `ws.status`.

TypeError: ws.on is not a function

Importing the package incorrectly or using a version that does not support event methods.

fix

Use the default import: `import ElmerSocket from 'elmer-socket'`.

Upgrade

Version history

2.0.14latest on npm

Audit

Dependencies

wsrequiredPeer dependency for underlying WebSocket implementation

Agent activity

22 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packageelmer-socket ↗