@jotter/websocket NPM

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 WebSocketConnectOptions {
	// 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