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

package/src/UsbSerial.ts

@@ -266,7 +266,7 @@ export function getUsbSerial(): SerialTransport {
 
 /**
  * Override the transport returned by {@link getUsbSerial}. Pass a
- * {@link SerialTransport} (e.g. a `VirtualSerialTransport`) to make the
+ * {@link SerialTransport} (e.g. an `InMemorySerialTransport`) 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.

package/src/WebSerial.ts

@@ -1,11 +1,11 @@
-import {
-  ByteLengthQueuingStrategy,
-  ReadableStream,
-  WritableStream,
-} from 'web-streams-polyfill';
 import {DOMException} from './lib/dom-exception';
 import {Event, EventTarget, setEventParent} from './lib/event-target';
 import {createDeferredPromise} from './lib/promise';
+import {
+  ByteLengthQueuingStrategyImpl as ByteLengthQueuingStrategy,
+  ReadableStreamImpl as ReadableStream,
+  WritableStreamImpl as WritableStream,
+} from './lib/web-streams';
 import type {
   ConnectEvent,
   DataEvent,
@@ -23,14 +23,14 @@ import {getUsbSerial} from './UsbSerial';
  * even - Data word plus parity bit has even parity.
  * odd - Data word plus parity bit has odd parity.
  */
-type ParityType = 'none' | 'even' | 'odd';
+export type Parity = 'none' | 'even' | 'odd';
 
 /**
  * @see https://wicg.github.io/serial/#dom-flowcontroltype
  * none - No flow control is enabled.
  * hardware - Hardware flow control using the RTS and CTS signals is enabled.
  */
-type FlowControlType = 'none' | 'hardware';
+type FlowControl = 'none' | 'hardware';
 
 /**
  * @see https://wicg.github.io/serial/#dom-serialoptions
@@ -60,7 +60,7 @@ export type SerialOptions = {
   /**
    * The parity mode.
    */
-  parity?: ParityType;
+  parity?: Parity;
   /**
    * A positive, non-zero value indicating the size of the read and write
    * buffers that should be created.
@@ -69,7 +69,7 @@ export type SerialOptions = {
   /**
    * The flow control mode.
    */
-  flowControl?: FlowControlType;
+  flowControl?: FlowControl;
 };
 
 /**
@@ -175,21 +175,23 @@ type PortInternals = {
   setDeviceId(id: number): void;
   /** Reset to a closed, re-openable state after the device is physically lost. */
   handleDeviceLost(): void;
+  /** Reset to a closed, re-openable state after a clean physical detach. */
+  handleDeviceDetached(): void;
 };
 const portInternals = new WeakMap<SerialPort, PortInternals>();
 
 const kDefaultDataBits = 8;
 const kDefaultStopBits = 1;
-const kDefaultParity: ParityType = 'none';
+const kDefaultParity: Parity = 'none';
 const kDefaultBufferSize = 255;
-const kDefaultFlowControl: FlowControlType = 'none';
+const kDefaultFlowControl: FlowControl = 'none';
 
 const kAcceptableDataBits = [7, 8] as const;
 const kAcceptableStopBits = [1, 2] as const;
-const kAcceptableParity: ParityType[] = ['none', 'even', 'odd'];
-const kAcceptableFlowControl: FlowControlType[] = ['none', 'hardware'];
+const kAcceptableParity: Parity[] = ['none', 'even', 'odd'];
+const kAcceptableFlowControl: FlowControl[] = ['none', 'hardware'];
 
