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

package/src/transport.ts

@@ -0,0 +1,200 @@
+/**
+ * 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.
+ */
+
+// UsbSerialPort.ControlLine enum
+export type ControlLine = 'RTS' | 'CTS' | 'DTR' | 'DSR' | 'CD' | 'RI';
+
+// UsbSerialPort.FlowControl enum
+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 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;
+};
+
+export const DEFAULT_OPEN_OPTIONS: Required<Omit<OpenOptions, 'baudRate'>> = {
+  dataBits: DataBits.EIGHT,
+  stopBits: StopBits.ONE,
+  parity: Parity.NONE,
+};
+
+/** 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 {
+  // Discovery & permission
+  findAllDrivers(): Promise<ReadonlyArray<PortId>>;
+  showPortPicker(
+    filter: ReadonlyArray<PortFilter>,
+    labels?: PortPickerLabels,
+  ): Promise<PortId>;
+  requestPermission(deviceId: number): Promise<boolean>;
+
+  // Lifecycle
+  open(
+    deviceId: number,
+    portNumber: number,
+    options: OpenOptions,
+  ): Promise<void>;
+  close(deviceId: number, portNumber: number): Promise<void>;
+  isOpen(deviceId: number, portNumber: number): boolean;
+
+  // I/O
+  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>;
+
+  // Parameters
+  setParameters(
+    deviceId: number,
+    portNumber: number,
+    options: OpenOptions,
+  ): Promise<void>;
+
+  // Control signals
+  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[]>;
+
+  // Flow control
+  setFlowControl(
+    deviceId: number,
+    portNumber: number,
+    flowControl: FlowControl,
+  ): Promise<void>;
+  getFlowControl(deviceId: number, portNumber: number): Promise<FlowControl>;
+  getSupportedFlowControl(
+    deviceId: number,
+    portNumber: number,
+  ): Promise<FlowControl[]>;
+
+  // Misc
+  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>;
+
+  // Event subscriptions
+  onData(listener: (event: DataEvent) => void): Subscription;
+  onError(listener: (event: ErrorEvent) => void): Subscription;
+  onConnect(listener: (event: ConnectEvent) => void): Subscription;
+  onDisconnect(listener: (event: ConnectEvent) => void): Subscription;
+}

package/babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: ['module:@react-native/babel-preset'],
-};

package/biome.json

@@ -1,35 +0,0 @@
-{
-  "$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git",
-    "useIgnoreFile": true
-  },
-  "files": {
-    "includes": ["src/**/*.{ts,tsx}"]
-  },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "space",
-    "indentWidth": 2,
-    "lineWidth": 80
-  },
-  "javascript": {
-    "formatter": {
-      "quoteStyle": "single",
-      "trailingCommas": "all",
-      "bracketSpacing": false,
-      "bracketSameLine": true,
-      "arrowParentheses": "asNeeded"
-    }
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true,
-      "style": {
-        "noNonNullAssertion": "off"
-      }
-    }
-  }
-}

package/example/.watchmanconfig

@@ -1 +0,0 @@
-{}

package/example/App.tsx

