@technoculture/data-bridge 0.1.0

package/CMakeLists.txt

@@ -0,0 +1,57 @@
+cmake_minimum_required(VERSION 3.15)
+project(data_bridge_node)
+
+set(CMAKE_CXX_STANDARD 17)
+
+# Root of the data-bridge project
+get_filename_component(PROJECT_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../.." ABSOLUTE)
+
+# Include Node-API headers
+include_directories(${CMAKE_JS_INC})
+
+# Platform-specific serial implementation
+if(WIN32)
+    set(PLATFORM_SOURCES
+        ${PROJECT_ROOT}/src/transport/platform/windows/windows_serial.cpp
+    )
+else()
+    set(PLATFORM_SOURCES
+        ${PROJECT_ROOT}/src/transport/platform/linux/linux_serial.cpp
+    )
+endif()
+
+# Build core library sources directly
+set(CORE_SOURCES
+    ${PROJECT_ROOT}/src/protocol/crc16.cpp
+    ${PLATFORM_SOURCES}
+)
+
+# Build the native addon
+add_library(${PROJECT_NAME} SHARED
+    src/addon.cpp
+    src/serial_wrapper.cpp
+    ${CORE_SOURCES}
+    ${CMAKE_JS_SRC}
+)
+
+# Set properties for Node.js addon
+set_target_properties(${PROJECT_NAME} PROPERTIES 
+    PREFIX "" 
+    SUFFIX ".node"
+)
+
+# Include paths
+target_include_directories(${PROJECT_NAME} PRIVATE
+    ${PROJECT_ROOT}/include
+    ${CMAKE_JS_INC}
+)
+
+target_link_libraries(${PROJECT_NAME} PRIVATE
+    ${CMAKE_JS_LIB}
+)
+
+# Enable N-API version 8
+target_compile_definitions(${PROJECT_NAME} PRIVATE
+    NAPI_VERSION=8
+    NODE_ADDON_API_DISABLE_DEPRECATED
+)

package/README.md

@@ -0,0 +1,77 @@
+# @aspect-labs/data-bridge
+
+Guaranteed reliable serial communication for Node.js and Electron.
+
+## Installation
+
+```bash
+npm install @aspect-labs/data-bridge
+```
+
+Pre-built binaries are included for Windows and Linux (x64, arm64).
+
+## Usage
+
+```typescript
+import { DataBridge } from '@aspect-labs/data-bridge';
+
+// Open a serial port
+const bridge = await DataBridge.open('/dev/ttyUSB0', { baudRate: 115200 });
+
+// Receive data
+bridge.on('data', (data) => {
+  console.log('Received:', data.toString());
+});
+
+// Send with guaranteed delivery
+await bridge.send('Hello, World!');
+
+// Close when done
+await bridge.close();
+```
+
+## Features
+
+- **Guaranteed Delivery** — Every packet is acknowledged; lost packets are automatically retried
+- **Corruption Detection** — CRC32 checksum on every packet
+- **Large Message Support** — Automatic fragmentation and reassembly
+- **Electron Compatible** — Works in both main and renderer processes
+
+## API
+
+### `DataBridge.open(port, options?)`
+
+Opens a serial port with reliable communication enabled.
+
+- `port` — Port path (e.g., `/dev/ttyUSB0` on Linux, `COM3` on Windows)
+- `options.baudRate` — Baud rate (default: 115200)
+
+Returns: `Promise<DataBridge>`
+
+### `bridge.send(data)`
+
+Sends data with guaranteed delivery.
+
+- `data` — `Buffer` or `string` to send
+
+Returns: `Promise<void>` — Resolves when acknowledged
+
+### `bridge.on('data', callback)`
+
+Subscribe to received data.
+
+### `bridge.close()`
+
+Closes the serial port.
+
+## Building from Source
+
+```bash
+cd bindings/node
+npm install
+npm run build
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,148 @@
+import { EventEmitter } from 'events';
+
+/**
+ * ResilientDataBridge - Connection-resilient wrapper
+ *
+ * Guarantees message delivery across USB disconnections by:
+ * 1. Auto-reconnection with exponential backoff
+ * 2. Message queue for pending sends during disconnect
+ * 3. Automatic re-handshake and queue flush on reconnect
+ */
+
+interface ResilientOptions extends DataBridgeOptions {
+    /** Enable auto-reconnection (default: true) */
+    reconnect?: boolean;
+    /** Initial reconnect delay in ms (default: 1000) */
+    reconnectDelay?: number;
+    /** Maximum reconnect delay in ms (default: 30000) */
+    maxReconnectDelay?: number;
+    /** Maximum queue size before dropping old messages (default: 1000) */
+    maxQueueSize?: number;
+}
+interface ResilientEvents {
+    data: (data: Buffer) => void;
+    error: (error: Error) => void;
+    close: () => void;
+    disconnect: () => void;
+    reconnecting: (attempt: number, delay: number) => void;
+    reconnected: () => void;
+}
+declare class ResilientDataBridge extends EventEmitter {
+    private bridge;
+    private port;
+    private options;
+    private messageQueue;
+    private isConnected;
+    private isReconnecting;
+    private shouldReconnect;
+    private reconnectAttempt;
+    private reconnectTimeout;
+    private constructor();
+    /**
+     * Open a resilient serial connection.
+     *
+     * @param port - Serial port path
+     * @param options - Configuration including reconnection settings
+     */
+    static open(port: string, options?: ResilientOptions): Promise<ResilientDataBridge>;
+    private connect;
+    private handleDisconnect;
+    private scheduleReconnect;
+    /**
+     * Send data with guaranteed delivery.
+     *
+     * If disconnected, the message is queued and will be sent
+     * automatically when the connection is restored.
+     *
+     * @param data - Data to send
+     * @returns Promise that resolves when data is acknowledged
+     */
+    send(data: Buffer | string): Promise<void>;
+    private queueMessage;
+    private flushQueue;
+    /**
+     * Close the connection permanently.
+     * Rejects all pending queued messages.
+     */
+    close(): Promise<void>;
+    /** Current connection state */
+    get connected(): boolean;
+    /** Number of messages waiting in queue */
+    get queueLength(): number;
+    on<K extends keyof ResilientEvents>(event: K, listener: ResilientEvents[K]): this;
+    once<K extends keyof ResilientEvents>(event: K, listener: ResilientEvents[K]): this;
+    emit<K extends keyof ResilientEvents>(event: K, ...args: Parameters<ResilientEvents[K]>): boolean;
+}
+
+/**
+ * Data Bridge - Guaranteed Reliable Serial Communication
+ *
+ * TypeScript wrapper for the native Node-API addon.
+ * Provides a clean, async-friendly API for Electron applications.
+ */
+
+interface DataBridgeOptions {
+    baudRate?: number;
+}
+interface DataBridgeEvents {
+    data: (data: Buffer) => void;
+    error: (error: Error) => void;
+    close: () => void;
+}
+/**
+ * DataBridge provides guaranteed reliable serial communication.
+ *
+ * Features:
+ * - Automatic retransmission on packet loss
+ * - CRC32 integrity checking
+ * - COBS framing for robust delimitation
+ * - Fragmentation for large messages
+ *
+ * @example
+ * ```typescript
+ * const bridge = await DataBridge.open('/dev/ttyUSB0');
+ *
+ * bridge.on('data', (data) => {
+ *   console.log('Received:', data.toString());
+ * });
+ *
+ * await bridge.send('Hello, World!');
+ * await bridge.close();
+ * ```
+ */
+declare class DataBridge extends EventEmitter {
+    private native;
+    private _isOpen;
+    private constructor();
+    /**
+     * Open a serial port with guaranteed reliable communication.
+     *
+     * @param port - Serial port path (e.g., '/dev/ttyUSB0' or 'COM3')
+     * @param options - Configuration options
+     * @returns Promise resolving to a DataBridge instance
+     */
+    static open(port: string, options?: DataBridgeOptions): Promise<DataBridge>;
+    /**
+     * Send data with guaranteed delivery.
+     *
+     * The data will be fragmented if necessary, checksummed, and
+     * retransmitted until acknowledged by the receiver.
+     *
+     * @param data - Data to send (Buffer or string)
+     * @returns Promise resolving when data is acknowledged
+     */
+    send(data: Buffer | string): Promise<void>;
+    /**
+     * Close the serial port.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the port is currently open.
+     */
+    get isOpen(): boolean;
+    on<K extends keyof DataBridgeEvents>(event: K, listener: DataBridgeEvents[K]): this;
+    once<K extends keyof DataBridgeEvents>(event: K, listener: DataBridgeEvents[K]): this;
+    emit<K extends keyof DataBridgeEvents>(event: K, ...args: Parameters<DataBridgeEvents[K]>): boolean;
+}
+
+export { DataBridge, type DataBridgeEvents, type DataBridgeOptions, ResilientDataBridge, type ResilientEvents, type ResilientOptions, DataBridge as default };

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import { EventEmitter } from 'events';
+
+/**
+ * ResilientDataBridge - Connection-resilient wrapper
+ *
+ * Guarantees message delivery across USB disconnections by:
+ * 1. Auto-reconnection with exponential backoff
+ * 2. Message queue for pending sends during disconnect
+ * 3. Automatic re-handshake and queue flush on reconnect
+ */
+
+interface ResilientOptions extends DataBridgeOptions {
+    /** Enable auto-reconnection (default: true) */
+    reconnect?: boolean;
+    /** Initial reconnect delay in ms (default: 1000) */
+    reconnectDelay?: number;
+    /** Maximum reconnect delay in ms (default: 30000) */
+    maxReconnectDelay?: number;
+    /** Maximum queue size before dropping old messages (default: 1000) */
+    maxQueueSize?: number;
+}
+interface ResilientEvents {
+    data: (data: Buffer) => void;
+    error: (error: Error) => void;
+    close: () => void;
+    disconnect: () => void;
+    reconnecting: (attempt: number, delay: number) => void;
+    reconnected: () => void;
+}
+declare class ResilientDataBridge extends EventEmitter {
+    private bridge;
+    private port;
+    private options;
+    private messageQueue;
+    private isConnected;
+    private isReconnecting;
+    private shouldReconnect;
+    private reconnectAttempt;
+    private reconnectTimeout;
+    private constructor();
+    /**
+     * Open a resilient serial connection.
+     *
+     * @param port - Serial port path
+     * @param options - Configuration including reconnection settings
+     */
+    static open(port: string, options?: ResilientOptions): Promise<ResilientDataBridge>;
+    private connect;
+    private handleDisconnect;
+    private scheduleReconnect;
+    /**
+     * Send data with guaranteed delivery.
+     *
+     * If disconnected, the message is queued and will be sent
+     * automatically when the connection is restored.
+     *
+     * @param data - Data to send
+     * @returns Promise that resolves when data is acknowledged
+     */
+    send(data: Buffer | string): Promise<void>;
+    private queueMessage;
+    private flushQueue;
+    /**
+     * Close the connection permanently.
+     * Rejects all pending queued messages.
+     */
+    close(): Promise<void>;
+    /** Current connection state */
+    get connected(): boolean;
+    /** Number of messages waiting in queue */
+    get queueLength(): number;
+    on<K extends keyof ResilientEvents>(event: K, listener: ResilientEvents[K]): this;
+    once<K extends keyof ResilientEvents>(event: K, listener: ResilientEvents[K]): this;
+    emit<K extends keyof ResilientEvents>(event: K, ...args: Parameters<ResilientEvents[K]>): boolean;
+}
+
+/**
+ * Data Bridge - Guaranteed Reliable Serial Communication
+ *
+ * TypeScript wrapper for the native Node-API addon.
+ * Provides a clean, async-friendly API for Electron applications.
+ */
+
+interface DataBridgeOptions {
+    baudRate?: number;
+}
+interface DataBridgeEvents {
+    data: (data: Buffer) => void;
+    error: (error: Error) => void;
+    close: () => void;
+}
+/**
+ * DataBridge provides guaranteed reliable serial communication.
+ *
+ * Features:
+ * - Automatic retransmission on packet loss
+ * - CRC32 integrity checking
+ * - COBS framing for robust delimitation
+ * - Fragmentation for large messages
+ *
+ * @example
+ * ```typescript
+ * const bridge = await DataBridge.open('/dev/ttyUSB0');
+ *
+ * bridge.on('data', (data) => {
+ *   console.log('Received:', data.toString());
+ * });
+ *
+ * await bridge.send('Hello, World!');
+ * await bridge.close();
+ * ```
+ */
+declare class DataBridge extends EventEmitter {
+    private native;
+    private _isOpen;
+    private constructor();
+    /**
+     * Open a serial port with guaranteed reliable communication.
+     *
+     * @param port - Serial port path (e.g., '/dev/ttyUSB0' or 'COM3')
+     * @param options - Configuration options
+     * @returns Promise resolving to a DataBridge instance
+     */
+    static open(port: string, options?: DataBridgeOptions): Promise<DataBridge>;
+    /**
+     * Send data with guaranteed delivery.
+     *
+     * The data will be fragmented if necessary, checksummed, and
+     * retransmitted until acknowledged by the receiver.
+     *
+     * @param data - Data to send (Buffer or string)
+     * @returns Promise resolving when data is acknowledged
+     */
+    send(data: Buffer | string): Promise<void>;
+    /**
+     * Close the serial port.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the port is currently open.
+     */
+    get isOpen(): boolean;
+    on<K extends keyof DataBridgeEvents>(event: K, listener: DataBridgeEvents[K]): this;
+    once<K extends keyof DataBridgeEvents>(event: K, listener: DataBridgeEvents[K]): this;
+    emit<K extends keyof DataBridgeEvents>(event: K, ...args: Parameters<DataBridgeEvents[K]>): boolean;
+}
+
+export { DataBridge, type DataBridgeEvents, type DataBridgeOptions, ResilientDataBridge, type ResilientEvents, type ResilientOptions, DataBridge as default };