serial-core 0.2.3 → 0.3.0

package/llms.txt

@@ -0,0 +1,191 @@
+# serial-core
+
+> Node.js serial transport service with bounded command queuing, discovery, optional verification and automatic recovery. This file documents the repository API for coding assistants and other documentation consumers.
+
+## Documentation map
+
+- [README.md](README.md): Complete human reference, examples, all methods/options/events, extension contracts, error handling and compatibility.
+- [AGENTS.md](AGENTS.md): Repository contributor/agent guidance; source checkout only, not an npm package file.
+- [src/index.ts](src/index.ts): Authoritative package-root export inventory in a source checkout.
+- [src/SerialService.ts](src/SerialService.ts): Lifecycle, queue integration, event emission, teardown and recovery.
+- [src/types.ts](src/types.ts): JSDoc for every configuration, command, event and discovery field.
+- [src/core/PortScanner.ts](src/core/PortScanner.ts): Exact filtering and enumeration behavior.
+- [src/core/QueueManager.ts](src/core/QueueManager.ts): Internal FIFO and response/timeout race handling.
+- [src/core/PortRegistry.ts](src/core/PortRegistry.ts): Internal module-local exact-path reservations.
+- [src/utils/buffers.ts](src/utils/buffers.ts): Buffer utility implementation and memory ownership.
+- [CONTRIBUTING.md](CONTRIBUTING.md): General contributor workflow.
+
+An installed npm package provides README.md, this file and dist declarations/bundles; source checkout links may not exist there. Inspect dist/index.d.ts (ESM) or dist/index.d.cts (CommonJS) for installed signatures and IDE JSDoc. The export map exposes only the package root; documentation files are package files, not importable code subpaths.
+
+## Runtime and imports
+
+Use Node.js with serialport ^13.0.0 as an installed peer. serialport 13 requires Node >=20; serial-core's current own engine declaration of >=18 does not relax the peer requirement. Node streams and Buffer are used. This is not browser Web Serial.
+
+ESM: import { SerialService, SerialStatus, PortScanner } from 'serial-core'.
+CJS: const { SerialService, SerialStatus, PortScanner } = require('serial-core').
+Types: SerialConfig, SendOptions, PortFilter, SerialPortInfo, SerialEvents.
+Functions: toBuffer, toUint8Array, toString, toAscii, toArray.
+Internal QueueManager, PortRegistry and QueueItem are not root exports or supported deep imports.
+
+## Complete serial-specific callable API
+
+new SerialService(config: SerialConfig)
+SerialService.listPorts(filter?: PortFilter): Promise<SerialPortInfo[]>
+SerialService.findPorts(filter?: PortFilter): Promise<SerialPortInfo[]>
+serial.listPorts(filter?: PortFilter): Promise<SerialPortInfo[]>
+serial.findPorts(filter?: PortFilter): Promise<SerialPortInfo[]>
+serial.connect(): Promise<void>
+serial.disconnect(): Promise<void>
+serial.send(data: string | Buffer, options?: SendOptions): Promise<void>
+serial.queueIsIdle(): boolean
+serial.portIsOpen(): boolean
+serial.getPortPath(): string | null
+serial.getLastAlias(): string | null
+serial.status: SerialStatus (read-only)
+serial.autoConnect: boolean (read-only)
+PortScanner.listPorts(filter?: PortFilter): Promise<SerialPortInfo[]>
+PortScanner.findPorts(filter?: PortFilter): Promise<SerialPortInfo[]>
+PortScanner.findPort(vendorId?: string, productId?: string): Promise<string | null>
+toBuffer(data: string | number[] | Uint8Array | Buffer): Buffer
+toUint8Array(buf: Buffer): Uint8Array
+toString(buf: Buffer, encoding?: BufferEncoding): string
+toAscii(buf: Buffer): string
+toArray(buf: Buffer): number[]
+
+Inherited EventEmitter listener/introspection APIs include on/addListener, once, prependListener, prependOnceListener, off/removeListener, removeAllListeners, emit, eventNames, listenerCount, listeners, rawListeners, getMaxListeners and setMaxListeners. Their Node behavior applies. Listener removal does not disconnect. Do not manually emit lifecycle events to perform a serial action or remove internal handshake data listeners with removeAllListeners while verification runs.
+
+## Configuration inventory
+
+SerialConfig.baudRate: required positive finite number; no default baud rate.
+Supply at least one non-empty path, vendorId, productId or serialNumber.
+path?: fixed OS path; takes precedence over discovery selectors.
+vendorId?, productId?: USB IDs, normalized exact comparison.
+serialNumber?: exact case-sensitive unit identity.
+autoConnect?: false; if true starts in a microtask after construction.
+autoReconnect?: true.
+reconnectInterval?: 2000 ms.
+reconnectBackoffFactor?: 1; finite and >=1.
+maxReconnectInterval?: Math.max(30000, reconnectInterval); >=reconnectInterval.
+maxReconnectAttempts?: Infinity; non-negative integer or Infinity; initial attempt excluded.
+writeTimeout?: 5000 ms; always bounds physical write plus drain, including handshake command.
+responseTimeout?: 5000 ms; starts after writing.
+maxQueueSize?: 1000; positive integer, active plus pending commands.
+parser?: NodeJS.ReadWriteStream, reused across sessions.
+parserFactory?: () => NodeJS.ReadWriteStream, fresh parser each connection recommended.
+parser and parserFactory are mutually exclusive.
+handshake?: nested options below.
+
+Omit optional fields to use defaults. Numeric timer values must be positive finite numbers <=2147483647 ms; 0/Infinity are invalid timeouts. Invalid configuration throws synchronously at construction. Driver-level validity remains the driver's responsibility. Config references should not be mutated during use.
+
+Handshake fields:
+- command: required string | Buffer, sent outside FIFO after opening.
+- pattern: required string | RegExp; strings are regex sources, not literal comparisons.
+- timeout: required positive deadline in ms, including command transmission.
+- hexPattern?: false; regex uses lowercase hex rather than UTF-8 when true.
+- callback?: ((data: Buffer | string) => boolean) | null; synchronous, priority over regex/hex mode, individual chunks/parsed frames, not accumulated input. pattern remains required by the type even if ignored.
+- maxBufferSize?: 65536 positive integer bytes; regex accumulation only, not callback.
+
+## Autodiscovery recipes (omit path)
+
+Vendor-only, without productId:
+```typescript
+const serial = new SerialService({ baudRate: 9600, vendorId: '0403', autoConnect: true });
+serial.on('connected', ({ path }) => console.log('Vendor device ready:', path));
+serial.on('error', error => console.error(error.message));
+```
+
+Product-only, without vendorId:
+```typescript
+const serial = new SerialService({ baudRate: 115200, productId: '6001', autoConnect: true });
+serial.on('connected', ({ path }) => console.log('Product device ready:', path));
+serial.on('error', error => console.error(error.message));
+```
+
+Both IDs, optional exact unit:
+```typescript
+const serial = new SerialService({
+  baudRate: 115200, vendorId: '0403', productId: '6001',
+  serialNumber: 'DEVICE-001', autoConnect: true
+});
+serial.on('connected', ({ path }) => console.log('Unit ready:', path));
+serial.on('error', error => console.error(error.message));
+```
+
+Import SerialService from serial-core for each recipe. Example IDs and baud rates must match the actual device. Discover IDs using await SerialService.listPorts(). VID/PID are hex strings, not numbers. Vendor-only can match multiple products; product-only can match multiple vendors. Both IDs are AND-combined. A configured path bypasses discovery and does not validate its USB identity. With no path, automatic recovery reruns selectors and can follow changed USB paths. autoReconnect defaults true, retry budget defaults Infinity; disconnect stops searching. These are retry-driven connection attempts, not a watchPorts API. See README's dedicated Autodiscovery section for complete examples.
+
+## Lifecycle contracts
+
+States: DISCONNECTED, SCANNING, CONNECTING, CONNECTED, RECONNECTING.
+SCANNING can include waiting for old transport teardown, including when a fixed path is configured.
+CONNECTING includes handshake. Only CONNECTED permits send().
+connect() starts an attempt; its resolution is not readiness. Register connected/error listeners before calling it. Operational failures use events/retry policy, not a readiness rejection promise.
+Parallel connect calls do not start duplicate attempts. They do not share a readiness promise.
+Explicit connect() while inactive/reconnecting resets the retry budget; calls while scanning/connecting/connected are no-ops.
+A successful verified connection resets the retry count.
+One-based retry delay: min(maxReconnectInterval, reconnectInterval * reconnectBackoffFactor ** (attempt - 1)).
+At most one retry timer per service. maxReconnectAttempts: 0 permits initial attempt only. autoReconnect: false disables retries.
+Fixed paths are reused. Discovery selects the first currently unreserved match on every attempt, allowing changed USB paths. First-match order is driver-defined; use serialNumber to distinguish identical VID/PID devices.
+Errors without a close event also trigger recovery. Old stream callbacks are guarded.
+disconnect() cancels retries, invalidates in-flight discovery, cancels verification and rejects unfinished commands. Pending opens close when their callback arrives.
+DISCONNECTED can be observed before physical closure completes. Await disconnect() for closure.
+OS enumeration/open/close have no service-level timeout. Application wait timeouts do not forcibly cancel the OS operation.
+If closure fails while still open, disconnect() rejects and retains the reservation; call disconnect() again to retry.
+The instance and consumer listeners can be reused after disconnect().
+queueIsIdle() is not connectivity or device idleness. portIsOpen() may be true before handshake readiness. getPortPath() reports only the currently tracked transport, not a configured fallback.
+
+## Send and response contracts
+
+SendOptions: alias?: string; timeout?: number; waitResponse?: boolean (false); responseMatcher?: (data: Buffer | string) => boolean.
+Commands are FIFO and Buffer input is copied when enqueued. Terminators are not appended automatically.
+send() resolves to void, not the response. Read payloads through data events.
+No queued command is automatically replayed after disconnect. Active/pending commands reject. The device may already have acted; clients determine safe retries.
+Without waitResponse, resolve after write/drain; optional timeout starts when processing begins and bounds queue write wait.
+With waitResponse, timeout overrides responseTimeout and starts after writing. Physical writeTimeout applies independently.
+Waiting in the queue has no independent enqueue deadline. Capacity is bounded; individual command cancellation is not an API.
+An early response is retained until writing completes. A timed-out writer cannot overlap the next physical writer; it may remain busy until its callback/physical timeout.
+No matcher means next chunk/frame counts, possibly unsolicited input. Matcher false ignores a frame; exceptions reject the command. Async matchers are unsupported.
+Raw stream data is arbitrary chunks, not complete messages. Use a parser and protocol-aware matcher for framing.
+A response timeout rejects that command and advances the queue without an inherent reconnect. Late replies require protocol IDs/types to avoid being mistaken for the next response.
+Alias is local active/latest context, not a protocol ID or acknowledgement; it can persist while idle and label unsolicited input. Cleanup clears it. Capture the data event alias rather than reading mutable last context later.
+
+## Events
+
+SerialEvents maps event names to listener function signatures (not tuple arrays):
+status: (status: SerialStatus) => void; only changed values.
+data: (data: Buffer | string, alias?: string) => void; includes handshake traffic.
+error: (err: Error) => void; operational diagnostics, emitted only with an attached listener. Missing listeners do not stop recovery.
+connected: (info: { path: string; baudRate: number }) => void; each verified ready connection.
+disconnected: (reason: string) => void; current reasons Manual / Unexpected; not every failed scan/open.
+reconnecting: (info: { attempt: number; delay: number }) => void; scheduled retry, 1-based attempt, ms.
+reconnectFailed: (info: { attempts: number }) => void; exhausted retry budget, initial attempt excluded; not for disabled autoReconnect.
+
+Listeners run synchronously. Do not throw; handle async listener rejections inside the listener. captureRejections is not enabled. Returned send/disconnect/scanner promises must be handled independently of error listeners. Not every command rejection emits error. Error text is diagnostic, not a stable coded error API.
+Node events.once(serial, 'connected', { signal }) rejects on error/abort; using it for readiness is fail-fast on the first connection error even if recovery continues. Aborting such a wait does not disconnect.
+
+## Discovery contracts
+
+PortFilter: path?, vendorId?, productId?, serialNumber?, manufacturer? (strings), availableOnly? (false).
+All provided filters combine with AND. VID/PID normalization: trim, lowercase, remove leading 0x and leading zeros, then exact compare. Other strings are case-sensitive exact matches.
+Metadata is passed through from serialport; optional manufacturer/serialNumber/pnpId/locationId/VID/PID may be absent. Missing fields cannot match a supplied selector.
+Empty filters list all devices; result order is not sorted.
+Enumeration never opens/reserves ports. Empty [] or null means no match. Enumeration/driver errors reject and are not swallowed.
+findPort requires at least one non-empty VID/PID, returns first path or null, and does not filter reservations.
+availableOnly checks this loaded module's exact-path registry only, not other apps/processes/workers/module copies or path aliases. Availability can change before opening.
+Instance discovery methods do not implicitly apply the service config.
+
+## Parsers, handshake and memory ownership
+
+Use parserFactory for a fresh parser with Buffer/string output each session. The service unpipes without ending parsers and removes its own listeners; does not destroy parsers/manage their external resources. Shared parser buffer/reset state belongs to the client. Parser errors trigger recovery.
+Regex handshake matching accumulates bounded bytes and decodes UTF-8/hex; split input can match and regex lastIndex resets per test. Callback mode gets individual chunks/frames. Callback exceptions, overflow, timeout or write failure trigger recovery.
+Readiness requires both a matched response and successful handshake transmission. Temporary verification listeners/timers are canceled on success/failure/disconnect.
+toBuffer(Buffer) returns the same object; toBuffer(Uint8Array) shares backing storage. Strings use UTF-8 and arrays allocate via Buffer.from.
+toUint8Array(Buffer) is the same object, not a copy. toArray allocates an independent array. toString defaults to UTF-8; toAscii uses Node's ASCII high-bit masking semantics.
+Use Buffer.from(existingBuffer) when an independent copy is required. These helpers perform no protocol framing/checksum/endianness handling.
+
+## Extension and validation notes
+
+Protected hooks: setStatus(status), openPort(path), performWrite(data), handleConnectionFailure(reason), scheduleReconnect(), cleanup(error?), performHandshake(). These are implementation hooks, not stable transport adapters or public client actions. See README and source JSDoc for their ownership and lifecycle requirements.
+Internal QueueManager exposes constructor(writer,maxSize,responseTimeout), add, currentAlias, clear, notifyResponse and isIdle. Its writer supplies physical deadlines; clear() does not cancel that writer. Internal PortRegistry exposes getInstance, register, unregister and isLocked for exact-path reservations.
+No public watchPorts, reconnect, destroy, dispose, sendAndReceive, browser chooser, individual command cancellation, live baud-rate update or control-signal API exists. Do not invent these methods.
+Source validation: pnpm typecheck; pnpm exec vitest run; pnpm lint; pnpm build.
+Build names must continue matching package exports and declarations. Keep JSDoc in generated declarations. Automated mocks do not establish real hardware/driver reliability.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "serial-core",
   "type": "module",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Resilient serial communication service with automatic reconnection and queues.",
   "author": "Danidoble <danidoble@gmail.com>",
   "license": "GPL-3.0-only",
