icom-wlan-node 0.2.3 → 0.2.5

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

@@ -5,3 +5,4 @@ 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.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;
+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
@@ -48,3 +48,7 @@ Object.defineProperty(exports, "AUDIO_RATE", { enumerable: true, get: function (
 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,29 +274,26 @@ 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);
+        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}`);
             }
-            try {
-                rejectCiv(error);
-            }
-            catch (err) {
-                (0, debug_1.dbg)(`Warning: Failed to reject civReady promise: ${err}`);
-            }
-            try {
-                rejectAudio(error);
-            }
-            catch (err) {
-                (0, debug_1.dbg)(`Warning: Failed to reject audioReady 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
@@ -401,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');
@@ -428,7 +439,7 @@ class IcomControl {
         if (currentPhase === types_1.ConnectionPhase.CONNECTING || currentPhase === types_1.ConnectionPhase.RECONNECTING) {
             try {
                 (0, debug_1.dbg)(`Aborting ongoing connection attempt (sessionId=${currentSessionId})`);
-                this.abortConnectionAttempt(currentSessionId, 'User disconnect()');
+                this.abortConnectionAttempt(currentSessionId, reason, silent);
             }
             catch (abortErr) {
                 // Log but continue - abort failure shouldn't prevent disconnect
@@ -437,7 +448,8 @@ class IcomControl {
             }
         }
         // 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
@@ -1132,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

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/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.3",
+  "version": "0.2.5",
   "description": "Icom WLAN (CI‑V, audio) protocol implementation for Node.js/TypeScript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",