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

package/src/WebSerial.ts

@@ -4,7 +4,7 @@ import {
   WritableStream,
 } from 'web-streams-polyfill';
 import {DOMException} from './lib/dom-exception';
-import {Event, EventTarget} from './lib/event-target';
+import {Event, EventTarget, setEventParent} from './lib/event-target';
 import {createDeferredPromise} from './lib/promise';
 import type {
   ConnectEvent,
@@ -12,8 +12,8 @@ import type {
   ErrorEvent,
   OpenOptions,
   PortId,
-  UsbSerialModule,
-} from './UsbSerial';
+  SerialTransport,
+} from './transport';
 import {getUsbSerial} from './UsbSerial';
 
 /**
@@ -171,7 +171,7 @@ type PortInternals = {
   getVid(): number | undefined;
   getPid(): number | undefined;
   getPortNumber(): number;
-  getDeviceId(): number;
+  isForgotten(): boolean;
   setDeviceId(id: number): void;
   /** Reset to a closed, re-openable state after the device is physically lost. */
   handleDeviceLost(): void;
@@ -187,6 +187,7 @@ const kDefaultFlowControl: FlowControlType = 'none';
 const kAcceptableDataBits = [7, 8] as const;
 const kAcceptableStopBits = [1, 2] as const;
 const kAcceptableParity: ParityType[] = ['none', 'even', 'odd'];
+const kAcceptableFlowControl: FlowControlType[] = ['none', 'hardware'];
 
 function parityToNative(parity: ParityType): number {
   switch (parity) {
@@ -199,8 +200,15 @@ function parityToNative(parity: ParityType): number {
   }
 }
 
+const FLOW_CONTROL_NATIVE: Readonly<
+  Record<FlowControlType, 'RTS_CTS' | 'NONE'>
+> = {
+  none: 'NONE',
+  hardware: 'RTS_CTS',
+};
+
 function flowControlToNative(flowControl: FlowControlType): 'RTS_CTS' | 'NONE' {
-  return flowControl === 'hardware' ? 'RTS_CTS' : 'NONE';
+  return FLOW_CONTROL_NATIVE[flowControl];
 }
 
 /**
@@ -239,7 +247,7 @@ export class SerialPort extends EventTarget {
   #pendingClosePromise: ReturnType<typeof createDeferredPromise<void>> | null =
     null; // [[pendingClosePromise]] = null
 
-  #usb: UsbSerialModule;
+  #usb: SerialTransport;
   #deviceId: number;
   #portNumber: number;
   #usbVendorId?: number;
@@ -255,8 +263,34 @@ export class SerialPort extends EventTarget {
   #dataSubscription: {remove: () => void} | null = null;
   #errorSubscription: {remove: () => void} | null = null;
 
+  // The live stream controllers, captured in the readable/writable getters, so
+  // a device loss can error the in-flight read/write with a "NetworkError".
+  #readableController: ReadableStreamDefaultController<Uint8Array> | null =
+    null;
+  #writableController: WritableStreamDefaultController | null = null;
+  #forgetRequested: boolean = false;
+
+  #resetToClosedState(state: 'closed' | 'forgotten' = 'closed'): void {
+    this.#dataSubscription?.remove();
+    this.#errorSubscription?.remove();
+    this.#dataSubscription = null;
+    this.#errorSubscription = null;
+    this.#readableController = null;
+    this.#writableController = null;
+
+    this.#readable = null;
+    this.#writable = null;
+    this.#readFatal = false;
+    this.#writeFatal = false;
+    this.#pendingClosePromise = null;
+    this.#bufferSize = undefined;
+    this.#state = state;
+    this.#connected = false;
+    this.#forgetRequested = state === 'forgotten';
+  }
+
   constructor(
-    usb: UsbSerialModule,
+    usb: SerialTransport,
     deviceId: number,
     portNumber: number,
     usbVendorId: number,
@@ -275,7 +309,7 @@ export class SerialPort extends EventTarget {
       getVid: () => this.#usbVendorId,
       getPid: () => this.#usbProductId,
       getPortNumber: () => this.#portNumber,
-      getDeviceId: () => this.#deviceId,
+      isForgotten: () => this.#state === 'forgotten',
       setDeviceId: (id: number) => {
         this.#deviceId = id;
         serialPortDeviceIds.set(this, id);
@@ -291,33 +325,26 @@ export class SerialPort extends EventTarget {
    * After this, a later open() (e.g. when the device is re-attached) succeeds.
    */
   #handleDeviceLost(): void {
-    // Tear down read/write streams without invoking the OS on the dead device.
+    const wasForgotten = this.#state === 'forgotten';
+
+    // Reject any in-flight read/write with a "NetworkError" (per spec), erroring
+    // the stream controllers directly. We must NOT cancel()/abort() the streams:
+    // cancel() rejects on a reader-locked stream (leaving the read orphaned) and
+    // both would try to invoke the OS on the now-gone device.
+    const lost = new DOMException('The device has been lost.', 'NetworkError');
     if (this.#readable) {
       this.#readFatal = true;
       try {
-        // No active reader is required for cancel(); errors are non-fatal here.
-        this.#readable.cancel().catch(() => {});
+        this.#readableController?.error(lost);
       } catch {}
     }
     if (this.#writable) {
       this.#writeFatal = true;
       try {
-        this.#writable.abort().catch(() => {});
+        this.#writableController?.error(lost);
       } catch {}
     }
-    this.#dataSubscription?.remove();
-    this.#errorSubscription?.remove();
-    this.#dataSubscription = null;
-    this.#errorSubscription = null;
-
-    this.#readable = null;
-    this.#writable = null;
-    this.#readFatal = false;
-    this.#writeFatal = false;
-    this.#pendingClosePromise = null;
-    this.#bufferSize = undefined;
-    this.#state = 'closed';
-    this.#connected = false;
+    this.#resetToClosedState(wasForgotten ? 'forgotten' : 'closed');
 
     this.dispatchEvent(new Event('disconnect'));
   }