@@ -1,71 +0,0 @@
-import React from 'react';
-import {StatusBar, StyleSheet, View} from 'react-native';
-import type {SerialPort} from 'react-native-web-serial-api';
-import {ConnectScreen} from './src/screens/ConnectScreen';
-import {DevicesScreen} from './src/screens/DevicesScreen';
-import {TerminalScreen} from './src/screens/TerminalScreen';
-import {type ConnectionSettings, DEFAULT_SETTINGS} from './src/settings';
-import {colors} from './src/theme';
-
-type Screen = 'devices' | 'connect' | 'terminal';
-
-/**
- * A React Native clone of Kai Morich's SimpleUsbTerminal, built on the
- * react-native-web-serial-api Web Serial API. Runs on Android and (Chromium) web.
- */
-function App(): React.JSX.Element {
-  const [screen, setScreen] = React.useState<Screen>('devices');
-  const [port, setPort] = React.useState<SerialPort | null>(null);
-  const [settings, setSettings] =
-    React.useState<ConnectionSettings>(DEFAULT_SETTINGS);
-
-  // Devices -> Connect form
-  const selectPort = (p: SerialPort) => {
-    setPort(p);
-    setScreen('connect');
-  };
-
-  // Connect form -> Terminal
-  const startTerminal = (s: ConnectionSettings) => {
-    setSettings(s);
-    setScreen('terminal');
-  };
-
-  const backToDevices = () => {
-    setScreen('devices');
-    setPort(null);
-  };
-
-  const backToConnect = () => setScreen('connect');
-
-  return (
-    <View style={styles.root}>
-      <StatusBar
-        barStyle="light-content"
-        backgroundColor={colors.primaryDark}
-      />
-      {screen === 'terminal' && port ? (
-        <TerminalScreen
-          port={port}
-          settings={settings}
-          onBack={backToConnect}
-        />
-      ) : screen === 'connect' && port ? (
-        <ConnectScreen
-          port={port}
-          initial={settings}
-          onBack={backToDevices}
-          onConnect={startTerminal}
-        />
-      ) : (
-        <DevicesScreen onSelect={selectPort} />
-      )}
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  root: {flex: 1, backgroundColor: colors.background},
-});
-
-export default App;

package/example/__tests__/App.test.tsx

@@ -1,16 +0,0 @@
-/**
- * @format
- */
-
-// Note: import explicitly to use the types shipped with jest.
-import {expect, it} from '@jest/globals';
-import {render, screen, waitFor} from '@testing-library/react-native';
-import App from '../App';
-
-it('renders the devices screen', async () => {
-  render(<App />);
-  expect(screen.getByText('USB Devices')).toBeTruthy();
-  // DevicesScreen kicks off an async serial.getPorts() refresh on mount; let it
-  // settle so the state update is wrapped in act() (avoids a console warning).
-  await waitFor(() => expect(screen.queryByText('USB Devices')).toBeTruthy());
-});

package/example/__tests__/connectEvents.test.tsx

@@ -1,81 +0,0 @@
-/**
- * @format
- *
- * Verifies that subscribing to Serial "connect"/"disconnect" wires up the
- * native USB state listeners WITHOUT first calling getPorts()/requestPort(),
- * and that a native event (e.g. the "connect" emitted when USB permission is
- * granted) reaches the JS listener. This is what lets the example's device
- * list auto-refresh on attach / detach / permission-grant.
- */
-
-import {afterEach, beforeEach, expect, it, jest} from '@jest/globals';
-import {NativeModules} from 'react-native';
-
-// Capture the JS listeners registered against the native event emitter so the
-// test can drive them like the native side would.
-const nativeListeners: Record<string, ((event: unknown) => void)[]> = {};
-
-beforeEach(() => {
-  for (const k of Object.keys(nativeListeners)) {
-    delete nativeListeners[k];
-  }
-  (NativeModules as any).NativeUsbSerial = {
-    findAllDrivers: jest.fn(async () => []),
-    addListener: jest.fn(),
-    removeListeners: jest.fn(),
-  };
-});
-
-afterEach(() => {
-  // RCTDeviceEventEmitter is a global singleton across the RN copy; clear it so
-  // listeners from one test don't leak into the next.
-  const {DeviceEventEmitter} = require('react-native');
-  DeviceEventEmitter.removeAllListeners('connect');
-  DeviceEventEmitter.removeAllListeners('disconnect');
-});
-
-function freshSerial() {
-  let api: any;
-  jest.isolateModules(() => {
-    api = require('react-native-web-serial-api');
-  });
-  return new api.Serial();
-}
-
-// Emit a native device event the way the TurboModule does (via
-// RCTDeviceEventEmitter, which NativeEventEmitter listens on).
-function emitNative(event: 'connect' | 'disconnect', payload: unknown) {
-  const {DeviceEventEmitter} = require('react-native');
-  DeviceEventEmitter.emit(event, payload);
-}
-
-it('addEventListener("connect") receives native events without calling getPorts() first', () => {
-  const serial = freshSerial();
-  const onConnect = jest.fn();
-
-  // Subscribe only — no getPorts()/requestPort() beforehand.
-  serial.addEventListener('connect', onConnect);
-
-  // Native fires "connect" (e.g. attach or permission-grant).
-  emitNative('connect', {
-    deviceId: 7,
-    usbVendorId: 0x0403,
-    usbProductId: 0x6001,
-  });
-
-  expect(onConnect).toHaveBeenCalledTimes(1);
-});
-
-it('forwards native disconnect to Serial listeners', () => {
-  const serial = freshSerial();
-  const onDisconnect = jest.fn();
-  serial.addEventListener('disconnect', onDisconnect);
-
-  emitNative('disconnect', {
-    deviceId: 7,
-    usbVendorId: 0x0403,
-    usbProductId: 0x6001,
-  });
-
-  expect(onDisconnect).toHaveBeenCalledTimes(1);
-});

