TypeScript Guest API
Relevant source files
The following files were used as context for generating this wiki page:
The TypeScript Guest API provides a high-level, object-oriented interface for interacting with serial ports within a Tauri application. It abstracts complex Inter-Process Communication (IPC) calls into a manageable SerialPort class, allowing developers to discover, configure, open, and communicate with hardware devices using standard TypeScript patterns.
The API supports both synchronous and asynchronous operations, including event-driven data reception, binary and text-based transmission, and fine-grained control over hardware signals such as RTS and DTR. It is designed to work across desktop and mobile platforms by leveraging Tauri's plugin system.
Core Architecture and Data Flow
The Guest API serves as a wrapper around the Rust backend. When a method is called on the SerialPort instance, it translates the request into an IPC invoke call targeted at the serialplugin.
The diagram above illustrates the path from a TypeScript method call to the hardware interaction and the event-driven feedback loop for receiving data.
Sources: guest-js/index.ts, guest-js/listener-manager.ts
Configuration Interfaces
The API uses strongly-typed enums and interfaces to ensure valid port configurations.
| Enum / Interface | Description |
|---|---|
SerialPortOptions | Configuration object for path, baud rate, data bits, parity, etc. |
DataBits | Defines number of bits per character (Five, Six, Seven, Eight). |
Parity | Defines error checking bits (None, Odd, Even). |
StopBits | Defines number of stop bits (One, Two). |
FlowControl | Defines flow control method (None, Software, Hardware). |
Sources: guest-js/index.ts:1-55
The SerialPort Class
The SerialPort class is the primary entry point for all port operations. It maintains the state of the connection and manages listeners for data events.
Lifecycle Management
The lifecycle of a connection involves instantiation, opening, optional listening, and closing. Static methods are also provided for global management.
This sequence shows the typical flow from port creation to closing, including the asynchronous data reception mechanism.
Sources: guest-js/index.ts:100-300, tests/port-operations.test.ts:15-60
Key Methods
Data Transmission
write(value: string): Sends a string to the port. Returns the number of bytes written.writeBinary(value: Uint8Array | number[]): Sends raw binary data.read(options?: ReadOptions): Performs a one-time read of string data from the port.readBinary(options?: ReadOptions): Performs a one-time read of binary data.
Hardware Control
setRequestToSend(value: boolean): Controls the RTS signal.setDataTerminalReady(value: boolean): Controls the DTR signal.readClearToSend(): Returns the state of the CTS signal.readDataSetReady(): Returns the state of the DSR signal.
Sources: guest-js/index.ts:350-550, examples/serialport-test/src/components/SerialPortComponent.svelte:100-180
Event and Listener Management
The ListenerManager handles the registration and execution of callbacks when the backend emits serial data or status changes.
The ListenerManager Logic
The API maintains a mapping of port paths to active listeners. When startListening() is called, the backend begins polling the hardware. Data is then emitted via Tauri events, which the ListenerManager catches and routes to the appropriate callback registered via port.listen().
| Feature | Implementation Detail |
|---|---|
| Data Throttling | Listeners receive data based on the backend's buffer size and timeout settings. |
| Encoding | Default is utf-8, but can be set to ascii or other formats supported by TextDecoder. |
| Physical Disconnect | The disconnected(callback) method allows handling of unexpected hardware removal. |
Sources: guest-js/listener-manager.ts:1-50, guest-js/index.ts:250-280, tests/encoding-operations.test.ts:50-90
Static Port Discovery
The API provides static methods to query the system for available hardware without needing to instantiate a SerialPort first.
SerialPort.available_ports(): Returns an object containing information about all detected serial ports on the system.SerialPort.managed_ports(): Returns a list of ports currently managed by the plugin instance.SerialPort.closeAll(): A safety utility to close all open handles across the application.
Sources: guest-js/index.ts:60-95, examples/serialport-test/src/components/SerialPortComponent.svelte:20-45
Error Handling and Recovery
The TypeScript API validates arguments before invoking the backend to provide immediate feedback. For example, calling write() on a port that has not been opened will throw a descriptive error string rather than failing silently at the IPC layer.
Conclusion
The TypeScript Guest API provides a robust bridge between the web-based frontend and native serial hardware. By encapsulating IPC complexities and providing strong typing, it enables developers to build desktop-grade hardware interfaces with the ease of modern JavaScript/TypeScript. The architecture ensures that resource-heavy operations like continuous polling are handled by the native backend while keeping the frontend responsive through an event-driven listener model.