@profullstack/websocket-client

A robust WebSocket client with connection management, reconnection logic, and message handling.

Features

• Universal: Works in both browser and Node.js environments
• Reconnection: Automatic reconnection with exponential backoff
• Event-based: Simple event-based API
• Message Queue: Queues messages sent before connection is established
• Adapters: Pluggable adapters for different environments
• Customizable: Configurable reconnection behavior, protocols, and headers

Installation

1npm install @profullstack/websocket-client

Basic Usage

1import { createWebSocketClient } from '@profullstack/websocket-client';
2
3// Create a WebSocket client
4const client = createWebSocketClient({
5  url: 'wss://echo.websocket.org'
6});
7
8// Listen for connection open
9client.on('open', () => {
10  console.log('Connected!');
11  
12  // Send a message
13  client.send('Hello WebSocket!');
14  
15  // Send a JSON message
16  client.send({
17    type: 'greeting',
18    content: 'Hello from client!'
19  });
20});
21
22// Listen for messages
23client.on('message', (data) => {
24  console.log('Received:', data);
25});
26
27// Listen for connection close
28client.on('close', (event) => {
29  console.log(`Connection closed: ${event.code} ${event.reason}`);
30});
31
32// Listen for errors
33client.on('error', (error) => {
34  console.error('WebSocket error:', error);
35});

API Reference

Creating a WebSocket Client

1import { createWebSocketClient } from '@profullstack/websocket-client';
2
3const client = createWebSocketClient({
4  // WebSocket server URL (required)
5  url: 'wss://example.com/socket',
6  
7  // WebSocket protocols (optional)
8  protocols: ['v1.protocol.example'],
9  
10  // Additional headers for the connection (Node.js only, optional)
11  headers: {
12    'Authorization': 'Bearer token123'
13  },
14  
15  // Reconnection interval in milliseconds (default: 1000)
16  reconnectInterval: 1000,
17  
18  // Maximum reconnection interval in milliseconds (default: 30000)
19  maxReconnectInterval: 30000,
20  
21  // Reconnection decay factor (default: 1.5)
22  reconnectDecay: 1.5,
23  
24  // Maximum number of reconnection attempts (default: Infinity)
25  maxReconnectAttempts: 10,
26  
27  // Whether to automatically connect on instantiation (default: true)
28  automaticOpen: true,
29  
30  // Whether to automatically reconnect on disconnect (default: true)
31  automaticReconnect: true,
32  
33  // Function to determine whether to reconnect (default: always)
34  shouldReconnect: (event) => event.code !== 1000,
35  
36  // Custom WebSocket adapter (default: auto-detect)
37  adapter: null
38});

Connection Management

1// Connect to the WebSocket server
2await client.connect();
3
4// Disconnect from the WebSocket server
5client.disconnect(1000, 'Normal closure');
6
7// Manually trigger reconnection
8client.reconnect();

Sending Messages

1// Send a string message
2client.send('Hello WebSocket!');
3
4// Send a JSON message (automatically stringified)
5client.send({
6  type: 'greeting',
7  content: 'Hello from client!'
8});
9
10// Send binary data (ArrayBuffer or Blob)
11const buffer = new ArrayBuffer(8);
12client.send(buffer);

Event Handling

1// Connection opened
2client.on('open', (event) => {
3  console.log('Connected!');
4});
5
6// Message received
7client.on('message', (data, event) => {
8  console.log('Received:', data);
9});
10
11// Connection closed
12client.on('close', (event) => {
13  console.log(`Connection closed: ${event.code} ${event.reason}`);
14});
15
16// Connection error
17client.on('error', (error) => {
18  console.error('WebSocket error:', error);
19});
20
21// Reconnecting
22client.on('reconnecting', (info) => {
23  console.log(`Reconnecting... Attempt ${info.attempt} after ${info.interval}ms`);
24});
25
26// Reconnection failed
27client.on('reconnect_failed', () => {
28  console.error('Failed to reconnect after maximum attempts');
29});
30
31// Remove event listener
32const onMessage = (data) => console.log('Received:', data);
33client.on('message', onMessage);
34client.off('message', onMessage);

Advanced Usage

Custom Adapter

1import { createWebSocketClient, createBrowserAdapter } from '@profullstack/websocket-client';
2
3// Create a custom adapter
4const customAdapter = createBrowserAdapter();
5
6// Use the custom adapter
7const client = createWebSocketClient({
8  url: 'wss://example.com/socket',
9  adapter: customAdapter
10});

Custom Reconnection Logic

1const client = createWebSocketClient({
2  url: 'wss://example.com/socket',
3  
4  // Custom reconnection interval
5  reconnectInterval: 2000,
6  
7  // Maximum reconnection interval
8  maxReconnectInterval: 60000,
9  
10  // Exponential backoff factor
11  reconnectDecay: 2.0,
12  
13  // Maximum number of reconnection attempts
14  maxReconnectAttempts: 5,
15  
16  // Custom logic to determine whether to reconnect
17  shouldReconnect: (event) => {
18    // Don't reconnect on normal closure or if the server is going away
19    if (event.code === 1000 || event.code === 1001) {
20      return false;
21    }
22    
23    // Don't reconnect if the server rejected the connection
24    if (event.code === 1003 || event.code === 1008 || event.code === 1009) {
25      return false;
26    }
27    
28    // Reconnect on all other close codes
29    return true;
30  }
31});

Node.js Usage with Headers

1import { createWebSocketClient } from '@profullstack/websocket-client';
2
3const client = createWebSocketClient({
4  url: 'wss://api.example.com/socket',
5  headers: {
6    'Authorization': 'Bearer token123',
7    'User-Agent': 'MyApp/1.0',
8    'X-Custom-Header': 'CustomValue'
9  }
10});

Browser Support

The WebSocket client works in all modern browsers that support the WebSocket API:

• Chrome 4+
• Firefox 4+
• Safari 5+
• Edge 12+
• Opera 10.7+
• iOS Safari 4.2+
• Android Browser 4.4+
• Chrome for Android 86+

Examples

See the examples directory for complete usage examples.

License

MIT