package/example/__tests__/getPorts.test.tsx

@@ -1,140 +0,0 @@
-/**
- * @format
- *
- * Android/native permission-model contract for the Web Serial polyfill.
- *
- * getPorts() enumerates every probed USB-serial port the app can currently
- * access through Android USB permission (PortId.hasPermission === true) —
- * whether that permission came from requestPort() or was granted natively
- * (e.g. the system "use by default for this device" attach dialog). Ports the
- * app cannot access yet are excluded.
- *
- * requestPort() is unchanged: it shows the native picker and resolves with the
- * chosen port; it does not consult getPorts()/hasPermission.
- */
-
-import {afterEach, beforeEach, describe, expect, it, jest} from '@jest/globals';
-import {NativeModules} from 'react-native';
-
-type FakePort = {
-  deviceId: number;
-  portNumber: number;
-  usbVendorId: number;
-  usbProductId: number;
-  hasPermission: boolean;
-};
-
-const findAllDrivers = jest.fn<() => Promise<FakePort[]>>();
-const showPortPicker = jest.fn<() => Promise<FakePort>>();
-
-// In jest, TurboModuleRegistry.get() falls back to NativeModules[name], so
-// registering a fake here lets the real library (Serial -> UsbSerialModule)
-// run against controlled data. addListener/removeListeners are required by
-// NativeEventEmitter.
-beforeEach(() => {
-  (NativeModules as any).NativeUsbSerial = {
-    findAllDrivers,
-    showPortPicker,
-    addListener: jest.fn(),
-    removeListeners: jest.fn(),
-  };
-});
-
-afterEach(() => {
-  findAllDrivers.mockReset();
-  showPortPicker.mockReset();
-});
-
-// Fresh module graph each time so the Serial singleton / known-port cache does
-// not leak between tests.
-function freshSerial() {
-  let api: any;
-  jest.isolateModules(() => {
-    api = require('react-native-web-serial-api');
-  });
-  return new api.Serial();
-}
-
-const ftdi: FakePort = {
-  deviceId: 1,
-  portNumber: 0,
-  usbVendorId: 0x0403,
-  usbProductId: 0x6001,
-  hasPermission: true,
-};
-const cp210xUnpermitted: FakePort = {
-  deviceId: 2,
-  portNumber: 0,
-  usbVendorId: 0x10c4,
-  usbProductId: 0xea60,
-  hasPermission: false,
-};
-
-describe('getPorts() Android permission filtering', () => {
-  it('includes a device granted natively (never via requestPort)', async () => {
-    findAllDrivers.mockResolvedValueOnce([ftdi]);
-    const ports = await freshSerial().getPorts();
-    expect(ports).toHaveLength(1);
-    expect(ports[0].getInfo()).toEqual({
-      usbVendorId: 0x0403,
-      usbProductId: 0x6001,
-    });
-  });
-
-  it('excludes a probed device the app has no permission for', async () => {
-    findAllDrivers.mockResolvedValueOnce([cp210xUnpermitted]);
-    const ports = await freshSerial().getPorts();
-    expect(ports).toHaveLength(0);
-  });
-
-  it('returns only the permitted subset when mixed', async () => {
-    findAllDrivers.mockResolvedValueOnce([ftdi, cp210xUnpermitted]);
-    const ports = await freshSerial().getPorts();
-    expect(ports).toHaveLength(1);
-    expect(ports[0].getInfo().usbVendorId).toBe(0x0403);
-  });
-
-  it('returns an empty list when nothing is permitted', async () => {
-    findAllDrivers.mockResolvedValueOnce([
-      cp210xUnpermitted,
-      {...cp210xUnpermitted, deviceId: 3},
-    ]);
-    expect(await freshSerial().getPorts()).toHaveLength(0);
-  });
-
-  it('lists each port of a multi-port permitted device', async () => {
-    findAllDrivers.mockResolvedValueOnce([
-      {...ftdi, portNumber: 0},
-      {...ftdi, portNumber: 1},
-    ]);
-    const ports = await freshSerial().getPorts();
-    expect(ports).toHaveLength(2);
-  });
-
-  it('returns the SAME SerialPort instance across repeated calls', async () => {
-    const serial = freshSerial();
-    findAllDrivers.mockResolvedValue([ftdi]);
-    const first = await serial.getPorts();
-    const second = await serial.getPorts();
-    expect(first[0]).toBe(second[0]); // cached, not re-created
-  });
-});
-
-describe('requestPort() is unaffected by the permission filter', () => {
-  it('resolves with the picked port even if getPorts would exclude it', async () => {
-    // getPorts sees nothing permitted...
-    findAllDrivers.mockResolvedValue([]);
-    // ...but the user picks a device through the native picker.
-    showPortPicker.mockResolvedValueOnce(ftdi);
-
-    const serial = freshSerial();
-    expect(await serial.getPorts()).toHaveLength(0);
-
-    const port = await serial.requestPort();
-    expect(port.getInfo()).toEqual({
-      usbVendorId: 0x0403,
-      usbProductId: 0x6001,
-    });
-    expect(showPortPicker).toHaveBeenCalledTimes(1);
-  });
-});

