@gibme/websocket

Simple cross-platform WebSocket client helper for Node.js and browsers.

Provides a unified, event-driven interface with automatic message buffering, auto-reconnect support, and consistent Buffer-based message delivery across platforms.

Installation

npm install @gibme/websocket
# or
yarn add @gibme/websocket

Requirements

• Node.js >= 22

Quick Start

import WebSocket from '@gibme/websocket';

const socket = new WebSocket({
    url: 'wss://echo.websocket.org/echo',
    autoReconnect: true
});

socket.connect();

socket.on('message', (message) => {
    console.log('Received:', message.toString());
});

socket.send(JSON.stringify({ hello: 'world' }));

Constructor Options

Option	Type	Default	Description
url	string	required	WebSocket server URL
protocols	string | string[]	undefined	WebSocket sub-protocols
binaryType	'arraybuffer' | 'nodebuffer' | 'fragments'	'arraybuffer'	Binary data representation
autoReconnect	boolean	false	Automatically reconnect on close

Methods

connect() / open()

Opens the WebSocket connection. Can be called again to reconnect after a close.

send(data)

Sends data through the WebSocket. If the connection is not yet open, messages are automatically queued and sent once the connection is ready.

Accepts string, ArrayBufferLike, ArrayBufferView, or Buffer.

close(code?, reason?)

Closes the WebSocket connection. Prevents auto-reconnect from triggering.

Properties

Property	Type	Description
readyState	number	Connection state: 0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED
bufferedAmount	number	Bytes of data queued in the underlying WebSocket
extensions	string	Negotiated extensions
protocol	string	Negotiated sub-protocol
url	string	Remote WebSocket URL
binaryType	string	Get/set binary data representation

Events

Event	Payload	Description
open	—	Connection established
ready	—	Connection confirmed ready; queued messages are flushed
message	Buffer	Message received (always delivered as a Buffer)
close	—	Connection closed
error	Error	An error occurred

Browser Support

This package uses isomorphic-ws to provide a consistent WebSocket API across Node.js and browser environments. A webpack bundle is available at dist/websocket.min.js for direct browser usage.

License

MIT - see LICENSE for details.

Documentation

Full API documentation is available at https://gibme-npm.github.io/websocket/.