@technoculture/safeserial 0.1.0

package/lib/native.ts

@@ -0,0 +1,108 @@
+import path from "path";
+
+// Load native addon
+function loadAddon(): any {
+  const possiblePaths = [
+    `../prebuilds/${process.platform}-${process.arch}/safeserial_node.node`,
+    "../build/Release/safeserial_node.node",
+  ];
+
+  for (const p of possiblePaths) {
+    try {
+      return require(path.join(__dirname, p));
+    } catch {
+      continue;
+    }
+  }
+  throw new Error("Failed to load native addon. Run `npm run build` first.");
+}
+
+const addon = loadAddon();
+
+export interface SerialPort {
+  open(port: string, baud: number, callback: (data: Buffer) => void): boolean;
+  write(data: Buffer): number;
+  close(): boolean;
+  isOpen(): boolean;
+}
+
+export const SerialPort: {
+  new (): SerialPort;
+} = addon.SerialPort;
+
+export interface NativeDataBridge {
+  open(port: string, baud?: number): boolean;
+  close(): boolean;
+  send(
+    data: Buffer | string,
+    ackTimeoutMs?: number,
+    maxRetries?: number,
+    fragmentSize?: number,
+  ): number;
+  isOpen(): boolean;
+  onData(callback: (data: Buffer) => void): void;
+}
+
+export const NativeDataBridge: {
+  new (): NativeDataBridge;
+} = addon.DataBridge;
+
+export interface NativeResilientDataBridge {
+  open(port: string): boolean;
+  close(): boolean;
+  send(data: Buffer | string): number;
+  isConnected(): boolean;
+  queueLength(): number;
+  onData(callback: (data: Buffer) => void): void;
+  onError(callback: (message: string) => void): void;
+  onDisconnect(callback: () => void): void;
+  onReconnecting(callback: (attempt: number, delay: number) => void): void;
+  onReconnected(callback: () => void): void;
+  onClose(callback: () => void): void;
+}
+
+export const NativeResilientDataBridge: {
+  new (options?: any): NativeResilientDataBridge;
+} = addon.ResilientDataBridge;
+
+export interface Frame {
+  valid: boolean;
+  header: {
+    type: number;
+    seq_id: number;
+    fragment_id: number;
+    total_frags: number;
+    payload_len: number;
+    crc32: number;
+  };
+  payload: Buffer;
+}
+
+export interface PacketHelper {
+  serialize(
+    type: number,
+    seq: number,
+    payload: string | Buffer,
+    frag_id?: number,
+    total_frags?: number,
+  ): Buffer;
+  deserialize(buffer: Buffer): { frame: Frame; remaining: Buffer };
+  TYPE_DATA: number;
+  TYPE_ACK: number;
+  TYPE_NACK: number;
+  TYPE_SYN: number;
+}
+
+export const Packet: PacketHelper = addon.Packet;
+
+export interface Reassembler {
+  processFragment(frame: Frame): boolean;
+  isComplete(frame: Frame): boolean;
+  getData(): Buffer;
+  isDuplicate(frame: Frame): boolean;
+  getBufferedSize(): number;
+}
+
+export const Reassembler: {
+  new (): Reassembler;
+} = addon.Reassembler;

package/lib/reliable.ts

