a2bei4-utils 1.0.0 → 1.0.1

package/types/index.d.ts

@@ -29,6 +29,129 @@ declare class IntervalTimer {
     isRunning(): boolean;
 }
 
+/**
+ * @class WebSocketManager - 一个功能强大、高度可定制的 WebSocket 助手类
+ *
+ * @features
+ * - 智能断线重连 (指数退避算法)
+ * - 网络状态监听
+ * - 高度可定制的心跳保活机制 (通过注入函数实现)
+ * - 页面可见性 API 集成
+ * - 消息发送队列
+ * - 事件驱动的消息分发
+ * - 清晰的生命周期管理
+ * - 优雅的资源销毁
+ * - 可配置的数据序列化/反序列化
+ */
+declare class WebSocketManager {
+    /**
+     * @param {string} url - WebSocket 服务器的地址
+     * @param {object} [options={}] - 配置选项
+     * @param {number} [options.heartbeatInterval=30000] - 心跳间隔 (毫秒)
+     * @param {number} [options.heartbeatTimeout=10000] - 心跳超时时间 (毫秒)
+     * @param {number} [options.reconnectBaseInterval=1000] - 重连基础间隔 (毫秒)
+     * @param {number} [options.maxReconnectInterval=30000] - 最大重连间隔 (毫秒)
+     * @param {number} [options.maxReconnectAttempts=Infinity] - 最大重连次数
+     * @param {boolean} [options.autoConnect=true] - 是否在实例化后自动连接
+     * @param {boolean} [options.serializeData=false] - 发送数据时是否自动序列化为JSON字符串
+     * @param {boolean} [options.deserializeData=false] - 接收数据时是否自动反序列化为JSON对象
+     * @param {function|null} [options.getPingMessage=null] - 返回要发送的 ping 消息内容的函数。如果为 null，则不发送心跳。
+     * @param {function|null} [options.isPongMessage=null] - 判断接收到的消息是否为 pong 的函数。接收 MessageEvent 对象作为参数，返回布尔值。
+     * @param {object} [options.protocols] - WebSocket 协议
+     */
+    constructor(url: string, options?: {
+        heartbeatInterval?: number | undefined;
+        heartbeatTimeout?: number | undefined;
+        reconnectBaseInterval?: number | undefined;
+        maxReconnectInterval?: number | undefined;
+        maxReconnectAttempts?: number | undefined;
+        autoConnect?: boolean | undefined;
+        serializeData?: boolean | undefined;
+        deserializeData?: boolean | undefined;
+        getPingMessage?: Function | null | undefined;
+        isPongMessage?: Function | null | undefined;
+        protocols?: object | undefined;
+    });
+    url: string;
+    options: {
+        heartbeatInterval: number;
+        heartbeatTimeout: number;
+        reconnectBaseInterval: number;
+        maxReconnectInterval: number;
+        maxReconnectAttempts: number;
+        autoConnect: boolean;
+        serializeData: boolean;
+        deserializeData: boolean;
+        getPingMessage: Function | null;
+        isPongMessage: Function | null;
+        protocols?: object | undefined;
+    };
+    ws: WebSocket | null;
+    readyState: 3;
+    reconnectAttempts: number;
+    forcedClose: boolean;
+    isReconnecting: boolean;
+    heartbeatTimer: number | null;
+    heartbeatTimeoutTimer: number | null;
+    reconnectTimer: number | null;
+    messageQueue: any[];
+    listeners: Map<any, any>;
+    _onOpen(event: any): void;
+    /**
+     * 优化后的消息处理方法，使用注入的函数来判断心跳
+     * @param {MessageEvent} event
+     */
+    _onMessage(event: MessageEvent): void;
+    _onClose(event: any): void;
+    _onError(event: any): void;
+    _handleVisibilityChange(): void;
+    _handleOnline(): void;
+    _handleOffline(): void;
+    /**
+     * 连接到 WebSocket 服务器
+     */
+    connect(): void;
+    /**
+     * 发送数据
+     * @param {string|object|ArrayBuffer|Blob} data - 要发送的数据
+     */
+    send(data: string | object | ArrayBuffer | Blob): void;
+    /**
+     * 主动关闭连接
+     * @param {number} [code=1000] - 关闭代码
+     * @param {string} [reason=''] - 关闭原因
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * 彻底销毁实例，清理所有资源
+     */
+    destroy(): void;
+    /**
+     * 添加事件监听器
+     * @param {string} eventName - 事件名 (e.g., 'open', 'message', 'close', 'error', 'reconnect')
+     * @param {function} callback - 回调函数
+     */
+    on(eventName: string, callback: Function): void;
+    /**
+     * 移除事件监听器
+     * @param {string} eventName - 事件名
+     * @param {function} callback - 回调函数
+     */
+    off(eventName: string, callback: Function): void;
+    _startHeartbeat(): void;
+    _stopHeartbeat(): void;
+    _setHeartbeatTimeout(): void;
+    _clearHeartbeatTimeout(): void;
+    _handlePong(): void;
+    _scheduleReconnect(): void;
+    _clearReconnectTimer(): void;
+    _flushMessageQueue(): void;
+    _emit(eventName: any, ...args: any[]): void;
+    _updateReadyState(newState: any): void;
+    _setupEventListeners(): void;
+    _removeEventListeners(): void;
+}
+
 /**
  * 使用 Fisher-Yates 算法对数组 **原地** 随机乱序。
  * @template T
@@ -46,6 +169,62 @@ declare function shuffle<T>(arr: T[]): T[];
  */
 declare function moveItem<T>(arr: T[], fromIndex: number, toIndex: number): T[];
 
+/**
+ * 将 16-bit 单声道 PCM 数据封装成标准 WAV Blob。
+ *
+ * @param {Int16Array} pcmData - PCM 采样数据
+ * @param {number} [sampleRate=16000] - 采样率，默认 16 kHz
+ * @returns {Blob} audio/wav Blob
+ */
+declare function pcmToWavBlob(pcmData: Int16Array, sampleRate?: number): Blob;
+/**
+ * 浏览器端实时音频流重采样器。
+ * 基于 AudioWorklet 将麦克风/媒体流转换为 16 kHz、16-bit、单声道 PCM，
+ * 并通过回调逐块输出，可选保存完整 PCM 用于后续合并。
+ */
+declare class AudioStreamResampler {
+    /**
+     * @param {object} config
+     * @param {function(Int16Array)} config.onData - 收到一个 chunk PCM 数据的回调
+     * @param {function(string, string)} [config.onStateChange] - 状态变化回调
+     * @param {object} [config.processorOptions] - 传递给 AudioWorklet 的选项
+     * @param {boolean} [config.saveFullPcm=false] - 是否在内部保存所有 PCM 用于 stop 时合并（长时间录音建议关闭）
+     */
+    constructor(config: {
+        onData: (arg0: Int16Array) => any;
+        onStateChange?: ((arg0: string, arg1: string) => any) | undefined;
+        processorOptions?: object | undefined;
+        saveFullPcm?: boolean | undefined;
+    });
+    onData: (arg0: Int16Array) => any;
+    onStateChange: (arg0: string, arg1: string) => any;
+    processorOptions: object;
+    saveFullPcm: boolean;
+    audioContext: AudioContext | null;
+    workletNode: AudioWorkletNode | null;
+    source: MediaStreamAudioSourceNode | null;
+    workletUrl: string | null;
+    fullPcmData: never[] | null;
+    isInitialized: boolean;
+    isProcessing: boolean;
+    /**
+     * 初始化 AudioContext 并加载 AudioWorklet。
+     * 完成后状态变为 `"ready"`。
+     */
+    init(): Promise<void>;
+    /**
+     * 绑定媒体流，开始实时处理。
+     * @param {MediaStream} stream - 通过 getUserMedia 或其他方式获得的流
+     */
+    setMediaStream(stream: MediaStream): void;
+    /**
+     * 停止处理并释放资源。
+     * @param {(fullPcm: Int16Array) => void} [callback] - 若构造时 `saveFullPcm=true`，会把合并后的完整 PCM 通过此回调传出
+     */
+    stop(callback?: (fullPcm: Int16Array) => void): void;
+    _cleanup(): void;
+}
+
 /**
  * 视口尺寸对象。
  * @typedef {Object} ViewportDimensions
@@ -342,6 +521,7 @@ declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Para
 
 /**
  * 通过动态创建 `<a>` 标签触发浏览器下载。
+ * 注意：此方法可能无法强制下载浏览器原生支持的文件（如图片、PDF），浏览器可能会选择直接打开。
  *
  * @param {string} url - 任意可下载地址（同源或允许跨域）
  * @param {string} [fileName] - 保存到本地的文件名；不传时使用时间戳
@@ -377,6 +557,16 @@ declare function downloadExcel(data: string | ArrayBufferView | ArrayBuffer | Bl
  * @param {string} [fileName] - 保存到本地的文件名
  */
 declare function downloadJSON(data: any, fileName?: string): void;
