serial-core 0.2.0-dev.5 → 0.2.0

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,27 +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;
     /**
-     * Indicates whether the queue is idle (no pending items,
-     * not processing, not waiting for response)
+     * 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,27 +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;
     /**
-     * Indicates whether the queue is idle (no pending items,
-     * not processing, not waiting for response)
+     * 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/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.5",
+  "version": "0.2.0",
   "description": "Resilient serial communication service with automatic reconnection and queues.",
   "author": "Danidoble <danidoble@gmail.com>",
   "license": "GPL-3.0-only",