icom-wlan-node 0.2.2 → 0.2.4

package/README.md

@@ -29,7 +29,7 @@ npm run build
 ## Quick Start
 
 ```ts
-import { IcomControl, AUDIO_RATE } from 'icom-wlan-node';
+import { IcomControl, AUDIO_RATE, DisconnectReason } from 'icom-wlan-node';
 
 const rig = new IcomControl({
   control: { ip: '192.168.1.50', port: 50001 },
@@ -111,7 +111,8 @@ await rig.setPtt(false);
   - `reconnectAttempting(ReconnectAttemptInfo)` — reconnect attempt started
   - `reconnectFailed(ReconnectFailedInfo)` — reconnect attempt failed
 - Methods
-  - **Connection**: `connect()` / `disconnect()` — connects control + CIV + audio sub‑sessions; resolves when all ready
+  - **Connection**: `connect()` / `disconnect(options?)` — connects control + CIV + audio sub‑sessions; resolves when all ready
+    - `disconnect()` accepts optional `DisconnectOptions` or `DisconnectReason` for better error handling
   - **Raw CI‑V**: `sendCiv(buf: Buffer)` — send a raw CI‑V frame
   - **Audio TX**: `setPtt(on: boolean)`, `sendAudioFloat32()`, `sendAudioPcm16()`
   - **Rig Control**: `setFrequency()`, `setMode()`, `setConnectorDataMode()`, `setConnectorWLanLevel()`
@@ -151,6 +152,12 @@ console.log(metrics.sessions);    // Per-session states {control, civ, audio}
 
 // Disconnect (also idempotent)
 await rig.disconnect();
+
+// Disconnect with reason (provides better error messages)
+await rig.disconnect(DisconnectReason.TIMEOUT);
+
+// Silent disconnect (cleanup mode - no error events)
+await rig.disconnect({ reason: DisconnectReason.CLEANUP, silent: true });
 ```
 
 #### Connection Monitoring Events

package/dist/core/Session.js