@@ -24,18 +24,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
-  "scripts": {
-    "dev": "tsdown --watch",
-    "build": "prettier --write ./src/ && tsdown",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest",
-    "prepublishOnly": "npm run build",
-    "clean": "rm -rf ./dist/",
-    "format": "prettier --write ./src/",
-    "lint": "eslint ."
-  },
   "keywords": [
     "serialport",
     "iot",
@@ -50,23 +41,32 @@
     "event-driven"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^20.19.30",
-    "bumpp": "^10.4.0",
-    "eslint": "^9.39.2",
-    "globals": "^17.1.0",
-    "jiti": "^2.6.1",
-    "prettier": "^3.8.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^20.19.43",
+    "bumpp": "^10.4.1",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0",
+    "jiti": "^2.7.0",
+    "prettier": "^3.9.10",
     "serialport": "^13.0.0",
-    "tsdown": "^0.2.17",
+    "tsdown": "^0.23.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.54.0",
-    "vitest": "^4.0.18"
+    "typescript-eslint": "^8.72.0",
+    "vitest": "^4.1.12"
   },
   "peerDependencies": {
     "serialport": "^13.0.0"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "prettier --write ./src/ && tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "clean": "rm -rf ./dist/",
+    "format": "prettier --write ./src/",
+    "lint": "eslint ."
   }