@@ -394,6 +421,7 @@ export class SerialPort extends EventTarget {
     const stream = new ReadableStream<Uint8Array>(
       {
         start(controller) {
+          self.#readableController = controller;
           self.#dataSubscription = self.#usb.onData((event: DataEvent) => {
             if (
               event.deviceId === deviceId &&
@@ -409,7 +437,15 @@ export class SerialPort extends EventTarget {
               event.portNumber === portNumber
             ) {
               self.#readFatal = true; // Set this.[[readFatal]] to true.
-              controller.error(new DOMException(event.error, 'NetworkError'));
+              // Surface the spec error type (BreakError, BufferOverrunError,
+              // FramingError, ParityError, …) when the transport reports one;
+              // fall back to NetworkError otherwise.
+              controller.error(
+                new DOMException(
+                  event.error,
+                  event.errorName ?? 'NetworkError',
+                ),
+              );
               self.#handleClosingReadableStream();
             }
           });
@@ -456,6 +492,9 @@ export class SerialPort extends EventTarget {
 
     const stream = new WritableStream<Uint8Array>(
       {
+        start(controller) {
+          self.#writableController = controller;
+        },
         async write(chunk) {
           try {
             await self.#usb.write(deviceId, portNumber, Array.from(chunk));
@@ -541,7 +580,7 @@ export class SerialPort extends EventTarget {
 
     // 3. If options["baudRate"] is 0, reject promise with a TypeError and
     // return promise.
-    if (options.baudRate === 0) {
+    if (!Number.isFinite(options.baudRate) || options.baudRate <= 0) {
       throw new TypeError('baudRate must be a positive, non-zero value.');
     }
 
@@ -562,7 +601,7 @@ export class SerialPort extends EventTarget {
     // 6. If options["bufferSize"] is 0, reject promise with a TypeError and
     // return promise.
     const bufferSize = options.bufferSize ?? kDefaultBufferSize;
-    if (bufferSize === 0) {
+    if (!Number.isFinite(bufferSize) || bufferSize <= 0) {
       throw new TypeError('bufferSize must be a positive, non-zero value.');
     }
 
@@ -574,6 +613,11 @@ export class SerialPort extends EventTarget {
     }
 
     const flowControl = options.flowControl ?? kDefaultFlowControl;
+    if (!kAcceptableFlowControl.includes(flowControl)) {
+      throw new TypeError(
+        `flowControl must be one of: ${kAcceptableFlowControl.join(', ')}.`,
+      );
+    }
 
     // 8. Set this.[[state]] to "opening".
     this.#state = 'opening';
@@ -599,19 +643,60 @@ export class SerialPort extends EventTarget {
       );
     }
 
-    if (flowControl !== 'none') {
-      await this.#usb.setFlowControl(
-        this.#deviceId,
-        this.#portNumber,
-        flowControlToNative(flowControl),
+    try {
+      if (flowControl !== 'none') {
+        await this.#usb.setFlowControl(
+          this.#deviceId,
+          this.#portNumber,
+          flowControlToNative(flowControl),
+        );
+      }
+
+      await this.#usb.startReading(this.#deviceId, this.#portNumber);
+    } catch (e) {
+      // If post-open setup fails (flow-control/read pump), best-effort close
+      // and reset local state so a subsequent open() can succeed cleanly.
+      try {
+        await this.#usb.close(this.#deviceId, this.#portNumber);
+      } catch {
+        // ignore
+      }
+
+      this.#resetToClosedState(this.#forgetRequested ? 'forgotten' : 'closed');
+
+      throw new DOMException(
+        `Failed to open serial port: ${(e as Error).message}`,
+        'NetworkError',
+      );
+    }
+
+    // Guard against lifecycle races (e.g. forget() called while open() is
+    // still awaiting native setup). Do not revive a forgotten/changed state.
+    if (this.#state !== 'opening') {
+      try {
+        await this.#usb.close(this.#deviceId, this.#portNumber);
+      } catch {
+        // ignore
+      }
+
+      if (this.#state === 'forgotten' || this.#state === 'forgetting') {
+        this.#resetToClosedState('forgotten');
+        throw new DOMException(
+          'The port has been forgotten while opening.',
+          'InvalidStateError',
+        );
+      }
+
+      this.#resetToClosedState();
+      throw new DOMException(
+        'Failed to open serial port: state changed while opening.',
+        'NetworkError',
       );
     }
 
     this.#state = 'opened'; // 9.3. Set this.[[state]] to "opened".
     this.#bufferSize = bufferSize; // 9.4. Set this.[[bufferSize]] to options["bufferSize"].
 
-    await this.#usb.startReading(this.#deviceId, this.#portNumber);
-
     // When the port becomes logically connected:
     this.#connected = true; // 2. Set port.[[connected]] to true.
     // NOTE: the port-level "connect"/"disconnect" events represent physical
@@ -676,18 +761,10 @@ export class SerialPort extends EventTarget {
       // ignore
     }
 
-    this.#dataSubscription?.remove();
-    this.#errorSubscription?.remove();
-    this.#dataSubscription = null;
-    this.#errorSubscription = null;
-
-    this.#state = 'closed'; // 10.1.2. Set this.[[state]] to "closed".
-    this.#readFatal = false; // 10.1.3. Set this.[[readFatal]] and this.[[writeFatal]] to false.
-    this.#writeFatal = false; // 10.1.3. (continued)
-    this.#pendingClosePromise = null; // 10.1.4. Set this.[[pendingClosePromise]] to null.
-
-    // When the port is no longer logically connected:
-    this.#connected = false; // 2. Set port.[[connected]] to false.
+    // 10.1.2-10.1.4 and logical disconnect bookkeeping.
+    // If forget() was requested while close() was in flight, preserve
+    // forgotten semantics instead of reviving the port to "closed".
+    this.#resetToClosedState(this.#forgetRequested ? 'forgotten' : 'closed');
     // (No port-level "disconnect" dispatch here — that event signals physical
     // detach, fired by Serial from the native USB state events. See open().)
   }
@@ -698,6 +775,14 @@ export class SerialPort extends EventTarget {
   async forget(): Promise<void> {
     // The forget() method steps are:
 
+    this.#forgetRequested = true;
+
+    // Forgetting an open port must not leave active streams/native resources
+    // behind. Close first so the instance becomes cleanly unusable afterwards.
+    if (this.#state === 'opened') {
+      await this.close();
+    }
+
     // 2.1. Set this.[[state]] to "forgetting".
     this.#state = 'forgetting';
     // 2.2. Remove this from the sequence of serial ports on the system which
@@ -824,6 +909,17 @@ export class SerialPort extends EventTarget {
   #handleClosingReadableStream(): void {
     // To handle closing the readable stream perform the following steps:
 
+    // Drop the native data/error subscription tied to this readable. Without
+    // this a later readable (after cancel() + re-acquire) would coexist with the
+    // old subscription, which then enqueues into the cancelled controller and
+    // throws. close()/handleDeviceLost() also clear these; doing it here covers
+    // a standalone readable.cancel().
+    this.#dataSubscription?.remove();
+    this.#errorSubscription?.remove();
+    this.#dataSubscription = null;
+    this.#errorSubscription = null;
+    this.#readableController = null;
+
     // 1. Set this.[[readable]] to null.
     this.#readable = null;
 
@@ -840,6 +936,8 @@ export class SerialPort extends EventTarget {
   #handleClosingWritableStream(): void {
     // To handle closing the writable stream perform the following steps:
 
+    this.#writableController = null;
+
     // 1. Set this.[[writable]] to null.
     this.#writable = null;
 
@@ -860,9 +958,23 @@ export class Serial extends EventTarget {
     disconnect: null as ((event: Event) => void) | null,
   };
 
-  #usb: UsbSerialModule | null = null;
+  #usb: SerialTransport | null = null;
   #knownPorts: Map<string, SerialPort> = new Map();
   #initialized = false;
+  #injected: SerialTransport | null;
+
+  /**
+   * @param transport Optional transport override. When provided, this `Serial`
+   * talks to it instead of the global native module — the seam used by tests
+   * and the virtual-device harness (`new Serial(new VirtualSerialTransport())`).
+   * Omit it for the normal native-backed instance; the singleton `serial`
+   * export is created this way and can still be redirected globally via
+   * `setUsbSerial()`.
+   */
+  constructor(transport?: SerialTransport) {
+    super();
+    this.#injected = transport ?? null;
+  }
 
   /**
    * Subscribing to "connect"/"disconnect" must wire up the native USB state
@@ -880,42 +992,49 @@ export class Serial extends EventTarget {
    * Deferring native access out of the module-import path avoids touching the
    * TurboModule before the runtime is ready.
    */
-  #ensureInit(): UsbSerialModule | null {
+  #ensureInit(): SerialTransport | null {
     if (this.#initialized) return this.#usb;
     this.#initialized = true;
     try {
-      this.#usb = getUsbSerial();
+      this.#usb = this.#injected ?? getUsbSerial();
 
       // A USB device was attached. Android assigns a NEW deviceId on every
       // attach, so match previously-known ports of the same physical device by
       // VID/PID, update their deviceId, re-key them, and fire "connect" on the
       // same SerialPort instance (W3C spec model: the port is reused).
       this.#usb.onConnect((event: ConnectEvent) => {
-        let matched = false;
-        for (const [key, port] of [...this.#knownPorts.entries()]) {
-          const internals = portInternals.get(port);
-          if (!internals) continue;
-          if (
-            internals.getVid() === event.usbVendorId &&
-            internals.getPid() === event.usbProductId
-          ) {
-            internals.setDeviceId(event.deviceId);
-            const newKey = this.#portKey(
-              event.deviceId,
-              internals.getPortNumber(),
-            );
-            if (newKey !== key) {
-              this.#knownPorts.delete(key);
-              this.#knownPorts.set(newKey, port);
-            }
-            port.dispatchEvent(new Event('connect'));
-            matched = true;
-          }
+        // Native connect events expose VID/PID but not a stable unique
+        // identifier. To avoid mis-associating identical devices, remap only
+        // when there is exactly one disconnected candidate.
+        const candidates = Array.from(this.#knownPorts.entries()).filter(
+          ([, port]) => {
+            const internals = portInternals.get(port)!;
+            if (internals.getVid() !== event.usbVendorId) return false;
+            if (internals.getPid() !== event.usbProductId) return false;
+            if (internals.isForgotten()) return false;
+            return !port.connected;
+          },
+        );
+
+        if (candidates.length === 1) {
+          const [key, port] = candidates[0];
+          const internals = portInternals.get(port)!;
+          internals.setDeviceId(event.deviceId);
+          const newKey = this.#portKey(
+            event.deviceId,
+            internals.getPortNumber(),
+          );
+          this.#knownPorts.delete(key);
+          this.#knownPorts.set(newKey, port);
+          // Dispatched on the port; it bubbles to this Serial (event.target
+          // stays the port, per spec — see setEventParent below).
+          port.dispatchEvent(new Event('connect'));
+          return;
         }
+
+        // No known port matched (or matching is ambiguous): fire a Serial-level
+        // "connect" so listeners refresh; getPorts() surfaces the new port.
         this.dispatchEvent(new Event('connect'));
-        // If we matched no known port this is a brand-new device; getPorts()
-        // will surface it on the next refresh.
-        void matched;
       });
 
       // A USB device was detached. Reset the matching port(s) to a closed,
@@ -924,12 +1043,18 @@ export class Serial extends EventTarget {
       // dispatches "disconnect" on the port.
       this.#usb.onDisconnect((event: ConnectEvent) => {
         const prefix = `${event.deviceId}:`;
+        let matched = false;
         for (const [key, port] of [...this.#knownPorts.entries()]) {
           if (key.startsWith(prefix)) {
+            // handleDeviceLost() dispatches "disconnect" on the port, which
+            // bubbles here with event.target === the port (per spec).
             portInternals.get(port)?.handleDeviceLost();
+            matched = true;
           }
         }
-        this.dispatchEvent(new Event('disconnect'));
+        // No known port matched (e.g. a device never opened): fire a
+        // Serial-level "disconnect" so listeners can still refresh.
+        if (!matched) this.dispatchEvent(new Event('disconnect'));
       });
     } catch {
       this.#usb = null;
@@ -1007,11 +1132,18 @@ export class Serial extends EventTarget {
     } of portIds) {
       if (!hasPermission) continue;
       const key = this.#portKey(deviceId, portNumber);
-      if (!this.#knownPorts.has(key)) {
-        this.#knownPorts.set(
-          key,
-          new SerialPort(usb, deviceId, portNumber, usbVendorId, usbProductId),
+      const known = this.#knownPorts.get(key);
+      if (!known || portInternals.get(known)?.isForgotten()) {
+        const port = new SerialPort(
+          usb,
+          deviceId,
+          portNumber,
+          usbVendorId,
+          usbProductId,
         );
+        // The port's connect/disconnect events bubble to this Serial.
+        setEventParent(port, this);
+        this.#knownPorts.set(key, port);
       }
       ports.push(this.#knownPorts.get(key)!);
     }
@@ -1036,6 +1168,12 @@ export class Serial extends EventTarget {
       );
     }
 
+    if ((options.allowedBluetoothServiceClassIds?.length ?? 0) > 0) {
+      throw new TypeError(
+        'allowedBluetoothServiceClassIds is not supported in Android USB mode.',
+      );
+    }
+
     // 4. If options["filters"] is present, then for each filter in
     // options["filters"] run the following steps:
     if (options.filters) {
@@ -1083,17 +1221,18 @@ export class Serial extends EventTarget {
 
     // 5.6. Let port be a SerialPort representing the port chosen by the user.
     const key = `${portId.deviceId}:${portId.portNumber}`;
-    if (!this.#knownPorts.has(key)) {
-      this.#knownPorts.set(
-        key,
-        new SerialPort(
-          usb,
-          portId.deviceId,
-          portId.portNumber,
-          portId.usbVendorId,
-          portId.usbProductId,
-        ),
+    const known = this.#knownPorts.get(key);
+    if (!known || portInternals.get(known)?.isForgotten()) {
+      const port = new SerialPort(
+        usb,
+        portId.deviceId,
+        portId.portNumber,
+        portId.usbVendorId,
+        portId.usbProductId,
       );
+      // The port's connect/disconnect events bubble to this Serial.
+      setEventParent(port, this);
+      this.#knownPorts.set(key, port);
     }
 
     // 5.7. Resolve promise with port.

package/src/index.ts

@@ -1,7 +1,6 @@
-// Platform-resolved Web Serial API instance.
-// On React Native (Android) this is the USB-serial-backed polyfill; on web it
-// is the browser's native navigator.serial. (See serial.android.ts / serial.web.ts)
 export {default as serial} from './serial';
+export type {SerialTransport} from './transport';
+export {resetUsbSerial, setUsbSerial} from './UsbSerial';
 export type {
   SerialInputSignals,
   SerialOptions,
@@ -13,11 +12,7 @@ export type {
 // W3C Web Serial API classes
 export {Serial, SerialPort} from './WebSerial';
 
-// Lower-level access to the raw USB-serial TurboModule (Android only).
-// (Imported + re-exported rather than `export * as` so older Babel presets
-// without @babel/plugin-transform-export-namespace-from can consume the source.)
 import * as UsbSerial from './UsbSerial';
 
-// Web Serial API event/exception primitives used by the polyfill
 export {Event, EventTarget} from './lib/event-target';
 export {UsbSerial};