@@ -111,6 +111,8 @@ class Session {
      * (especially important after radio restart)
      */
     resetState() {
+        // Stop all timers to prevent leaks and interference with new connection
+        this.stopTimers();
         // Reset destroyed flag to ensure session is usable after state reset
         this.destroyed = false;
         // Generate new IDs

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export { MODE_MAP, CONNECTOR_MODE_MAP, DEFAULT_CONTROLLER_ADDR, METER_THRESHOLDS
 export { parseTwoByteBcd, intToTwoByteBcd } from './utils/bcd';
 export { IcomRigCommands } from './rig/IcomRigCommands';
 export { AUDIO_RATE } from './rig/IcomAudio';
+export { setupGlobalErrorHandlers, setupBasicErrorProtection, GlobalErrorHandlerOptions } from './utils/errorHandling';
+export { ConnectionAbortedError, getDisconnectMessage } from './utils/errors';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUDIO_RATE = exports.IcomRigCommands = exports.intToTwoByteBcd = exports.parseTwoByteBcd = exports.rawToCurrent = exports.rawToVoltage = exports.rawToPowerPercent = exports.getFilterString = exports.getConnectorModeString = exports.getModeString = exports.getConnectorModeCode = exports.getModeCode = exports.METER_CALIBRATION = exports.METER_THRESHOLDS = exports.DEFAULT_CONTROLLER_ADDR = exports.CONNECTOR_MODE_MAP = exports.MODE_MAP = exports.IcomControl = void 0;
+exports.getDisconnectMessage = exports.ConnectionAbortedError = exports.setupBasicErrorProtection = exports.setupGlobalErrorHandlers = exports.AUDIO_RATE = exports.IcomRigCommands = exports.intToTwoByteBcd = exports.parseTwoByteBcd = exports.rawToCurrent = exports.rawToVoltage = exports.rawToPowerPercent = exports.getFilterString = exports.getConnectorModeString = exports.getModeString = exports.getConnectorModeCode = exports.getModeCode = exports.METER_CALIBRATION = exports.METER_THRESHOLDS = exports.DEFAULT_CONTROLLER_ADDR = exports.CONNECTOR_MODE_MAP = exports.MODE_MAP = exports.IcomControl = void 0;
 // Export types (includes ConnectionPhase, ConnectionMetrics, etc.)
 __exportStar(require("./types"), exports);
 // Export main class
@@ -44,3 +44,11 @@ var IcomRigCommands_1 = require("./rig/IcomRigCommands");
 Object.defineProperty(exports, "IcomRigCommands", { enumerable: true, get: function () { return IcomRigCommands_1.IcomRigCommands; } });
 var IcomAudio_1 = require("./rig/IcomAudio");
 Object.defineProperty(exports, "AUDIO_RATE", { enumerable: true, get: function () { return IcomAudio_1.AUDIO_RATE; } });
+// Export error handling utilities (optional, for robustness)
+var errorHandling_1 = require("./utils/errorHandling");
+Object.defineProperty(exports, "setupGlobalErrorHandlers", { enumerable: true, get: function () { return errorHandling_1.setupGlobalErrorHandlers; } });
+Object.defineProperty(exports, "setupBasicErrorProtection", { enumerable: true, get: function () { return errorHandling_1.setupBasicErrorProtection; } });
+// Export disconnect error utilities
+var errors_1 = require("./utils/errors");
+Object.defineProperty(exports, "ConnectionAbortedError", { enumerable: true, get: function () { return errors_1.ConnectionAbortedError; } });
+Object.defineProperty(exports, "getDisconnectMessage", { enumerable: true, get: function () { return errors_1.getDisconnectMessage; } });

package/dist/rig/IcomControl.d.ts

@@ -1,4 +1,4 @@
-import { IcomRigOptions, RigEventEmitter, IcomMode, ConnectorDataMode, SetModeOptions, QueryOptions, SwrReading, AlcReading, WlanLevelReading, LevelMeterReading, SquelchStatusReading, AudioSquelchReading, OvfStatusReading, PowerLevelReading, CompLevelReading, VoltageReading, CurrentReading, ConnectionState, ConnectionMonitorConfig, ConnectionPhase, ConnectionMetrics } from '../types';
+import { IcomRigOptions, RigEventEmitter, IcomMode, ConnectorDataMode, SetModeOptions, QueryOptions, SwrReading, AlcReading, WlanLevelReading, LevelMeterReading, SquelchStatusReading, AudioSquelchReading, OvfStatusReading, PowerLevelReading, CompLevelReading, VoltageReading, CurrentReading, ConnectionState, ConnectionMonitorConfig, ConnectionPhase, ConnectionMetrics, DisconnectReason, DisconnectOptions } from '../types';
 import { IcomCiv } from './IcomCiv';
 import { IcomAudio } from './IcomAudio';
 export declare class IcomControl {
@@ -66,7 +66,12 @@ export declare class IcomControl {
      * @private
      */
     private stopUnifiedMonitoring;
-    disconnect(): Promise<void>;
+    /**
+     * Disconnect from the rig
+     * @param options - Optional disconnect options (reason, silent mode)
+     * @returns Promise that resolves when disconnect is complete
+     */
+    disconnect(options?: DisconnectOptions | DisconnectReason): Promise<void>;
     sendCiv(data: Buffer): void;
     /**
      * Set PTT (Push-To-Talk) state

package/dist/rig/IcomControl.js

@@ -44,6 +44,7 @@ const IcomAudio_1 = require("./IcomAudio");
 const IcomRigCommands_1 = require("./IcomRigCommands");
 const IcomConstants_1 = require("./IcomConstants");
 const bcd_1 = require("../utils/bcd");
+const errors_1 = require("../utils/errors");
 class IcomControl {
     constructor(options) {
         this.ev = new events_1.EventEmitter();
@@ -134,11 +135,12 @@ class IcomControl {
      * Abort an ongoing connection attempt by session ID
      * @private
      */
-    abortConnectionAttempt(sessionId, reason) {
+    abortConnectionAttempt(sessionId, reason, silent = false) {
         const abortHandler = this.abortHandlers.get(sessionId);
         if (abortHandler) {
-            (0, debug_1.dbg)(`Aborting connection session ${sessionId}: ${reason}`);
-            abortHandler(reason);
+            const message = (0, errors_1.getDisconnectMessage)(reason);
+            (0, debug_1.dbg)(`Aborting connection session ${sessionId}: ${message} (silent=${silent})`);
+            abortHandler(reason, silent);
             this.abortHandlers.delete(sessionId);
         }
     }
@@ -272,27 +274,48 @@ class IcomControl {
         });
         // Store abort handler bound to this specific sessionId
         // This prevents race conditions when multiple connection attempts overlap
-        const abortHandler = (reason) => {
-            (0, debug_1.dbg)(`Aborting connection session ${sessionId}: ${reason}`);
-            const error = new Error(reason);
-            rejectLogin(error);
-            rejectCiv(error);
-            rejectAudio(error);
+        const abortHandler = (reason, silent) => {
+            const message = (0, errors_1.getDisconnectMessage)(reason);
+            (0, debug_1.dbg)(`Aborting connection session ${sessionId}: ${message} (silent=${silent})`);
+            // Create a single error instance to be shared across all rejections
+            const error = new errors_1.ConnectionAbortedError(reason, sessionId, this.connectionSession.phase);
+            // IMPORTANT: Always reject promises to unblock waiting code
+            // The "silent" flag only affects whether errors propagate to user code,
+            // but internally we must settle the promise to prevent hanging
+            (0, debug_1.dbg)(`${silent ? 'Silent' : 'Normal'} abort - rejecting login promise for session ${sessionId}`);
+            // Defensive error handling: wrap reject calls in try-catch to prevent
+            // synchronous errors from propagating if promises are already settled
+            // Only reject one promise to avoid duplicate errors
+            try {
+                rejectLogin(error);
+            }
+            catch (err) {
+                (0, debug_1.dbg)(`Warning: Failed to reject loginReady promise: ${err}`);
+            }
+            // Don't reject civ and audio promises separately - they'll be cleaned up
+            // This prevents the "3x User disconnect()" log spam
         };
         this.abortHandlers.set(sessionId, abortHandler);
+        // Track promise states for defensive cleanup
+        let loginResolved = false;
+        let civResolved = false;
+        let audioResolved = false;
         // Temporary event listeners (local scope)
         const onLogin = (res) => {
             if (res.ok) {
-                (0, debug_1.dbg)('Login ready - resolving local loginReady promise');
+                (0, debug_1.dbg)(`Login ready - resolving local loginReady promise (sessionId=${sessionId})`);
+                loginResolved = true;
                 resolveLogin();
             }
         };
         const onCivReady = () => {
-            (0, debug_1.dbg)('CIV ready - resolving local civReady promise');
+            (0, debug_1.dbg)(`CIV ready - resolving local civReady promise (sessionId=${sessionId})`);
+            civResolved = true;
             resolveCiv();
         };
         const onAudioReady = () => {
-            (0, debug_1.dbg)('Audio ready - resolving local audioReady promise');
+            (0, debug_1.dbg)(`Audio ready - resolving local audioReady promise (sessionId=${sessionId})`);
+            audioResolved = true;
             resolveAudio();
         };
         this.ev.once('login', onLogin);
@@ -303,13 +326,36 @@ class IcomControl {
             civReady,
             audioReady,
             cleanup: () => {
+                // Defensive cleanup: wrap each cleanup step in try-catch
+                // to ensure all cleanup steps execute even if one fails
+                (0, debug_1.dbg)(`Cleaning up connection session ${sessionId} (login=${loginResolved}, civ=${civResolved}, audio=${audioResolved})`);
                 // Remove abort handler for this specific sessionId
-                // This is safe because the connection attempt is complete (success or failure)
-                this.abortHandlers.delete(sessionId);
-                // Remove event listeners
-                this.ev.off('login', onLogin);
-                this.ev.off('_civReady', onCivReady);
-                this.ev.off('_audioReady', onAudioReady);
+                try {
+                    this.abortHandlers.delete(sessionId);
+                }
+                catch (err) {
+                    (0, debug_1.dbg)(`Warning: Failed to delete abort handler: ${err}`);
+                }
+                // Remove event listeners - wrap each in try-catch
+                try {
+                    this.ev.off('login', onLogin);
+                }
+                catch (err) {
+                    (0, debug_1.dbg)(`Warning: Failed to remove login listener: ${err}`);
+                }
+                try {
+                    this.ev.off('_civReady', onCivReady);
+                }
+                catch (err) {
+                    (0, debug_1.dbg)(`Warning: Failed to remove civReady listener: ${err}`);
+                }
+                try {
+                    this.ev.off('_audioReady', onAudioReady);
+                }
+                catch (err) {
+                    (0, debug_1.dbg)(`Warning: Failed to remove audioReady listener: ${err}`);
+                }
+                (0, debug_1.dbg)(`Cleanup complete for session ${sessionId}`);
             }
         };
     }
@@ -354,8 +400,20 @@ class IcomControl {
             this.monitorTimer = undefined;
         }
     }
-    async disconnect() {
+    /**
+     * Disconnect from the rig
+     * @param options - Optional disconnect options (reason, silent mode)
+     * @returns Promise that resolves when disconnect is complete
+     */
+    async disconnect(options) {
+        // Support both object and enum parameter for backward compatibility
+        const opts = typeof options === 'string'
+            ? { reason: options, silent: false }
+            : { reason: types_1.DisconnectReason.USER_REQUEST, silent: false, ...options };
+        const reason = opts.reason ?? types_1.DisconnectReason.USER_REQUEST;
+        const silent = opts.silent ?? false;
         const currentPhase = this.connectionSession.phase;
+        (0, debug_1.dbg)(`disconnect() called with reason=${reason}, silent=${silent}, currentPhase=${currentPhase}`);
         // If already disconnecting or idle, avoid duplicate work
         if (currentPhase === types_1.ConnectionPhase.DISCONNECTING) {
             (0, debug_1.dbg)('disconnect() called but already DISCONNECTING - waiting for completion');
@@ -376,14 +434,22 @@ class IcomControl {
             (0, debug_1.dbg)('disconnect() called but already IDLE - no-op');
             return;
         }
-        // Abort any ongoing connection attempts
+        // Abort any ongoing connection attempts - wrap in try-catch for defensive programming
         const currentSessionId = this.connectionSession.sessionId;
         if (currentPhase === types_1.ConnectionPhase.CONNECTING || currentPhase === types_1.ConnectionPhase.RECONNECTING) {
-            (0, debug_1.dbg)(`Aborting ongoing connection attempt (sessionId=${currentSessionId})`);
-            this.abortConnectionAttempt(currentSessionId, 'User disconnect()');
+            try {
+                (0, debug_1.dbg)(`Aborting ongoing connection attempt (sessionId=${currentSessionId})`);
+                this.abortConnectionAttempt(currentSessionId, reason, silent);
+            }
+            catch (abortErr) {
+                // Log but continue - abort failure shouldn't prevent disconnect
+                const errMsg = abortErr instanceof Error ? abortErr.message : String(abortErr);
+                (0, debug_1.dbg)(`Warning: Failed to abort connection attempt: ${errMsg} - continuing with disconnect`);
+            }
         }
         // Transition to DISCONNECTING state
-        this.transitionTo(types_1.ConnectionPhase.DISCONNECTING, 'User disconnect()');
+        const transitionReason = (0, errors_1.getDisconnectMessage)(reason);
+        this.transitionTo(types_1.ConnectionPhase.DISCONNECTING, transitionReason);
         try {
             // 1. Stop all timers first to prevent interference
             this.stopUnifiedMonitoring(); // Stop unified monitoring
@@ -1078,7 +1144,7 @@ class IcomControl {
                     const currentPhase = this.connectionSession.phase;
                     if (currentPhase === types_1.ConnectionPhase.CONNECTING || currentPhase === types_1.ConnectionPhase.RECONNECTING) {
                         (0, debug_1.dbg)('Aborting ongoing connection attempt due to connected=false');
-                        this.abortConnectionAttempt(this.connectionSession.sessionId, 'Radio reported connected=false');
+                        this.abortConnectionAttempt(this.connectionSession.sessionId, types_1.DisconnectReason.ERROR, false);
                     }
                     else if (currentPhase === types_1.ConnectionPhase.CONNECTED) {
                         // Trigger reconnection for established connection
@@ -1544,9 +1610,16 @@ class IcomControl {
                 (0, debug_1.dbg)(`Full reconnect attempt #${attempt} (delay: ${delay}ms)`);
                 await this.sleep(delay);
                 try {
-                    // Disconnect all sessions
+                    // Disconnect all sessions - wrap in try-catch to prevent disconnect errors from aborting reconnect
                     (0, debug_1.dbg)('Full reconnect: disconnecting all sessions');
-                    await this.disconnect();
+                    try {
+                        await this.disconnect();
+                    }
+                    catch (disconnectErr) {
+                        // Log but don't fail - we still want to attempt reconnect even if disconnect fails
+                        const errMsg = disconnectErr instanceof Error ? disconnectErr.message : String(disconnectErr);
+                        (0, debug_1.dbg)(`Warning: Disconnect failed during reconnect: ${errMsg} - continuing with reconnect anyway`);
+                    }
                     // Wait longer before reconnecting to allow rig to fully clean up old connection
                     // This is critical - rig may report CONNINFO busy=true if we reconnect too quickly
                     (0, debug_1.dbg)('Full reconnect: waiting 5s for rig to clean up old session...');

package/dist/types.d.ts

@@ -373,6 +373,38 @@ export interface ReconnectFailedInfo {
     /** Next retry delay (ms), if retrying */
     nextRetryDelay?: number;
 }
+/**
+ * Reason for disconnection
+ * Used to distinguish between different types of disconnections
+ */
+export declare enum DisconnectReason {
+    /** User explicitly called disconnect() */
+    USER_REQUEST = "user_request",
+    /** Connection timed out */
+    TIMEOUT = "timeout",
+    /** Cleanup after connection failure */
+    CLEANUP = "cleanup",
+    /** Error occurred during connection */
+    ERROR = "error",
+    /** Network connection was lost */
+    NETWORK_LOST = "network_lost"
+}
+/**
+ * Options for disconnect() method
+ */
+export interface DisconnectOptions {
+    /**
+     * Reason for disconnection
+     * Used to generate appropriate error messages and logs
+     */
+    reason?: DisconnectReason;
+    /**
+     * Silent mode - don't throw exceptions or emit error events
+     * Useful for cleanup operations where exceptions are not desired
+     * Default: false
+     */
+    silent?: boolean;
+}
 /**
  * Configuration for connection monitoring
  */

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionType = exports.ConnectionPhase = exports.ConnectionState = void 0;
+exports.DisconnectReason = exports.SessionType = exports.ConnectionPhase = exports.ConnectionState = void 0;
 // ============================================================================
 // Connection Monitoring Types
 // ============================================================================
@@ -46,3 +46,20 @@ var SessionType;
     /** Audio streaming session */
     SessionType["AUDIO"] = "AUDIO";
 })(SessionType || (exports.SessionType = SessionType = {}));
+/**
+ * Reason for disconnection
+ * Used to distinguish between different types of disconnections
+ */
+var DisconnectReason;
+(function (DisconnectReason) {
+    /** User explicitly called disconnect() */
+    DisconnectReason["USER_REQUEST"] = "user_request";
+    /** Connection timed out */
+    DisconnectReason["TIMEOUT"] = "timeout";
+    /** Cleanup after connection failure */
+    DisconnectReason["CLEANUP"] = "cleanup";
+    /** Error occurred during connection */
+    DisconnectReason["ERROR"] = "error";
+    /** Network connection was lost */
+    DisconnectReason["NETWORK_LOST"] = "network_lost";
+})(DisconnectReason || (exports.DisconnectReason = DisconnectReason = {}));

package/dist/utils/errorHandling.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 全局错误处理工具函数
+ *
+ * 这个模块提供可选的全局错误处理器，帮助用户防止未捕获的 Promise rejection 和异常导致进程崩溃。
+ *
+ * 使用方式：
+ * ```typescript
+ * import { setupGlobalErrorHandlers } from 'icom-wlan-node/utils/errorHandling';
+ *
+ * // 在应用启动时调用（可选）
+ * setupGlobalErrorHandlers({
+ *   onUnhandledRejection: (reason, promise) => {
+ *     console.error('未处理的 Promise rejection:', reason);
+ *     // 自定义处理逻辑
+ *   },
+ *   onUncaughtException: (error, origin) => {
+ *     console.error('未捕获的异常:', error);
+ *     // 自定义处理逻辑
+ *   }
+ * });
+ * ```
+ */
+export interface GlobalErrorHandlerOptions {
+    /**
+     * 处理未捕获的 Promise rejection
+     * @param reason - rejection 的原因
+     * @param promise - 被 reject 的 Promise
+     */
+    onUnhandledRejection?: (reason: any, promise: Promise<any>) => void;
+    /**
+     * 处理未捕获的异常
+     * @param error - 异常对象
+     * @param origin - 异常来源 ('uncaughtException' 或 'unhandledRejection')
+     */
+    onUncaughtException?: (error: Error, origin: string) => void;
+    /**
+     * 是否在处理错误后阻止进程退出（默认 true）
+     * 设为 false 时，错误会被记录但进程仍可能退出
+     */
+    preventExit?: boolean;
+}
+/**
+ * 设置全局错误处理器
+ *
+ * 注意：这是一个可选的工具函数，仅在需要时使用。
+ * 如果你的应用已经有全局错误处理逻辑，不需要调用此函数。
+ *
+ * @param options - 错误处理选项
+ * @returns cleanup 函数，用于移除错误处理器
+ */
+export declare function setupGlobalErrorHandlers(options?: GlobalErrorHandlerOptions): () => void;
+/**
+ * 快速设置：仅防止进程崩溃，使用默认错误处理
+ */
+export declare function setupBasicErrorProtection(): () => void;

package/dist/utils/errorHandling.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * 全局错误处理工具函数
+ *
+ * 这个模块提供可选的全局错误处理器，帮助用户防止未捕获的 Promise rejection 和异常导致进程崩溃。
+ *
+ * 使用方式：
+ * ```typescript
+ * import { setupGlobalErrorHandlers } from 'icom-wlan-node/utils/errorHandling';
+ *
+ * // 在应用启动时调用（可选）
+ * setupGlobalErrorHandlers({
+ *   onUnhandledRejection: (reason, promise) => {
+ *     console.error('未处理的 Promise rejection:', reason);
+ *     // 自定义处理逻辑
+ *   },
+ *   onUncaughtException: (error, origin) => {
+ *     console.error('未捕获的异常:', error);
+ *     // 自定义处理逻辑
+ *   }
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupGlobalErrorHandlers = setupGlobalErrorHandlers;
+exports.setupBasicErrorProtection = setupBasicErrorProtection;
+/**
+ * 设置全局错误处理器
+ *
+ * 注意：这是一个可选的工具函数，仅在需要时使用。
+ * 如果你的应用已经有全局错误处理逻辑，不需要调用此函数。
+ *
+ * @param options - 错误处理选项
+ * @returns cleanup 函数，用于移除错误处理器
+ */
+function setupGlobalErrorHandlers(options = {}) {
+    const { onUnhandledRejection = defaultUnhandledRejectionHandler, onUncaughtException = defaultUncaughtExceptionHandler, preventExit = true } = options;
+    // 未处理的 Promise rejection 处理器
+    const unhandledRejectionHandler = (reason, promise) => {
+        console.error('⚠️  [icom-wlan-node] 检测到未处理的 Promise rejection:');
+        console.error('原因:', reason);
+        console.error('Promise:', promise);
+        if (reason instanceof Error) {
+            console.error('错误堆栈:', reason.stack);
+        }
+        // 调用用户自定义处理器
+        onUnhandledRejection(reason, promise);
+    };
+    // 未捕获的异常处理器
+    const uncaughtExceptionHandler = (error, origin) => {
+        console.error('⚠️  [icom-wlan-node] 检测到未捕获的异常:');
+        console.error('错误:', error);
+        console.error('来源:', origin);
+        console.error('堆栈:', error.stack);
+        // 调用用户自定义处理器
+        onUncaughtException(error, origin);
+        // 根据配置决定是否退出
+        if (!preventExit) {
+            console.error('进程即将退出...');
+            process.exit(1);
+        }
+    };
+    // 注册处理器
+    process.on('unhandledRejection', unhandledRejectionHandler);
+    process.on('uncaughtException', uncaughtExceptionHandler);
+    console.log('✓ [icom-wlan-node] 全局错误处理器已设置');
+    // 返回 cleanup 函数
+    return () => {
+        process.off('unhandledRejection', unhandledRejectionHandler);
+        process.off('uncaughtException', uncaughtExceptionHandler);
+        console.log('✓ [icom-wlan-node] 全局错误处理器已移除');
+    };
+}
+/**
+ * 默认的未处理 Promise rejection 处理器
+ */
+function defaultUnhandledRejectionHandler(reason, promise) {
+    // 检查是否是网络错误（可以优雅处理）
+    if (isNetworkError(reason)) {
+        console.warn('网络错误已被捕获，但未影响进程稳定性');
+        return;
+    }
+    // 其他错误记录为警告
+    console.warn('检测到未处理的 Promise rejection，但进程继续运行');
+}
+/**
+ * 默认的未捕获异常处理器
+ */
+function defaultUncaughtExceptionHandler(error, origin) {
+    // 检查是否是可恢复的错误
+    if (isRecoverableError(error)) {
+        console.warn('可恢复的错误已被捕获，进程继续运行');
+        return;
+    }
+    console.error('检测到严重错误，建议检查应用逻辑');
+}
+/**
+ * 判断是否是网络错误
+ */
+function isNetworkError(error) {
+    if (!error)
+        return false;
+    const networkErrorCodes = [
+        'EHOSTDOWN',
+        'EHOSTUNREACH',
+        'ENETDOWN',
+        'ENETUNREACH',
+        'ECONNREFUSED',
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'ENOTFOUND'
+    ];
+    // 检查错误码
+    if (error.code && networkErrorCodes.includes(error.code)) {
+        return true;
+    }
+    // 检查错误消息
+    if (error.message && typeof error.message === 'string') {
+        return networkErrorCodes.some(code => error.message.includes(code));
+    }
+    return false;
+}
+/**
+ * 判断是否是可恢复的错误
+ */
+function isRecoverableError(error) {
+    // 网络错误通常是可恢复的
+    if (isNetworkError(error)) {
+        return true;
+    }
+    // 连接相关的错误也是可恢复的
+    const recoverableMessages = [
+        'Connection failed',
+        'User disconnect',
+        'Connection timeout',
+        'CIV/Audio sessions timeout'
+    ];
+    return recoverableMessages.some(msg => error.message.includes(msg));
+}
+/**
+ * 快速设置：仅防止进程崩溃，使用默认错误处理
+ */
+function setupBasicErrorProtection() {
+    return setupGlobalErrorHandlers({
+        preventExit: true
+    });
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,33 @@
+import { DisconnectReason, ConnectionPhase } from '../types';
+/**
+ * Get human-readable message for a disconnect reason
+ */
+export declare function getDisconnectMessage(reason: DisconnectReason): string;
+/**
+ * Error thrown when a connection attempt is aborted
+ * This is typically used when disconnect() is called during connect()
+ */
+export declare class ConnectionAbortedError extends Error {
+    readonly reason: DisconnectReason;
+    readonly sessionId: number;
+    readonly phase: ConnectionPhase;
+    readonly context?: Record<string, any> | undefined;
+    readonly name = "ConnectionAbortedError";
+    constructor(reason: DisconnectReason, sessionId: number, phase: ConnectionPhase, context?: Record<string, any> | undefined);
+    /**
+     * Check if this error should be silent (not thrown to user)
+     * Cleanup and timeout errors during connect are typically expected
+     */
+    isSilent(): boolean;
+    /**
+     * Get detailed error information for debugging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        reason: DisconnectReason;
+        sessionId: number;
+        phase: ConnectionPhase;
+        context: Record<string, any> | undefined;
+    };
+}

package/dist/utils/errors.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionAbortedError = void 0;
+exports.getDisconnectMessage = getDisconnectMessage;
+const types_1 = require("../types");
+/**
+ * Get human-readable message for a disconnect reason
+ */
+function getDisconnectMessage(reason) {
+    switch (reason) {
+        case types_1.DisconnectReason.USER_REQUEST:
+            return 'Connection closed by user request';
+        case types_1.DisconnectReason.TIMEOUT:
+            return 'Connection timed out';
+        case types_1.DisconnectReason.CLEANUP:
+            return 'Connection cleanup';
+        case types_1.DisconnectReason.ERROR:
+            return 'Connection closed due to error';
+        case types_1.DisconnectReason.NETWORK_LOST:
+            return 'Network connection lost';
+        default:
+            return 'Connection closed';
+    }
+}
+/**
+ * Error thrown when a connection attempt is aborted
+ * This is typically used when disconnect() is called during connect()
+ */
+class ConnectionAbortedError extends Error {
+    constructor(reason, sessionId, phase, context) {
+        super(getDisconnectMessage(reason));
+        this.reason = reason;
+        this.sessionId = sessionId;
+        this.phase = phase;
+        this.context = context;
+        this.name = 'ConnectionAbortedError';
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ConnectionAbortedError);
+        }
+    }
+    /**
+     * Check if this error should be silent (not thrown to user)
+     * Cleanup and timeout errors during connect are typically expected
+     */
+    isSilent() {
+        return this.reason === types_1.DisconnectReason.CLEANUP ||
+            this.reason === types_1.DisconnectReason.TIMEOUT;
+    }
+    /**
+     * Get detailed error information for debugging
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            reason: this.reason,
+            sessionId: this.sessionId,
+            phase: this.phase,
+            context: this.context
+        };
+    }
+}
+exports.ConnectionAbortedError = ConnectionAbortedError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icom-wlan-node",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Icom WLAN (CI‑V, audio) protocol implementation for Node.js/TypeScript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",