mstf-kit
Version:
一个现代化的 JavaScript/TypeScript 工具库，提供了丰富的常用工具函数
357 lines (356 loc) • 8.68 kB
TypeScript
/**
* WebSocket 连接管理与消息传输工具
*/
/**
* WebSocket 连接状态
*/
export declare enum WebSocketState {
CONNECTING = "connecting",
OPEN = "open",
CLOSING = "closing",
CLOSED = "closed",
RECONNECTING = "reconnecting"
}
/**
* 消息优先级
*/
export declare enum MessagePriority {
HIGH = "high",// 高优先级，如用户交互相关
NORMAL = "normal",// 普通优先级，默认
LOW = "low"
}
/**
* 心跳配置
*/
export interface HeartbeatConfig {
/** 是否启用心跳 */
enabled: boolean;
/** 心跳间隔(ms) */
interval: number;
/** 心跳消息内容 */
message: any;
/** 心跳超时判定时间(ms) */
timeout: number;
}
/**
* 重连配置
*/
export interface ReconnectConfig {
/** 是否启用自动重连 */
enabled: boolean;
/** 最大重试次数，-1表示无限 */
maxRetries: number;
/** 初始重连延迟(ms) */
initialDelay: number;
/** 最大重连延迟(ms) */
maxDelay: number;
/** 重试延迟系数（指数退避） */
factor: number;
/** 随机化系数(0-1) */
jitter: number;
}
/**
* 消息处理配置
*/
export interface MessageConfig {
/** 默认消息超时时间(ms) */
timeout: number;
/** 消息缓冲区大小 */
maxQueueSize: number;
/** 自动序列化JSON */
autoJsonStringify: boolean;
/** 自动反序列化JSON */
autoJsonParse: boolean;
/** 批处理阈值（达到多少消息一起发送） */
batchThreshold: number;
/** 批处理时间窗口(ms) */
batchTimeWindow: number;
}
/**
* WebSocket 配置选项
*/
export interface WebSocketOptions {
/** websocket 连接地址 */
url: string;
/** 传递给WebSocket构造函数的协议参数 */
protocols?: string | string[];
/** 自定义请求头（仅适用于某些实现） */
headers?: Record<string, string>;
/** 连接超时(ms) */
connectionTimeout?: number;
/** 心跳配置 */
heartbeat?: Partial<HeartbeatConfig>;
/** 重连配置 */
reconnect?: Partial<ReconnectConfig>;
/** 消息处理配置 */
message?: Partial<MessageConfig>;
/** 调试模式 */
debug?: boolean;
/** 认证令牌 */
authToken?: string;
/** 认证处理器 */
authHandler?: (socket: WebSocketClient) => Promise<void>;
/** 消息处理器 */
messageHandler?: (data: any, socket: WebSocketClient) => void;
}
/**
* 消息发送配置
*/
export interface SendOptions {
/** 消息ID */
id?: string;
/** 期望响应 */
expectResponse?: boolean;
/** 响应超时(ms) */
timeout?: number;
/** 重试次数 */
retries?: number;
/** 重试延迟(ms) */
retryDelay?: number;
/** 消息优先级 */
priority?: MessagePriority;
/** 离线时是否缓存消息 */
cacheIfOffline?: boolean;
/** 强制文本格式发送JSON */
forceText?: boolean;
/** 是否作为二进制发送 */
binary?: boolean;
}
/**
* WebSocket 客户端
*/
export declare class WebSocketClient {
private socket;
private state;
private messageQueue;
private pendingMessages;
private reconnectAttempts;
private reconnectTimer;
private heartbeatTimer;
private heartbeatTimeoutTimer;
private batchTimer;
private batchedMessages;
private eventListeners;
private connectionStartTime;
private lastMessageTime;
private metrics;
private readonly defaultHeartbeatConfig;
private readonly defaultReconnectConfig;
private readonly defaultMessageConfig;
private options;
private heartbeatConfig;
private reconnectConfig;
private messageConfig;
/**
* 创建WebSocket客户端实例
* @param options WebSocket配置选项
*/
constructor(options: WebSocketOptions);
/**
* 连接到WebSocket服务器
* @returns 连接Promise
*/
connect(): Promise<WebSocketClient>;
/**
* 关闭WebSocket连接
* @param code 关闭代码
* @param reason 关闭原因
*/
close(code?: number, reason?: string): void;
/**
* 发送消息
* @param data 要发送的数据
* @param options 发送选项
* @returns 如果expectResponse为true，则返回响应数据的Promise
*/
send(data: any, options?: SendOptions): Promise<any>;
/**
* 订阅WebSocket事件
* @param event 事件名称
* @param listener 监听器函数
* @returns this 实例，用于链式调用
*/
on(event: string, listener: Function): this;
/**
* 取消订阅WebSocket事件
* @param event 事件名称
* @param listener 监听器函数
* @returns this 实例，用于链式调用
*/
off(event: string, listener: Function): this;
/**
* 获取当前WebSocket状态
* @returns 当前状态
*/
getState(): WebSocketState;
/**
* 获取延迟时间 (从最后一次心跳响应计算)
* @returns 延迟时间 (ms)
*/
getLatency(): number;
/**
* 获取连接统计信息
* @returns 统计指标
*/
getMetrics(): {
messagesSent: number;
messagesReceived: number;
bytesReceived: number;
bytesSent: number;
errors: number;
reconnects: number;
};
/**
* 清除消息队列
*/
clearQueue(): void;
/**
* 检查连接是否活跃
* @returns 是否为活跃连接
*/
isConnected(): boolean;
/**
* 手动触发重连
* @returns 重连Promise
*/
reconnect(): Promise<WebSocketClient>;
/**
* 触发事件
* @param event 事件名称
* @param data 事件数据
*/
private emit;
/**
* 设置WebSocket状态
* @param state 新状态
*/
private setState;
/**
* 生成唯一消息ID
* @returns 唯一ID
*/
private generateId;
/**
* 发送实际的WebSocket消息
* @param message 消息对象
*/
private sendMessage;
/**
* 将消息添加到队列
* @param message 消息对象
*/
private queueMessage;
/**
* 处理队列中的消息
*/
private processPendingMessages;
/**
* 将消息添加到批处理
* @param message 消息对象
*/
private addToBatch;
/**
* 发送批处理消息
*/
private flushBatchMessages;
/**
* 启动心跳
*/
private startHeartbeat;
/**
* 发送心跳
*/
private sendHeartbeat;
/**
* 处理心跳响应
* @param data 响应数据
*/
private handleHeartbeatResponse;
/**
* 停止心跳
*/
private stopHeartbeat;
/**
* 处理连接失败
*/
private handleConnectionFailure;
/**
* 处理重连逻辑
* @param immediate 是否立即重连
* @returns 重连Promise
*/
private handleReconnect;
/**
* 计算重连延迟时间
* @returns 延迟时间 (ms)
*/
private calculateReconnectDelay;
/**
* 清理Socket资源
*/
private cleanupSocket;
/**
* 停止重连尝试
*/
private stopReconnect;
/**
* 拒绝所有等待的消息
* @param reason 拒绝原因
*/
private rejectAllPendingMessages;
/**
* 记录日志
* @param level 日志级别
* @param message 日志消息
* @param error 错误对象（可选）
*/
private log;
/**
* 获取连接统计信息
* @returns 统计信息对象
*/
getConnectionStats(): {
uptime: number;
messagesSent: number;
messagesReceived: number;
bytesSent: number;
bytesReceived: number;
errors: number;
reconnects: number;
latency: number;
queueSize: number;
pendingResponses: number;
};
/**
* 重置统计信息
*/
resetStats(): void;
/**
* 设置心跳配置
* @param config 心跳配置
*/
setHeartbeatConfig(config: Partial<HeartbeatConfig>): void;
/**
* 设置重连配置
* @param config 重连配置
*/
setReconnectConfig(config: Partial<ReconnectConfig>): void;
/**
* 设置消息配置
* @param config 消息配置
*/
setMessageConfig(config: Partial<MessageConfig>): void;
/**
* 获取当前配置
* @returns 当前配置对象
*/
getConfig(): {
heartbeat: HeartbeatConfig;
reconnect: ReconnectConfig;
message: MessageConfig;
};
/**
* 销毁WebSocket客户端
*/
destroy(): void;
}