ly-utils-lib 2.4.0 → 2.6.0

package/README.md

@@ -87,6 +87,9 @@ import { exportExcel, importExcel } from 'ly-utils-lib/excel'
 
 // 只导入 PDF 模块
 import { captureToPDF, createPDF } from 'ly-utils-lib/pdf'
+
+// 只导入 WebSocket 模块
+import { createWebSocket, quickConnect } from 'ly-utils-lib/websocket'
 ```
 
 ## 模块文档
@@ -672,6 +675,117 @@ map.destroy()
 | `lonLatToXY(lon, lat)`                   | 经纬度转投影   | `lonLatToXY(116.39, 39.90)`               |
 | `xyToLonLat(x, y)`                       | 投影转经纬度   | `xyToLonLat(x, y)`                        |
 
+### 🔌 WebSocket Module - WebSocket 工具
+
+提供简化的 WebSocket 连接、消息发送、心跳检测和重连机制。
+
+```typescript
+import {
+  createWebSocket,
+  quickConnect,
+  WebSocketState,
+} from 'ly-utils-lib/websocket'
+
+// 方式 1: 使用 createWebSocket
+const ws = createWebSocket({
+  url: 'echo.websocket.org',
+  autoReconnect: true,
+  reconnectAttempts: 3,
+  heartbeatInterval: 30000,
+  onOpen: (event) => console.log('Connected'),
+  onMessage: (data, event) => console.log('Received:', data),
+  onClose: (event) => console.log('Disconnected'),
+  onError: (event) => console.error('Error:', event),
+  onReconnect: (attempt) => console.log(`Reconnecting... (${attempt})`),
+  onHeartbeat: () => console.log('Heartbeat'),
+})
+
+// 发送消息
+ws.send('Hello, WebSocket!')
+ws.send({ type: 'message', content: 'Hello' })
+
+// 检查连接状态
+if (ws.isConnected()) {
+  console.log('Connected')
+}
+
+// 断开连接
+ws.disconnect()
+
+// 方式 2: 使用 quickConnect
+const ws2 = quickConnect('echo.websocket.org', {
+  onMessage: (data) => console.log('Received:', data),
+})
+
+// 重新连接
+ws.reconnect()
+```
+
+**API 列表:**
+
+#### 创建客户端
+
+| 类/函数                                       | 说明                  | 示例                                   |
+| --------------------------------------------- | --------------------- | -------------------------------------- |
+| `createWebSocket(options)`                    | 创建 WebSocket 客户端 | `createWebSocket({url: '...'})`        |
+| `quickConnect(url, handlers?)`               | 快速连接              | `quickConnect('...')`                   |
+| `WebSocketClient`                             | WebSocket 客户端类    | `new WebSocketClient({url: '...'})`    |
+
+#### 连接管理
+
+| 类/函数                                       | 说明                  | 示例                                   |
+| --------------------------------------------- | --------------------- | -------------------------------------- |
+| `connect()`                                   | 连接                  | `ws.connect()`                          |
+| `disconnect()`                                | 断开连接              | `ws.disconnect()`                       |
+| `reconnect()`                                 | 重新连接              | `ws.reconnect()`                        |
+| `getState()`                                  | 获取连接状态          | `ws.getState()`                         |
+| `isConnected()`                               | 是否已连接            | `ws.isConnected()`                      |
+| `getInstance()`                               | 获取 WebSocket 实例   | `ws.getInstance()`                      |
+
+#### 消息发送
+
+| 类/函数                                       | 说明                  | 示例                                   |
+| --------------------------------------------- | --------------------- | -------------------------------------- |
+| `send(data)`                                  | 发送消息（异步）      | `ws.send('Hello')`                      |
+| `sendSync(data)`                              | 发送消息（同步）      | `ws.sendSync('Hello')`                  |
+
+#### 事件处理
+
+| 类/函数                                       | 说明                  | 示例                                   |
+| --------------------------------------------- | --------------------- | -------------------------------------- |
+| `on(event, handler)`                          | 设置事件处理器        | `ws.on('message', handler)`             |
+| `off(event, handler?)`                        | 移除事件处理器        | `ws.off('message', handler)`            |
+
+#### 配置选项
+
+| 选项                                          | 说明                  | 默认值                                 |
+| --------------------------------------------- | --------------------- | -------------------------------------- |
+| `url`                                         | WebSocket 地址        | -                                      |
+| `protocol`                                    | 协议 (ws/wss)         | 自动检测                               |
+| `protocols`                                   | 子协议                | []                                     |
+| `autoReconnect`                               | 自动重连              | true                                   |
+| `reconnectAttempts`                           | 重连次数              | 3                                      |
+| `reconnectInterval`                           | 重连间隔(ms)          | 3000                                   |
+| `heartbeatInterval`                           | 心跳间隔(ms)          | 30000                                  |
+| `heartbeatMessage`                            | 心跳消息              | 'ping'                                 |
+| `heartbeatTimeout`                            | 心跳超时(ms)          | 5000                                   |
+| `connectTimeout`                              | 连接超时(ms)          | 10000                                  |
+| `debug`                                       | 调试日志              | true                                   |
+
+#### 事件处理器
+
+| 事件                                          | 说明                  | 示例                                   |
+| --------------------------------------------- | --------------------- | -------------------------------------- |
+| `onOpen`                                      | 连接成功              | `onOpen: (event) => void`              |
+| `onMessage`                                   | 接收消息              | `onMessage: (data, event) => void`     |
+| `onClose`                                     | 连接关闭              | `onClose: (event) => void`             |
+| `onError`                                     | 错误                  | `onError: (event) => void`             |
+| `onReconnect`                                 | 重连开始              | `onReconnect: (attempt) => void`       |
+| `onReconnectSuccess`                          | 重连成功              | `onReconnectSuccess: (attempt) => void`|
+| `onReconnectFailed`                           | 重连失败              | `onReconnectFailed: () => void`        |
+| `onHeartbeat`                                 | 心跳                  | `onHeartbeat: () => void`              |
+| `onHeartbeatTimeout`                          | 心跳超时              | `onHeartbeatTimeout: () => void`       |
+
 ### 💾 Storage Module - 存储处理
 
 基于浏览器 Web Storage API 和 Cookie（使用 [js-cookie](https://github.com/js-cookie/js-cookie) 封装），提供统一的存储操作功能。

package/dist/index-Cq1GhjpY.d.cts

@@ -0,0 +1,229 @@
+/**
+ * WebSocket Module - WebSocket 工具
+ *
+ * 提供简化的 WebSocket 连接、消息发送、心跳检测和重连机制
+ */
+/**
+ * WebSocket 连接状态
+ */
+declare enum WebSocketState {
+    CONNECTING = 0,
+    OPEN = 1,
+    CLOSING = 2,
+    CLOSED = 3
+}
+/**
+ * WebSocket 配置选项
+ */
+interface WebSocketOptions {
+    /** WebSocket 服务器地址 */
+    url: string;
+    /** 协议（wss:// 或 ws://），默认自动检测 */
+    protocol?: 'ws' | 'wss';
+    /** 子协议 */
+    protocols?: string | string[];
+    /** 是否自动重连，默认 true */
+    autoReconnect?: boolean;
+    /** 重连次数，默认 3 */
+    reconnectAttempts?: number;
+    /** 重连间隔（毫秒），默认 3000 */
+    reconnectInterval?: number;
+    /** 心跳检测间隔（毫秒），默认 30000 */
+    heartbeatInterval?: number;
+    /** 心跳消息内容，默认 'ping' */
+    heartbeatMessage?: string | object;
+    /** 心跳超时时间（毫秒），默认 5000 */
+    heartbeatTimeout?: number;
+    /** 连接超时时间（毫秒），默认 10000 */
+    connectTimeout?: number;
+    /** 是否记录日志，默认 true */
+    debug?: boolean;
+}
+/**
+ * WebSocket 消息类型
+ */
+type WebSocketMessage = string | object | ArrayBuffer | Blob;
+/**
+ * WebSocket 事件处理器
+ */
+interface WebSocketEventHandlers {
+    /** 连接成功回调 */
+    onOpen?: (event: Event) => void;
+    /** 接收消息回调 */
+    onMessage?: (data: WebSocketMessage, event: MessageEvent) => void;
+    /** 连接关闭回调 */
+    onClose?: (event: CloseEvent) => void;
+    /** 错误回调 */
+    onError?: (event: Event) => void;
+    /** 重连开始回调 */
+    onReconnect?: (attempt: number) => void;
+    /** 重连成功回调 */
+    onReconnectSuccess?: (attempt: number) => void;
+    /** 重连失败回调 */
+    onReconnectFailed?: () => void;
+    /** 心跳回调 */
+    onHeartbeat?: () => void;
+    /** 心跳超时回调 */
+    onHeartbeatTimeout?: () => void;
+}
+/**
+ * WebSocket 实例接口
+ */
+interface IWebSocketClient {
+    /** 连接 WebSocket */
+    connect(): void;
+    /** 断开连接 */
+    disconnect(): void;
+    /** 发送消息 */
+    send(data: WebSocketMessage): Promise<void>;
+    /** 发送消息（不带 Promise） */
+    sendSync(data: WebSocketMessage): void;
+    /** 获取连接状态 */
+    getState(): WebSocketState;
+    /** 是否已连接 */
+    isConnected(): boolean;
+    /** 获取 WebSocket 实例 */
+    getInstance(): WebSocket | null;
+    /** 设置事件处理器 */
+    on<K extends keyof WebSocketEventHandlers>(event: K, handler: WebSocketEventHandlers[K]): void;
+    /** 移除事件处理器 */
+    off<K extends keyof WebSocketEventHandlers>(event: K, handler?: WebSocketEventHandlers[K]): void;
+    /** 重新连接 */
+    reconnect(): void;
+}
+/**
+ * WebSocket 客户端类
+ */
+declare class WebSocketClient implements IWebSocketClient {
+    private ws;
+    private options;
+    private handlers;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private heartbeatTimeoutTimer;
+    private reconnectCount;
+    private isManualDisconnect;
+    private messageQueue;
+    private connectResolve;
+    private connectReject;
+    constructor(options: WebSocketOptions);
+    /**
+     * 连接 WebSocket
+     */
+    connect(): void;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 发送消息（异步）
+     */
+    send(data: WebSocketMessage): Promise<void>;
+    /**
+     * 发送消息（同步）
+     */
+    sendSync(data: WebSocketMessage): void;
+    /**
+     * 获取连接状态
+     */
+    getState(): WebSocketState;
+    /**
+     * 是否已连接
+     */
+    isConnected(): boolean;
+    /**
+     * 获取 WebSocket 实例
+     */
+    getInstance(): WebSocket | null;
+    /**
+     * 设置事件处理器
+     */
+    on<K extends keyof WebSocketEventHandlers>(event: K, handler: WebSocketEventHandlers[K]): void;
+    /**
+     * 移除事件处理器
+     */
+    off<K extends keyof WebSocketEventHandlers>(event: K, handler?: WebSocketEventHandlers[K]): void;
+    /**
+     * 重新连接
+     */
+    reconnect(): void;
+    /**
+     * 设置事件处理器
+     */
+    private setupEventHandlers;
+    /**
+     * 尝试重连
+     */
+    private attemptReconnect;
+    /**
+     * 启动心跳
+     */
+    private startHeartbeat;
+    /**
+     * 停止心跳
+     */
+    private stopHeartbeat;
+    /**
+     * 清理资源
+     */
+    private cleanup;
+    /**
+     * 处理错误
+     */
+    private handleError;
+    /**
+     * 日志输出
+     */
+    private log;
+}
+/**
+ * 创建 WebSocket 客户端
+ * @param options - 配置选项
+ * @returns WebSocket 客户端实例
+ * @example
+ * ```ts
+ * const ws = createWebSocket({
+ *   url: 'echo.websocket.org',
+ *   autoReconnect: true,
+ *   onMessage: (data) => console.log('Received:', data)
+ * })
+ *
+ * ws.send('Hello, WebSocket!')
+ * ```
+ */
+declare function createWebSocket(options: WebSocketOptions): IWebSocketClient;
+/**
+ * 快速连接 WebSocket
+ * @param url - WebSocket 服务器地址
+ * @param handlers - 事件处理器
+ * @returns WebSocket 客户端实例
+ * @example
+ * ```ts
+ * const ws = quickConnect('echo.websocket.org', {
+ *   onMessage: (data) => console.log('Received:', data)
+ * })
+ * ```
+ */
+declare function quickConnect(url: string, handlers?: WebSocketEventHandlers): IWebSocketClient;
+declare const _default: {
+    WebSocketClient: typeof WebSocketClient;
+    createWebSocket: typeof createWebSocket;
+    quickConnect: typeof quickConnect;
+    WebSocketState: typeof WebSocketState;
+};
+
+type index_IWebSocketClient = IWebSocketClient;
+type index_WebSocketClient = WebSocketClient;
+declare const index_WebSocketClient: typeof WebSocketClient;
+type index_WebSocketEventHandlers = WebSocketEventHandlers;
+type index_WebSocketMessage = WebSocketMessage;
+type index_WebSocketOptions = WebSocketOptions;
+type index_WebSocketState = WebSocketState;
+declare const index_WebSocketState: typeof WebSocketState;
+declare const index_createWebSocket: typeof createWebSocket;
+declare const index_quickConnect: typeof quickConnect;
+declare namespace index {
+  export { type index_IWebSocketClient as IWebSocketClient, index_WebSocketClient as WebSocketClient, type index_WebSocketEventHandlers as WebSocketEventHandlers, type index_WebSocketMessage as WebSocketMessage, type index_WebSocketOptions as WebSocketOptions, index_WebSocketState as WebSocketState, index_createWebSocket as createWebSocket, _default as default, index_quickConnect as quickConnect };
+}
+
+export { type IWebSocketClient as I, WebSocketClient as W, _default as _, type WebSocketEventHandlers as a, type WebSocketMessage as b, type WebSocketOptions as c, WebSocketState as d, createWebSocket as e, index as i, quickConnect as q };

package/dist/index-Cq1GhjpY.d.ts

@@ -0,0 +1,229 @@
+/**
+ * WebSocket Module - WebSocket 工具
+ *
+ * 提供简化的 WebSocket 连接、消息发送、心跳检测和重连机制
+ */
+/**
+ * WebSocket 连接状态
+ */
+declare enum WebSocketState {
+    CONNECTING = 0,
+    OPEN = 1,
+    CLOSING = 2,
+    CLOSED = 3
+}
+/**
+ * WebSocket 配置选项
+ */
+interface WebSocketOptions {
+    /** WebSocket 服务器地址 */
+    url: string;
+    /** 协议（wss:// 或 ws://），默认自动检测 */
+    protocol?: 'ws' | 'wss';
+    /** 子协议 */
+    protocols?: string | string[];
+    /** 是否自动重连，默认 true */
+    autoReconnect?: boolean;
+    /** 重连次数，默认 3 */
+    reconnectAttempts?: number;
+    /** 重连间隔（毫秒），默认 3000 */
+    reconnectInterval?: number;
+    /** 心跳检测间隔（毫秒），默认 30000 */
+    heartbeatInterval?: number;
+    /** 心跳消息内容，默认 'ping' */
+    heartbeatMessage?: string | object;
+    /** 心跳超时时间（毫秒），默认 5000 */
+    heartbeatTimeout?: number;
+    /** 连接超时时间（毫秒），默认 10000 */
+    connectTimeout?: number;
+    /** 是否记录日志，默认 true */
+    debug?: boolean;
+}
+/**
+ * WebSocket 消息类型
+ */
+type WebSocketMessage = string | object | ArrayBuffer | Blob;
+/**
+ * WebSocket 事件处理器
+ */
+interface WebSocketEventHandlers {
+    /** 连接成功回调 */
+    onOpen?: (event: Event) => void;
+    /** 接收消息回调 */
+    onMessage?: (data: WebSocketMessage, event: MessageEvent) => void;
+    /** 连接关闭回调 */
+    onClose?: (event: CloseEvent) => void;
+    /** 错误回调 */
+    onError?: (event: Event) => void;
+    /** 重连开始回调 */
+    onReconnect?: (attempt: number) => void;
+    /** 重连成功回调 */
+    onReconnectSuccess?: (attempt: number) => void;
+    /** 重连失败回调 */
+    onReconnectFailed?: () => void;
+    /** 心跳回调 */
+    onHeartbeat?: () => void;
+    /** 心跳超时回调 */
+    onHeartbeatTimeout?: () => void;
+}
+/**
+ * WebSocket 实例接口
+ */
+interface IWebSocketClient {
+    /** 连接 WebSocket */
+    connect(): void;
+    /** 断开连接 */
+    disconnect(): void;
+    /** 发送消息 */
+    send(data: WebSocketMessage): Promise<void>;
+    /** 发送消息（不带 Promise） */
+    sendSync(data: WebSocketMessage): void;
+    /** 获取连接状态 */
+    getState(): WebSocketState;
+    /** 是否已连接 */
+    isConnected(): boolean;
+    /** 获取 WebSocket 实例 */
+    getInstance(): WebSocket | null;
+    /** 设置事件处理器 */
+    on<K extends keyof WebSocketEventHandlers>(event: K, handler: WebSocketEventHandlers[K]): void;
+    /** 移除事件处理器 */
+    off<K extends keyof WebSocketEventHandlers>(event: K, handler?: WebSocketEventHandlers[K]): void;
+    /** 重新连接 */
+    reconnect(): void;
+}
+/**
+ * WebSocket 客户端类
+ */
+declare class WebSocketClient implements IWebSocketClient {
+    private ws;
+    private options;
+    private handlers;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private heartbeatTimeoutTimer;
+    private reconnectCount;
+    private isManualDisconnect;
+    private messageQueue;
+    private connectResolve;
+    private connectReject;
+    constructor(options: WebSocketOptions);
+    /**
+     * 连接 WebSocket
+     */
+    connect(): void;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 发送消息（异步）
+     */
+    send(data: WebSocketMessage): Promise<void>;
+    /**
+     * 发送消息（同步）
+     */
+    sendSync(data: WebSocketMessage): void;
+    /**
+     * 获取连接状态
+     */
+    getState(): WebSocketState;
+    /**
+     * 是否已连接
+     */
+    isConnected(): boolean;
+    /**
+     * 获取 WebSocket 实例
+     */
+    getInstance(): WebSocket | null;
+    /**
+     * 设置事件处理器
+     */
+    on<K extends keyof WebSocketEventHandlers>(event: K, handler: WebSocketEventHandlers[K]): void;
+    /**
+     * 移除事件处理器
+     */
+    off<K extends keyof WebSocketEventHandlers>(event: K, handler?: WebSocketEventHandlers[K]): void;
+    /**
+     * 重新连接
+     */
+    reconnect(): void;
+    /**
+     * 设置事件处理器
+     */
+    private setupEventHandlers;
+    /**
+     * 尝试重连
+     */
+    private attemptReconnect;
+    /**
+     * 启动心跳
+     */
+    private startHeartbeat;
+    /**
+     * 停止心跳
+     */
+    private stopHeartbeat;
+    /**
+     * 清理资源
+     */
+    private cleanup;
+    /**
+     * 处理错误
+     */
+    private handleError;
+    /**
+     * 日志输出
+     */
+    private log;
+}
+/**
+ * 创建 WebSocket 客户端
+ * @param options - 配置选项
+ * @returns WebSocket 客户端实例
+ * @example
+ * ```ts
+ * const ws = createWebSocket({
+ *   url: 'echo.websocket.org',
+ *   autoReconnect: true,
+ *   onMessage: (data) => console.log('Received:', data)
+ * })
+ *
+ * ws.send('Hello, WebSocket!')
+ * ```
+ */
+declare function createWebSocket(options: WebSocketOptions): IWebSocketClient;
+/**
+ * 快速连接 WebSocket
+ * @param url - WebSocket 服务器地址
+ * @param handlers - 事件处理器
+ * @returns WebSocket 客户端实例
+ * @example
+ * ```ts
+ * const ws = quickConnect('echo.websocket.org', {
+ *   onMessage: (data) => console.log('Received:', data)
+ * })
+ * ```
+ */
+declare function quickConnect(url: string, handlers?: WebSocketEventHandlers): IWebSocketClient;
+declare const _default: {
+    WebSocketClient: typeof WebSocketClient;
+    createWebSocket: typeof createWebSocket;
+    quickConnect: typeof quickConnect;
+    WebSocketState: typeof WebSocketState;
+};
+
+type index_IWebSocketClient = IWebSocketClient;
+type index_WebSocketClient = WebSocketClient;
+declare const index_WebSocketClient: typeof WebSocketClient;
+type index_WebSocketEventHandlers = WebSocketEventHandlers;
+type index_WebSocketMessage = WebSocketMessage;
+type index_WebSocketOptions = WebSocketOptions;
+type index_WebSocketState = WebSocketState;
+declare const index_WebSocketState: typeof WebSocketState;
+declare const index_createWebSocket: typeof createWebSocket;
+declare const index_quickConnect: typeof quickConnect;
+declare namespace index {
+  export { type index_IWebSocketClient as IWebSocketClient, index_WebSocketClient as WebSocketClient, type index_WebSocketEventHandlers as WebSocketEventHandlers, type index_WebSocketMessage as WebSocketMessage, type index_WebSocketOptions as WebSocketOptions, index_WebSocketState as WebSocketState, index_createWebSocket as createWebSocket, _default as default, index_quickConnect as quickConnect };
+}
+
+export { type IWebSocketClient as I, WebSocketClient as W, _default as _, type WebSocketEventHandlers as a, type WebSocketMessage as b, type WebSocketOptions as c, WebSocketState as d, createWebSocket as e, index as i, quickConnect as q };