@technoculture/data-bridge 0.1.0

package/lib/index.ts

@@ -0,0 +1,171 @@
+/**
+ * Data Bridge - Guaranteed Reliable Serial Communication
+ * 
+ * TypeScript wrapper for the native Node-API addon.
+ * Provides a clean, async-friendly API for Electron applications.
+ */
+
+import { EventEmitter } from 'events';
+import path from 'path';
+
+// Load native addon - works in both ESM and CJS
+let addon: NativeAddon;
+
+function loadAddon (): NativeAddon {
+  const possiblePaths = [
+    // Prebuilt binaries
+    `../prebuilds/${process.platform}-${process.arch}/data_bridge_node.node`,
+    // Local build
+    '../build/Release/data_bridge_node.node',
+  ];
+
+  for (const p of possiblePaths)
+  {
+    try
+    {
+      // Use require for native addons (works in both ESM and CJS)
+      return require(path.join(__dirname, p));
+    } catch
+    {
+      continue;
+    }
+  }
+
+  throw new Error('Failed to load native addon. Run `npm run build` first.');
+}
+
+addon = loadAddon();
+
+interface NativeAddon {
+  DataBridge: new () => NativeDataBridge;
+}
+
+interface NativeDataBridge {
+  open (port: string, baud: number, callback?: (data: Buffer) => void): Promise<boolean>;
+  send (data: Buffer | string): Promise<number>;
+  close (): boolean;
+  isOpen (): boolean;
+}
+
+export interface DataBridgeOptions {
+  baudRate?: number;
+}
+
+export 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();
+ * ```
+ */
+export class DataBridge extends EventEmitter {
+  private native: NativeDataBridge;
+  private _isOpen = false;
+
+  private constructor() {
+    super();
+    this.native = new addon.DataBridge();
+  }
+
+  /**
+   * 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 async open (port: string, options: DataBridgeOptions = {}): Promise<DataBridge> {
+    const instance = new DataBridge();
+    const baud = options.baudRate ?? 115200;
+
+    const onData = (data: Buffer) => {
+      instance.emit('data', data);
+    };
+
+    try
+    {
+      await instance.native.open(port, baud, onData);
+      instance._isOpen = true;
+      return instance;
+    } catch (err)
+    {
+      throw new Error(`Failed to open ${port}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
+  /**
+   * 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
+   */
+  async send (data: Buffer | string): Promise<void> {
+    if (!this._isOpen)
+    {
+      throw new Error('Port not open');
+    }
+
+    const buffer = typeof data === 'string' ? Buffer.from(data) : data;
+    await this.native.send(buffer);
+  }
+
+  /**
+   * Close the serial port.
+   */
+  async close (): Promise<void> {
+    if (this._isOpen)
+    {
+      this.native.close();
+      this._isOpen = false;
+      this.emit('close');
+    }
+  }
+
+  /**
+   * Check if the port is currently open.
+   */
+  get isOpen (): boolean {
+    return this._isOpen && this.native.isOpen();
+  }
+
+  // Type-safe event emitter methods
+  on<K extends keyof DataBridgeEvents> (event: K, listener: DataBridgeEvents[K]): this {
+    return super.on(event, listener);
+  }
+
+  once<K extends keyof DataBridgeEvents> (event: K, listener: DataBridgeEvents[K]): this {
+    return super.once(event, listener);
+  }
+
+  emit<K extends keyof DataBridgeEvents> (event: K, ...args: Parameters<DataBridgeEvents[K]>): boolean {
+    return super.emit(event, ...args);
+  }
+}
+
+export default DataBridge;
+
+// Re-export resilient wrapper
+export { ResilientDataBridge, ResilientOptions, ResilientEvents } from './resilient';

package/lib/resilient.ts

