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

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,10 @@ 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 {
+  EventImpl as Event,
+  EventTargetImpl as EventTarget,
+} from './lib/event-target';
 export {UsbSerial};

package/src/lib/dom-exception.ts

@@ -33,7 +33,7 @@ const DOM_EXCEPTION_CODES: Record<string, number> = {
 };
 
 const DOM_EXCEPTION_NAMES: Record<number, string> = Object.fromEntries(
-  Object.entries(DOM_EXCEPTION_CODES).map(([name, code]) => [code, name])
+  Object.entries(DOM_EXCEPTION_CODES).map(([name, code]) => [code, name]),
 );
 
 export interface DOMExceptionConstructor {
@@ -78,74 +78,134 @@ class DOMExceptionPolyfill extends Error {
   readonly name: string;
 
   // --- Static legacy-code constants ---
-  static readonly INDEX_SIZE_ERR             = 1  as const;
-  static readonly DOMSTRING_SIZE_ERR         = 2  as const;
-  static readonly HIERARCHY_REQUEST_ERR      = 3  as const;
-  static readonly WRONG_DOCUMENT_ERR         = 4  as const;
-  static readonly INVALID_CHARACTER_ERR      = 5  as const;
-  static readonly NO_DATA_ALLOWED_ERR        = 6  as const;
+  static readonly INDEX_SIZE_ERR = 1 as const;
+  static readonly DOMSTRING_SIZE_ERR = 2 as const;
+  static readonly HIERARCHY_REQUEST_ERR = 3 as const;
+  static readonly WRONG_DOCUMENT_ERR = 4 as const;
+  static readonly INVALID_CHARACTER_ERR = 5 as const;
+  static readonly NO_DATA_ALLOWED_ERR = 6 as const;
   static readonly NO_MODIFICATION_ALLOWED_ERR = 7 as const;
-  static readonly NOT_FOUND_ERR              = 8  as const;
-  static readonly NOT_SUPPORTED_ERR          = 9  as const;
-  static readonly INUSE_ATTRIBUTE_ERR        = 10 as const;
-  static readonly INVALID_STATE_ERR          = 11 as const;
-  static readonly SYNTAX_ERR                 = 12 as const;
-  static readonly INVALID_MODIFICATION_ERR   = 13 as const;
-  static readonly NAMESPACE_ERR              = 14 as const;
-  static readonly INVALID_ACCESS_ERR         = 15 as const;
-  static readonly VALIDATION_ERR             = 16 as const;
-  static readonly TYPE_MISMATCH_ERR          = 17 as const;
-  static readonly SECURITY_ERR               = 18 as const;
-  static readonly NETWORK_ERR                = 19 as const;
-  static readonly ABORT_ERR                  = 20 as const;
-  static readonly URL_MISMATCH_ERR           = 21 as const;
-  static readonly QUOTA_EXCEEDED_ERR         = 22 as const;
-  static readonly TIMEOUT_ERR                = 23 as const;
-  static readonly INVALID_NODE_TYPE_ERR      = 24 as const;
-  static readonly DATA_CLONE_ERR             = 25 as const;
+  static readonly NOT_FOUND_ERR = 8 as const;
+  static readonly NOT_SUPPORTED_ERR = 9 as const;
+  static readonly INUSE_ATTRIBUTE_ERR = 10 as const;
+  static readonly INVALID_STATE_ERR = 11 as const;
+  static readonly SYNTAX_ERR = 12 as const;
+  static readonly INVALID_MODIFICATION_ERR = 13 as const;
+  static readonly NAMESPACE_ERR = 14 as const;
+  static readonly INVALID_ACCESS_ERR = 15 as const;
+  static readonly VALIDATION_ERR = 16 as const;
+  static readonly TYPE_MISMATCH_ERR = 17 as const;
+  static readonly SECURITY_ERR = 18 as const;
+  static readonly NETWORK_ERR = 19 as const;
+  static readonly ABORT_ERR = 20 as const;
+  static readonly URL_MISMATCH_ERR = 21 as const;
+  static readonly QUOTA_EXCEEDED_ERR = 22 as const;
+  static readonly TIMEOUT_ERR = 23 as const;
+  static readonly INVALID_NODE_TYPE_ERR = 24 as const;
+  static readonly DATA_CLONE_ERR = 25 as const;
 
-  constructor(message = "", name = "Error") {
+  constructor(message = '', name = 'Error') {
     super(message);
 
     // Restore the correct prototype chain when transpiled to ES5
     Object.setPrototypeOf(this, new.target.prototype);
 
-    this.name    = name;
+    this.name = name;
     this.message = message;
-    this.code    = DOM_EXCEPTION_CODES[name] ?? 0;
+    this.code = DOM_EXCEPTION_CODES[name] ?? 0;
 
     // Provide a useful stack trace in V8 / SpiderMonkey
-    if (typeof (Error as any).captureStackTrace === "function") {
-      (Error as any).captureStackTrace(this, new.target);
+    const ErrorWithStack = Error as ErrorConstructor & {
+      captureStackTrace?: (
+        target: object,
+        constructorOpt?:
+          | ((...args: never[]) => unknown)
+          | (abstract new (
+              ...args: never[]
+            ) => unknown),
+      ) => void;
+    };
+    if (typeof ErrorWithStack.captureStackTrace === 'function') {
+      ErrorWithStack.captureStackTrace(this, new.target);
     }
   }
 
   /** Mirror static constants on the prototype (spec §3.1.2) */
-  get INDEX_SIZE_ERR()              { return 1; }
-  get DOMSTRING_SIZE_ERR()          { return 2; }
-  get HIERARCHY_REQUEST_ERR()       { return 3; }
-  get WRONG_DOCUMENT_ERR()          { return 4; }
-  get INVALID_CHARACTER_ERR()       { return 5; }
-  get NO_DATA_ALLOWED_ERR()         { return 6; }
-  get NO_MODIFICATION_ALLOWED_ERR() { return 7; }
-  get NOT_FOUND_ERR()               { return 8; }
-  get NOT_SUPPORTED_ERR()           { return 9; }
-  get INUSE_ATTRIBUTE_ERR()         { return 10; }
-  get INVALID_STATE_ERR()           { return 11; }
-  get SYNTAX_ERR()                  { return 12; }
-  get INVALID_MODIFICATION_ERR()    { return 13; }
-  get NAMESPACE_ERR()               { return 14; }
-  get INVALID_ACCESS_ERR()          { return 15; }
-  get VALIDATION_ERR()              { return 16; }
-  get TYPE_MISMATCH_ERR()           { return 17; }
-  get SECURITY_ERR()                { return 18; }
-  get NETWORK_ERR()                 { return 19; }
-  get ABORT_ERR()                   { return 20; }
-  get URL_MISMATCH_ERR()            { return 21; }
-  get QUOTA_EXCEEDED_ERR()          { return 22; }
-  get TIMEOUT_ERR()                 { return 23; }
-  get INVALID_NODE_TYPE_ERR()       { return 24; }
-  get DATA_CLONE_ERR()              { return 25; }
+  get INDEX_SIZE_ERR() {
+    return 1;
+  }
+  get DOMSTRING_SIZE_ERR() {
+    return 2;
+  }
+  get HIERARCHY_REQUEST_ERR() {
+    return 3;
+  }
+  get WRONG_DOCUMENT_ERR() {
+    return 4;
+  }
+  get INVALID_CHARACTER_ERR() {
+    return 5;
+  }
+  get NO_DATA_ALLOWED_ERR() {
+    return 6;
+  }
+  get NO_MODIFICATION_ALLOWED_ERR() {
+    return 7;
+  }
+  get NOT_FOUND_ERR() {
+    return 8;
+  }
+  get NOT_SUPPORTED_ERR() {
+    return 9;
+  }
+  get INUSE_ATTRIBUTE_ERR() {
+    return 10;
+  }
+  get INVALID_STATE_ERR() {
+    return 11;
+  }
+  get SYNTAX_ERR() {
+    return 12;
+  }
+  get INVALID_MODIFICATION_ERR() {
+    return 13;
+  }
+  get NAMESPACE_ERR() {
+    return 14;
+  }
+  get INVALID_ACCESS_ERR() {
+    return 15;
+  }
+  get VALIDATION_ERR() {
+    return 16;
+  }
+  get TYPE_MISMATCH_ERR() {
+    return 17;
+  }
+  get SECURITY_ERR() {
+    return 18;
+  }
+  get NETWORK_ERR() {
+    return 19;
+  }
+  get ABORT_ERR() {
+    return 20;
+  }
+  get URL_MISMATCH_ERR() {
+    return 21;
+  }
+  get QUOTA_EXCEEDED_ERR() {
+    return 22;
+  }
+  get TIMEOUT_ERR() {
+    return 23;
+  }
+  get INVALID_NODE_TYPE_ERR() {
+    return 24;
+  }
+  get DATA_CLONE_ERR() {
+    return 25;
+  }
 
   /** Canonical string representation */
   toString(): string {
@@ -153,9 +213,18 @@ class DOMExceptionPolyfill extends Error {
   }
 }
 
-export const DOMExceptionImpl = (globalThis as any).DOMException
-    ? (globalThis as any).DOMException as DOMExceptionConstructor
-    : DOMExceptionPolyfill as DOMExceptionConstructor;
+export const DOMExceptionImpl = (globalThis as Record<string, unknown>)
+  .DOMException
+  ? ((globalThis as Record<string, unknown>)
+      .DOMException as DOMExceptionConstructor)
+  : (DOMExceptionPolyfill as DOMExceptionConstructor);
 
-export { DOM_EXCEPTION_CODES, DOM_EXCEPTION_NAMES };
-export { DOMExceptionImpl as DOMException };
+export {
+  DOM_EXCEPTION_CODES,
+  DOM_EXCEPTION_NAMES,
+  DOMExceptionImpl as DOMException,
+  // Exported for testing: in environments that already provide a global
+  // DOMException (Node, modern browsers) the export above is the native one, so
+  // the polyfill class would otherwise never run.
+  DOMExceptionPolyfill,
+};

package/src/lib/event-target.ts

@@ -1,4 +1,3 @@
-
 export interface EventInit {
   bubbles?: boolean;
   cancelable?: boolean;
@@ -66,7 +65,7 @@ export class Event {
   }
 }
 
-type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+type Mutable<T> = {-readonly [P in keyof T]: T[P]};
 
 type EventListener = (event: Event) => void;
 
@@ -77,7 +76,7 @@ interface EventListenerObject {
 type EventListenerOrEventListenerObject = EventListener | EventListenerObject;
 
 type ListenerOptions =
-  | { once?: boolean; capture?: boolean; passive?: boolean }
+  | {once?: boolean; capture?: boolean; passive?: boolean}
   | boolean
   | undefined;
 
@@ -91,7 +90,23 @@ type SecretMap = Record<string, ListenerInfo[]>;
 
 const wm = new WeakMap<object, SecretMap>();
 
-function define<T extends object>(target: T, name: string, value: unknown): void {
+// Optional event-propagation parents. An event dispatched on a child also runs
+// its parent's listeners, while event.target stays the original child. This
+// models the W3C "SerialPort's parent is the Serial" relationship, so a
+// connect/disconnect observed on `serial` reports event.target === the
+// SerialPort (per the Web Serial spec and WPT).
+const eventParents = new WeakMap<EventTarget, EventTarget>();
+
+/** Make events dispatched on `child` also bubble to `parent`'s listeners. */
+export function setEventParent(child: EventTarget, parent: EventTarget): void {
+  eventParents.set(child, parent);
+}
+
+function define<T extends object>(
+  target: T,
+  name: string,
+  value: unknown,
+): void {
   Object.defineProperty(target, name, {
     configurable: true,
     writable: true,
@@ -102,13 +117,13 @@ function define<T extends object>(target: T, name: string, value: unknown): void
 function dispatch(this: Event, info: ListenerInfo): boolean {
   const options = info.options;
   const once =
-    typeof options === "object" && options !== null ? options.once : false;
+    typeof options === 'object' && options !== null ? options.once : false;
 
   if (once) {
     info.target.removeEventListener(this.type, info.listener);
   }
 
-  if (typeof info.listener === "function") {
+  if (typeof info.listener === 'function') {
     info.listener.call(info.target, this);
   } else {
     info.listener.handleEvent(this);
@@ -125,40 +140,50 @@ export class EventTarget {
   addEventListener(
     type: string,
     listener: EventListenerOrEventListenerObject,
-    options?: ListenerOptions
+    options?: ListenerOptions,
   ): void {
     const secret = wm.get(this)!;
-    const listeners: ListenerInfo[] = secret[type] ?? (secret[type] = []);
+    let listeners = secret[type];
+    if (!listeners) {
+      listeners = [];
+      secret[type] = listeners;
+    }
 
     for (let i = 0; i < listeners.length; i++) {
       if (listeners[i].listener === listener) return;
     }
 
-    listeners.push({ target: this, listener, options });
+    listeners.push({target: this, listener, options});
   }
 
   dispatchEvent(event: Event): boolean {
-    const secret = wm.get(this)!;
-    const listeners = secret[event.type];
-
-    if (listeners) {
-      define(event, "target", this);
-      define(event, "currentTarget", this);
-      listeners.slice(0).some(dispatch, event);
-      define(event, "target", null);
-      define(event, "currentTarget", null);
+    // The event's target is the node it was dispatched on; it then bubbles up
+    // the eventParents chain (currentTarget changes, target does not).
+    define(event, 'target', this);
+    let node: EventTarget | null = this;
+    while (node) {
+      const listeners = wm.get(node)?.[event.type];
+      if (listeners?.length) {
+        define(event, 'currentTarget', node);
+        listeners.slice(0).some(dispatch, event);
+      }
+      if (event.cancelBubble) break;
+      node = eventParents.get(node) ?? null;
     }
-
+    // Per the DOM, target persists after dispatch (a re-dispatch overwrites it
+    // at the top of this method); only currentTarget is cleared.
+    define(event, 'currentTarget', null);
     return true;
   }
 
   removeEventListener(
     type: string,
     listener: EventListenerOrEventListenerObject,
-    _options?: ListenerOptions
+    _options?: ListenerOptions,
   ): void {
     const secret = wm.get(this)!;
-    const listeners: ListenerInfo[] = secret[type] ?? (secret[type] = []);
+    const listeners = secret[type];
+    if (!listeners) return;
 
     for (let i = 0; i < listeners.length; i++) {
       if (listeners[i].listener === listener) {
@@ -168,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/promise.ts

@@ -1,19 +1,19 @@
 type DeferredPromise<T> = {
   promise: Promise<T>;
   resolve: (value?: T) => void;
-  reject: (reason?: any) => void;
+  reject: (reason?: unknown) => void;
 };
 
 /**
  * @returns An object containing a promise and its resolve/reject methods.
  */
 export function createDeferredPromise<T>(): DeferredPromise<T> {
-  let res: any;
-  let rej: any;
+  let res: unknown;
+  let rej: unknown;
   const promise = new Promise<T>((resolve, reject) => {
-    res = resolve
-    rej = reject
-  })
+    res = resolve;
+    rej = reject;
+  });
 
-  return { promise, resolve: res, reject: rej } as DeferredPromise<T>;
+  return {promise, resolve: res, reject: rej} as DeferredPromise<T>;
 }

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(),
+  };
+}