serial-core 0.2.0-dev.4 → 0.2.0

package/README.md

@@ -91,6 +91,94 @@ async function sendCommand() {
 // serial.disconnect();
 ```
 
+## Handshake
+
+The handshake feature allows you to verify the device identity and connection before considering the port as fully connected. This is useful when you need to confirm that the connected device is the expected one.
+
+### Basic Handshake Configuration
+
+```typescript
+const serial = new SerialService({
+  path: '/dev/ttyUSB0',
+  baudRate: 9600,
+  autoConnect: true,
+  reconnectInterval: 5000,
+  handshake: {
+    command: 'AT\r\n',        // Command to send to the device
+    pattern: /OK/,            // Expected response pattern (string or RegExp)
+    timeout: 2000             // Maximum time to wait for response (ms)
+  }
+});
+```
+
+### Handshake with Binary Data (Hex Comparison)
+
+When working with devices that respond with binary data or non-printable characters, you can use the `hexPattern` option to compare responses in hexadecimal format:
+
+```typescript
+const connectionCommand = Buffer.from([0x01, 0x02, 0x03, 0x04]);
+
+const serial = new SerialService({
+  path: '/dev/ttyUSB0',
+  baudRate: 9600,
+  autoConnect: true,
+  reconnectInterval: 5000,
+  handshake: {
+    command: connectionCommand,
+    pattern: connectionCommand.toString('hex'), // Compare in hex format
+    timeout: 3000,
+    hexPattern: true  // Enable hex comparison
+  }
+});
+```
+
+### Handshake Configuration Options
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `command` | `string \| Buffer` | Yes | Command to send to the device upon connection. |
+| `pattern` | `string \| RegExp` | Yes | Expected pattern in the device response. |
+| `timeout` | `number` | Yes | Maximum time (in ms) to wait for the handshake response. |
+| `hexPattern` | `boolean` | No | If `true`, received data will be converted to hex before pattern matching. Useful for binary protocols. |
+
+### How Handshake Works
+
+1. The service opens the serial port
+2. Sends the handshake `command` to the device
+3. Waits for a response that matches the `pattern`
+4. If the pattern matches within the `timeout` period, the connection is considered successful
+5. If no match or timeout occurs, the connection fails and a reconnection attempt is scheduled
+
+### Handshake Examples
+
+**Text-based handshake:**
+```typescript
+handshake: {
+  command: 'PING\n',
+  pattern: 'PONG',
+  timeout: 1000
+}
+```
+
+**RegExp pattern for version checking:**
+```typescript
+handshake: {
+  command: 'VERSION\r\n',
+  pattern: /v\d+\.\d+\.\d+/,  // Matches v1.2.3 format
+  timeout: 2000
+}
+```
+
+**Binary protocol with hex comparison:**
+```typescript
+handshake: {
+  command: Buffer.from([0xFF, 0x01, 0x00]),
+  pattern: 'ff0100',  // Expected response in hex
+  timeout: 3000,
+  hexPattern: true
+}
+```
+
 ## API Reference
 
 ### `SerialService`
@@ -107,7 +195,7 @@ The main class for managing the serial connection.
 | `baudRate` | `number` | Serial baud rate (default: `9600`). |
 | `autoConnect` | `boolean` | Whether to connect automatically on instantiation. |
 | `reconnectInterval` | `number` | Time in ms to wait before retrying connection. |
-| `handshake?` | `object` | Optional handshake configuration to verify device identity. |
+| `handshake?` | `object` | Optional handshake configuration to verify device identity. See [Handshake](#handshake) section for details. |
 
 #### Methods
 

package/dist/SerialService.d.cts

@@ -14,28 +14,51 @@ export declare class SerialService extends EventEmitter {
     protected config: SerialConfig;
     protected intentionalDisconnect: boolean;
     protected reconnectTimer: NodeJS.Timeout | null;
+    /**
+     * Initializes the SerialService with the provided configuration.
+     * @param config - Configuration object for serial connection
+     */
     constructor(config: SerialConfig);
+    /**
+     * Gets the autoConnect configuration value.
+     * @returns Whether the service should automatically connect on instantiation
+     */
     get autoConnect(): boolean;
+    /**
+     * Gets the current connection status.
+     * @returns The current serial connection status
+     */
     get status(): SerialStatus;
     /**
-     * Updates status and emits the corresponding event.
+     * Updates the service status and emits the corresponding event.
+     * @param newStatus - The new status to set
      */
     protected setStatus(newStatus: SerialStatus): void;
     /**
      * Starts the connection process.
      * Handles both direct connection (known path) and scanning (VID/PID).
+     * @throws Will emit error events if connection fails
      */
     connect(): Promise<void>;
     /**
-     * Physically opens the port and configures listeners.
+     * Physically opens the serial port and configures all necessary listeners.
+     * @param path - The port path to open (e.g., '/dev/ttyUSB0' or 'COM3')
      */
     protected openPort(path: string): void;
     /**
-     * Manual disconnection.
+     * Manually disconnects from the serial port.
+     * @returns A promise that resolves when the port is fully closed
      */
     disconnect(): Promise<void>;
     /**
-     * Public method to send data. Uses internal queue.
+     * Sends data through the serial port using the internal queue.
+     * @param data - The data to send (string or Buffer)
+     * @param options - Optional send configuration
+     * @param options.alias - A command identifier to correlate with responses
+     * @param options.timeout - Maximum time to wait for the operation in milliseconds
+     * @param options.waitResponse - If true, wait for a response before processing the next item in the queue
+     * @returns A promise that resolves when the data has been written to the port
+     * @throws If the port is not connected
      */
     send(data: string | Buffer, options?: {
         alias?: string;
@@ -43,24 +66,30 @@ export declare class SerialService extends EventEmitter {
         waitResponse?: boolean;
     }): Promise<void>;
     /**
-     * Low-level write logic, handled by QueueManager.
-     * Handles backpressure (drain).
+     * Low-level write logic executed by the QueueManager.
+     * Handles backpressure through the 'drain' event.
+     * @param data - The data to write to the port
+     * @returns A promise that resolves when the data has been fully written
      */
     protected performWrite(data: string | Buffer): Promise<void>;
     /**
-     * Centralized connection failure handling.
+     * Handles connection failures in a centralized manner.
+     * Emits error events and schedules reconnection attempts if not intentional.
+     * @param reason - The reason for the connection failure
      */
     protected handleConnectionFailure(reason: string): void;
     /**
-     * Schedules next connection attempt with simple backoff.
+     * Schedules the next connection attempt with a simple backoff strategy.
      */
     protected scheduleReconnect(): void;
     /**
-     * Resource cleanup.
+     * Cleans up resources and listeners.
+     * Unregisters the port and removes all event listeners.
      */
     protected cleanup(): void;
     /**
-     * Executes connection handshake.
+     * Executes the connection handshake to verify device responsiveness.
+     * Sends a handshake command and waits for a pattern match in the response.
      */
     protected performHandshake(): void;
 }

package/dist/SerialService.d.ts

@@ -14,28 +14,51 @@ export declare class SerialService extends EventEmitter {
     protected config: SerialConfig;
     protected intentionalDisconnect: boolean;
     protected reconnectTimer: NodeJS.Timeout | null;
+    /**
+     * Initializes the SerialService with the provided configuration.
+     * @param config - Configuration object for serial connection
+     */
     constructor(config: SerialConfig);
+    /**
+     * Gets the autoConnect configuration value.
+     * @returns Whether the service should automatically connect on instantiation
+     */
     get autoConnect(): boolean;
+    /**
+     * Gets the current connection status.
+     * @returns The current serial connection status
+     */
     get status(): SerialStatus;
     /**
-     * Updates status and emits the corresponding event.
+     * Updates the service status and emits the corresponding event.
+     * @param newStatus - The new status to set
      */
     protected setStatus(newStatus: SerialStatus): void;
     /**
      * Starts the connection process.
      * Handles both direct connection (known path) and scanning (VID/PID).
+     * @throws Will emit error events if connection fails
      */
     connect(): Promise<void>;
     /**
-     * Physically opens the port and configures listeners.
+     * Physically opens the serial port and configures all necessary listeners.
+     * @param path - The port path to open (e.g., '/dev/ttyUSB0' or 'COM3')
      */
     protected openPort(path: string): void;
     /**
-     * Manual disconnection.
+     * Manually disconnects from the serial port.
+     * @returns A promise that resolves when the port is fully closed
      */
     disconnect(): Promise<void>;
     /**
-     * Public method to send data. Uses internal queue.
+     * Sends data through the serial port using the internal queue.
+     * @param data - The data to send (string or Buffer)
+     * @param options - Optional send configuration
+     * @param options.alias - A command identifier to correlate with responses
+     * @param options.timeout - Maximum time to wait for the operation in milliseconds
+     * @param options.waitResponse - If true, wait for a response before processing the next item in the queue
+     * @returns A promise that resolves when the data has been written to the port
+     * @throws If the port is not connected
      */
     send(data: string | Buffer, options?: {
         alias?: string;
@@ -43,24 +66,30 @@ export declare class SerialService extends EventEmitter {
         waitResponse?: boolean;
     }): Promise<void>;
     /**
-     * Low-level write logic, handled by QueueManager.
-     * Handles backpressure (drain).
+     * Low-level write logic executed by the QueueManager.
+     * Handles backpressure through the 'drain' event.
+     * @param data - The data to write to the port
+     * @returns A promise that resolves when the data has been fully written
      */
     protected performWrite(data: string | Buffer): Promise<void>;
     /**
-     * Centralized connection failure handling.
+     * Handles connection failures in a centralized manner.
+     * Emits error events and schedules reconnection attempts if not intentional.
+     * @param reason - The reason for the connection failure
      */
     protected handleConnectionFailure(reason: string): void;
     /**
-     * Schedules next connection attempt with simple backoff.
+     * Schedules the next connection attempt with a simple backoff strategy.
      */
     protected scheduleReconnect(): void;
     /**
-     * Resource cleanup.
+     * Cleans up resources and listeners.
+     * Unregisters the port and removes all event listeners.
      */
     protected cleanup(): void;
     /**
-     * Executes connection handshake.
+     * Executes the connection handshake to verify device responsiveness.
+     * Sends a handshake command and waits for a pattern match in the response.
      */
     protected performHandshake(): void;
 }

package/dist/core/PortRegistry.d.cts

@@ -7,18 +7,26 @@ export declare class PortRegistry {
     private static instance;
     private lockedPorts;
     private constructor();
+    /**
+     * Gets the singleton instance of the PortRegistry.
+     * @returns The PortRegistry singleton instance
+     */
     static getInstance(): PortRegistry;
     /**
      * Attempts to register (lock) exclusive use of a port.
-     * Returns true if registered successfully, false if already occupied.
+     * @param path - The port path to register
+     * @returns True if successfully registered, false if already in use
      */
     register(path: string): boolean;
     /**
      * Releases the port so it can be used again.
+     * @param path - The port path to unregister
      */
     unregister(path: string): void;
     /**
-     * Checks if a port is currently in use by the library.
+     * Checks if a port is currently locked by the library.
+     * @param path - The port path to check
+     * @returns True if the port is in use, false otherwise
      */
     isLocked(path: string): boolean;
 }

package/dist/core/PortRegistry.d.ts

@@ -7,18 +7,26 @@ export declare class PortRegistry {
     private static instance;
     private lockedPorts;
     private constructor();
+    /**
+     * Gets the singleton instance of the PortRegistry.
+     * @returns The PortRegistry singleton instance
+     */
     static getInstance(): PortRegistry;
     /**
      * Attempts to register (lock) exclusive use of a port.
-     * Returns true if registered successfully, false if already occupied.
+     * @param path - The port path to register
+     * @returns True if successfully registered, false if already in use
      */
     register(path: string): boolean;
     /**
      * Releases the port so it can be used again.
+     * @param path - The port path to unregister
      */
     unregister(path: string): void;
     /**
-     * Checks if a port is currently in use by the library.
+     * Checks if a port is currently locked by the library.
+     * @param path - The port path to check
+     * @returns True if the port is in use, false otherwise
      */
     isLocked(path: string): boolean;
 }

package/dist/core/PortScanner.d.cts

@@ -4,8 +4,12 @@
  */
 export declare class PortScanner {
     /**
-     * Search for a port matching the provided VID and/or PID.
-     * Normalizes strings to avoid case sensitivity issues.
+     * Searches for a serial port matching the provided Vendor ID and/or Product ID.
+     * Normalizes strings to handle case sensitivity and '0x' prefixes.
+     * @param vendorId - The USB vendor ID to search for (optional if productId provided)
+     * @param productId - The USB product ID to search for (optional)
+     * @returns The port path if found, null otherwise
+     * @throws Error if neither vendorId nor productId is provided
      */
     static findPort(vendorId?: string, productId?: string): Promise<string | null>;
 }

package/dist/core/PortScanner.d.ts

@@ -4,8 +4,12 @@
  */
 export declare class PortScanner {
     /**
-     * Search for a port matching the provided VID and/or PID.
-     * Normalizes strings to avoid case sensitivity issues.
+     * Searches for a serial port matching the provided Vendor ID and/or Product ID.
+     * Normalizes strings to handle case sensitivity and '0x' prefixes.
+     * @param vendorId - The USB vendor ID to search for (optional if productId provided)
+     * @param productId - The USB product ID to search for (optional)
+     * @returns The port path if found, null otherwise
+     * @throws Error if neither vendorId nor productId is provided
      */
     static findPort(vendorId?: string, productId?: string): Promise<string | null>;
 }

package/dist/core/QueueManager.d.cts

@@ -11,10 +11,19 @@ export declare class QueueManager {
     private currentTimeoutTimer;
     private currentItem;
     private writeHandler;
+    /**
+     * Initializes the QueueManager with a write handler function.
+     * @param writeHandler - Function to execute when writing data to the port
+     */
     constructor(writeHandler: (data: Buffer | string) => Promise<void>);
     /**
-     * Adds a command to the queue and returns a promise
-     * that resolves when the command has been drained to the port.
+     * Adds a command to the queue and returns a promise that resolves when processed.
+     * @param data - The data to queue (string or Buffer)
+     * @param options - Optional queue item configuration
+     * @param options.alias - Command identifier for response correlation
+     * @param options.timeout - Maximum time to wait for operation/response in milliseconds
+     * @param options.waitResponse - If true, block queue until response is received
+     * @returns Promise that resolves when the command has been processed
      */
     add(data: Buffer | string, options?: {
         alias?: string;
@@ -22,22 +31,38 @@ export declare class QueueManager {
         waitResponse?: boolean;
     }): Promise<void>;
     /**
-     * Getter for the alias of the command currently processing (or just processed).
-     * Useful for correlating responses.
+     * Gets the alias of the command currently processing or just processed.
+     * Useful for correlating received responses with sent commands.
+     * @returns The alias of the current command, or undefined if none
      */
     get currentAlias(): string | undefined;
     /**
-     * Clears the queue (useful on abrupt disconnections)
+     * Clears all pending items from the queue.
+     * Useful when handling abrupt disconnections.
+     * All pending items will be rejected with a disconnection error.
      */
     clear(): void;
     /**
-     * Notification from service that data was received.
-     * If we are waiting for a response, this signals we can move on.
+     * Notifies the queue that a response has been received.
+     * If waiting for a response, this triggers resolution of the current command
+     * and processes the next item in the queue.
      */
     notifyResponse(): void;
     /**
-     * Recursive processing loop
+     * Processes the queue recursively, executing items one by one.
+     * Handles timeouts and response waiting when configured.
+     * @private
      */
     private process;
+    /**
+     * Handles timeout when waiting for a response to a sent command.
+     * @private
+     * @param item - The queue item that timed out
+     */
     private handleResponseTimeout;
+    /**
+     * Checks if the queue is idle (no pending items, not processing, not waiting for response).
+     * @returns True if the queue has no pending operations
+     */
+    isIdle(): boolean;
 }

package/dist/core/QueueManager.d.ts

@@ -11,10 +11,19 @@ export declare class QueueManager {
     private currentTimeoutTimer;
     private currentItem;
     private writeHandler;
+    /**
+     * Initializes the QueueManager with a write handler function.
+     * @param writeHandler - Function to execute when writing data to the port
+     */
     constructor(writeHandler: (data: Buffer | string) => Promise<void>);
     /**
-     * Adds a command to the queue and returns a promise
-     * that resolves when the command has been drained to the port.
+     * Adds a command to the queue and returns a promise that resolves when processed.
+     * @param data - The data to queue (string or Buffer)
+     * @param options - Optional queue item configuration
+     * @param options.alias - Command identifier for response correlation
+     * @param options.timeout - Maximum time to wait for operation/response in milliseconds
+     * @param options.waitResponse - If true, block queue until response is received
+     * @returns Promise that resolves when the command has been processed
      */
     add(data: Buffer | string, options?: {
         alias?: string;
@@ -22,22 +31,38 @@ export declare class QueueManager {
         waitResponse?: boolean;
     }): Promise<void>;
     /**
-     * Getter for the alias of the command currently processing (or just processed).
-     * Useful for correlating responses.
+     * Gets the alias of the command currently processing or just processed.
+     * Useful for correlating received responses with sent commands.
+     * @returns The alias of the current command, or undefined if none
      */
     get currentAlias(): string | undefined;
     /**
-     * Clears the queue (useful on abrupt disconnections)
+     * Clears all pending items from the queue.
+     * Useful when handling abrupt disconnections.
+     * All pending items will be rejected with a disconnection error.
      */
     clear(): void;
     /**
-     * Notification from service that data was received.
-     * If we are waiting for a response, this signals we can move on.
+     * Notifies the queue that a response has been received.
+     * If waiting for a response, this triggers resolution of the current command
+     * and processes the next item in the queue.
      */
     notifyResponse(): void;
     /**
-     * Recursive processing loop
+     * Processes the queue recursively, executing items one by one.
+     * Handles timeouts and response waiting when configured.
+     * @private
      */
     private process;
+    /**
+     * Handles timeout when waiting for a response to a sent command.
+     * @private
+     * @param item - The queue item that timed out
+     */
     private handleResponseTimeout;
+    /**
+     * Checks if the queue is idle (no pending items, not processing, not waiting for response).
+     * @returns True if the queue has no pending operations
+     */
+    isIdle(): boolean;
 }

package/dist/index.cjs

@@ -1 +1 @@
-var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));const c=s(require(`serialport`)),l=s(require(`events`)),u={DISCONNECTED:`DISCONNECTED`,SCANNING:`SCANNING`,CONNECTING:`CONNECTING`,CONNECTED:`CONNECTED`,RECONNECTING:`RECONNECTING`};var d=class{queue=[];isProcessing=!1;_currentAlias=void 0;waitingForResponse=!1;currentTimeoutTimer=null;currentItem=null;writeHandler;constructor(e){this.writeHandler=e}add(e,t){return new Promise((n,r)=>{this.queue.push({data:e,resolve:n,reject:r,alias:t?.alias,timeout:t?.timeout,waitResponse:t?.waitResponse}),this.process()})}get currentAlias(){return this._currentAlias}clear(){this.queue.forEach(e=>e.reject(Error(`Queue cleared due to disconnection`))),this.queue=[],this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.currentItem.reject(Error(`Queue cleared due to disconnection`))),this.isProcessing=!1,this.waitingForResponse=!1,this.currentItem=null,this.currentTimeoutTimer=null}notifyResponse(){this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}async process(){if(this.isProcessing||this.waitingForResponse||this.queue.length===0)return;this.isProcessing=!0;let e=this.queue.shift();if(!e){this.isProcessing=!1;return}this.currentItem=e,this._currentAlias=e.alias;let t=null,n=!1;try{if(!e.waitResponse&&e.timeout&&e.timeout>0&&(t=setTimeout(()=>{n=!0,e.reject(Error(`Write timeout after ${e.timeout}ms`)),this.isProcessing=!1,this.currentItem=null,this.process()},e.timeout)),await this.writeHandler(e.data),n)return;t&&clearTimeout(t),e.waitResponse?(this.waitingForResponse=!0,e.timeout&&e.timeout>0&&(this.currentTimeoutTimer=setTimeout(()=>{this.handleResponseTimeout(e)},e.timeout)),this.isProcessing=!1):(e.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}catch(r){n||(t&&clearTimeout(t),e.reject(r instanceof Error?r:Error(String(r))),this.waitingForResponse=!1,this.currentItem=null,this.isProcessing=!1,this.process())}}handleResponseTimeout(e){this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem=null,e.reject(Error(`Response timeout after ${e.timeout}ms`)),this.process()}},f=class{static async findPort(e,t){if(!e&&!t)throw Error(`VendorID or ProductID is required for automatic scanning.`);try{let n=await c.SerialPort.list(),r=n.find(n=>{let r=n.vendorId?.toLowerCase()||``,i=n.productId?.toLowerCase()||``,a=(e||``).toLowerCase().replace(`0x`,``),o=(t||``).toLowerCase().replace(`0x`,``),s=e?r.includes(a):!0,c=t?i.includes(o):!0;return s&&c});return r?r.path:null}catch(e){return console.error(`Error scanning ports:`,e),null}}},p=class e{static instance;lockedPorts=new Set;constructor(){}static getInstance(){return e.instance||=new e,e.instance}register(e){return this.lockedPorts.has(e)?!1:(this.lockedPorts.add(e),!0)}unregister(e){this.lockedPorts.delete(e)}isLocked(e){return this.lockedPorts.has(e)}},m=class extends l.EventEmitter{port=null;queue;_status=u.DISCONNECTED;config;intentionalDisconnect=!1;reconnectTimer=null;constructor(e){super(),this.config=e,this.queue=new d(async e=>this.performWrite(e)),this.config.autoConnect&&this.connect()}get autoConnect(){return this.config.autoConnect}get status(){return this._status}setStatus(e){this._status!==e&&(this._status=e,this.emit(`status`,e))}async connect(){if(this._status===u.CONNECTED||this._status===u.CONNECTING)return;this.intentionalDisconnect=!1,this.setStatus(u.SCANNING);let e=this.config.path;if(!e)try{let t=await f.findPort(this.config.vendorId,this.config.productId);if(t)e=t;else{this.handleConnectionFailure(`Device not found in scan`);return}}catch(e){this.handleConnectionFailure(`Error scanning: ${e}`);return}if(p.getInstance().isLocked(e)){this.handleConnectionFailure(`Port ${e} occupied by another internal instance`);return}if(!p.getInstance().register(e)){this.handleConnectionFailure(`Could not lock port ${e}`);return}this.setStatus(u.CONNECTING),this.openPort(e)}openPort(e){if(this.port=new c.SerialPort({path:e,baudRate:this.config.baudRate,autoOpen:!1}),this.port.open(t=>{if(t){this.handleConnectionFailure(t.message);return}this.config.handshake?this.performHandshake():(this.setStatus(u.CONNECTED),this.emit(`connected`,{path:e,baudRate:this.config.baudRate}))}),this.config.parser){let e=this.port.pipe(this.config.parser);e.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)}),e.on(`error`,e=>this.emit(`error`,e))}else this.port.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)});this.port.on(`error`,e=>{this.emit(`error`,e)}),this.port.on(`close`,()=>{this.cleanup(),this.emit(`disconnected`,this.intentionalDisconnect?`Manual`:`Unexpected`),this.intentionalDisconnect?this.setStatus(u.DISCONNECTED):(this.setStatus(u.RECONNECTING),this.scheduleReconnect())})}async disconnect(){if(this.intentionalDisconnect=!0,this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.port&&this.port.isOpen)return new Promise(e=>{this.port?.close(()=>e())})}send(e,t){return this._status===u.CONNECTED?this.queue.add(e,t):Promise.reject(Error(`Port not connected`))}performWrite(e){return new Promise((t,n)=>{if(!this.port||!this.port.isOpen)return n(Error(`Port closed during write`));let r=!this.port.write(e,e=>{if(e)return n(e);r||t()});r&&this.port.once(`drain`,t)})}handleConnectionFailure(e){this.emit(`error`,Error(`Connection failure: ${e}`)),this.cleanup(),this.intentionalDisconnect||(this.setStatus(u.RECONNECTING),this.scheduleReconnect())}scheduleReconnect(){this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.reconnectTimer=setTimeout(()=>{this.connect()},this.config.reconnectInterval)}cleanup(){this.port&&this.port.path&&p.getInstance().unregister(this.port.path),this.port&&(this.port.removeAllListeners(),this.port=null),this.config.parser&&(this.config.parser.removeAllListeners(`data`),this.config.parser.removeAllListeners(`error`)),this.intentionalDisconnect&&this.queue.clear()}performHandshake(){if(!this.port||!this.port.isOpen||!this.config.handshake)return;let{command:e,pattern:t,timeout:n}=this.config.handshake,r,i=e=>{let n=``;n=Buffer.isBuffer(e)?e.toString():typeof e==`string`?e:String(e);let r=typeof t==`string`?new RegExp(t):t;r.test(n)&&(a(),this.setStatus(u.CONNECTED),this.emit(`connected`,{path:this.port.path,baudRate:this.config.baudRate}))},a=()=>{clearTimeout(r),this.removeListener(`data`,o)},o=e=>i(e);this.on(`data`,o),r=setTimeout(()=>{a(),this.handleConnectionFailure(`Handshake timeout (pattern: ${t})`)},n),this.performWrite(e).catch(e=>{a(),this.handleConnectionFailure(`Error writing handshake: ${e.message}`)})}};function h(e){return Buffer.isBuffer(e)?e:e instanceof Uint8Array?Buffer.from(e.buffer,e.byteOffset,e.byteLength):(Array.isArray(e),Buffer.from(e))}function g(e){return e}function _(e,t=`utf8`){return e.toString(t)}function v(e){return e.toString(`ascii`)}function y(e){return[...e]}exports.PortScanner=f,exports.SerialService=m,exports.SerialStatus=u,exports.toArray=y,exports.toAscii=v,exports.toBuffer=h,exports.toString=_,exports.toUint8Array=g;
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));const c=s(require(`serialport`)),l=s(require(`events`)),u={DISCONNECTED:`DISCONNECTED`,SCANNING:`SCANNING`,CONNECTING:`CONNECTING`,CONNECTED:`CONNECTED`,RECONNECTING:`RECONNECTING`};var d=class{queue=[];isProcessing=!1;_currentAlias=void 0;waitingForResponse=!1;currentTimeoutTimer=null;currentItem=null;writeHandler;constructor(e){this.writeHandler=e}add(e,t){return new Promise((n,r)=>{this.queue.push({data:e,resolve:n,reject:r,alias:t?.alias,timeout:t?.timeout,waitResponse:t?.waitResponse}),this.process()})}get currentAlias(){return this._currentAlias}clear(){this.queue.forEach(e=>e.reject(Error(`Queue cleared due to disconnection`))),this.queue=[],this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.currentItem.reject(Error(`Queue cleared due to disconnection`))),this.isProcessing=!1,this.waitingForResponse=!1,this.currentItem=null,this.currentTimeoutTimer=null}notifyResponse(){this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}async process(){if(this.isProcessing||this.waitingForResponse||this.queue.length===0)return;this.isProcessing=!0;let e=this.queue.shift();if(!e){this.isProcessing=!1;return}this.currentItem=e,this._currentAlias=e.alias;let t=null,n=!1;try{if(!e.waitResponse&&e.timeout&&e.timeout>0&&(t=setTimeout(()=>{n=!0,e.reject(Error(`Write timeout after ${e.timeout}ms`)),this.isProcessing=!1,this.currentItem=null,this.process()},e.timeout)),await this.writeHandler(e.data),n)return;t&&clearTimeout(t),e.waitResponse?(this.waitingForResponse=!0,e.timeout&&e.timeout>0&&(this.currentTimeoutTimer=setTimeout(()=>{this.handleResponseTimeout(e)},e.timeout)),this.isProcessing=!1):(e.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}catch(r){n||(t&&clearTimeout(t),e.reject(r instanceof Error?r:Error(String(r))),this.waitingForResponse=!1,this.currentItem=null,this.isProcessing=!1,this.process())}}handleResponseTimeout(e){this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem=null,e.reject(Error(`Response timeout after ${e.timeout}ms`)),this.process()}isIdle(){return this.queue.length===0&&!this.isProcessing&&!this.waitingForResponse}},f=class{static async findPort(e,t){if(!e&&!t)throw Error(`VendorID or ProductID is required for automatic scanning.`);try{let n=await c.SerialPort.list(),r=n.find(n=>{let r=n.vendorId?.toLowerCase()||``,i=n.productId?.toLowerCase()||``,a=(e||``).toLowerCase().replace(`0x`,``),o=(t||``).toLowerCase().replace(`0x`,``),s=e?r.includes(a):!0,c=t?i.includes(o):!0;return s&&c});return r?r.path:null}catch(e){return console.error(`Error scanning ports:`,e),null}}},p=class e{static instance;lockedPorts=new Set;constructor(){}static getInstance(){return e.instance||=new e,e.instance}register(e){return this.lockedPorts.has(e)?!1:(this.lockedPorts.add(e),!0)}unregister(e){this.lockedPorts.delete(e)}isLocked(e){return this.lockedPorts.has(e)}},m=class extends l.EventEmitter{port=null;queue;_status=u.DISCONNECTED;config;intentionalDisconnect=!1;reconnectTimer=null;constructor(e){super(),this.config=e,this.queue=new d(async e=>this.performWrite(e)),this.config.autoConnect&&this.connect()}get autoConnect(){return this.config.autoConnect}get status(){return this._status}setStatus(e){this._status!==e&&(this._status=e,this.emit(`status`,e))}async connect(){if(this._status===u.CONNECTED||this._status===u.CONNECTING)return;this.intentionalDisconnect=!1,this.setStatus(u.SCANNING);let e=this.config.path;if(!e)try{let t=await f.findPort(this.config.vendorId,this.config.productId);if(t)e=t;else{this.handleConnectionFailure(`Device not found in scan`);return}}catch(e){this.handleConnectionFailure(`Error scanning: ${e}`);return}if(p.getInstance().isLocked(e)){this.handleConnectionFailure(`Port ${e} occupied by another internal instance`);return}if(!p.getInstance().register(e)){this.handleConnectionFailure(`Could not lock port ${e}`);return}this.setStatus(u.CONNECTING),this.openPort(e)}openPort(e){if(this.port=new c.SerialPort({path:e,baudRate:this.config.baudRate,autoOpen:!1}),this.port.open(t=>{if(t){this.handleConnectionFailure(t.message);return}this.config.handshake?this.performHandshake():(this.setStatus(u.CONNECTED),this.emit(`connected`,{path:e,baudRate:this.config.baudRate}))}),this.config.parser){let e=this.port.pipe(this.config.parser);e.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)}),e.on(`error`,e=>this.emit(`error`,e))}else this.port.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)});this.port.on(`error`,e=>{this.emit(`error`,e)}),this.port.on(`close`,()=>{this.cleanup(),this.emit(`disconnected`,this.intentionalDisconnect?`Manual`:`Unexpected`),this.intentionalDisconnect?this.setStatus(u.DISCONNECTED):(this.setStatus(u.RECONNECTING),this.scheduleReconnect())})}async disconnect(){if(this.intentionalDisconnect=!0,this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.port&&this.port.isOpen)return new Promise(e=>{this.port?.close(()=>e())})}send(e,t){return this._status===u.CONNECTED?this.queue.add(e,t):Promise.reject(Error(`Port not connected`))}performWrite(e){return new Promise((t,n)=>{if(!this.port||!this.port.isOpen)return n(Error(`Port closed during write`));let r=!this.port.write(e,e=>{if(e)return n(e);r||t()});r&&this.port.once(`drain`,t)})}handleConnectionFailure(e){this.emit(`error`,Error(`Connection failure: ${e}`)),this.cleanup(),this.intentionalDisconnect||(this.setStatus(u.RECONNECTING),this.scheduleReconnect())}scheduleReconnect(){this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.reconnectTimer=setTimeout(()=>{this.connect()},this.config.reconnectInterval)}cleanup(){this.port&&this.port.path&&p.getInstance().unregister(this.port.path),this.port&&(this.port.removeAllListeners(),this.port=null),this.config.parser&&(this.config.parser.removeAllListeners(`data`),this.config.parser.removeAllListeners(`error`)),this.intentionalDisconnect&&this.queue.clear()}performHandshake(){if(!this.port||!this.port.isOpen||!this.config.handshake)return;let{command:e,pattern:t,timeout:n,hexPattern:r}=this.config.handshake,i,a=e=>{let n=``;if(Buffer.isBuffer(e))n=r?e.toString(`hex`):e.toString();else if(typeof e==`string`)n=r?Buffer.from(e).toString(`hex`):e;else{let t=Buffer.from(String(e));n=r?t.toString(`hex`):t.toString()}let i=typeof t==`string`?new RegExp(t):t;i.test(n)&&(o(),this.setStatus(u.CONNECTED),this.emit(`connected`,{path:this.port.path,baudRate:this.config.baudRate}))},o=()=>{clearTimeout(i),this.removeListener(`data`,s)},s=e=>a(e);this.on(`data`,s),i=setTimeout(()=>{o(),this.handleConnectionFailure(`Handshake timeout (pattern: ${t})`)},n),this.performWrite(e).catch(e=>{o(),this.handleConnectionFailure(`Error writing handshake: ${e.message}`)})}};function h(e){return Buffer.isBuffer(e)?e:e instanceof Uint8Array?Buffer.from(e.buffer,e.byteOffset,e.byteLength):(Array.isArray(e),Buffer.from(e))}function g(e){return e}function _(e,t=`utf8`){return e.toString(t)}function v(e){return e.toString(`ascii`)}function y(e){return[...e]}exports.PortScanner=f,exports.SerialService=m,exports.SerialStatus=u,exports.toArray=y,exports.toAscii=v,exports.toBuffer=h,exports.toString=_,exports.toUint8Array=g;

package/dist/index.js

@@ -1 +1 @@
-import{SerialPort as e}from"serialport";import{EventEmitter as t}from"events";const n={DISCONNECTED:`DISCONNECTED`,SCANNING:`SCANNING`,CONNECTING:`CONNECTING`,CONNECTED:`CONNECTED`,RECONNECTING:`RECONNECTING`};var r=class{queue=[];isProcessing=!1;_currentAlias=void 0;waitingForResponse=!1;currentTimeoutTimer=null;currentItem=null;writeHandler;constructor(e){this.writeHandler=e}add(e,t){return new Promise((n,r)=>{this.queue.push({data:e,resolve:n,reject:r,alias:t?.alias,timeout:t?.timeout,waitResponse:t?.waitResponse}),this.process()})}get currentAlias(){return this._currentAlias}clear(){this.queue.forEach(e=>e.reject(Error(`Queue cleared due to disconnection`))),this.queue=[],this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.currentItem.reject(Error(`Queue cleared due to disconnection`))),this.isProcessing=!1,this.waitingForResponse=!1,this.currentItem=null,this.currentTimeoutTimer=null}notifyResponse(){this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}async process(){if(this.isProcessing||this.waitingForResponse||this.queue.length===0)return;this.isProcessing=!0;let e=this.queue.shift();if(!e){this.isProcessing=!1;return}this.currentItem=e,this._currentAlias=e.alias;let t=null,n=!1;try{if(!e.waitResponse&&e.timeout&&e.timeout>0&&(t=setTimeout(()=>{n=!0,e.reject(Error(`Write timeout after ${e.timeout}ms`)),this.isProcessing=!1,this.currentItem=null,this.process()},e.timeout)),await this.writeHandler(e.data),n)return;t&&clearTimeout(t),e.waitResponse?(this.waitingForResponse=!0,e.timeout&&e.timeout>0&&(this.currentTimeoutTimer=setTimeout(()=>{this.handleResponseTimeout(e)},e.timeout)),this.isProcessing=!1):(e.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}catch(r){n||(t&&clearTimeout(t),e.reject(r instanceof Error?r:Error(String(r))),this.waitingForResponse=!1,this.currentItem=null,this.isProcessing=!1,this.process())}}handleResponseTimeout(e){this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem=null,e.reject(Error(`Response timeout after ${e.timeout}ms`)),this.process()}},i=class{static async findPort(t,n){if(!t&&!n)throw Error(`VendorID or ProductID is required for automatic scanning.`);try{let r=await e.list(),i=r.find(e=>{let r=e.vendorId?.toLowerCase()||``,i=e.productId?.toLowerCase()||``,a=(t||``).toLowerCase().replace(`0x`,``),o=(n||``).toLowerCase().replace(`0x`,``),s=t?r.includes(a):!0,c=n?i.includes(o):!0;return s&&c});return i?i.path:null}catch(e){return console.error(`Error scanning ports:`,e),null}}},a=class e{static instance;lockedPorts=new Set;constructor(){}static getInstance(){return e.instance||=new e,e.instance}register(e){return this.lockedPorts.has(e)?!1:(this.lockedPorts.add(e),!0)}unregister(e){this.lockedPorts.delete(e)}isLocked(e){return this.lockedPorts.has(e)}},o=class extends t{port=null;queue;_status=n.DISCONNECTED;config;intentionalDisconnect=!1;reconnectTimer=null;constructor(e){super(),this.config=e,this.queue=new r(async e=>this.performWrite(e)),this.config.autoConnect&&this.connect()}get autoConnect(){return this.config.autoConnect}get status(){return this._status}setStatus(e){this._status!==e&&(this._status=e,this.emit(`status`,e))}async connect(){if(this._status===n.CONNECTED||this._status===n.CONNECTING)return;this.intentionalDisconnect=!1,this.setStatus(n.SCANNING);let e=this.config.path;if(!e)try{let t=await i.findPort(this.config.vendorId,this.config.productId);if(t)e=t;else{this.handleConnectionFailure(`Device not found in scan`);return}}catch(e){this.handleConnectionFailure(`Error scanning: ${e}`);return}if(a.getInstance().isLocked(e)){this.handleConnectionFailure(`Port ${e} occupied by another internal instance`);return}if(!a.getInstance().register(e)){this.handleConnectionFailure(`Could not lock port ${e}`);return}this.setStatus(n.CONNECTING),this.openPort(e)}openPort(t){if(this.port=new e({path:t,baudRate:this.config.baudRate,autoOpen:!1}),this.port.open(e=>{if(e){this.handleConnectionFailure(e.message);return}this.config.handshake?this.performHandshake():(this.setStatus(n.CONNECTED),this.emit(`connected`,{path:t,baudRate:this.config.baudRate}))}),this.config.parser){let e=this.port.pipe(this.config.parser);e.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)}),e.on(`error`,e=>this.emit(`error`,e))}else this.port.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)});this.port.on(`error`,e=>{this.emit(`error`,e)}),this.port.on(`close`,()=>{this.cleanup(),this.emit(`disconnected`,this.intentionalDisconnect?`Manual`:`Unexpected`),this.intentionalDisconnect?this.setStatus(n.DISCONNECTED):(this.setStatus(n.RECONNECTING),this.scheduleReconnect())})}async disconnect(){if(this.intentionalDisconnect=!0,this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.port&&this.port.isOpen)return new Promise(e=>{this.port?.close(()=>e())})}send(e,t){return this._status===n.CONNECTED?this.queue.add(e,t):Promise.reject(Error(`Port not connected`))}performWrite(e){return new Promise((t,n)=>{if(!this.port||!this.port.isOpen)return n(Error(`Port closed during write`));let r=!this.port.write(e,e=>{if(e)return n(e);r||t()});r&&this.port.once(`drain`,t)})}handleConnectionFailure(e){this.emit(`error`,Error(`Connection failure: ${e}`)),this.cleanup(),this.intentionalDisconnect||(this.setStatus(n.RECONNECTING),this.scheduleReconnect())}scheduleReconnect(){this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.reconnectTimer=setTimeout(()=>{this.connect()},this.config.reconnectInterval)}cleanup(){this.port&&this.port.path&&a.getInstance().unregister(this.port.path),this.port&&(this.port.removeAllListeners(),this.port=null),this.config.parser&&(this.config.parser.removeAllListeners(`data`),this.config.parser.removeAllListeners(`error`)),this.intentionalDisconnect&&this.queue.clear()}performHandshake(){if(!this.port||!this.port.isOpen||!this.config.handshake)return;let{command:e,pattern:t,timeout:r}=this.config.handshake,i,a=e=>{let r=``;r=Buffer.isBuffer(e)?e.toString():typeof e==`string`?e:String(e);let i=typeof t==`string`?new RegExp(t):t;i.test(r)&&(o(),this.setStatus(n.CONNECTED),this.emit(`connected`,{path:this.port.path,baudRate:this.config.baudRate}))},o=()=>{clearTimeout(i),this.removeListener(`data`,s)},s=e=>a(e);this.on(`data`,s),i=setTimeout(()=>{o(),this.handleConnectionFailure(`Handshake timeout (pattern: ${t})`)},r),this.performWrite(e).catch(e=>{o(),this.handleConnectionFailure(`Error writing handshake: ${e.message}`)})}};function s(e){return Buffer.isBuffer(e)?e:e instanceof Uint8Array?Buffer.from(e.buffer,e.byteOffset,e.byteLength):(Array.isArray(e),Buffer.from(e))}function c(e){return e}function l(e,t=`utf8`){return e.toString(t)}function u(e){return e.toString(`ascii`)}function d(e){return[...e]}export{i as PortScanner,o as SerialService,n as SerialStatus,d as toArray,u as toAscii,s as toBuffer,l as toString,c as toUint8Array};
+import{SerialPort as e}from"serialport";import{EventEmitter as t}from"events";const n={DISCONNECTED:`DISCONNECTED`,SCANNING:`SCANNING`,CONNECTING:`CONNECTING`,CONNECTED:`CONNECTED`,RECONNECTING:`RECONNECTING`};var r=class{queue=[];isProcessing=!1;_currentAlias=void 0;waitingForResponse=!1;currentTimeoutTimer=null;currentItem=null;writeHandler;constructor(e){this.writeHandler=e}add(e,t){return new Promise((n,r)=>{this.queue.push({data:e,resolve:n,reject:r,alias:t?.alias,timeout:t?.timeout,waitResponse:t?.waitResponse}),this.process()})}get currentAlias(){return this._currentAlias}clear(){this.queue.forEach(e=>e.reject(Error(`Queue cleared due to disconnection`))),this.queue=[],this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.currentItem.reject(Error(`Queue cleared due to disconnection`))),this.isProcessing=!1,this.waitingForResponse=!1,this.currentItem=null,this.currentTimeoutTimer=null}notifyResponse(){this.waitingForResponse&&this.currentItem&&(this.currentTimeoutTimer&&clearTimeout(this.currentTimeoutTimer),this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}async process(){if(this.isProcessing||this.waitingForResponse||this.queue.length===0)return;this.isProcessing=!0;let e=this.queue.shift();if(!e){this.isProcessing=!1;return}this.currentItem=e,this._currentAlias=e.alias;let t=null,n=!1;try{if(!e.waitResponse&&e.timeout&&e.timeout>0&&(t=setTimeout(()=>{n=!0,e.reject(Error(`Write timeout after ${e.timeout}ms`)),this.isProcessing=!1,this.currentItem=null,this.process()},e.timeout)),await this.writeHandler(e.data),n)return;t&&clearTimeout(t),e.waitResponse?(this.waitingForResponse=!0,e.timeout&&e.timeout>0&&(this.currentTimeoutTimer=setTimeout(()=>{this.handleResponseTimeout(e)},e.timeout)),this.isProcessing=!1):(e.resolve(),this.currentItem=null,this.isProcessing=!1,this.process())}catch(r){n||(t&&clearTimeout(t),e.reject(r instanceof Error?r:Error(String(r))),this.waitingForResponse=!1,this.currentItem=null,this.isProcessing=!1,this.process())}}handleResponseTimeout(e){this.waitingForResponse=!1,this.currentTimeoutTimer=null,this.currentItem=null,e.reject(Error(`Response timeout after ${e.timeout}ms`)),this.process()}isIdle(){return this.queue.length===0&&!this.isProcessing&&!this.waitingForResponse}},i=class{static async findPort(t,n){if(!t&&!n)throw Error(`VendorID or ProductID is required for automatic scanning.`);try{let r=await e.list(),i=r.find(e=>{let r=e.vendorId?.toLowerCase()||``,i=e.productId?.toLowerCase()||``,a=(t||``).toLowerCase().replace(`0x`,``),o=(n||``).toLowerCase().replace(`0x`,``),s=t?r.includes(a):!0,c=n?i.includes(o):!0;return s&&c});return i?i.path:null}catch(e){return console.error(`Error scanning ports:`,e),null}}},a=class e{static instance;lockedPorts=new Set;constructor(){}static getInstance(){return e.instance||=new e,e.instance}register(e){return this.lockedPorts.has(e)?!1:(this.lockedPorts.add(e),!0)}unregister(e){this.lockedPorts.delete(e)}isLocked(e){return this.lockedPorts.has(e)}},o=class extends t{port=null;queue;_status=n.DISCONNECTED;config;intentionalDisconnect=!1;reconnectTimer=null;constructor(e){super(),this.config=e,this.queue=new r(async e=>this.performWrite(e)),this.config.autoConnect&&this.connect()}get autoConnect(){return this.config.autoConnect}get status(){return this._status}setStatus(e){this._status!==e&&(this._status=e,this.emit(`status`,e))}async connect(){if(this._status===n.CONNECTED||this._status===n.CONNECTING)return;this.intentionalDisconnect=!1,this.setStatus(n.SCANNING);let e=this.config.path;if(!e)try{let t=await i.findPort(this.config.vendorId,this.config.productId);if(t)e=t;else{this.handleConnectionFailure(`Device not found in scan`);return}}catch(e){this.handleConnectionFailure(`Error scanning: ${e}`);return}if(a.getInstance().isLocked(e)){this.handleConnectionFailure(`Port ${e} occupied by another internal instance`);return}if(!a.getInstance().register(e)){this.handleConnectionFailure(`Could not lock port ${e}`);return}this.setStatus(n.CONNECTING),this.openPort(e)}openPort(t){if(this.port=new e({path:t,baudRate:this.config.baudRate,autoOpen:!1}),this.port.open(e=>{if(e){this.handleConnectionFailure(e.message);return}this.config.handshake?this.performHandshake():(this.setStatus(n.CONNECTED),this.emit(`connected`,{path:t,baudRate:this.config.baudRate}))}),this.config.parser){let e=this.port.pipe(this.config.parser);e.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)}),e.on(`error`,e=>this.emit(`error`,e))}else this.port.on(`data`,e=>{this.queue.notifyResponse(),this.emit(`data`,e,this.queue.currentAlias)});this.port.on(`error`,e=>{this.emit(`error`,e)}),this.port.on(`close`,()=>{this.cleanup(),this.emit(`disconnected`,this.intentionalDisconnect?`Manual`:`Unexpected`),this.intentionalDisconnect?this.setStatus(n.DISCONNECTED):(this.setStatus(n.RECONNECTING),this.scheduleReconnect())})}async disconnect(){if(this.intentionalDisconnect=!0,this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.port&&this.port.isOpen)return new Promise(e=>{this.port?.close(()=>e())})}send(e,t){return this._status===n.CONNECTED?this.queue.add(e,t):Promise.reject(Error(`Port not connected`))}performWrite(e){return new Promise((t,n)=>{if(!this.port||!this.port.isOpen)return n(Error(`Port closed during write`));let r=!this.port.write(e,e=>{if(e)return n(e);r||t()});r&&this.port.once(`drain`,t)})}handleConnectionFailure(e){this.emit(`error`,Error(`Connection failure: ${e}`)),this.cleanup(),this.intentionalDisconnect||(this.setStatus(n.RECONNECTING),this.scheduleReconnect())}scheduleReconnect(){this.reconnectTimer&&clearTimeout(this.reconnectTimer),this.reconnectTimer=setTimeout(()=>{this.connect()},this.config.reconnectInterval)}cleanup(){this.port&&this.port.path&&a.getInstance().unregister(this.port.path),this.port&&(this.port.removeAllListeners(),this.port=null),this.config.parser&&(this.config.parser.removeAllListeners(`data`),this.config.parser.removeAllListeners(`error`)),this.intentionalDisconnect&&this.queue.clear()}performHandshake(){if(!this.port||!this.port.isOpen||!this.config.handshake)return;let{command:e,pattern:t,timeout:r,hexPattern:i}=this.config.handshake,a,o=e=>{let r=``;if(Buffer.isBuffer(e))r=i?e.toString(`hex`):e.toString();else if(typeof e==`string`)r=i?Buffer.from(e).toString(`hex`):e;else{let t=Buffer.from(String(e));r=i?t.toString(`hex`):t.toString()}let a=typeof t==`string`?new RegExp(t):t;a.test(r)&&(s(),this.setStatus(n.CONNECTED),this.emit(`connected`,{path:this.port.path,baudRate:this.config.baudRate}))},s=()=>{clearTimeout(a),this.removeListener(`data`,c)},c=e=>o(e);this.on(`data`,c),a=setTimeout(()=>{s(),this.handleConnectionFailure(`Handshake timeout (pattern: ${t})`)},r),this.performWrite(e).catch(e=>{s(),this.handleConnectionFailure(`Error writing handshake: ${e.message}`)})}};function s(e){return Buffer.isBuffer(e)?e:e instanceof Uint8Array?Buffer.from(e.buffer,e.byteOffset,e.byteLength):(Array.isArray(e),Buffer.from(e))}function c(e){return e}function l(e,t=`utf8`){return e.toString(t)}function u(e){return e.toString(`ascii`)}function d(e){return[...e]}export{i as PortScanner,o as SerialService,n as SerialStatus,d as toArray,u as toAscii,s as toBuffer,l as toString,c as toUint8Array};

package/dist/types.d.cts

@@ -18,6 +18,7 @@ export interface SerialConfig {
         command: string | Buffer;
         pattern: string | RegExp;
         timeout: number;
+        hexPattern?: boolean;
     };
 }
 export interface QueueItem {

package/dist/types.d.ts

@@ -18,6 +18,7 @@ export interface SerialConfig {
         command: string | Buffer;
         pattern: string | RegExp;
         timeout: number;
+        hexPattern?: boolean;
     };
 }
 export interface QueueItem {

package/dist/utils/buffers.d.cts

@@ -5,23 +5,35 @@
 /**
  * Efficiently converts various input types to Buffer.
  * If input is already a Buffer, returns it as is (zero-copy).
+ * @param data - The data to convert (string, number array, Uint8Array, or Buffer)
+ * @returns A Buffer instance
  */
 export declare function toBuffer(data: string | number[] | Uint8Array | Buffer): Buffer;
 /**
  * Converts a Buffer to Uint8Array.
  * In Node.js, Buffers ARE Uint8Arrays, so this is ideally zero-copy.
+ * @param buf - The buffer to convert
+ * @returns The buffer as a Uint8Array
  */
 export declare function toUint8Array(buf: Buffer): Uint8Array;
 /**
  * Converts a Buffer to string with optional encoding (default utf8).
  * Wrapper alias for toString().
+ * @param buf - The buffer to convert
+ * @param encoding - The character encoding to use (default: 'utf8')
+ * @returns The buffer contents as a string
  */
 export declare function toString(buf: Buffer, encoding?: BufferEncoding): string;
 /**
- * Optimally converts to ASCII.
+ * Converts a Buffer to ASCII string representation.
+ * @param buf - The buffer to convert
+ * @returns The buffer contents as an ASCII string
  */
 export declare function toAscii(buf: Buffer): string;
 /**
- * Converts a Buffer to an Array of numbers (bytes).
+ * Converts a Buffer to an array of byte values.
+ * Note: Using spread operator may be slow for very large buffers.
+ * @param buf - The buffer to convert
+ * @returns An array of numbers representing each byte
  */
 export declare function toArray(buf: Buffer): number[];

package/dist/utils/buffers.d.ts

@@ -5,23 +5,35 @@
 /**
  * Efficiently converts various input types to Buffer.
  * If input is already a Buffer, returns it as is (zero-copy).
+ * @param data - The data to convert (string, number array, Uint8Array, or Buffer)
+ * @returns A Buffer instance
  */
 export declare function toBuffer(data: string | number[] | Uint8Array | Buffer): Buffer;
 /**
  * Converts a Buffer to Uint8Array.
  * In Node.js, Buffers ARE Uint8Arrays, so this is ideally zero-copy.
+ * @param buf - The buffer to convert
+ * @returns The buffer as a Uint8Array
  */
 export declare function toUint8Array(buf: Buffer): Uint8Array;
 /**
  * Converts a Buffer to string with optional encoding (default utf8).
  * Wrapper alias for toString().
+ * @param buf - The buffer to convert
+ * @param encoding - The character encoding to use (default: 'utf8')
+ * @returns The buffer contents as a string
  */
 export declare function toString(buf: Buffer, encoding?: BufferEncoding): string;
 /**
- * Optimally converts to ASCII.
+ * Converts a Buffer to ASCII string representation.
+ * @param buf - The buffer to convert
+ * @returns The buffer contents as an ASCII string
  */
 export declare function toAscii(buf: Buffer): string;
 /**
- * Converts a Buffer to an Array of numbers (bytes).
+ * Converts a Buffer to an array of byte values.
+ * Note: Using spread operator may be slow for very large buffers.
+ * @param buf - The buffer to convert
+ * @returns An array of numbers representing each byte
  */
 export declare function toArray(buf: Buffer): number[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "serial-core",
   "type": "module",
-  "version": "0.2.0-dev.4",
+  "version": "0.2.0",
   "description": "Resilient serial communication service with automatic reconnection and queues.",
   "author": "Danidoble <danidoble@gmail.com>",
   "license": "GPL-3.0-only",