-}
+}

package/dist/SerialService.d.cts

@@ -1,99 +0,0 @@
-import { SerialPort } from 'serialport';
-import { EventEmitter } from 'events';
-import type { SerialStatus as SerialStatusType, SerialConfig } from './types.ts';
-import { SerialStatus } from './types.ts';
-import { QueueManager } from './core/QueueManager.ts';
-/**
- * Main service. Implements a robust state machine.
- * Extends EventEmitter to notify the rest of the app about changes.
- */
-export declare class SerialService extends EventEmitter {
-    protected port: SerialPort | null;
-    protected queue: QueueManager;
-    protected _status: SerialStatusType;
-    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 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 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;
-    /**
-     * Manually disconnects from the serial port.
-     * @returns A promise that resolves when the port is fully closed
-     */
-    disconnect(): Promise<void>;
-    /**
-     * 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;
-        timeout?: number;
-        waitResponse?: boolean;
-    }): Promise<void>;
-    /**
-     * 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>;
-    /**
-     * 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 the next connection attempt with a simple backoff strategy.
-     */
-    protected scheduleReconnect(): void;
-    /**
-     * Cleans up resources and listeners.
-     * Unregisters the port and removes all event listeners.
-     */
-    protected cleanup(): void;
-    /**
-     * Executes the connection handshake to verify device responsiveness.
-     * Sends a handshake command and waits for a pattern match in the response.
-     */
-    protected performHandshake(): void;
-    queueIsIdle(): boolean;
-    portIsOpen(): boolean;
-    getPortPath(): string | null;
-    getLastAlias(): string | null;
-}