package/example/android/app/build.gradle

@@ -1,120 +0,0 @@
-apply plugin: "com.android.application"
-apply plugin: "org.jetbrains.kotlin.android"
-apply plugin: "com.facebook.react"
-
-/**
- * This is the configuration block to customize your React Native Android app.
- * By default you don't need to apply any configuration, just uncomment the lines you need.
- */
-react {
-    /* Folders */
-    //   The root of your project, i.e. where "package.json" lives. Default is '../..'
-    // root = file("../../")
-    //   The folder where the react-native NPM package is. Default is ../../node_modules/react-native
-    // reactNativeDir = file("../../node_modules/react-native")
-    //   The folder where the react-native Codegen package is. Default is ../../node_modules/@react-native/codegen
-    // codegenDir = file("../../node_modules/@react-native/codegen")
-    //   The cli.js file which is the React Native CLI entrypoint. Default is ../../node_modules/react-native/cli.js
-    // cliFile = file("../../node_modules/react-native/cli.js")
-
-    /* Variants */
-    //   The list of variants to that are debuggable. For those we're going to
-    //   skip the bundling of the JS bundle and the assets. By default is just 'debug'.
-    //   If you add flavors like lite, prod, etc. you'll have to list your debuggableVariants.
-    // debuggableVariants = ["liteDebug", "prodDebug"]
-
-    /* Bundling */
-    //   A list containing the node command and its flags. Default is just 'node'.
-    // nodeExecutableAndArgs = ["node"]
-    //
-    //   The command to run when bundling. By default is 'bundle'
-    // bundleCommand = "ram-bundle"
-    //
-    //   The path to the CLI configuration file. Default is empty.
-    // bundleConfig = file(../rn-cli.config.js)
-    //
-    //   The name of the generated asset file containing your JS bundle
-    // bundleAssetName = "MyApplication.android.bundle"
-    //
-    //   The entry file for bundle generation. Default is 'index.android.js' or 'index.js'
-    // entryFile = file("../js/MyApplication.android.js")
-    //
-    //   A list of extra flags to pass to the 'bundle' commands.
-    //   See https://github.com/react-native-community/cli/blob/main/docs/commands.md#bundle
-    // extraPackagerArgs = []
-
-    /* Hermes Commands */
-    //   The hermes compiler command to run. By default it is 'hermesc'
-    // hermesCommand = "$rootDir/my-custom-hermesc/bin/hermesc"
-    //
-    //   The list of flags to pass to the Hermes compiler. By default is "-O", "-output-source-map"
-    // hermesFlags = ["-O", "-output-source-map"]
-
-    /* Autolinking */
-    autolinkLibrariesWithApp()
-}
-
-/**
- * Set this to true to Run Proguard on Release builds to minify the Java bytecode.
- */
-def enableProguardInReleaseBuilds = false
-
-/**
- * The preferred build flavor of JavaScriptCore (JSC)
- *
- * For example, to use the international variant, you can use:
- * `def jscFlavor = 'org.webkit:android-jsc-intl:+'`
- *
- * The international variant includes ICU i18n library and necessary data
- * allowing to use e.g. `Date.toLocaleString` and `String.localeCompare` that
- * give correct results when using with locales other than en-US. Note that
- * this variant is about 6MiB larger per architecture than default.
- */
-def jscFlavor = 'org.webkit:android-jsc:+'
-
-android {
-    ndkVersion rootProject.ext.ndkVersion
-    buildToolsVersion rootProject.ext.buildToolsVersion
-    compileSdk rootProject.ext.compileSdkVersion
-
-    namespace "dev.react_native_web_serial_api.example"
-    defaultConfig {
-        applicationId "dev.react_native_web_serial_api.example"
-        minSdkVersion rootProject.ext.minSdkVersion
-        targetSdkVersion rootProject.ext.targetSdkVersion
-        versionCode 1
-        versionName "1.0"
-    }
-    signingConfigs {
-        debug {
-            storeFile file('debug.keystore')
-            storePassword 'android'
-            keyAlias 'androiddebugkey'
-            keyPassword 'android'
-        }
-    }
-    buildTypes {
-        debug {
-            signingConfig signingConfigs.debug
-        }
-        release {
-            // Caution! In production, you need to generate your own keystore file.
-            // see https://reactnative.dev/docs/signed-apk-android.
-            signingConfig signingConfigs.debug
-            minifyEnabled enableProguardInReleaseBuilds
-            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
-        }
-    }
-}
-
-dependencies {
-    // usb-serial-for-android is provided transitively by react-native-web-serial-api
-    // The version of react-native is set by the React Native Gradle Plugin
-    implementation("com.facebook.react:react-android")
-
-    if (hermesEnabled.toBoolean()) {
-        implementation("com.facebook.react:hermes-android")
-    } else {
-        implementation jscFlavor
-    }
-}

package/example/android/app/proguard-rules.pro

@@ -1,10 +0,0 @@
-# Add project specific ProGuard rules here.
-# By default, the flags in this file are appended to flags specified
-# in /usr/local/Cellar/android-sdk/24.3.3/tools/proguard/proguard-android.txt
-# You can edit the include path and order by changing the proguardFiles
-# directive in build.gradle.
-#
-# For more details, see
-#   http://developer.android.com/guide/developing/tools/proguard.html
-
-# Add any project specific keep options here: