websocket-client-plus/README.md

Enhanced WebSocket client with reconnect, heartbeat and message queue support.

# websocket-client-plus
> 一个支持自动重连与心跳检测的 WebSocket 客户端，适用于需要稳定长连接的前端应用。

## ✨ 功能特点
- 封装原生 WebSocket，支持断线自动重连
- 内置心跳检测机制，防止连接意外断开
- 支持单例模式，避免重复连接
- 简洁的事件驱动 API（支持 on / off / emit 方法）
- 类型安全、零依赖、易于扩展
- 适用于实时数据推送、消息系统、状态同步等场景

## 📦 安装
```bash
# 使用 pnpm
pnpm add websocket-client-plus

# 使用 npm
npm install websocket-client-plus

# 使用 yarn
yarn add websocket-client-plus
````

## 🔧 使用示例

```ts
import SocketClient from 'websocket-client-plus'

const client = SocketClient.getInstance('wss://example.com/ws', {
  heartbeatInterval: 5000,
  maxReconnectAttempts: 5
})

client.on('channel-open', () => {
  console.log('连接已建立')
  client.send('hello server')
})

client.on('channel-message', (msg) => {
  console.log('收到消息:', msg)
})

client.on('channel-error', (err) => {
  console.error('连接错误:', err)
})

client.on('channel-close', () => {
  console.log('连接已关闭')
})

client.on('state-change', (state) => {
  console.log('状态变更:', state)
})
```

## 🧩 支持的事件

| 事件名称                  | 描述                             |
| --------------------- | ------------------------------ |
| `channel-open`        | WebSocket 连接成功建立后触发            |
| `channel-message`     | 每收到一条服务端消息时触发                  |
| `channel-error`       | 连接错误时触发，包含异常详情                 |
| `channel-close`       | 连接被关闭时触发                       |
| `state-change`        | 连接状态变更时触发（如 CONNECTING、OPEN 等） |
| `reconnect-exhausted` | 超出最大重连次数后触发，停止继续重连             |

## ⚙️ 可选配置项

通过构造函数或 `getInstance()` 的第二个参数传入：

| 配置项                    | 类型       | 默认值      | 描述            |
| ---------------------- | -------- | -------- | ------------- |
| `baseRetryDelay`       | `number` | `2000`   | 初始重连延迟（ms）    |
| `maxRetryDelay`        | `number` | `60000`  | 最大重连延迟（ms）    |
| `maxReconnectAttempts` | `number` | `10`     | 最大自动重连尝试次数    |
| `heartbeatInterval`    | `number` | `5000`   | 心跳发送间隔（ms）    |
| `pingMessage`          | `string` | `'ping'` | 发送到服务端的心跳消息内容 |
| `pongMessage`          | `string` | `'pong'` | 服务端响应的心跳消息内容 |

## 🛠️ API 文档

### `SocketClient.getInstance(url: string, options?: SocketClientOptions): SocketClient`

创建并获取 WebSocket 单例客户端。

---

### `send(message: string): void`

发送字符串消息。

---

### `on(eventName: string, handler: (...args: any[]) => void): void`

注册事件监听器。

---

### `off(eventName: string, handler?: (...args: any[]) => void): void`

移除事件监听器。

---

### `destroy(): void`

销毁客户端，断开连接并清除资源。

---

## 🧪 示例场景

* 🧠 AI 聊天：基于 WebSocket 实现的实时多轮对话
* 📡 实时看板：服务端推送状态/指标数据更新
* 🎮 多人协作：白板、游戏状态同步等实时应用
* 📣 通知系统：基于频道的事件推送服务
* 📦 微前端桥接：跨子应用的事件总线通信

## 🧠 最后

如果你正在构建一个对实时性要求较高的 Web 项目，希望 `websocket-client-plus` 能为你提供一个稳定可靠的长连接方案，减少重复造轮子，专注业务逻辑。

如果你在使用过程中遇到问题，或者对 `websocket-client-plus` 感兴趣，欢迎一起交流探讨。

📬 可加微信（备注 “WebSocket + 昵称”）：**g_adiu**