+/**
+ * 通过 `fetch` 获取资源并强制下载，避免浏览器直接打开文件。
+ * 此方法适用于下载图片、PDF 等浏览器默认会打开的文件类型。
+ * 如果 `fetch` 失败（如 CORS 策略阻止），会回退到 `downloadByUrl` 方法作为备选方案。
+ *
+ * @param {string} url - 文件的 URL 地址
+ * @param {string} [fileName] - 保存到本地的文件名。如果不提供，会尝试从 URL 中自动提取
+ * @returns {Promise<void>} 返回一个 Promise，在下载开始或失败后 resolve
+ */
+declare function fetchOrDownloadByUrl(url: string, fileName?: string): Promise<void>;
 
 /**
  * 简单、高性能的通用事件总线。
@@ -494,6 +684,22 @@ declare function flatCompleteTree2NestedTree<T>(nodes: T[], parentId?: number |
     parentKey?: string | undefined;
     childrenKey?: string | undefined;
 }): (T & { [k in typeof childrenKey]: T[]; })[];
+/**
+ * 从服务端返回的已选 id 数组里，提取出
+ * 1. 叶子节点
+ * 2. 所有子节点都被选中的父节点
+ * 其余父节点一律丢弃（由前端 Tree 自动算半选）
+ *
+ * @param {Array}  treeData     完整树
+ * @param {Array}  selectedKeys 后端给的选中 id 数组
+ * @param {String} idKey        节点唯一字段
+ * @param {String} childrenKey  子节点字段
+ * @returns {{checked: string[], halfChecked: string[]}}
+ */
+declare function extractFullyCheckedKeys(treeData: any[], selectedKeys: any[], idKey?: string, childrenKey?: string): {
+    checked: string[];
+    halfChecked: string[];
+};
 declare function findObjAttrValueById<T>(id: string | number, arr: T[], resultKey?: string, idKey?: string, childrenKey?: string): any;
 
-export { IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };
+export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };

package/types/tree.d.ts

@@ -25,6 +25,22 @@ declare function flatCompleteTree2NestedTree<T>(nodes: T[], parentId?: number |
     parentKey?: string | undefined;
     childrenKey?: string | undefined;
 }): (T & { [k in typeof childrenKey]: T[]; })[];
+/**
+ * 从服务端返回的已选 id 数组里，提取出
+ * 1. 叶子节点
+ * 2. 所有子节点都被选中的父节点
+ * 其余父节点一律丢弃（由前端 Tree 自动算半选）
+ *
+ * @param {Array}  treeData     完整树
+ * @param {Array}  selectedKeys 后端给的选中 id 数组
+ * @param {String} idKey        节点唯一字段
+ * @param {String} childrenKey  子节点字段
+ * @returns {{checked: string[], halfChecked: string[]}}
+ */
+declare function extractFullyCheckedKeys(treeData: any[], selectedKeys: any[], idKey?: string, childrenKey?: string): {
+    checked: string[];
+    halfChecked: string[];
+};
 declare function findObjAttrValueById<T>(id: string | number, arr: T[], resultKey?: string, idKey?: string, childrenKey?: string): any;
 
-export { findObjAttrValueById, flatCompleteTree2NestedTree, nestedTree2IdMap };
+export { extractFullyCheckedKeys, findObjAttrValueById, flatCompleteTree2NestedTree, nestedTree2IdMap };

