websocket-client-plus/dist/index.d.ts

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

/**
 * 基于浏览器原生 EventTarget 的事件分发器封装类
 *
 * 主要用途：
 * - 轻松实现自定义事件机制
 * - 方便在类中进行事件通信和状态通知
 */
declare class EventDispatcher {
    private target;
    /**
     * 添加事件监听器
     * @param {string} eventName 事件名称，表示将要监听的事件
     * @param {EventListener} handler 事件处理函数，接收事件对象作为参数
     */
    on(eventName: string, handler: EventListener): void;
    /**
     * 移除事件监听器
     * @param {string} eventName 事件名称
     * @param {EventListener} handler - 事件处理函数
     */
    off(eventName: string, handler?: EventListener): void;
    /**
     * 统一的事件触发方法
     * @param {string} eventName 事件名称
     * @param {T} [detail] 事件携带的数据（可选）
     */
    emit<T = unknown>(eventName: string, detail?: T): void;
}

/**
 * SocketClient 的可选配置项，用于控制心跳间隔、重连策略等连接行为。
 */
interface SocketClientOptions {
    /**
     * 初始重连延迟时间（毫秒），用于控制首次重连等待的时间，默认值为 2 秒。
     * @default 2000
     */
    baseRetryDelay?: number;
    /**
     * 最大重连延迟时间（毫秒），限制指数退避策略的上限，默认值建议为 60 秒。
     * @default 60000
     */
    maxRetryDelay?: number;
    /**
     * 最大重连尝试次数，超出后将不再自动尝试连接，避免网络异常时陷入死循环。
     * @default 10
     */
    maxReconnectAttempts?: number;
    /**
     * 心跳检测的时间间隔（毫秒），用于定期发送 ping 保持连接，默认值建议为 5 秒。
     * @default 5000
     */
    heartbeatInterval?: number;
    /**
     * 心跳发送内容（默认 'ping'）
     */
    pingMessage?: string;
    /**
     * 心跳响应内容（默认 'pong'）
     */
    pongMessage?: string;
}
/**
 * 基于 WebSocket 协议实现的持久连接客户端。
 *
 * 它继承自自定义的 EventDispatcher，支持自动重连、心跳检测，并通过事件机制分发连接相关事件：
 *
 * - 'channel-open'：连接成功建立
 * - 'channel-message'：接收到服务端的消息（默认为 string 类型）
 * - 'channel-error'：连接发生错误
 * - 'channel-close'：连接被关闭
 * - 'state-change'：连接状态发生变化（CONNECTING、OPEN、CLOSING、CLOSED 等）
 *
 * 支持配置心跳间隔、最大重连次数、重连指数退避策略等参数，适用于需要稳定长连接的场景。
 */
declare class SocketClient extends EventDispatcher {
    private static _instance;
    private ws;
    private socketUrl;
    private state;
    /**
     * 是否为用户主动关闭连接（区分意外断开）
     */
    private manuallyClosed;
    /**
     * 当前是否正在等待服务器心跳响应
     */
    private isHeartbeatWaiting;
    /**
     * 心跳检测与重连的定时器容器
     */
    private timers;
    /**
     * 初始重连时间
     */
    private readonly baseRetryDelay;
    /**
     * 当前重连使用的延迟时间（用于指数退避，不影响 baseRetryDelay）
     */
    private currentRetryDelay;
    /**
     * 最大允许的重连延迟时间（用于限制指数退避）
     */
    private readonly maxRetryDelay;
    /**
     * 心跳发送间隔（毫秒）
     */
    private readonly heartbeatInterval;
    /**
     * 心跳发送数据
     */
    private readonly pingMessage;
    /**
     * 心跳预期响应数据
     */
    private readonly pongMessage;
    /**
     * 最大自动重连尝试次数，超过此值将放弃继续尝试
     */
    private maxReconnectAttempts;
    /**
     * 当前已尝试的重连次数
     */
    private reconnectAttempts;
    /**
     * 创建一个支持心跳检测与自动重连的 WebSocket 客户端实例。
     * @param socketUrl - WebSocket 服务端地址（必须以 ws:// 或 wss:// 开头）
     * @param options - 可选配置项，用于控制心跳和重连行为
     */
    constructor(socketUrl: string, options?: SocketClientOptions);
    /**
     * 获取 SocketClient 单例实例的静态方法
     */
    static getInstance(socketUrl: string, options?: SocketClientOptions): SocketClient;
    /**
     * 连接 WebSocket
     */
    private _connect;
    /**
     * 发送消息
     * @param {string} message 要发送的消息
     */
    send(message: string): void;
    /**
     * 尝试重新建立 WebSocket 连接，使用指数退避算法增加重连延迟。
     *
     * 超过最大尝试次数后将停止尝试，并触发 'reconnect-exhausted' 事件。
     */
    private _reconnect;
    /**
     * 启动心跳检测机制
     */
    private _startHeartbeat;
    /**
     * 重置连接状态
     */
    private _resetConnectionState;
    /**
     * 清除所有定时器（重连、心跳）
     */
    private _clearTimers;
    /**
     * 内部关闭连接方法（不重置实例）
     */
    private _close;
    /**
     * 更新当前连接状态并在状态发生变化时分发 `state-change` 事件
     * @param state - 要更新为的连接状态（枚举值 SocketState）
     */
    private _updateState;
    /**
     * 销毁客户端，彻底关闭连接和释放资源
     */
    destroy(): void;
}

export { SocketClient as default };