-function parityToNative(parity: ParityType): number {
+function parityToNative(parity: Parity): number {
   switch (parity) {
     case 'odd':
       return 1;
@@ -200,17 +202,34 @@ function parityToNative(parity: ParityType): number {
   }
 }
 
-const FLOW_CONTROL_NATIVE: Readonly<
-  Record<FlowControlType, 'RTS_CTS' | 'NONE'>
-> = {
+const FLOW_CONTROL_NATIVE: Readonly<Record<FlowControl, 'RTS_CTS' | 'NONE'>> = {
   none: 'NONE',
   hardware: 'RTS_CTS',
 };
 
-function flowControlToNative(flowControl: FlowControlType): 'RTS_CTS' | 'NONE' {
+function flowControlToNative(flowControl: FlowControl): 'RTS_CTS' | 'NONE' {
   return FLOW_CONTROL_NATIVE[flowControl];
 }
 
+/**
+ * Normalise a writable chunk to a plain byte array. The Web Serial writable
+ * accepts any BufferSource — a bare `ArrayBuffer` or any `ArrayBufferView`
+ * (`DataView`, typed arrays, including views with a non-zero `byteOffset`). A
+ * naive `Array.from(chunk)` only works for the iterable typed arrays and
+ * silently yields `[]` for an `ArrayBuffer`/`DataView`, so handle each shape.
+ */
+function bufferSourceToBytes(chunk: ArrayBufferView | ArrayBuffer): number[] {
+  if (chunk instanceof Uint8Array) {
+    return Array.from(chunk);
+  }
+  if (ArrayBuffer.isView(chunk)) {
+    return Array.from(
+      new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength),
+    );
+  }
+  return Array.from(new Uint8Array(chunk as ArrayBuffer));
+}
+
 /**
  * Methods on this interface typically complete asynchronously, queuing work on
  * the serial port task source.
@@ -252,13 +271,8 @@ export class SerialPort extends EventTarget {
   #portNumber: number;
   #usbVendorId?: number;
   #usbProductId?: number;
-
-  // Tracks the current state of output signals for partial updates
-  #outputSignals: Required<SerialOutputSignals> = {
-    dataTerminalReady: false,
-    requestToSend: false,
-    break: false,
-  };
+  // Baud rate of the current open(), used to size the native write timeout.
+  #baudRate: number = 0;
 
   #dataSubscription: {remove: () => void} | null = null;
   #errorSubscription: {remove: () => void} | null = null;
@@ -284,11 +298,26 @@ export class SerialPort extends EventTarget {
     this.#writeFatal = false;
     this.#pendingClosePromise = null;
     this.#bufferSize = undefined;
+    this.#baudRate = 0;
     this.#state = state;
     this.#connected = false;
     this.#forgetRequested = state === 'forgotten';
   }
 
+  /**
+   * Compute a native write timeout (ms) large enough to actually drain `length`
+   * bytes at the negotiated baud rate. A fixed 2 s timeout spuriously fails
+   * large writes on slow links; this scales with the payload while keeping a 2 s
+   * floor. ~10 bits per byte (start + 8 data + stop) with a 2× safety margin.
+   */
+  #writeTimeoutFor(length: number): number {
+    const kMinTimeoutMs = 2000;
+    /* istanbul ignore next — baudRate is always > 0 when the port is open */
+    const baud = this.#baudRate > 0 ? this.#baudRate : 9600;
+    const estimatedMs = Math.ceil((length * 10 * 1000) / baud) * 2;
+    return Math.max(kMinTimeoutMs, estimatedMs);
+  }
+
   constructor(
     usb: SerialTransport,
     deviceId: number,
@@ -315,6 +344,7 @@ export class SerialPort extends EventTarget {
         serialPortDeviceIds.set(this, id);
       },
       handleDeviceLost: () => this.#handleDeviceLost(),
+      handleDeviceDetached: () => this.#handleDeviceDetached(),
     });
   }
 
@@ -349,6 +379,53 @@ export class SerialPort extends EventTarget {
     this.dispatchEvent(new Event('disconnect'));
   }
 
+  /**
+   * Reset this port to a closed, re-openable state after a clean physical
+   * detach. Unlike device loss, buffered readable bytes should still be
+   * observable before the stream ends.
+   */
+  #handleDeviceDetached(): void {
+    const wasForgotten = this.#state === 'forgotten';
+    const readable = this.#readable;
+    const writable = this.#writable;
+
+    // Keep the public event and state transition synchronous so existing
+    // callers observe the detach immediately, but defer the stream teardown by
+    // one microtask to let already-queued data drain first.
+    this.#state = wasForgotten ? 'forgotten' : 'closed';
+    this.#connected = false;
+    this.#readable = null;
+    this.#writable = null;
+    this.dispatchEvent(new Event('disconnect'));
+
+    queueMicrotask(() => {
+      // Close the readable stream so any bytes already queued can still be
+      // drained by the consumer before EOF.
+      try {
+        if (readable) this.#readableController?.close();
+      } catch {}
+
+      // A detached device can no longer accept writes, so reject any writable
+      // traffic and clear local state.
+      const lost = new DOMException(
+        'The device has been lost.',
+        'NetworkError',
+      );
+      if (writable) {
+        this.#writeFatal = true;
+        try {
+          this.#writableController?.error(lost);
+        } catch {}
+      }
+
+      // Mirror the stream-closing bookkeeping without treating this as a hard
+      // read fatal error.
+      this.#handleClosingReadableStream();
+      this.#handleClosingWritableStream();
+      this.#resetToClosedState(wasForgotten ? 'forgotten' : 'closed');
+    });
+  }
+
   /**
    * @see https://wicg.github.io/serial/#dom-serialport-onconnect
    */
@@ -427,7 +504,15 @@ export class SerialPort extends EventTarget {
               event.deviceId === deviceId &&
               event.portNumber === portNumber
             ) {
-              controller.enqueue(new Uint8Array(event.data));
+              try {
+                controller.enqueue(new Uint8Array(event.data));
+              } catch {
+                // The stream may already be closing/closed — e.g. a data event
+                // racing cancel()/close(), where the stream is closed but this
+                // subscription is not yet torn down. Dropping the chunk is
+                // correct (the consumer has stopped reading) and avoids throwing
+                // out of the transport's event-dispatch loop.
+              }
             }
           });
 
@@ -496,8 +581,14 @@ export class SerialPort extends EventTarget {
           self.#writableController = controller;
         },
         async write(chunk) {
+          const bytes = bufferSourceToBytes(chunk);
           try {
-            await self.#usb.write(deviceId, portNumber, Array.from(chunk));
+            await self.#usb.write(
+              deviceId,
+              portNumber,
+              bytes,
+              self.#writeTimeoutFor(bytes.length),
+            );
           } catch (e) {
             // If the port was disconnected, set this.[[writeFatal]] to true.
             self.#writeFatal = true;
@@ -696,6 +787,7 @@ export class SerialPort extends EventTarget {
 
     this.#state = 'opened'; // 9.3. Set this.[[state]] to "opened".
     this.#bufferSize = bufferSize; // 9.4. Set this.[[bufferSize]] to options["bufferSize"].
+    this.#baudRate = options.baudRate;
 
     // When the port becomes logically connected:
     this.#connected = true; // 2. Set port.[[connected]] to true.
@@ -703,6 +795,13 @@ export class SerialPort extends EventTarget {
     // device presence (attach/detach), dispatched by Serial from the native
     // USB state events — not logical open()/close(). So we do not dispatch them
     // here; that also avoids re-entrancy with auto-reconnect listeners.
+
+    // Materialise the readable eagerly so its data subscription is live the
+    // instant the native read pump (startReading, above) begins emitting. The
+    // device may transmit immediately on open; without an active subscription
+    // those first bytes would be delivered to no listener and silently lost in
+    // the window between open() resolving and the first port.readable access.
+    void this.readable;
   }
 
   /**
@@ -814,9 +913,6 @@ export class SerialPort extends EventTarget {
       throw new TypeError('At least one signal must be specified.');
     }
 
-    // Merge with current output signal state for partial updates
-    this.#outputSignals = {...this.#outputSignals, ...signals};
-
     const promises: Promise<void>[] = [];
 
     // 4.1. If signals["dataTerminalReady"] is present, invoke the operating
@@ -965,8 +1061,8 @@ export class Serial extends EventTarget {
 
   /**
    * @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())`).
+   * talks to it instead of the global native module — the transport override used by tests
+   * and the virtual serial device harness (`new Serial(new InMemorySerialTransport())`).
    * Omit it for the normal native-backed instance; the singleton `serial`
    * export is created this way and can still be redirected globally via
    * `setUsbSerial()`.
@@ -1042,13 +1138,16 @@ export class Serial extends EventTarget {
       // SerialPort instance so a re-attach can reuse it. handleDeviceLost()
       // dispatches "disconnect" on the port.
       this.#usb.onDisconnect((event: ConnectEvent) => {
+        const wasLost = (event as ConnectEvent & {lost?: boolean}).lost ?? true;
         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();
+            // Physical loss tears down the stream immediately; a clean detach
+            // lets any already-buffered bytes drain before EOF.
+            const internals = portInternals.get(port);
+            if (wasLost) internals?.handleDeviceLost();
+            else internals?.handleDeviceDetached();
             matched = true;
           }
         }

package/src/index.ts

@@ -14,5 +14,8 @@ export {Serial, SerialPort} from './WebSerial';
 
 import * as UsbSerial from './UsbSerial';
 
-export {Event, EventTarget} from './lib/event-target';
+export {
+  EventImpl as Event,
+  EventTargetImpl as EventTarget,
+} from './lib/event-target';
 export {UsbSerial};

package/src/lib/event-target.ts

@@ -193,3 +193,15 @@ export class EventTarget {
     }
   }
 }
+
+type MaybeGlobal = Record<string, unknown>;
+
+export const EventImpl =
+  typeof (globalThis as MaybeGlobal).Event === 'function'
+    ? ((globalThis as MaybeGlobal).Event as typeof Event)
+    : Event;
+
+export const EventTargetImpl =
+  typeof (globalThis as MaybeGlobal).EventTarget === 'function'
+    ? ((globalThis as MaybeGlobal).EventTarget as typeof EventTarget)
+    : EventTarget;

package/src/lib/web-streams.ts

@@ -0,0 +1,43 @@
+import {
+  ByteLengthQueuingStrategy as ByteLengthQueuingStrategyPolyfill,
+  ReadableStream as ReadableStreamPolyfill,
+  WritableStream as WritableStreamPolyfill,
+} from 'web-streams-polyfill';
+
+type MaybeGlobal = Record<string, unknown>;
+
+function getCtor<T>(name: string, fallback: T): T {
+  const value = (globalThis as MaybeGlobal)[name];
+  return typeof value === 'function' ? (value as T) : fallback;
+}
+
+export {
+  ByteLengthQueuingStrategyPolyfill,
+  ReadableStreamPolyfill,
+  WritableStreamPolyfill,
+};
+
+export const ReadableStreamImpl = getCtor(
+  'ReadableStream',
+  ReadableStreamPolyfill,
+);
+
+export const WritableStreamImpl = getCtor(
+  'WritableStream',
+  WritableStreamPolyfill,
+);
+
+export const ByteLengthQueuingStrategyImpl = getCtor(
+  'ByteLengthQueuingStrategy',
+  ByteLengthQueuingStrategyPolyfill,
+);
+
+// Companion TYPE aliases so that `Impl as X` imports carry a type too. Without
+// these, an annotation like `ReadableStream<Uint8Array>` (where `ReadableStream`
+// is the imported value) falls back to the ambient *global* ReadableStream and
+// no longer matches the polyfill instances actually constructed — the runtime
+// pick stays native-or-polyfill; only the static type is anchored to the
+// (structurally faithful) polyfill instance type.
+export type ReadableStreamImpl<R = unknown> = ReadableStreamPolyfill<R>;
+export type WritableStreamImpl<W = unknown> = WritableStreamPolyfill<W>;
+export type ByteLengthQueuingStrategyImpl = ByteLengthQueuingStrategyPolyfill;

package/src/testing/device-fixture.ts

@@ -0,0 +1,150 @@
+/**
+ * `createDeviceFixture` — the one-call fixture for testing serial code. It wires a
+ * {@link SimulatedDevice} simulator to an {@link InMemorySerialTransport} + `Serial`,
+ * and hands back everything a test needs to drive *both* sides:
+ *
+ *   - `serial`/`port` — what the app-under-test consumes,
+ *   - `simulatedDevice` (typed) + `device` handle — drive the device (inject data,
+ *     move the GPS, inject faults),
+ *   - `client` — a host-side {@link SerialClient} (for protocol tests), and
+ *   - `whenOpened()/whenClosed()` — `await` the app connecting.
+ *
+ * @example Test how your app reacts to a device event
+ * const {simulatedDevice, device, whenOpened} = await createDeviceFixture(new MyGps());
+ * renderMyApp(); // opens the port itself
+ * await whenOpened();
+ * simulatedDevice.update({latitude: 51.48, longitude: 0});
+ * // …assert your app's UI updated
+ */
+
+import {setUsbSerial} from '../UsbSerial';
+import type {SerialPort} from '../WebSerial';
+import {Serial} from '../WebSerial';
+import type {
+  DeviceOptions,
+  InMemorySerialTransportOptions,
+} from './in-memory-serial-transport';
+import {
+  type DeviceHandle,
+  InMemorySerialTransport,
+} from './in-memory-serial-transport';
+import {SerialClient} from './serial-client';
+import type {
+  SimulatedDevice,
+  SimulatedDeviceOpenOptions,
+} from './simulated-device';
+
+export type DeviceFixtureOptions = {
+  /** Per-device transport knobs (single-device form). */
+  device?: DeviceOptions;
+  /** Per-device transport knobs, by index (multi-device form). */
+  devices?: DeviceOptions[];
+  /** Transport-level options (latencyMs, chunkSize, autoGrantPermission). */
+  transport?: InMemorySerialTransportOptions;
+  /** Whether each device is already permitted. Defaults to true (so it lists). */
+  hasPermission?: boolean;
+  /** Also `setUsbSerial(transport)` so a running app's `serial` sees it. Default false. */
+  installGlobally?: boolean;
+  /** Options for the host-side {@link SerialClient}. */
+  client?: {defaultTimeoutMs?: number};
+};
+
+export type MountedDeviceFixture<D extends SimulatedDevice = SimulatedDevice> =
+  {
+    transport: InMemorySerialTransport;
+    serial: Serial;
+    port: SerialPort;
+    /** The transport-side handle: push/emitError/failNext/written/attach/detach/… */
+    device: DeviceHandle;
+    /** The concrete device simulator, typed (e.g. call `gps.update(...)`). */
+    simulatedDevice: D;
+    /** A host-side client bound to `port` — NOT opened (call `client.open()`). */
+    client: SerialClient;
+    /** Resolve when the app opens the port (now if already open). */
+    whenOpened(): Promise<SimulatedDeviceOpenOptions>;
+    /** Resolve when the app closes the port (now if not open). */
+    whenClosed(): Promise<void>;
+  };
+
+export type MountedDeviceFixtures = {
+  transport: InMemorySerialTransport;
+  serial: Serial;
+  ports: SerialPort[];
+  devices: DeviceHandle[];
+  simulatedDevices: SimulatedDevice[];
+  clients: SerialClient[];
+  /** Resolve when device `index` opens, or any device when `index` is omitted. */
+  whenOpened(index?: number): Promise<SimulatedDeviceOpenOptions>;
+  /** Resolve when device `index` closes, or any device when `index` is omitted. */
+  whenClosed(index?: number): Promise<void>;
+};
+
+export function createDeviceFixture<D extends SimulatedDevice>(
+  device: D,
+  options?: DeviceFixtureOptions,
+): Promise<MountedDeviceFixture<D>>;
+export function createDeviceFixture(
+  devices: SimulatedDevice[],
+  options?: DeviceFixtureOptions,
+): Promise<MountedDeviceFixtures>;
+export async function createDeviceFixture(
+  deviceOrDevices: SimulatedDevice | SimulatedDevice[],
+  options: DeviceFixtureOptions = {},
+): Promise<MountedDeviceFixture | MountedDeviceFixtures> {
+  const list = Array.isArray(deviceOrDevices)
+    ? deviceOrDevices
+    : [deviceOrDevices];
+  const hasPermission = options.hasPermission ?? true;
+  const transport = new InMemorySerialTransport(options.transport);
+  const handles = list.map((dev, i) =>
+    transport.addDevice(dev, {
+      hasPermission,
+      ...(Array.isArray(deviceOrDevices)
+        ? options.devices?.[i]
+        : options.device),
+    }),
+  );
+  const serial = new Serial(transport);
+  if (options.installGlobally) setUsbSerial(transport);
+
+  const ports = await serial.getPorts();
+  const clients = ports.map(
+    p =>
+      new SerialClient(p, {
+        defaultTimeoutMs: options.client?.defaultTimeoutMs,
+      }),
+  );
+
+  if (!Array.isArray(deviceOrDevices)) {
+    const handle = handles[0];
+    const port = ports[0];
+    if (!port) throw new Error('createDeviceFixture: device did not enumerate');
+    return {
+      transport,
+      serial,
+      port,
+      device: handle,
+      simulatedDevice: deviceOrDevices,
+      client: clients[0],
+      whenOpened: () => handle.whenOpened(),
+      whenClosed: () => handle.whenClosed(),
+    };
+  }
+
+  return {
+    transport,
+    serial,
+    ports,
+    devices: handles,
+    simulatedDevices: list,
+    clients,
+    whenOpened: (index?: number) =>
+      index === undefined
+        ? Promise.race(handles.map(h => h.whenOpened()))
+        : handles[index].whenOpened(),
+    whenClosed: (index?: number) =>
+      index === undefined
+        ? Promise.race(handles.map(h => h.whenClosed()))
+        : handles[index].whenClosed(),
+  };
+}