package/dist/SerialService.d.ts

@@ -1,99 +0,0 @@
-import { SerialPort } from 'serialport';
-import { EventEmitter } from 'events';
-import type { SerialStatus as SerialStatusType, SerialConfig } from './types.ts';
-import { SerialStatus } from './types.ts';
-import { QueueManager } from './core/QueueManager.ts';
-/**
- * Main service. Implements a robust state machine.
- * Extends EventEmitter to notify the rest of the app about changes.
- */
-export declare class SerialService extends EventEmitter {
-    protected port: SerialPort | null;
-    protected queue: QueueManager;
-    protected _status: SerialStatusType;
-    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 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 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;
-    /**
-     * Manually disconnects from the serial port.
-     * @returns A promise that resolves when the port is fully closed
-     */
-    disconnect(): Promise<void>;
-    /**
-     * 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;
-        timeout?: number;
-        waitResponse?: boolean;
-    }): Promise<void>;
-    /**
-     * 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>;
-    /**
-     * 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 the next connection attempt with a simple backoff strategy.
-     */
-    protected scheduleReconnect(): void;
-    /**
-     * Cleans up resources and listeners.
-     * Unregisters the port and removes all event listeners.
-     */
-    protected cleanup(): void;
-    /**
-     * Executes the connection handshake to verify device responsiveness.
-     * Sends a handshake command and waits for a pattern match in the response.
-     */
-    protected performHandshake(): void;
-    queueIsIdle(): boolean;
-    portIsOpen(): boolean;
-    getPortPath(): string | null;
-    getLastAlias(): string | null;
-}