@@ -0,0 +1,94 @@
+import { EventEmitter } from "events";
+import { NativeDataBridge } from "./native";
+
+export interface DataBridgeOptions {
+  baudRate?: number;
+  maxRetries?: number;
+  ackTimeoutMs?: number;
+  fragmentSize?: number;
+}
+
+/**
+ * ReliableDataBridge
+ *
+ * Thin wrapper around the native C++ DataBridge implementation.
+ */
+export class ReliableDataBridge extends EventEmitter {
+  private bridge: NativeDataBridge;
+  private isOpen_ = false;
+
+  // Config
+  private options: Required<DataBridgeOptions>;
+
+  constructor(options: DataBridgeOptions = {}) {
+    super();
+    this.bridge = new NativeDataBridge();
+
+    this.options = {
+      baudRate: options.baudRate ?? 115200,
+      maxRetries: options.maxRetries ?? 10,
+      ackTimeoutMs: options.ackTimeoutMs ?? 500,
+      fragmentSize: options.fragmentSize ?? 200,
+    };
+
+    this.bridge.onData((data) => {
+      this.emit("data", data);
+    });
+  }
+
+  static async open(
+    port: string,
+    baudOrOptions?: number | DataBridgeOptions,
+    cb?: (data: Buffer) => void,
+  ): Promise<ReliableDataBridge> {
+    let opts: DataBridgeOptions = {};
+    if (typeof baudOrOptions === "number") {
+      opts.baudRate = baudOrOptions;
+    } else if (baudOrOptions) {
+      opts = baudOrOptions;
+    }
+
+    const bridge = new ReliableDataBridge(opts);
+    if (cb) bridge.on("data", cb);
+
+    await bridge.open(port);
+    return bridge;
+  }
+
+  async open(port: string, baud?: number): Promise<boolean> {
+    if (this.isOpen_) return true;
+
+    // Backward compatibility: override baud from options if provided
+    const baudRate = baud ?? this.options.baudRate;
+
+    const success = this.bridge.open(port, baudRate);
+    if (!success) {
+      throw new Error(`Failed to open ${port}`);
+    }
+    this.isOpen_ = true;
+    return true;
+  }
+
+  async close(): Promise<void> {
+    if (this.isOpen_) {
+      this.bridge.close();
+      this.isOpen_ = false;
+      this.emit("close");
+    }
+  }
+
+  get isOpen(): boolean {
+    return this.isOpen_;
+  }
+
+  async send(data: string | Buffer): Promise<void> {
+    if (!this.isOpen_) throw new Error("Port not open");
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    this.bridge.send(
+      buf,
+      this.options.ackTimeoutMs,
+      this.options.maxRetries,
+      this.options.fragmentSize,
+    );
+  }
+}

package/lib/resilient.ts

@@ -0,0 +1,122 @@
+/**
+ * ResilientDataBridge - Connection-resilient wrapper
+ *
+ * Thin wrapper around the native C++ ResilientDataBridge implementation.
+ */
+
+import { EventEmitter } from "events";
+import { DataBridgeOptions } from "./reliable";
+import { NativeResilientDataBridge } from "./native";
+
+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;
+}
+
+export class ResilientDataBridge extends EventEmitter {
+  private bridge: NativeResilientDataBridge;
+  private port: string;
+  private options: ResilientOptions;
+
+  private constructor(port: string, options: ResilientOptions) {
+    super();
+    this.port = port;
+    this.options = options;
+
+    this.bridge = new NativeResilientDataBridge(options);
+    this.bridge.onData((data) => this.emit("data", data));
+    this.bridge.onError((message) => this.emit("error", new Error(message)));
+    this.bridge.onDisconnect(() => this.emit("disconnect"));
+    this.bridge.onReconnecting((attempt, delay) =>
+      this.emit("reconnecting", attempt, delay),
+    );
+    this.bridge.onReconnected(() => this.emit("reconnected"));
+    this.bridge.onClose(() => this.emit("close"));
+  }
+
+  /**
+   * 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.open();
+    return instance;
+  }
+
+  async open(): Promise<boolean> {
+    return this.bridge.open(this.port);
+  }
+
+  /**
+   * Send data with guaranteed delivery.
+   *
+   * @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;
+    this.bridge.send(buffer);
+  }
+
+  /**
+   * Close the connection permanently.
+   */
+  async close(): Promise<void> {
+    this.bridge.close();
+  }
+
+  /** Current connection state */
+  get connected(): boolean {
+    return this.bridge.isConnected();
+  }
+
+  /** Number of messages waiting in queue */
+  get queueLength(): number {
+    return this.bridge.queueLength();
+  }
+
+  // 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,78 @@
+{
+  "name": "@technoculture/safeserial",
+  "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": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "install": "node scripts/copy_deps.js && (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\")",
+    "prepack": "node scripts/copy_deps.js && npm run build:ts",
+    "prepublishOnly": "npm run build:ts",
+    "test": "VITE_CJS_IGNORE_WARNING=1 vitest run",
+    "clean": "cmake-js clean && rm -rf dist prebuilds deps"
+  },
+  "files": [
+    "dist",
+    "prebuilds/**/*.node",
+    "deps",
+    "src",
+    "lib",
+    "scripts",
+    "CMakeLists.txt"
+  ],
+  "dependencies": {
+    "node-addon-api": "^7.0.0",
+    "prebuild-install": "^7.1.1",
+    "cmake-js": "^7.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.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/technoculture/safeserial"
+  },
+  "keywords": [
+    "serial",
+    "uart",
+    "reliable",
+    "medical",
+    "embedded",
+    "electron",
+    "napi"
+  ],
+  "license": "MIT"
+}

