react-native-web-serial-api 0.0.3 → 0.1.0

package/lib/typescript/src/testing/virtual-serial.d.ts

@@ -0,0 +1,205 @@
+/**
+ * VirtualSerialTransport — an in-memory {@link SerialTransport} for tests and
+ * on-device demos.
+ *
+ * It implements the exact same interface the production `UsbSerialModule` does,
+ * but talks to simulated devices instead of real USB hardware. Because it has
+ * **no `react-native` dependency**, the same instance drives:
+ *
+ *   - Jest/Node unit tests and the conformance suite,
+ *   - the example app's "virtual device" mode on a real Android device, and
+ *   - the example app running in a browser (react-native-web).
+ *
+ * Inject it via `new Serial(transport)` or globally with `setUsbSerial(transport)`.
+ *
+ * @example
+ * const transport = new VirtualSerialTransport();
+ * transport.addDevice(new EchoDevice(), {hasPermission: true});
+ * const serial = new Serial(transport);
+ * const [port] = await serial.getPorts();
+ * await port.open({baudRate: 115200});
+ * // writes to port.writable now come back on port.readable (echo)
+ */
+import type { ConnectEvent, ControlLine, DataEvent, ErrorEvent, FlowControl, OpenOptions, PortFilter, PortId, PortPickerLabels, SerialTransport, Subscription } from '../transport';
+import type { SerialDevice } from './serial-device';
+/** Transport-side knobs when registering a {@link SerialDevice}. */
+export type VirtualDeviceOptions = {
+    /** Whether the app already holds USB permission. Defaults to false. */
+    hasPermission?: boolean;
+    /** Defaults to 0. A USB device may expose several ports. */
+    portNumber?: number;
+    /** Override the device's serialNumber for enumeration. */
+    serialNumber?: string;
+    /**
+     * Cross-wire output signals onto inputs the way a null-modem/loopback plug
+     * would (DTR→DSR+DCD, RTS→CTS) so getSignals() reflects setSignals().
+     * Defaults to true.
+     */
+    loopbackSignals?: boolean;
+    /**
+     * When the port is opened with hardware (RTS/CTS) flow control, the device
+     * de-asserts CTS once this many bytes have been written without the receiver
+     * draining — modelling a full receive buffer. Defaults to 256.
+     */
+    flowControlThreshold?: number;
+};
+export type VirtualSerialOptions = {
+    /** Devices to register on construction (same as calling addDevice). */
+    devices?: SerialDevice[];
+    /**
+     * Delay (ms) applied to async operations and to inbound data delivery.
+     * 0 (default) resolves on a microtask — deterministic for Jest. A small
+     * positive value makes streaming feel realistic on a device.
+     */
+    latencyMs?: number;
+    /**
+     * Whether showPortPicker() grants USB permission to the chosen device,
+     * mirroring the real Android picker. Defaults to true.
+     */
+    autoGrantPermission?: boolean;
+    /**
+     * If set, inbound data larger than this is delivered as several `onData`
+     * events of at most this many bytes — modelling how a real serial port hands
+     * data up in chunks. 0/undefined delivers each write's reply in one event.
+     */
+    chunkSize?: number;
+};
+/** Operations whose next invocation can be made to fail (error injection). */
+export type FailableOp = 'open' | 'close' | 'write' | 'startReading' | 'stopReading' | 'setSignals' | 'getSignals';
+type OutputSignals = {
+    dtr: boolean;
+    rts: boolean;
+    brk: boolean;
+};
+type InputSignals = {
+    dcd: boolean;
+    cts: boolean;
+    ri: boolean;
+    dsr: boolean;
+};
+/**
+ * A simulated USB-serial device. Returned by {@link VirtualSerialTransport.addDevice}.
+ * The mutable fields and the helper methods let a test or demo drive the device
+ * the way physical hardware (and a human plugging cables) otherwise would.
+ */
+export declare class VirtualDevice {
+    #private;
+    readonly usbVendorId: number;
+    readonly usbProductId: number;
+    readonly portNumber: number;
+    serialNumber: string;
+    /** Reassigned on every (re)attach, mirroring Android's behaviour. */
+    deviceId: number;
+    attached: boolean;
+    hasPermission: boolean;
+    isOpen: boolean;
+    reading: boolean;
+    /** The hosted behaviour. */
+    readonly serialDevice: SerialDevice;
+    loopbackSignals: boolean;
+    flowControl: FlowControl;
+    flowControlThreshold: number;
+    openOptions: Required<OpenOptions> | null;
+    /**
+     * When non-null, the device delivers at most this many bytes before raising a
+     * `BufferOverrunError` — models a fixed-size receive buffer overflowing.
+     */
+    overrunLimit: number | null;
+    _rxDelivered: number;
+    _overran: boolean;
+    _hwWritten: number;
+    readonly output: OutputSignals;
+    readonly input: InputSignals;
+    /** Every byte frame the host has written to this device, in order. */
+    readonly written: number[][];
+    constructor(transport: VirtualSerialTransport, deviceId: number, device: SerialDevice, options: VirtualDeviceOptions);
+    /** Push inbound bytes to the host as if the device sent them unprompted. */
+    push(bytes: number[] | Uint8Array): void;
+    /**
+     * Raise a read error on the host's readable stream. `name` is the W3C error
+     * type (e.g. "BreakError", "BufferOverrunError"); the current polyfill ignores
+     * it and surfaces "NetworkError" regardless (a documented spec gap).
+     */
+    emitError(message: string, name?: string): void;
+    /**
+     * Make the device deliver at most `bytes` bytes and then raise a
+     * `BufferOverrunError`, modelling a receive buffer of that size overflowing.
+     */
+    overrunAfter(bytes: number): this;
+    /** Make the next call to `op` reject once (error injection). */
+    failNext(op: FailableOp): this;
+    /** @internal consume a queued failure for `op`. */
+    _consumeFail(op: FailableOp): boolean;
+    /** Directly set device-asserted input signals (DCD/CTS/RI/DSR). */
+    setInputSignals(signals: Partial<InputSignals>): void;
+    /** Physically attach (or re-attach) this device — fires "connect". */
+    attach(): void;
+    /** Physically detach this device — fires "disconnect". */
+    detach(): void;
+    /** Simulate an unplug while open: errors the open stream, then disconnects. */
+    loseDevice(): void;
+}
+type Listener<E> = (event: E) => void;
+/**
+ * In-memory transport backing one or more {@link VirtualDevice}s.
+ */
+export declare class VirtualSerialTransport implements SerialTransport {
+    #private;
+    constructor(options?: VirtualSerialOptions);
+    /** All devices known to the transport (attached or not). */
+    get devices(): readonly VirtualDevice[];
+    /**
+     * Register a {@link SerialDevice}. It starts attached but does not fire
+     * "connect"; its identity (usbVendorId/usbProductId/serialNumber) is read from
+     * the device, and `options` carries the transport-side knobs.
+     */
+    addDevice(serialDevice: SerialDevice, options?: VirtualDeviceOptions): VirtualDevice;
+    /** Remove a device entirely; detaches it first if attached. */
+    removeDevice(device: VirtualDevice): void;
+    /** (Re)attach a device, assigning it a fresh deviceId, and fire "connect". */
+    attach(device: VirtualDevice): void;
+    /** Detach a device and fire "disconnect"; any open port becomes closed. */
+    detach(device: VirtualDevice): void;
+    /** Simulate an unplug while open: error the stream first, then disconnect. */
+    loseDevice(device: VirtualDevice): void;
+    /** Script the next showPortPicker() resolution (a device or a predicate). */
+    selectNextPort(target: VirtualDevice | ((d: VirtualDevice) => boolean)): void;
+    /** Make the next showPortPicker() reject (user cancelled / no port). */
+    rejectNextPortPicker(): void;
+    /** @internal deliver inbound bytes to the host's readable stream. */
+    _deliver(device: VirtualDevice, data: number[]): void;
+    /** @internal raise a read error for a device's open port. */
+    _error(device: VirtualDevice, message: string, name?: string): void;
+    findAllDrivers(): Promise<ReadonlyArray<PortId>>;
+    showPortPicker(filter: ReadonlyArray<PortFilter>, _labels?: PortPickerLabels): Promise<PortId>;
+    requestPermission(deviceId: number): Promise<boolean>;
+    open(deviceId: number, portNumber: number, options: OpenOptions): Promise<void>;
+    close(deviceId: number, portNumber: number): Promise<void>;
+    isOpen(deviceId: number, portNumber: number): boolean;
+    write(deviceId: number, portNumber: number, data: number[], _timeout?: number): Promise<void>;
+    startReading(deviceId: number, portNumber: number): Promise<void>;
+    stopReading(deviceId: number, portNumber: number): Promise<void>;
+    setParameters(deviceId: number, portNumber: number, options: OpenOptions): Promise<void>;
+    setDTR(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    setRTS(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    setBreak(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    getDTR(deviceId: number, portNumber: number): Promise<boolean>;
+    getRTS(deviceId: number, portNumber: number): Promise<boolean>;
+    getCD(deviceId: number, portNumber: number): Promise<boolean>;
+    getCTS(deviceId: number, portNumber: number): Promise<boolean>;
+    getRI(deviceId: number, portNumber: number): Promise<boolean>;
+    getDSR(deviceId: number, portNumber: number): Promise<boolean>;
+    getControlLines(deviceId: number, portNumber: number): Promise<ControlLine[]>;
+    getSupportedControlLines(_deviceId: number, _portNumber: number): Promise<ControlLine[]>;
+    setFlowControl(deviceId: number, portNumber: number, flowControl: FlowControl): Promise<void>;
+    getFlowControl(deviceId: number, portNumber: number): Promise<FlowControl>;
+    getSupportedFlowControl(_deviceId: number, _portNumber: number): Promise<FlowControl[]>;
+    purgeHwBuffers(_deviceId: number, _portNumber: number, _purgeWriteBuffers: boolean, _purgeReadBuffers: boolean): Promise<void>;
+    getSerial(deviceId: number, portNumber: number): Promise<string>;
+    onData(listener: Listener<DataEvent>): Subscription;
+    onError(listener: Listener<ErrorEvent>): Subscription;
+    onConnect(listener: Listener<ConnectEvent>): Subscription;
+    onDisconnect(listener: Listener<ConnectEvent>): Subscription;
+}
+export {};
+//# sourceMappingURL=virtual-serial.d.ts.map

package/lib/typescript/src/testing/virtual-serial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-serial.d.ts","sourceRoot":"","sources":["../../../../src/testing/virtual-serial.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/transport.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Hardware-transport seam for the Web Serial polyfill.
+ *
+ * `SerialTransport` is the single interface that the `Serial`/`SerialPort`
+ * classes depend on to talk to "the device". The production implementation
+ * (`UsbSerialModule`, backed by the `NativeUsbSerial` TurboModule — see
+ * {@link ./UsbSerial}) and the in-memory test/dev double
+ * (`VirtualSerialTransport` — see {@link ./testing/virtual-serial}) both
+ * implement it.
+ *
+ * This module is intentionally free of any `react-native` import. That is what
+ * lets the virtual transport — and therefore the conformance suite built on top
+ * of it — run unchanged under Node/Jest, in a browser, and on a device.
+ */
+export type ControlLine = 'RTS' | 'CTS' | 'DTR' | 'DSR' | 'CD' | 'RI';
+export type FlowControl = 'NONE' | 'RTS_CTS' | 'DTR_DSR' | 'XON_XOFF' | 'XON_XOFF_INLINE';
+export type PortFilter = {
+    usbVendorId?: number;
+    usbProductId?: number;
+};
+export type PortPickerLabels = {
+    titleSelectPort?: string;
+    titleNoPortsAvailable?: string;
+    messageNoPortsAvailable?: string;
+};
+export type PortId = {
+    deviceId: number;
+    portNumber: number;
+    usbVendorId: number;
+    usbProductId: number;
+    /**
+     * Whether the app currently holds Android USB permission to access this
+     * device (via the system attach dialog or a prior permission request).
+     */
+    hasPermission: boolean;
+};
+export type DataEvent = {
+    deviceId: number;
+    portNumber: number;
+    data: number[];
+};
+export type ErrorEvent = {
+    deviceId: number;
+    portNumber: number;
+    error: string;
+    /**
+     * Optional spec error name (e.g. "BreakError", "BufferOverrunError",
+     * "FramingError", "ParityError") for a typed read error. When present the
+     * polyfill surfaces a DOMException of that name on the readable stream
+     * (otherwise it defaults to "NetworkError"); the WPT-derived spec tests in
+     * src/__tests__/conformance-suite.ts exercise this (BreakError,
+     * BufferOverrunError).
+     */
+    errorName?: string;
+};
+export type ConnectEvent = {
+    deviceId: number;
+    usbVendorId: number;
+    usbProductId: number;
+};
+export declare const Parity: {
+    readonly NONE: 0;
+    readonly ODD: 1;
+    readonly EVEN: 2;
+    readonly MARK: 3;
+    readonly SPACE: 4;
+};
+export declare const DataBits: {
+    readonly FIVE: 5;
+    readonly SIX: 6;
+    readonly SEVEN: 7;
+    readonly EIGHT: 8;
+};
+export declare const StopBits: {
+    readonly ONE: 1;
+    readonly ONE_FIVE: 3;
+    readonly TWO: 2;
+};
+export type OpenOptions = {
+    baudRate: number;
+    dataBits?: number;
+    stopBits?: number;
+    parity?: number;
+};
+export declare const DEFAULT_OPEN_OPTIONS: Required<Omit<OpenOptions, 'baudRate'>>;
+/** Handle returned by the `on*` subscription methods. */
+export type Subscription = {
+    remove: () => void;
+};
+/**
+ * The contract every serial transport must satisfy. It mirrors the JS-friendly
+ * surface of `UsbSerialModule` exactly, so `UsbSerialModule implements
+ * SerialTransport` is a faithful 1:1 and any conforming double (e.g.
+ * `VirtualSerialTransport`) is a drop-in replacement.
+ *
+ * Ports are addressed by the pair `(deviceId, portNumber)`. Inbound bytes,
+ * read errors and device attach/detach arrive through the `on*` subscriptions.
+ */
+export interface SerialTransport {
+    findAllDrivers(): Promise<ReadonlyArray<PortId>>;
+    showPortPicker(filter: ReadonlyArray<PortFilter>, labels?: PortPickerLabels): Promise<PortId>;
+    requestPermission(deviceId: number): Promise<boolean>;
+    open(deviceId: number, portNumber: number, options: OpenOptions): Promise<void>;
+    close(deviceId: number, portNumber: number): Promise<void>;
+    isOpen(deviceId: number, portNumber: number): boolean;
+    write(deviceId: number, portNumber: number, data: number[], timeout?: number): Promise<void>;
+    startReading(deviceId: number, portNumber: number): Promise<void>;
+    stopReading(deviceId: number, portNumber: number): Promise<void>;
+    setParameters(deviceId: number, portNumber: number, options: OpenOptions): Promise<void>;
+    setDTR(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    setRTS(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    getDTR(deviceId: number, portNumber: number): Promise<boolean>;
+    getRTS(deviceId: number, portNumber: number): Promise<boolean>;
+    getCD(deviceId: number, portNumber: number): Promise<boolean>;
+    getCTS(deviceId: number, portNumber: number): Promise<boolean>;
+    getDSR(deviceId: number, portNumber: number): Promise<boolean>;
+    getRI(deviceId: number, portNumber: number): Promise<boolean>;
+    getControlLines(deviceId: number, portNumber: number): Promise<ControlLine[]>;
+    getSupportedControlLines(deviceId: number, portNumber: number): Promise<ControlLine[]>;
+    setFlowControl(deviceId: number, portNumber: number, flowControl: FlowControl): Promise<void>;
+    getFlowControl(deviceId: number, portNumber: number): Promise<FlowControl>;
+    getSupportedFlowControl(deviceId: number, portNumber: number): Promise<FlowControl[]>;
+    setBreak(deviceId: number, portNumber: number, value: boolean): Promise<void>;
+    purgeHwBuffers(deviceId: number, portNumber: number, purgeWriteBuffers: boolean, purgeReadBuffers: boolean): Promise<void>;
+    getSerial(deviceId: number, portNumber: number): Promise<string>;
+    onData(listener: (event: DataEvent) => void): Subscription;
+    onError(listener: (event: ErrorEvent) => void): Subscription;
+    onConnect(listener: (event: ConnectEvent) => void): Subscription;
+    onDisconnect(listener: (event: ConnectEvent) => void): Subscription;
+}
+//# sourceMappingURL=transport.d.ts.map

package/lib/typescript/src/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,17 +1,49 @@
 {
   "name": "react-native-web-serial-api",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "W3C Web Serial API (navigator.serial) for React Native on Android, backed by a USB-serial TurboModule (built on mik3y/usb-serial-for-android).",
   "main": "lib/commonjs/index.js",
   "react-native": "lib/commonjs/index.js",
   "source": "src/index.ts",
   "types": "lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "react-native": "./lib/commonjs/index.js",
+      "default": "./lib/commonjs/index.js"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./lib/typescript/src/testing/index.d.ts",
+      "react-native": "./lib/commonjs/testing/index.js",
+      "default": "./lib/commonjs/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "react-native.config.js",
+    "TESTING.md",
+    "!android/build",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
   "scripts": {
     "prepare": "bob build",
     "clean": "node -e \"require('fs').rm(\\\"./lib\\\", { recursive: true }, () => {console.log(\\\"'lib' folder deleted\\\")})\"",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src",
-    "format": "biome check --write src"
+    "format": "biome check --write src",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:emulator:e2e": "npm --prefix example run e2e",
+    "test:host+emulator": "node ./node_modules/jest/bin/jest.js && npm --prefix example run e2e"
   },
   "keywords": [
     "react-native",
@@ -53,7 +85,11 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
     "@react-native/babel-preset": "0.85.3",
+    "@react-native/jest-preset": "0.85.3",
+    "@types/jest": "^29.5.14",
     "@types/react": "^19.2.6",
+    "babel-jest": "29.6.3",
+    "jest": "29.6.3",
     "react": "19.2.3",
     "react-native": "0.85.3",
     "react-native-builder-bob": "^0.41.0",

package/src/UsbSerial.ts

@@ -1,92 +1,39 @@
 import {NativeEventEmitter, NativeModules} from 'react-native';
 import NativeUsbSerial from './NativeUsbSerial';
-
-export type ControlLine = 'RTS' | 'CTS' | 'DTR' | 'DSR' | 'CD' | 'RI';
-export type FlowControl =
-  | 'NONE'
-  | 'RTS_CTS'
-  | 'DTR_DSR'
-  | 'XON_XOFF'
-  | 'XON_XOFF_INLINE';
-
-export type PortFilter = {
-  usbVendorId?: number;
-  usbProductId?: number;
-};
-
-export type PortPickerLabels = {
-  titleSelectPort?: string;
-  titleNoPortsAvailable?: string;
-  messageNoPortsAvailable?: string;
-};
-
-export type PortId = {
-  deviceId: number;
-  portNumber: number;
-  usbVendorId: number;
-  usbProductId: number;
-  /**
-   * Whether the app currently holds Android USB permission to access this
-   * device (via the system attach dialog or a prior permission request).
-   */
-  hasPermission: boolean;
-};
-
-export type DataEvent = {
-  deviceId: number;
-  portNumber: number;
-  data: number[];
-};
-
-export type ErrorEvent = {
-  deviceId: number;
-  portNumber: number;
-  error: string;
-};
-
-export type ConnectEvent = {
-  deviceId: number;
-  usbVendorId: number;
-  usbProductId: number;
-};
-
-export const Parity = {
-  NONE: 0,
-  ODD: 1,
-  EVEN: 2,
-  MARK: 3,
-  SPACE: 4,
-} as const;
-
-export const DataBits = {
-  FIVE: 5,
-  SIX: 6,
-  SEVEN: 7,
-  EIGHT: 8,
-} as const;
-
-export const StopBits = {
-  ONE: 1,
-  ONE_FIVE: 3,
-  TWO: 2,
-} as const;
-
-export type OpenOptions = {
-  baudRate: number;
-  dataBits?: number;
-  stopBits?: number;
-  parity?: number;
-};
-
-const DEFAULT_OPEN_OPTIONS: Required<Omit<OpenOptions, 'baudRate'>> = {
-  dataBits: DataBits.EIGHT,
-  stopBits: StopBits.ONE,
-  parity: Parity.NONE,
-};
-
-type Subscription = {remove: () => void};
-
-export class UsbSerialModule {
+import type {
+  ConnectEvent,
+  ControlLine,
+  DataEvent,
+  ErrorEvent,
+  FlowControl,
+  OpenOptions,
+  PortFilter,
+  PortId,
+  PortPickerLabels,
+  SerialTransport,
+  Subscription,
+} from './transport';
+import {DEFAULT_OPEN_OPTIONS} from './transport';
+
+// These types and enums were originally declared in this module and form part
+// of the public `UsbSerial` namespace. They now live in ./transport (a
+// react-native-free module the virtual transport also builds on) and are
+// re-exported here unchanged for backwards compatibility.
+export type {
+  ConnectEvent,
+  ControlLine,
+  DataEvent,
+  ErrorEvent,
+  FlowControl,
+  OpenOptions,
+  PortFilter,
+  PortId,
+  PortPickerLabels,
+  SerialTransport,
+} from './transport';
+export {DataBits, Parity, StopBits} from './transport';
+
+export class UsbSerialModule implements SerialTransport {
   private readonly native: NonNullable<typeof NativeUsbSerial>;
   private readonly emitter: NativeEventEmitter;
 
@@ -300,11 +247,39 @@ export class UsbSerialModule {
   }
 }
 
-let instance: UsbSerialModule | null = null;
-
-export function getUsbSerial(): UsbSerialModule {
+let instance: SerialTransport | null = null;
+let override: SerialTransport | null = null;
+
+/**
+ * Resolve the active serial transport. Returns the override set via
+ * {@link setUsbSerial} if present (used by tests and by the example's on-device
+ * "virtual device" mode); otherwise lazily constructs the real native-backed
+ * {@link UsbSerialModule}.
+ */
+export function getUsbSerial(): SerialTransport {
+  if (override) return override;
   if (!instance) {
     instance = new UsbSerialModule();
   }
   return instance;
 }
+
+/**
+ * Override the transport returned by {@link getUsbSerial}. Pass a
+ * {@link SerialTransport} (e.g. a `VirtualSerialTransport`) to make the
+ * singleton `serial` instance — and any `new Serial()` created without an
+ * explicit transport — talk to it instead of real hardware. Pass `null` to
+ * clear the override.
+ *
+ * Inject before the first `getPorts()` / `requestPort()` / `addEventListener()`
+ * call so the lazy initialisation in `Serial` picks it up.
+ */
+export function setUsbSerial(transport: SerialTransport | null): void {
+  override = transport;
+}
+
+/** Clear any override and drop the cached native instance (test teardown). */
+export function resetUsbSerial(): void {
+  override = null;
+  instance = null;
+}