@ichaingo/web-socket 1.3.0

package/README.md

@@ -0,0 +1,451 @@
+# @ichaingo/socket
+
+基于WebSocket的单例模式连接库，提供稳定可靠的WebSocket连接管理功能和React Hooks。
+
+## 特性
+
+- 🔄 **单例模式**: 确保全局只有一个WebSocket连接实例
+- 🔁 **自动重连**: 连接断开时自动尝试重连，支持配置重连次数和间隔
+- 💓 **心跳检测**: 定期发送心跳包保持连接活跃
+- 📡 **事件驱动**: 支持多种事件监听（连接、消息、错误、状态变化等）
+- 🛡️ **错误处理**: 完善的错误处理和状态管理
+- 📝 **TypeScript**: 完整的TypeScript类型支持
+- 🐛 **调试模式**: 支持调试日志输出
+- ⚛️ **React Hooks**: 提供便捷的React Hooks用于组件集成
+
+## 安装
+
+```bash
+npm install @ichaingo/socket
+# 或
+pnpm add @ichaingo/socket
+# 或
+yarn add @ichaingo/socket
+```
+
+## 快速开始
+
+### 基本使用
+
+```typescript
+import SocketConnection, { ConnectionStatus } from '@ichaingo/socket';
+
+// 创建连接实例
+const socket = SocketConnection.getInstance({
+  url: 'ws://localhost:8080',
+  debug: true
+});
+
+// 连接WebSocket
+await socket.connect();
+
+// 发送消息
+socket.send('Hello WebSocket!');
+socket.sendJSON({ type: 'message', content: 'Hello!' });
+
+// 监听消息
+socket.on('message', (data) => {
+  console.log('收到消息:', data);
+});
+
+// 监听连接状态变化
+socket.on('statusChange', (status) => {
+  console.log('连接状态:', status);
+});
+```
+
+### React Hooks 使用
+
+#### useSocket Hook
+
+```tsx
+import React from 'react';
+import { useSocket } from '@ichaingo/socket';
+
+function ChatComponent() {
+  const socket = useSocket({
+    url: 'ws://localhost:8080',
+    debug: true,
+    autoConnect: true
+  });
+
+  const [messages, setMessages] = useState<string[]>([]);
+
+  useEffect(() => {
+    socket.on('message', (data) => {
+      if (typeof data === 'string') {
+        setMessages(prev => [...prev, data]);
+      }
+    });
+
+    return () => {
+      socket.off('message');
+    };
+  }, [socket]);
+
+  const sendMessage = (message: string) => {
+    socket.send(message);
+  };
+
+  return (
+    <div>
+      <div>连接状态: {socket.status}</div>
+      <div>是否已连接: {socket.isConnected ? '是' : '否'}</div>
+      {/* 你的UI组件 */}
+    </div>
+  );
+}
+```
+
+#### useSocketMessage Hook
+
+专门用于监听特定类型消息的简化Hook：
+
+```tsx
+import React from 'react';
+import { useSocketMessage } from '@ichaingo/socket';
+
+interface ChatMessage {
+  user: string;
+  content: string;
+  timestamp: number;
+}
+
+function ChatComponent() {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+
+  const socket = useSocketMessage<ChatMessage>({
+    url: 'ws://localhost:8080/chat',
+    debug: true,
+    autoConnect: true
+  }, (message) => {
+    setMessages(prev => [...prev, message]);
+  });
+
+  const sendMessage = (user: string, content: string) => {
+    socket.sendJSON({
+      user,
+      content,
+      timestamp: Date.now()
+    });
+  };
+
+  return (
+    <div>
+      <div>连接状态: {socket.status}</div>
+      {/* 你的UI组件 */}
+    </div>
+  );
+}
+```
+
+#### useSocketStatus Hook
+
+专门用于监听连接状态的简化Hook：
+
+```tsx
+import React from 'react';
+import { useSocketStatus } from '@ichaingo/socket';
+
+function StatusIndicator() {
+  const status = useSocketStatus({
+    url: 'ws://localhost:8080',
+    debug: true,
+    autoConnect: true
+  });
+
+  return (
+    <div>
+      <div>状态: {status.status}</div>
+      <div>是否已连接: {status.isConnected ? '是' : '否'}</div>
+      <div>是否正在连接: {status.isConnecting ? '是' : '否'}</div>
+      <div>是否正在重连: {status.isReconnecting ? '是' : '否'}</div>
+      <div>是否已断开: {status.isDisconnected ? '是' : '否'}</div>
+      <div>是否有错误: {status.hasError ? '是' : '否'}</div>
+    </div>
+  );
+}
+```
+
+## API 参考
+
+### SocketConnection
+
+#### 静态方法
+
+- `getInstance(config?: WebSocketConfig): SocketConnection` - 获取单例实例
+
+#### 实例方法
+
+- `connect(): Promise<void>` - 连接WebSocket
+- `disconnect(): void` - 断开连接
+- `send(data: string | ArrayBuffer | Blob): boolean` - 发送消息
+- `sendJSON(data: any): boolean` - 发送JSON消息
+- `on<K extends keyof WebSocketEvents>(event: K, listener: WebSocketEvents[K]): void` - 添加事件监听器
+- `off<K extends keyof WebSocketEvents>(event: K): void` - 移除事件监听器
+- `getStatus(): ConnectionStatus` - 获取连接状态
+- `isConnected(): boolean` - 检查是否已连接
+- `destroy(): void` - 销毁实例
+
+### React Hooks
+
+#### useSocket
+
+```typescript
+function useSocket(config: UseSocketConfig): UseSocketReturn
+```
+
+**参数:**
+- `config`: WebSocket配置选项，继承自`WebSocketConfig`并添加了React相关选项
+
+**返回值:**
+- `status`: 当前连接状态
+- `isConnected`: 是否已连接
+- `connect`: 连接方法
+- `disconnect`: 断开连接方法
+- `send`: 发送消息方法
+- `sendJSON`: 发送JSON消息方法
+- `on`: 添加事件监听器方法
+- `off`: 移除事件监听器方法
+- `error`: 当前错误状态
+- `reconnectAttempts`: 重连次数
+- `reconnect`: 手动重连方法
+
+#### useSocketMessage
+
+```typescript
+function useSocketMessage<T>(
+  config: UseSocketConfig,
+  messageHandler: (data: T) => void
+): UseSocketReturn
+```
+
+专门用于监听特定类型消息的简化Hook。
+
+#### useSocketStatus
+
+```typescript
+function useSocketStatus(config: UseSocketConfig): {
+  status: ConnectionStatus;
+  isConnected: boolean;
+  isConnecting: boolean;
+  isReconnecting: boolean;
+  isDisconnected: boolean;
+  hasError: boolean;
+}
+```
+
+专门用于监听连接状态的简化Hook。
+
+### 类型定义
+
+#### ConnectionStatus
+
+```typescript
+enum ConnectionStatus {
+  CONNECTING = 'connecting',
+  CONNECTED = 'connected',
+  DISCONNECTED = 'disconnected',
+  RECONNECTING = 'reconnecting',
+  ERROR = 'error'
+}
+```
+
+#### WebSocketConfig
+
+```typescript
+interface WebSocketConfig {
+  url: string;                    // WebSocket服务器URL
+  protocols?: string | string[];  // 子协议
+  reconnectInterval?: number;     // 重连间隔（默认3000ms）
+  maxReconnectAttempts?: number;  // 最大重连次数（默认5次）
+  heartbeatInterval?: number;     // 心跳间隔（默认30000ms）
+  debug?: boolean;               // 调试模式（默认false）
+}
+```
+
+#### UseSocketConfig
+
+```typescript
+interface UseSocketConfig extends WebSocketConfig {
+  autoConnect?: boolean;          // 是否自动连接（默认true）
+  reconnectOnMount?: boolean;     // 组件挂载时是否重连（默认true）
+}
+```
+
+#### WebSocketEvents
+
+```typescript
+interface WebSocketEvents {
+  open: () => void;                                    // 连接打开
+  message: (data: string | ArrayBuffer | Blob) => void; // 收到消息
+  close: (event: CloseEvent) => void;                  // 连接关闭
+  error: (error: Event) => void;                       // 连接错误
+  statusChange: (status: ConnectionStatus) => void;    // 状态变化
+}
+```
+
+## 使用示例
+
+### 聊天应用
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { useSocket } from '@ichaingo/socket';
+
+interface Message {
+  id: string;
+  user: string;
+  content: string;
+  timestamp: number;
+}
+
+function ChatApp() {
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [inputMessage, setInputMessage] = useState('');
+  const [username, setUsername] = useState('');
+
+  const socket = useSocket({
+    url: 'ws://localhost:8080/chat',
+    debug: true,
+    autoConnect: true
+  });
+
+  useEffect(() => {
+    socket.on('message', (data) => {
+      if (typeof data === 'string') {
+        try {
+          const message = JSON.parse(data) as Message;
+          setMessages(prev => [...prev, message]);
+        } catch (err) {
+          console.error('Failed to parse message:', err);
+        }
+      }
+    });
+
+    return () => {
+      socket.off('message');
+    };
+  }, [socket]);
+
+  const sendMessage = () => {
+    if (inputMessage.trim() && username.trim()) {
+      const message: Message = {
+        id: Date.now().toString(),
+        user: username,
+        content: inputMessage,
+        timestamp: Date.now()
+      };
+      
+      socket.sendJSON(message);
+      setInputMessage('');
+    }
+  };
+
+  return (
+    <div>
+      <div>连接状态: {socket.status}</div>
+      
+      <div>
+        <input
+          value={username}
+          onChange={(e) => setUsername(e.target.value)}
+          placeholder="用户名"
+        />
+        <input
+          value={inputMessage}
+          onChange={(e) => setInputMessage(e.target.value)}
+          placeholder="输入消息"
+          onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
+        />
+        <button onClick={sendMessage} disabled={!socket.isConnected}>
+          发送
+        </button>
+      </div>
+
+      <div>
+        {messages.map((message) => (
+          <div key={message.id}>
+            <strong>{message.user}:</strong> {message.content}
+            <small> ({new Date(message.timestamp).toLocaleTimeString()})</small>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### 实时通知系统
+
+```tsx
+import React, { useState } from 'react';
+import { useSocketMessage } from '@ichaingo/socket';
+
+interface Notification {
+  id: string;
+  type: 'info' | 'warning' | 'error';
+  title: string;
+  content: string;
+  timestamp: number;
+}
+
+function NotificationSystem() {
+  const [notifications, setNotifications] = useState<Notification[]>([]);
+
+  const socket = useSocketMessage<Notification>({
+    url: 'ws://localhost:8080/notifications',
+    debug: true,
+    autoConnect: true
+  }, (notification) => {
+    setNotifications(prev => [notification, ...prev]);
+  });
+
+  const clearNotifications = () => {
+    setNotifications([]);
+  };
+
+  return (
+    <div>
+      <div>连接状态: {socket.status}</div>
+      <button onClick={clearNotifications}>清空通知</button>
+      
+      <div>
+        {notifications.map((notification) => (
+          <div
+            key={notification.id}
+            style={{
+              padding: '10px',
+              margin: '5px 0',
+              border: '1px solid #ccc',
+              borderRadius: '4px',
+              backgroundColor: notification.type === 'error' ? '#ffebee' : 
+                              notification.type === 'warning' ? '#fff3e0' : '#e3f2fd'
+            }}
+          >
+            <strong>{notification.title}</strong>
+            <div>{notification.content}</div>
+            <small>{new Date(notification.timestamp).toLocaleString()}</small>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## 构建
+
+```bash
+nx build socket
+```
+
+## 测试
+
+```bash
+nx test socket
+```
+
+## 许可证
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * WebSocket连接状态枚举
+ */
+export declare enum ConnectionStatus {
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    DISCONNECTED = "disconnected",
+    RECONNECTING = "reconnecting",
+    ERROR = "error"
+}
+/**
+ * WebSocket事件类型
+ */
+export interface WebSocketEvents {
+    open: () => void;
+    message: (data: string | ArrayBuffer | Blob) => void;
+    close: (event: CloseEvent) => void;
+    error: (error: Event) => void;
+    statusChange: (status: ConnectionStatus) => void;
+}
+/**
+ * WebSocket配置选项
+ */
+export interface WebSocketConfig {
+    url: string;
+    protocols?: string | string[];
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+    heartbeatInterval?: number;
+    debug?: boolean;
+}
+/**
+ * WebSocket单例连接类
+ * 提供WebSocket连接的创建、管理、重连等功能
+ */
+declare class SocketConnection {
+    private static instance;
+    private socket;
+    private config;
+    private status;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private eventListeners;
+    private constructor();
+    /**
+     * 获取单例实例
+     */
+    static getInstance(config?: WebSocketConfig): SocketConnection;
+    /**
+     * 连接WebSocket
+     */
+    connect(): Promise<void>;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 发送消息
+     */
+    send(data: string | ArrayBuffer | Blob): boolean;
+    /**
+     * 发送JSON消息
+     */
+    sendJSON(data: unknown): boolean;
+    /**
+     * 添加事件监听器
+     */
+    on<K extends keyof WebSocketEvents>(event: K, listener: WebSocketEvents[K]): void;
+    /**
+     * 移除事件监听器
+     */
+    off<K extends keyof WebSocketEvents>(event: K): void;
+    /**
+     * 获取连接状态
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * 检查是否已连接
+     */
+    isConnected(): boolean;
+    /**
+     * 设置事件监听器
+     */
+    private setupEventListeners;
+    /**
+     * 设置连接状态
+     */
+    private setStatus;
+    /**
+     * 安排重连
+     */
+    private scheduleReconnect;
+    /**
+     * 清除重连定时器
+     */
+    private clearReconnectTimer;
+    /**
+     * 开始心跳检测
+     */
+    private startHeartbeat;
+    /**
+     * 停止心跳检测
+     */
+    private stopHeartbeat;
+    /**
+     * 日志输出
+     */
+    private log;
+    /**
+     * 销毁实例
+     */
+    destroy(): void;
+}
+export default SocketConnection;
+export { useSocket, useSocketMessage, useSocketStatus } from './useSocket.js';
+export type { UseSocketConfig, UseSocketReturn } from './useSocket.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACrD,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,cAAM,gBAAgB;IACpB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IACxD,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAAmD;IACjE,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAAgC;IAEtD,OAAO;IAUP;;OAEG;WACW,WAAW,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,gBAAgB;IAUrE;;OAEG;IACI,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC/B;;OAEG;IACI,UAAU,IAAI,IAAI;IAazB;;OAEG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,OAAO;IAWvD;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAIvC;;OAEG;IACI,EAAE,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI;IAIxF;;OAEG;IACI,GAAG,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAI3D;;OAEG;IACI,SAAS,IAAI,gBAAgB;IAIpC;;OAEG;IACI,WAAW,IAAI,OAAO;IAI7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2B3B;;OAEG;IACH,OAAO,CAAC,SAAS;IAQjB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACI,OAAO,IAAI,IAAI;CAKvB;AAED,eAAe,gBAAgB,CAAC;AAGhC,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,241 @@
+/**
+ * WebSocket连接状态枚举
+ */
+export var ConnectionStatus;
+(function (ConnectionStatus) {
+    ConnectionStatus["CONNECTING"] = "connecting";
+    ConnectionStatus["CONNECTED"] = "connected";
+    ConnectionStatus["DISCONNECTED"] = "disconnected";
+    ConnectionStatus["RECONNECTING"] = "reconnecting";
+    ConnectionStatus["ERROR"] = "error";
+})(ConnectionStatus || (ConnectionStatus = {}));
+/**
+ * WebSocket单例连接类
+ * 提供WebSocket连接的创建、管理、重连等功能
+ */
+class SocketConnection {
+    static instance = null;
+    socket = null;
+    config;
+    status = ConnectionStatus.DISCONNECTED;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    heartbeatTimer = null;
+    eventListeners = {};
+    constructor(config) {
+        this.config = {
+            reconnectInterval: 3000,
+            maxReconnectAttempts: 5,
+            heartbeatInterval: 30000,
+            debug: false,
+            ...config
+        };
+    }
+    /**
+     * 获取单例实例
+     */
+    static getInstance(config) {
+        if (!SocketConnection.instance) {
+            if (!config) {
+                throw new Error('首次创建SocketConnection实例时必须提供配置');
+            }
+            SocketConnection.instance = new SocketConnection(config);
+        }
+        return SocketConnection.instance;
+    }
+    /**
+     * 连接WebSocket
+     */
+    connect() {
+        return new Promise((resolve, reject) => {
+            if (this.socket?.readyState === WebSocket.OPEN) {
+                resolve();
+                return;
+            }
+            this.setStatus(ConnectionStatus.CONNECTING);
+            this.log('正在连接WebSocket...', this.config.url);
+            try {
+                this.socket = new WebSocket(this.config.url, this.config.protocols);
+                this.setupEventListeners();
+                this.socket.onopen = () => {
+                    this.log('WebSocket连接成功');
+                    this.setStatus(ConnectionStatus.CONNECTED);
+                    this.reconnectAttempts = 0;
+                    this.startHeartbeat();
+                    this.eventListeners.open?.();
+                    resolve();
+                };
+                this.socket.onerror = (error) => {
+                    this.log('WebSocket连接错误:', error);
+                    this.setStatus(ConnectionStatus.ERROR);
+                    this.eventListeners.error?.(error);
+                    reject(error);
+                };
+            }
+            catch (error) {
+                this.log('创建WebSocket连接失败:', error);
+                this.setStatus(ConnectionStatus.ERROR);
+                reject(error);
+            }
+        });
+    }
+    /**
+     * 断开连接
+     */
+    disconnect() {
+        this.log('正在断开WebSocket连接...');
+        this.stopHeartbeat();
+        this.clearReconnectTimer();
+        if (this.socket) {
+            this.socket.close(1000, '主动断开连接');
+            this.socket = null;
+        }
+        this.setStatus(ConnectionStatus.DISCONNECTED);
+    }
+    /**
+     * 发送消息
+     */
+    send(data) {
+        if (this.socket?.readyState === WebSocket.OPEN) {
+            this.socket.send(data);
+            this.log('发送消息:', data);
+            return true;
+        }
+        else {
+            this.log('WebSocket未连接，无法发送消息');
+            return false;
+        }
+    }
+    /**
+     * 发送JSON消息
+     */
+    sendJSON(data) {
+        return this.send(JSON.stringify(data));
+    }
+    /**
+     * 添加事件监听器
+     */
+    on(event, listener) {
+        this.eventListeners[event] = listener;
+    }
+    /**
+     * 移除事件监听器
+     */
+    off(event) {
+        delete this.eventListeners[event];
+    }
+    /**
+     * 获取连接状态
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * 检查是否已连接
+     */
+    isConnected() {
+        return this.status === ConnectionStatus.CONNECTED && this.socket?.readyState === WebSocket.OPEN;
+    }
+    /**
+     * 设置事件监听器
+     */
+    setupEventListeners() {
+        if (!this.socket)
+            return;
+        this.socket.onmessage = (event) => {
+            this.log('收到消息:', event.data);
+            this.eventListeners.message?.(event.data);
+        };
+        this.socket.onclose = (event) => {
+            this.log('WebSocket连接关闭:', event.code, event.reason);
+            this.setStatus(ConnectionStatus.DISCONNECTED);
+            this.stopHeartbeat();
+            this.eventListeners.close?.(event);
+            // 如果不是主动断开，尝试重连
+            if (event.code !== 1000 && this.reconnectAttempts < (this.config.maxReconnectAttempts || 5)) {
+                this.scheduleReconnect();
+            }
+        };
+        this.socket.onerror = (error) => {
+            this.log('WebSocket错误:', error);
+            this.setStatus(ConnectionStatus.ERROR);
+            this.eventListeners.error?.(error);
+        };
+    }
+    /**
+     * 设置连接状态
+     */
+    setStatus(status) {
+        if (this.status !== status) {
+            this.status = status;
+            this.log('连接状态变更:', status);
+            this.eventListeners.statusChange?.(status);
+        }
+    }
+    /**
+     * 安排重连
+     */
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectAttempts++;
+        this.setStatus(ConnectionStatus.RECONNECTING);
+        this.log(`准备重连 (第${this.reconnectAttempts}次)...`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect().catch(() => {
+                // 重连失败，继续尝试
+            });
+        }, this.config.reconnectInterval || 3000);
+    }
+    /**
+     * 清除重连定时器
+     */
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    /**
+     * 开始心跳检测
+     */
+    startHeartbeat() {
+        this.stopHeartbeat();
+        if (this.config.heartbeatInterval && this.config.heartbeatInterval > 0) {
+            this.heartbeatTimer = setInterval(() => {
+                if (this.isConnected()) {
+                    this.send('ping');
+                }
+            }, this.config.heartbeatInterval);
+        }
+    }
+    /**
+     * 停止心跳检测
+     */
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    /**
+     * 日志输出
+     */
+    log(...args) {
+        if (this.config.debug) {
+            console.log('[SocketConnection]', ...args);
+        }
+    }
+    /**
+     * 销毁实例
+     */
+    destroy() {
+        this.disconnect();
+        this.eventListeners = {};
+        SocketConnection.instance = null;
+    }
+}
+export default SocketConnection;
+// 导出React Hooks
+export { useSocket, useSocketMessage, useSocketStatus } from './useSocket.js';

package/dist/useSocket.d.ts

@@ -0,0 +1,57 @@
+import { ConnectionStatus, WebSocketConfig, WebSocketEvents } from './index.js';
+/**
+ * useSocket Hook 的配置选项
+ */
+export interface UseSocketConfig extends WebSocketConfig {
+    autoConnect?: boolean;
+    reconnectOnMount?: boolean;
+}
+/**
+ * useSocket Hook 的返回值
+ */
+export interface UseSocketReturn {
+    status: ConnectionStatus;
+    isConnected: boolean;
+    connect: () => Promise<void>;
+    disconnect: () => void;
+    send: (data: string | ArrayBuffer | Blob) => boolean;
+    sendJSON: (data: unknown) => boolean;
+    on: <K extends keyof WebSocketEvents>(event: K, listener: WebSocketEvents[K]) => void;
+    off: <K extends keyof WebSocketEvents>(event: K) => void;
+    error: Event | null;
+    reconnectAttempts: number;
+    reconnect: () => void;
+}
+/**
+ * useSocket Hook
+ * 提供在React组件中使用WebSocket连接的便捷方法
+ *
+ * @param config WebSocket配置选项
+ * @returns useSocket的返回值对象
+ */
+export declare function useSocket(config: UseSocketConfig): UseSocketReturn;
+/**
+ * useSocketMessage Hook
+ * 专门用于监听特定类型消息的简化Hook
+ *
+ * @param config WebSocket配置选项
+ * @param messageHandler 消息处理函数
+ * @returns useSocket的返回值对象
+ */
+export declare function useSocketMessage<T = any>(config: UseSocketConfig, messageHandler: (data: T) => void): UseSocketReturn;
+/**
+ * useSocketStatus Hook
+ * 专门用于监听连接状态的简化Hook
+ *
+ * @param config WebSocket配置选项
+ * @returns 连接状态和状态变化回调
+ */
+export declare function useSocketStatus(config: UseSocketConfig): {
+    status: ConnectionStatus;
+    isConnected: boolean;
+    isConnecting: boolean;
+    isReconnecting: boolean;
+    isDisconnected: boolean;
+    hasError: boolean;
+};
+//# sourceMappingURL=useSocket.d.ts.map

package/dist/useSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSocket.d.ts","sourceRoot":"","sources":["../src/useSocket.ts"],"names":[],"mappings":"AACA,OAAyB,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElG;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAE9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IAGrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,IAAI,CAAC;IAGvB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,KAAK,OAAO,CAAC;IACrD,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IAGrC,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACtF,GAAG,EAAE,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAGzD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAGpB,iBAAiB,EAAE,MAAM,CAAC;IAG1B,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAiKlE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EACtC,MAAM,EAAE,eAAe,EACvB,cAAc,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAChC,eAAe,CAmBjB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe;;;;;;;EAmBtD"}

package/dist/useSocket.js

@@ -0,0 +1,203 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import SocketConnection, { ConnectionStatus } from './index.js';
+/**
+ * useSocket Hook
+ * 提供在React组件中使用WebSocket连接的便捷方法
+ *
+ * @param config WebSocket配置选项
+ * @returns useSocket的返回值对象
+ */
+export function useSocket(config) {
+    const [status, setStatus] = useState(ConnectionStatus.DISCONNECTED);
+    const [error, setError] = useState(null);
+    const [reconnectAttempts, setReconnectAttempts] = useState(0);
+    const socketRef = useRef(null);
+    const isInitializedRef = useRef(false);
+    const configRef = useRef(config);
+    // 更新配置引用
+    useEffect(() => {
+        configRef.current = config;
+    }, [config]);
+    // 获取或创建socket实例
+    const getSocket = useCallback(() => {
+        if (!socketRef.current) {
+            try {
+                socketRef.current = SocketConnection.getInstance(configRef.current);
+            }
+            catch (err) {
+                console.error('Failed to create socket instance:', err);
+                throw err;
+            }
+        }
+        return socketRef.current;
+    }, []);
+    // 连接WebSocket
+    const connect = useCallback(async () => {
+        try {
+            setError(null);
+            const socket = getSocket();
+            await socket.connect();
+        }
+        catch (err) {
+            const errorEvent = err;
+            setError(errorEvent);
+            throw err;
+        }
+    }, [getSocket]);
+    // 断开连接
+    const disconnect = useCallback(() => {
+        const socket = socketRef.current;
+        if (socket) {
+            socket.disconnect();
+        }
+    }, []);
+    // 发送消息
+    const send = useCallback((data) => {
+        const socket = socketRef.current;
+        if (socket) {
+            return socket.send(data);
+        }
+        return false;
+    }, []);
+    // 发送JSON消息
+    const sendJSON = useCallback((data) => {
+        const socket = socketRef.current;
+        if (socket) {
+            return socket.sendJSON(data);
+        }
+        return false;
+    }, []);
+    // 添加事件监听器
+    const on = useCallback((event, listener) => {
+        const socket = socketRef.current;
+        if (socket) {
+            socket.on(event, listener);
+        }
+    }, []);
+    // 移除事件监听器
+    const off = useCallback((event) => {
+        const socket = socketRef.current;
+        if (socket) {
+            socket.off(event);
+        }
+    }, []);
+    // 手动重连
+    const reconnect = useCallback(async () => {
+        disconnect();
+        await new Promise(resolve => setTimeout(resolve, 1000)); // 等待1秒
+        await connect();
+    }, [disconnect, connect]);
+    // 初始化socket和事件监听
+    useEffect(() => {
+        if (isInitializedRef.current)
+            return;
+        try {
+            const socket = getSocket();
+            // 监听状态变化
+            socket.on('statusChange', (newStatus) => {
+                setStatus(newStatus);
+                // 更新重连次数
+                if (newStatus === ConnectionStatus.RECONNECTING) {
+                    setReconnectAttempts(prev => prev + 1);
+                }
+                else if (newStatus === ConnectionStatus.CONNECTED) {
+                    setReconnectAttempts(0);
+                }
+            });
+            // 监听错误
+            socket.on('error', (errorEvent) => {
+                setError(errorEvent);
+            });
+            // 监听连接关闭
+            socket.on('close', () => {
+                setError(null);
+            });
+            isInitializedRef.current = true;
+        }
+        catch (err) {
+            console.error('Failed to initialize socket:', err);
+            setError(err);
+        }
+    }, [getSocket]);
+    // 自动连接
+    useEffect(() => {
+        if (config.autoConnect !== false && !isInitializedRef.current) {
+            connect().catch(console.error);
+        }
+    }, [config.autoConnect, connect]);
+    // 组件卸载时清理
+    useEffect(() => {
+        return () => {
+            const socket = socketRef.current;
+            if (socket && config.autoConnect !== false) {
+                socket.disconnect();
+            }
+        };
+    }, [config.autoConnect]);
+    // 检查是否已连接
+    const isConnected = status === ConnectionStatus.CONNECTED;
+    return {
+        status,
+        isConnected,
+        connect,
+        disconnect,
+        send,
+        sendJSON,
+        on,
+        off,
+        error,
+        reconnectAttempts,
+        reconnect,
+    };
+}
+/**
+ * useSocketMessage Hook
+ * 专门用于监听特定类型消息的简化Hook
+ *
+ * @param config WebSocket配置选项
+ * @param messageHandler 消息处理函数
+ * @returns useSocket的返回值对象
+ */
+export function useSocketMessage(config, messageHandler) {
+    const socket = useSocket(config);
+    useEffect(() => {
+        socket.on('message', (data) => {
+            try {
+                const parsedData = typeof data === 'string' ? JSON.parse(data) : data;
+                messageHandler(parsedData);
+            }
+            catch (err) {
+                console.error('Failed to parse message:', err);
+            }
+        });
+        return () => {
+            socket.off('message');
+        };
+    }, [socket, messageHandler]);
+    return socket;
+}
+/**
+ * useSocketStatus Hook
+ * 专门用于监听连接状态的简化Hook
+ *
+ * @param config WebSocket配置选项
+ * @returns 连接状态和状态变化回调
+ */
+export function useSocketStatus(config) {
+    const [status, setStatus] = useState(ConnectionStatus.DISCONNECTED);
+    const socket = useSocket(config);
+    useEffect(() => {
+        socket.on('statusChange', setStatus);
+        return () => {
+            socket.off('statusChange');
+        };
+    }, [socket]);
+    return {
+        status,
+        isConnected: status === ConnectionStatus.CONNECTED,
+        isConnecting: status === ConnectionStatus.CONNECTING,
+        isReconnecting: status === ConnectionStatus.RECONNECTING,
+        isDisconnected: status === ConnectionStatus.DISCONNECTED,
+        hasError: status === ConnectionStatus.ERROR,
+    };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ichaingo/web-socket",
+  "version": "1.3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    }
+  }
+}