package/scripts/copy_deps.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '../../..');
+const PKG_ROOT = path.resolve(__dirname, '..');
+const DEPS_DIR = path.join(PKG_ROOT, 'deps');
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  let entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (let entry of entries) {
+    let srcPath = path.join(src, entry.name);
+    let destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+console.log('[copy_deps] Bundling C++ core files...');
+
+// Clean deps
+if (fs.existsSync(DEPS_DIR)) {
+  fs.rmSync(DEPS_DIR, { recursive: true, force: true });
+}
+fs.mkdirSync(DEPS_DIR);
+
+// Copy src
+const srcDir = path.join(PROJECT_ROOT, 'src');
+const destSrc = path.join(DEPS_DIR, 'src');
+console.log(`Copying ${srcDir} -> ${destSrc}`);
+copyDir(srcDir, destSrc);
+
+// Copy include
+const incDir = path.join(PROJECT_ROOT, 'include');
+const destInc = path.join(DEPS_DIR, 'include');
+console.log(`Copying ${incDir} -> ${destInc}`);
+copyDir(incDir, destInc);
+
+console.log('[copy_deps] Done.');

package/scripts/receiver.js

@@ -0,0 +1,37 @@
+const { ResilientDataBridge } = require('../dist/index.js');
+
+async function main() {
+  const port = process.argv[2];
+
+  // We don't strictly need item count here for logic, but helpful for knowing when to stop logging?
+  // The python runner kills us, so we just log what we get.
+
+  if (!port) {
+    console.error("Usage: node receiver.js <port>");
+    process.exit(1);
+  }
+
+  console.log(`[RECEIVER] Connecting to ${port}...`);
+  const bridge = await ResilientDataBridge.open(port, {
+    baudRate: 115200,
+    reconnect: true
+  });
+
+  let receivedCount = 0;
+
+  bridge.on('data', (data) => {
+    const str = data.toString();
+    receivedCount++;
+    console.log(`[RECEIVER] Got: ${str} (Total: ${receivedCount})`);
+  });
+
+  console.log("[RECEIVER] Listening...");
+
+  // Keep alive until killed
+  await new Promise(() => { });
+}
+
+main().catch(err => {
+  console.error("[RECEIVER] Fatal:", err);
+  process.exit(1);
+});

package/scripts/sender.js

@@ -0,0 +1,48 @@
+const { ResilientDataBridge } = require('../dist/index.js');
+
+async function main() {
+  const port = process.argv[2];
+  const itemCount = parseInt(process.argv[3] || '20', 10);
+  const baudRate = 115200; // Match Chaos Monkey defaults
+
+  if (!port) {
+    console.error("Usage: node sender.js <port> [item_count]");
+    process.exit(1);
+  }
+
+  console.log(`[SENDER] Connecting to ${port}...`);
+  const bridge = await ResilientDataBridge.open(port, {
+    baudRate,
+    reconnect: true
+  });
+
+  console.log(`[SENDER] Starting transmission of ${itemCount} items...`);
+
+  for (let i = 0; i < itemCount; i++) {
+    const msg = `Packet-${i}`;
+    try {
+      await bridge.send(msg);
+      console.log(`[SENDER] Sent: ${msg}`);
+    } catch (err) {
+      console.error(`[SENDER] Error sending ${msg}:`, err);
+    }
+
+    // Small delay to prevent overwhelming the chaos monkey's internal buffer too fast 
+    // if we want to simulate realistic traffic, though the bridge handles backpressure.
+    await new Promise(r => setTimeout(r, 50));
+  }
+
+  // Give time for final ACKs
+  await new Promise(r => setTimeout(r, 2000));
+
+  console.log("[SENDER] TEST COMPLETE");
+
+  // Clean exit
+  await bridge.close();
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error("[SENDER] Fatal:", err);
+  process.exit(1);
+});