package/types/webSocket.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @class WebSocketManager - 一个功能强大、高度可定制的 WebSocket 助手类
+ *
+ * @features
+ * - 智能断线重连 (指数退避算法)
+ * - 网络状态监听
+ * - 高度可定制的心跳保活机制 (通过注入函数实现)
+ * - 页面可见性 API 集成
+ * - 消息发送队列
+ * - 事件驱动的消息分发
+ * - 清晰的生命周期管理
+ * - 优雅的资源销毁
+ * - 可配置的数据序列化/反序列化
+ */
+declare class WebSocketManager {
+    /**
+     * @param {string} url - WebSocket 服务器的地址
+     * @param {object} [options={}] - 配置选项
+     * @param {number} [options.heartbeatInterval=30000] - 心跳间隔 (毫秒)
+     * @param {number} [options.heartbeatTimeout=10000] - 心跳超时时间 (毫秒)
+     * @param {number} [options.reconnectBaseInterval=1000] - 重连基础间隔 (毫秒)
+     * @param {number} [options.maxReconnectInterval=30000] - 最大重连间隔 (毫秒)
+     * @param {number} [options.maxReconnectAttempts=Infinity] - 最大重连次数
+     * @param {boolean} [options.autoConnect=true] - 是否在实例化后自动连接
+     * @param {boolean} [options.serializeData=false] - 发送数据时是否自动序列化为JSON字符串
+     * @param {boolean} [options.deserializeData=false] - 接收数据时是否自动反序列化为JSON对象
+     * @param {function|null} [options.getPingMessage=null] - 返回要发送的 ping 消息内容的函数。如果为 null，则不发送心跳。
+     * @param {function|null} [options.isPongMessage=null] - 判断接收到的消息是否为 pong 的函数。接收 MessageEvent 对象作为参数，返回布尔值。
+     * @param {object} [options.protocols] - WebSocket 协议
+     */
+    constructor(url: string, options?: {
+        heartbeatInterval?: number | undefined;
+        heartbeatTimeout?: number | undefined;
+        reconnectBaseInterval?: number | undefined;
+        maxReconnectInterval?: number | undefined;
+        maxReconnectAttempts?: number | undefined;
+        autoConnect?: boolean | undefined;
+        serializeData?: boolean | undefined;
+        deserializeData?: boolean | undefined;
+        getPingMessage?: Function | null | undefined;
+        isPongMessage?: Function | null | undefined;
+        protocols?: object | undefined;
+    });
+    url: string;
+    options: {
+        heartbeatInterval: number;
+        heartbeatTimeout: number;
+        reconnectBaseInterval: number;
+        maxReconnectInterval: number;
+        maxReconnectAttempts: number;
+        autoConnect: boolean;
+        serializeData: boolean;
+        deserializeData: boolean;
+        getPingMessage: Function | null;
+        isPongMessage: Function | null;
+        protocols?: object | undefined;
+    };
+    ws: WebSocket | null;
+    readyState: 3;
+    reconnectAttempts: number;
+    forcedClose: boolean;
+    isReconnecting: boolean;
+    heartbeatTimer: number | null;
+    heartbeatTimeoutTimer: number | null;
+    reconnectTimer: number | null;
+    messageQueue: any[];
+    listeners: Map<any, any>;
+    _onOpen(event: any): void;
+    /**
+     * 优化后的消息处理方法，使用注入的函数来判断心跳
+     * @param {MessageEvent} event
+     */
+    _onMessage(event: MessageEvent): void;
+    _onClose(event: any): void;
+    _onError(event: any): void;
+    _handleVisibilityChange(): void;
+    _handleOnline(): void;
+    _handleOffline(): void;
+    /**
+     * 连接到 WebSocket 服务器
+     */
+    connect(): void;
+    /**
+     * 发送数据
+     * @param {string|object|ArrayBuffer|Blob} data - 要发送的数据
+     */
+    send(data: string | object | ArrayBuffer | Blob): void;
+    /**
+     * 主动关闭连接
+     * @param {number} [code=1000] - 关闭代码
+     * @param {string} [reason=''] - 关闭原因
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * 彻底销毁实例，清理所有资源
+     */
+    destroy(): void;
+    /**
+     * 添加事件监听器
+     * @param {string} eventName - 事件名 (e.g., 'open', 'message', 'close', 'error', 'reconnect')
+     * @param {function} callback - 回调函数
+     */
+    on(eventName: string, callback: Function): void;
+    /**
+     * 移除事件监听器
+     * @param {string} eventName - 事件名
+     * @param {function} callback - 回调函数
+     */
+    off(eventName: string, callback: Function): void;
+    _startHeartbeat(): void;
+    _stopHeartbeat(): void;
+    _setHeartbeatTimeout(): void;
+    _clearHeartbeatTimeout(): void;
+    _handlePong(): void;
+    _scheduleReconnect(): void;
+    _clearReconnectTimer(): void;
+    _flushMessageQueue(): void;
+    _emit(eventName: any, ...args: any[]): void;
+    _updateReadyState(newState: any): void;
+    _setupEventListeners(): void;
+    _removeEventListeners(): void;
+}
+
+export { WebSocketManager };