README.md

WebSocketConnect

Modern and useful WebSocket API wrapper class with additional features such as auto-reconnect, message queuing and Keep-alive detection.

标准且实用的 WebSocket 包装器，具有标准 WebSocket API。支持心跳检测，异常消息处理和自动重连机制。

Features

• ⏰ With Standard WebSocket API
• 🧬 Automatic Reconnection
• 💓 Keep-alive (Ping) Support
• 📮 Message Queuing
• 🌐 Flexible Configuration

Installation

npm

npm install @jotter/websocket

browser

https://cdn.jsdelivr.net/npm/@jotter/websocket/dist/index.min.js

Usage

Fully compatible with the WebSocket API, for specific usage, please refer to: MDN WebSocket API

Basic:

import WebSocketConnect from '@jotter/websocket'

// Basic WebSocket connection
const ws = new WebSocketConnect('wss://example.com/')

// Event listeners
ws.addEventListener('open', (event) => {
	console.log('Connection established')
	ws.send('Hello, server!')
})

ws.onmessage = (event) => {
	console.log('Received message:', event.data)
}

// Send text
ws.send('Hello, world!')

// Send JSON
ws.send({ type: 'message', content: 'Hello' })

// Send binary data
ws.send(new ArrayBuffer(8))

Advanced:

const ws = new WebSocketConnect('wss://example.com/', {
	// Reconnection options
	reconnect: {
		enabled: true,
		maxAttempts: 5,
		delay: (attempt) => Math.min(2000 * Math.pow(1.2, attempt), 30000),
	},

	// Ping (Keep-alive) options
	ping: {
		enabled: true,
		interval: 3000,
		message: 'ping',
	},

	// Message queue options
	messageQueue: 100,

	// Optional WebSocket protocols
	protocols: ['chat', 'json'],
})

API

Constructor

new WebSocketConnect(
  url: string,
  protocols?: string | string[],
  options?: IOptions
)

url

WebSocket connection Url.

• Type: string

protocols

WebSocket connection protocol.

• Type: string | string[]

Options

WebSocket connection options.

interface IOptions {
	// Reconnection configuration
	reconnect?:
		| boolean
		| {
				enabled?: boolean
				maxAttempts?: number
				delay?: number | ((attempt: number) => number)
				shouldReconnect?: (event: CloseEvent, context: any) => boolean
		  }

	// Keep-alive (Ping) configuration
	ping?:
		| boolean
		| {
				enabled?: boolean
				interval?: number
				message?: any
		  }

	// Message queue configuration (Storing Unsent Messages)
	messageQueue?:
		| boolean
		| number
		| {
				enabled?: boolean
				max?: number
		  }

	// WebSocket protocols
	protocols?: string | string[]
}

reconnect

Reconnection configuration.

prop	type	default	description
enabled	boolean	true	Whether to automatically reconnect
maxAttempts	number | (attempt)=>number	10	Maximum number of reconnection attempts
delay	number	1000	Reconnection delay (ms)
shouldReconnect	(event, ctx) => boolean		User-defined reconnection rules

ping

Keep-alive (Ping) configuration.

prop	type	default	description
enabled	boolean	true	Whether to send keep-alive (Ping)
interval	number	30000	Keep-alive (Ping) interval (ms)
message	any	'ping'	Keep-alive (Ping) message

messageQueue

Message queue configuration. (Accumulated unsent-messages are sent when the connection is successful)

prop	type	default	description
enabled	boolean	true	Whether to enable message queue
max	number	100	Maximum number of messages in the queue

Methods

• send(data: any): Send a message
• close(code?: number, reason?: string): Close the connection

Events

• open: Connection established
• close: Connection closed
• message: Message received
• error: Connection error
• connecting: Connection is being established
• reconnect: Reconnection attempt
• reconnectend: Reconnection attempts ended

Properties

• url: WebSocket URL
• readyState: Current connection state
• protocol: Negotiated protocol
• bufferedAmount: Number of bytes queued
• binaryType: Binary data type
• extensions: Negotiated extensions

Browser Compatibility

Supports all modern browsers with WebSocket API support.

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.