package/dist/core/PortRegistry.d.cts

@@ -1,32 +0,0 @@
-/**
- * Singleton that keeps track of which serial ports are in use
- * by this application. Prevents conflicts if multiple SerialServices
- * are instantiated for the same port.
- */
-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.
-     * @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 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

@@ -1,32 +0,0 @@
-/**
- * Singleton that keeps track of which serial ports are in use
- * by this application. Prevents conflicts if multiple SerialServices
- * are instantiated for the same port.
- */
-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.
-     * @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 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

@@ -1,15 +0,0 @@
-/**
- * Utility static class to find devices.
- * Solves the problem of "on which COM/tty is my Arduino?".
- */
-export declare class PortScanner {
-    /**
-     * 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

@@ -1,15 +0,0 @@
-/**
- * Utility static class to find devices.
- * Solves the problem of "on which COM/tty is my Arduino?".
- */
-export declare class PortScanner {
-    /**
-     * 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

@@ -1,68 +0,0 @@
-/**
- * QueueManager acts as an intermediate buffer.
- * It prevents serial port saturation and guarantees messages
- * leave in the order they arrived (FIFO).
- */
-export declare class QueueManager {
-    private queue;
-    private isProcessing;
-    private _currentAlias;
-    private waitingForResponse;
-    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 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;
-        timeout?: number;
-        waitResponse?: boolean;
-    }): Promise<void>;
-    /**
-     * 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 all pending items from the queue.
-     * Useful when handling abrupt disconnections.
-     * All pending items will be rejected with a disconnection error.
-     */
-    clear(): void;
-    /**
-     * 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;
-    /**
-     * 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;
-}