@@ -0,0 +1,276 @@
+/**
+ * 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
+ */
+
+import { EventEmitter } from 'events';
+import { DataBridge, DataBridgeOptions } from './index';
+
+export 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;
+}
+
+export interface ResilientEvents {
+  data: (data: Buffer) => void;
+  error: (error: Error) => void;
+  close: () => void;
+  disconnect: () => void;
+  reconnecting: (attempt: number, delay: number) => void;
+  reconnected: () => void;
+}
+
+interface QueuedMessage {
+  data: Buffer;
+  resolve: () => void;
+  reject: (err: Error) => void;
+  timestamp: number;
+}
+
+export class ResilientDataBridge extends EventEmitter {
+  private bridge: DataBridge | null = null;
+  private port: string;
+  private options: Required<ResilientOptions>;
+  private messageQueue: QueuedMessage[] = [];
+  private isConnected = false;
+  private isReconnecting = false;
+  private shouldReconnect = true;
+  private reconnectAttempt = 0;
+  private reconnectTimeout: NodeJS.Timeout | null = null;
+
+  private constructor(port: string, options: ResilientOptions) {
+    super();
+    this.port = port;
+    this.options = {
+      baudRate: options.baudRate ?? 115200,
+      reconnect: options.reconnect ?? true,
+      reconnectDelay: options.reconnectDelay ?? 1000,
+      maxReconnectDelay: options.maxReconnectDelay ?? 30000,
+      maxQueueSize: options.maxQueueSize ?? 1000,
+    };
+  }
+
+  /**
+   * Open a resilient serial connection.
+   * 
+   * @param port - Serial port path
+   * @param options - Configuration including reconnection settings
+   */
+  static async open (port: string, options: ResilientOptions = {}): Promise<ResilientDataBridge> {
+    const instance = new ResilientDataBridge(port, options);
+    await instance.connect();
+    return instance;
+  }
+
+  private async connect (): Promise<void> {
+    try
+    {
+      this.bridge = await DataBridge.open(this.port, {
+        baudRate: this.options.baudRate,
+      });
+
+      this.isConnected = true;
+      this.reconnectAttempt = 0;
+
+      // Forward data events
+      this.bridge.on('data', (data) => {
+        this.emit('data', data);
+      });
+
+      // Handle errors and detect disconnection
+      this.bridge.on('error', (err) => {
+        this.emit('error', err);
+        this.handleDisconnect();
+      });
+
+      // If we're reconnecting, emit event and flush queue
+      if (this.isReconnecting)
+      {
+        this.isReconnecting = false;
+        this.emit('reconnected');
+        await this.flushQueue();
+      }
+    } catch (err)
+    {
+      this.isConnected = false;
+      if (this.shouldReconnect && this.options.reconnect)
+      {
+        this.scheduleReconnect();
+      } else
+      {
+        throw err;
+      }
+    }
+  }
+
+  private handleDisconnect (): void {
+    if (!this.isConnected) return;
+
+    this.isConnected = false;
+    this.bridge = null;
+    this.emit('disconnect');
+
+    if (this.shouldReconnect && this.options.reconnect)
+    {
+      this.scheduleReconnect();
+    }
+  }
+
+  private scheduleReconnect (): void {
+    if (this.reconnectTimeout) return;
+
+    this.isReconnecting = true;
+    this.reconnectAttempt++;
+
+    // Exponential backoff with jitter
+    const baseDelay = this.options.reconnectDelay;
+    const maxDelay = this.options.maxReconnectDelay;
+    const delay = Math.min(
+      baseDelay * Math.pow(2, this.reconnectAttempt - 1) + Math.random() * 1000,
+      maxDelay
+    );
+
+    this.emit('reconnecting', this.reconnectAttempt, delay);
+
+    this.reconnectTimeout = setTimeout(async () => {
+      this.reconnectTimeout = null;
+      try
+      {
+        await this.connect();
+      } catch
+      {
+        // connect() will schedule another attempt if needed
+      }
+    }, delay);
+  }
+
+  /**
+   * 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
+   */
+  async send (data: Buffer | string): Promise<void> {
+    const buffer = typeof data === 'string' ? Buffer.from(data) : data;
+
+    if (this.isConnected && this.bridge)
+    {
+      // Connected - send immediately
+      try
+      {
+        await this.bridge.send(buffer);
+      } catch (err)
+      {
+        // Send failed - queue it and handle disconnect
+        return this.queueMessage(buffer);
+      }
+    } else
+    {
+      // Disconnected - queue the message
+      return this.queueMessage(buffer);
+    }
+  }
+
+  private queueMessage (data: Buffer): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Enforce max queue size (drop oldest)
+      while (this.messageQueue.length >= this.options.maxQueueSize)
+      {
+        const dropped = this.messageQueue.shift();
+        dropped?.reject(new Error('Message dropped: queue overflow'));
+      }
+
+      this.messageQueue.push({
+        data,
+        resolve,
+        reject,
+        timestamp: Date.now(),
+      });
+    });
+  }
+
+  private async flushQueue (): Promise<void> {
+    while (this.messageQueue.length > 0 && this.isConnected && this.bridge)
+    {
+      const msg = this.messageQueue.shift()!;
+      try
+      {
+        await this.bridge.send(msg.data);
+        msg.resolve();
+      } catch (err)
+      {
+        // Put it back at the front and stop flushing
+        this.messageQueue.unshift(msg);
+        break;
+      }
+    }
+  }
+
+  /**
+   * Close the connection permanently.
+   * Rejects all pending queued messages.
+   */
+  async close (): Promise<void> {
+    this.shouldReconnect = false;
+
+    if (this.reconnectTimeout)
+    {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    // Reject all queued messages
+    for (const msg of this.messageQueue)
+    {
+      msg.reject(new Error('Connection closed'));
+    }
+    this.messageQueue = [];
+
+    if (this.bridge)
+    {
+      await this.bridge.close();
+      this.bridge = null;
+    }
+
+    this.isConnected = false;
+    this.emit('close');
+  }
+
+  /** Current connection state */
+  get connected (): boolean {
+    return this.isConnected;
+  }
+
+  /** Number of messages waiting in queue */
+  get queueLength (): number {
+    return this.messageQueue.length;
+  }
+
+  // Type-safe event emitter
+  on<K extends keyof ResilientEvents> (event: K, listener: ResilientEvents[K]): this {
+    return super.on(event, listener);
+  }
+
+  once<K extends keyof ResilientEvents> (event: K, listener: ResilientEvents[K]): this {
+    return super.once(event, listener);
+  }
+
+  emit<K extends keyof ResilientEvents> (event: K, ...args: Parameters<ResilientEvents[K]>): boolean {
+    return super.emit(event, ...args);
+  }
+}
+
+export default ResilientDataBridge;

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@technoculture/data-bridge",
+  "version": "0.1.0",
+  "description": "Guaranteed reliable serial communication for Node.js and Electron",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "install": "prebuild-install || cmake-js compile",
+    "build": "npm run build:native && npm run build:ts",
+    "build:native": "cmake-js compile",
+    "build:ts": "tsup lib/index.ts --format cjs,esm --dts",
+    "prebuild": "cmake-js compile -O prebuilds/$(node -p \"process.platform + '-' + process.arch\")",
+    "prepublishOnly": "npm run build:ts",
+    "test": "vitest run",
+    "clean": "cmake-js clean && rm -rf dist prebuilds"
+  },
+  "files": [
+    "dist",
+    "prebuilds",
+    "src",
+    "lib",
+    "CMakeLists.txt"
+  ],
+  "dependencies": {
+    "node-addon-api": "^7.0.0",
+    "prebuild-install": "^7.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "cmake-js": "^7.3.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "win32",
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64",
+    "ia32"
+  ],
+  "binary": {
+    "napi_versions": [
+      8
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aspect-labs/data-bridge"
+  },
+  "keywords": [
+    "serial",
+    "uart",
+    "reliable",
+    "medical",
+    "embedded",
+    "electron",
+    "napi"
+  ],
+  "license": "MIT"
+}

package/prebuilds/darwin-arm64/.ninja_log

@@ -0,0 +1,6 @@
+# ninja log v6
+1	42	1767813639052166764	CMakeFiles/data_bridge_node.dir/Users/satyamtiwary/Documents/Python-Things/data-bridge/src/protocol/crc16.cpp.o	44a8848073165fd4
+1	286	1767813639052016345	CMakeFiles/data_bridge_node.dir/src/serial_wrapper.cpp.o	9b7a8f38fa1f98b2
+1	301	1767813639052311933	CMakeFiles/data_bridge_node.dir/Users/satyamtiwary/Documents/Python-Things/data-bridge/src/transport/platform/linux/linux_serial.cpp.o	1a4595fea1e208f8
+1	698	1767813639051708840	CMakeFiles/data_bridge_node.dir/src/addon.cpp.o	7d74cb8705ae44b7
+698	745	1767813639749307606	Release/data_bridge_node.node	1305e389db74efac