npm package: @lejurobot/stomp-websocket
Description: A Vue 3 STOMP WebSocket library with composable hooks
Latest version: 1.0.3

# @lejurobot/stomp-websocket

一个基于 Vue 3 的 STOMP WebSocket 库，提供组合式 API（Composable Hooks），让 WebSocket 通信变得更加简单。

## 这个包提供了什么

本包提供了两个核心的组合式函数，帮助你在 Vue 3 项目中轻松实现 STOMP WebSocket 通信：

### 1. **useStomp** - 基础连接管理

提供完整的 STOMP WebSocket 连接管理功能：

- ✅ 连接/断开管理
- ✅ 订阅/取消订阅主题
- ✅ 发送消息
- ✅ 自动重连机制
- ✅ 连接状态实时监听
- ✅ 消息接收处理

### 2. **useStompChannel** - 高级通道管理

在 useStomp 基础上提供更高级的功能：

- ✅ 自动订阅主题
- ✅ 定时轮询发送消息
- ✅ 连接状态变化时自动恢复订阅
- ✅ 组件卸载时自动清理资源
- ✅ 手动发送消息接口

## 主要特性

- 🎯 完美支持 Vue 3 Composition API
- 🔄 自动重连处理，无需手动干预
- 📦 简单直观的 API 设计
- 🎨 完整的 TypeScript 类型支持
- ⚡ 轻量级，性能优异
- 🛡️ 自动资源清理，避免内存泄漏

## 安装

```bash
npm install @lejurobot/stomp-websocket
# 或
pnpm add @lejurobot/stomp-websocket
# 或
yarn add @lejurobot/stomp-websocket
```

## 依赖要求

本包需要以下 peer dependencies：

```json
{
  "vue": "^3.0.0",
  "@stomp/stompjs": "^7.0.0"
}
```

## 使用示例

### 基础用法 - useStomp

```typescript
import { useStomp } from "@lejurobot/stomp-websocket";

// 创建 STOMP 实例
const { connectionStatus, connect, disconnect, subscribe, send } = useStomp(
  "ws://localhost:8080/ws",
);

// 连接到服务器
connect();

// 订阅主题
subscribe("/topic/messages", (payload) => {
  console.log("收到消息:", payload);
});

// 发送消息
send("/app/chat", { message: "Hello World" });

// 断开连接
disconnect();
```

### 高级用法 - useStompChannel

```typescript
import { useStomp, useStompChannel } from "@lejurobot/stomp-websocket";

// 创建基础 STOMP 实例
const stomp = useStomp("ws://localhost:8080/ws");
stomp.connect();

// 使用通道管理器
const { isConnected, lastMessage, send } = useStompChannel(stomp, {
  // 自动订阅的主题
  subscribeTopic: "/topic/updates",

  // 定时发送的配置
  sends: [
    {
      destination: "/app/ping",
      interval: 5000, // 每5秒发送一次
      payload: () => ({ data: "ping" }),
    },
  ],

  // 收到消息的回调
  onMessage: (payload) => {
    console.log("收到消息:", payload);
  },

  // 连接成功的回调
  onConnected: (sendFn) => {
    console.log("已连接!");
    sendFn("/app/hello", { greeting: "Hi there!" });
  },
});
```

## API 参考

### useStomp

返回一个包含以下属性和方法的对象：

| 属性/方法          | 类型                                            | 说明                                                                                                 |
| ------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `connectionStatus` | `Ref<ConnectionStatus>`                         | 当前连接状态：'disconnected'（断开）、'connecting'（连接中）、'connected'（已连接）、'error'（错误） |
| `messages`         | `Ref<any[]>`                                    | 接收到的消息数组                                                                                     |
| `connect`          | `() => void`                                    | 连接到 WebSocket 服务器                                                                              |
| `disconnect`       | `() => void`                                    | 断开与服务器的连接                                                                                   |
| `subscribe`        | `(topic: string, callback: Function) => string` | 订阅主题，返回主题 ID                                                                                |
| `unsubscribe`      | `(topic: string) => void`                       | 取消订阅主题                                                                                         |
| `send`             | `(destination: string, body: object) => void`   | 向指定目标发送消息                                                                                   |
| `isConnected`      | `() => boolean`                                 | 检查当前是否已连接                                                                                   |

### useStompChannel

用于管理订阅和定时发送的高级组合式函数。

#### 配置选项

```typescript
interface StompChannelOptions {
  subscribeTopic?: string; // 要订阅的主题
  sends?: SendConfig[]; // 定时发送配置数组
  onMessage?: (payload: any) => void; // 消息回调函数
  onConnected?: (sendFn: Function) => void; // 连接成功回调函数
}

interface SendConfig {
  destination: string; // 发送目标
  interval?: number; // 发送间隔（毫秒，默认 3000）
  payload?: () => any; // 返回负载数据的函数
}
```

#### 返回值

| 属性/方法         | 类型                                              | 说明             |
| ----------------- | ------------------------------------------------- | ---------------- |
| `subscriptionId`  | `Ref<string \| null>`                             | 当前订阅 ID      |
| `isConnected`     | `Ref<boolean>`                                    | 连接状态         |
| `lastMessage`     | `Ref<any>`                                        | 最后收到的消息   |
| `send`            | `(destination: string, payload?: any) => boolean` | 手动发送消息函数 |
| `startAllSending` | `() => void`                                      | 启动所有定时发送 |
| `stopAllSending`  | `() => void`                                      | 停止所有定时发送 |
| `unsubscribe`     | `() => void`                                      | 取消订阅主题     |

## TypeScript 支持

本包使用 TypeScript 编写，包含完整的类型定义：

```typescript
import type { PayloadType, ConnectionStatus } from "@lejurobot/stomp-websocket";
import type {
  SendConfig,
  StompChannelOptions,
} from "@lejurobot/stomp-websocket";
```

## 许可证

MIT

## 贡献

欢迎贡献！请随时提交 Pull Request。