@yume-chan/adb-daemon-webusb 0.0.23 → 1.0.0

package/src/manager.ts

@@ -1,14 +1,13 @@
-import { ADB_DEFAULT_DEVICE_FILTER, AdbDaemonWebUsbDevice } from "./device.js";
-import type { AdbDeviceFilter } from "./utils.js";
 import {
-    findUsbAlternateInterface,
-    getSerialNumber,
-    isErrorName,
-} from "./utils.js";
+    AdbDaemonWebUsbDevice,
+    mergeDefaultAdbInterfaceFilter,
+} from "./device.js";
+import { AdbDaemonWebUsbDeviceObserver } from "./observer.js";
+import { isErrorName, matchFilters } from "./utils.js";
 
 export namespace AdbDaemonWebUsbDeviceManager {
     export interface RequestDeviceOptions {
-        filters?: AdbDeviceFilter[] | undefined;
+        filters?: USBDeviceFilter[] | undefined;
         exclusionFilters?: USBDeviceFilter[] | undefined;
     }
 }
@@ -36,34 +35,33 @@ export class AdbDaemonWebUsbDeviceManager {
     }
 
     /**
-     * Request access to a connected device.
-     * This is a convince method for `usb.requestDevice()`.
-     * @param filters
-     * The filters to apply to the device list.
-     *
-     * It must have `classCode`, `subclassCode` and `protocolCode` fields for selecting the ADB interface,
-     * but might also have `vendorId`, `productId` or `serialNumber` fields to limit the displayed device list.
-     *
-     * Defaults to {@link ADB_DEFAULT_DEVICE_FILTER}.
-     * @returns An {@link AdbDaemonWebUsbDevice} instance if the user selected a device,
-     * or `undefined` if the user cancelled the device picker.
+     * Call `USB#requestDevice()` to prompt the user to select a device.
      */
     async requestDevice(
         options: AdbDaemonWebUsbDeviceManager.RequestDeviceOptions = {},
     ): Promise<AdbDaemonWebUsbDevice | undefined> {
-        if (!options.filters) {
-            options.filters = [ADB_DEFAULT_DEVICE_FILTER];
-        } else if (options.filters.length === 0) {
-            throw new TypeError("filters must not be empty");
-        }
+        const filters = mergeDefaultAdbInterfaceFilter(options.filters);
 
         try {
-            const device = await this.#usbManager.requestDevice(
-                options as USBDeviceRequestOptions,
+            const device = await this.#usbManager.requestDevice({
+                filters,
+                exclusionFilters: options.exclusionFilters,
+            });
+
+            const interface_ = matchFilters(
+                device,
+                filters,
+                options.exclusionFilters,
             );
+            if (!interface_) {
+                // `#usbManager` doesn't support `exclusionFilters`,
+                // selected device is invalid
+                return undefined;
+            }
+
             return new AdbDaemonWebUsbDevice(
                 device,
-                options.filters,
+                interface_,
                 this.#usbManager,
             );
         } catch (e) {
@@ -77,63 +75,39 @@ export class AdbDaemonWebUsbDeviceManager {
     }
 
     /**
-     * Get all connected and authenticated devices.
-     * This is a convince method for `usb.getDevices()`.
-     * @param filters
-     * The filters to apply to the device list.
-     *
-     * It must have `classCode`, `subclassCode` and `protocolCode` fields for selecting the ADB interface,
-     * but might also have `vendorId`, `productId` or `serialNumber` fields to limit the device list.
-     *
-     * Defaults to {@link ADB_DEFAULT_DEVICE_FILTER}.
-     * @returns An array of {@link AdbDaemonWebUsbDevice} instances for all connected and authenticated devices.
+     * Get all connected and requested devices that match the specified filters.
      */
     async getDevices(
-        filters: AdbDeviceFilter[] = [ADB_DEFAULT_DEVICE_FILTER],
+        options: AdbDaemonWebUsbDeviceManager.RequestDeviceOptions = {},
     ): Promise<AdbDaemonWebUsbDevice[]> {
-        if (filters.length === 0) {
-            throw new TypeError("filters must not be empty");
-        }
+        const filters = mergeDefaultAdbInterfaceFilter(options.filters);
 
         const devices = await this.#usbManager.getDevices();
-        return devices
-            .filter((device) => {
-                for (const filter of filters) {
-                    if (
-                        "vendorId" in filter &&
-                        device.vendorId !== filter.vendorId
-                    ) {
-                        continue;
-                    }
-                    if (
-                        "productId" in filter &&
-                        device.productId !== filter.productId
-                    ) {
-                        continue;
-                    }
-                    if (
-                        "serialNumber" in filter &&
-                        getSerialNumber(device) !== filter.serialNumber
-                    ) {
-                        continue;
-                    }
-
-                    try {
-                        findUsbAlternateInterface(device, filters);
-                        return true;
-                    } catch {
-                        continue;
-                    }
-                }
-                return false;
-            })
-            .map(
-                (device) =>
+        // filter map
+        const result: AdbDaemonWebUsbDevice[] = [];
+        for (const device of devices) {
+            const interface_ = matchFilters(
+                device,
+                filters,
+                options.exclusionFilters,
+            );
+            if (interface_) {
+                result.push(
                     new AdbDaemonWebUsbDevice(
                         device,
-                        filters,
+                        interface_,
                         this.#usbManager,
                     ),
-            );
+                );
+            }
+        }
+
+        return result;
+    }
+
+    trackDevices(
+        options: AdbDaemonWebUsbDeviceManager.RequestDeviceOptions = {},
+    ): AdbDaemonWebUsbDeviceObserver {
+        return new AdbDaemonWebUsbDeviceObserver(this.#usbManager, options);
     }
 }

package/src/observer.ts

@@ -0,0 +1,90 @@
+import type { DeviceObserver } from "@yume-chan/adb";
+import { EventEmitter } from "@yume-chan/event";
+
+import {
+    AdbDaemonWebUsbDevice,
+    mergeDefaultAdbInterfaceFilter,
+} from "./device.js";
+import type { AdbDaemonWebUsbDeviceManager } from "./manager.js";
+import type { UsbInterfaceFilter } from "./utils.js";
+import { matchFilters } from "./utils.js";
+
+/**
+ * A watcher that listens for new WebUSB devices and notifies the callback when
+ * a new device is connected or disconnected.
+ */
+export class AdbDaemonWebUsbDeviceObserver
+    implements DeviceObserver<AdbDaemonWebUsbDevice>
+{
+    #filters: (USBDeviceFilter & UsbInterfaceFilter)[];
+    #exclusionFilters?: USBDeviceFilter[] | undefined;
+    #usbManager: USB;
+
+    #onDeviceAdd = new EventEmitter<AdbDaemonWebUsbDevice[]>();
+    onDeviceAdd = this.#onDeviceAdd.event;
+
+    #onDeviceRemove = new EventEmitter<AdbDaemonWebUsbDevice[]>();
+    onDeviceRemove = this.#onDeviceRemove.event;
+
+    #onListChange = new EventEmitter<AdbDaemonWebUsbDevice[]>();
+    onListChange = this.#onListChange.event;
+
+    current: AdbDaemonWebUsbDevice[] = [];
+
+    constructor(
+        usb: USB,
+        options: AdbDaemonWebUsbDeviceManager.RequestDeviceOptions = {},
+    ) {
+        this.#filters = mergeDefaultAdbInterfaceFilter(options.filters);
+        this.#exclusionFilters = options.exclusionFilters;
+        this.#usbManager = usb;
+
+        this.#usbManager.addEventListener("connect", this.#handleConnect);
+        this.#usbManager.addEventListener("disconnect", this.#handleDisconnect);
+    }
+
+    #handleConnect = (e: USBConnectionEvent) => {
+        const interface_ = matchFilters(
+            e.device,
+            this.#filters,
+            this.#exclusionFilters,
+        );
+        if (!interface_) {
+            return;
+        }
+
+        const device = new AdbDaemonWebUsbDevice(
+            e.device,
+            interface_,
+            this.#usbManager,
+        );
+        this.#onDeviceAdd.fire([device]);
+        this.current.push(device);
+        this.#onListChange.fire(this.current);
+    };
+
+    #handleDisconnect = (e: USBConnectionEvent) => {
+        const index = this.current.findIndex(
+            (device) => device.raw === e.device,
+        );
+        if (index !== -1) {
+            const device = this.current[index]!;
+            this.#onDeviceRemove.fire([device]);
+            this.current[index] = this.current[this.current.length - 1]!;
+            this.current.length -= 1;
+            this.#onListChange.fire(this.current);
+        }
+    };
+
+    stop(): void {
+        this.#usbManager.removeEventListener("connect", this.#handleConnect);
+        this.#usbManager.removeEventListener(
+            "disconnect",
+            this.#handleDisconnect,
+        );
+
+        this.#onDeviceAdd.dispose();
+        this.#onDeviceRemove.dispose();
+        this.#onListChange.dispose();
+    }
+}

package/src/utils.ts

@@ -1,4 +1,4 @@
-export function isErrorName(e: unknown, name: string): boolean {
+export function isErrorName(e: unknown, name: string): e is Error {
     // node-usb package doesn't use `DOMException`,
     // so use a looser check
     // https://github.com/node-usb/node-usb/issues/573
@@ -7,42 +7,60 @@ export function isErrorName(e: unknown, name: string): boolean {
     );
 }
 
+export type PickNonNullable<T, K extends keyof T> = {
+    [P in K]-?: NonNullable<T[P]>;
+};
+
 /**
  * `classCode`, `subclassCode` and `protocolCode` are required
  * for selecting correct USB configuration and interface.
  */
-export type AdbDeviceFilter = USBDeviceFilter &
-    Required<
-        Pick<USBDeviceFilter, "classCode" | "subclassCode" | "protocolCode">
-    >;
+export type UsbInterfaceFilter = PickNonNullable<
+    USBDeviceFilter,
+    "classCode" | "subclassCode" | "protocolCode"
+>;
+
+export function isUsbInterfaceFilter(
+    filter: USBDeviceFilter,
+): filter is UsbInterfaceFilter {
+    return (
+        filter.classCode !== undefined &&
+        filter.subclassCode !== undefined &&
+        filter.protocolCode !== undefined
+    );
+}
 
-function alternateMatchesFilter(
+function matchUsbInterfaceFilter(
     alternate: USBAlternateInterface,
-    filters: AdbDeviceFilter[],
+    filter: UsbInterfaceFilter,
 ) {
-    return filters.some(
-        (filter) =>
-            alternate.interfaceClass === filter.classCode &&
-            alternate.interfaceSubclass === filter.subclassCode &&
-            alternate.interfaceProtocol === filter.protocolCode,
+    return (
+        alternate.interfaceClass === filter.classCode &&
+        alternate.interfaceSubclass === filter.subclassCode &&
+        alternate.interfaceProtocol === filter.protocolCode
     );
 }
 
-export function findUsbAlternateInterface(
+export interface UsbInterfaceIdentifier {
+    configuration: USBConfiguration;
+    interface_: USBInterface;
+    alternate: USBAlternateInterface;
+}
+
+export function findUsbInterface(
     device: USBDevice,
-    filters: AdbDeviceFilter[],
-) {
+    filter: UsbInterfaceFilter,
+): UsbInterfaceIdentifier | undefined {
     for (const configuration of device.configurations) {
         for (const interface_ of configuration.interfaces) {
             for (const alternate of interface_.alternates) {
-                if (alternateMatchesFilter(alternate, filters)) {
+                if (matchUsbInterfaceFilter(alternate, filter)) {
                     return { configuration, interface_, alternate };
                 }
             }
         }
     }
-
-    throw new Error("No matched alternate interface found");
+    return undefined;
 }
 
 function padNumber(value: number) {
@@ -56,3 +74,109 @@ export function getSerialNumber(device: USBDevice) {
 
     return padNumber(device.vendorId) + "x" + padNumber(device.productId);
 }
+
+/**
+ * Find the first pair of input and output endpoints from an alternate interface.
+ *
+ * ADB interface only has two endpoints, one for input and one for output.
+ */
+export function findUsbEndpoints(endpoints: USBEndpoint[]) {
+    if (endpoints.length === 0) {
+        throw new TypeError("No endpoints given");
+    }
+
+    let inEndpoint: USBEndpoint | undefined;
+    let outEndpoint: USBEndpoint | undefined;
+
+    for (const endpoint of endpoints) {
+        switch (endpoint.direction) {
+            case "in":
+                inEndpoint = endpoint;
+                if (outEndpoint) {
+                    return { inEndpoint, outEndpoint };
+                }
+                break;
+            case "out":
+                outEndpoint = endpoint;
+                if (inEndpoint) {
+                    return { inEndpoint, outEndpoint };
+                }
+                break;
+        }
+    }
+
+    if (!inEndpoint) {
+        throw new TypeError("No input endpoint found.");
+    }
+    if (!outEndpoint) {
+        throw new TypeError("No output endpoint found.");
+    }
+    throw new Error("unreachable");
+}
+
+export function matchFilter(
+    device: USBDevice,
+    filter: USBDeviceFilter & UsbInterfaceFilter,
+): UsbInterfaceIdentifier | false;
+export function matchFilter(
+    device: USBDevice,
+    filter: USBDeviceFilter,
+): boolean;
+export function matchFilter(
+    device: USBDevice,
+    filter: USBDeviceFilter,
+): UsbInterfaceIdentifier | boolean {
+    if (filter.vendorId !== undefined && device.vendorId !== filter.vendorId) {
+        return false;
+    }
+
+    if (
+        filter.productId !== undefined &&
+        device.productId !== filter.productId
+    ) {
+        return false;
+    }
+
+    if (
+        filter.serialNumber !== undefined &&
+        getSerialNumber(device) !== filter.serialNumber
+    ) {
+        return false;
+    }
+
+    if (isUsbInterfaceFilter(filter)) {
+        return findUsbInterface(device, filter) || false;
+    }
+
+    return true;
+}
+
+export function matchFilters(
+    device: USBDevice,
+    filters: (USBDeviceFilter & UsbInterfaceFilter)[],
+    exclusionFilters?: USBDeviceFilter[],
+): UsbInterfaceIdentifier | false;
+export function matchFilters(
+    device: USBDevice,
+    filters: USBDeviceFilter[],
+    exclusionFilters?: USBDeviceFilter[],
+): boolean;
+export function matchFilters(
+    device: USBDevice,
+    filters: USBDeviceFilter[],
+    exclusionFilters?: USBDeviceFilter[],
+): UsbInterfaceIdentifier | boolean {
+    if (exclusionFilters && exclusionFilters.length > 0) {
+        if (matchFilters(device, exclusionFilters)) {
+            return false;
+        }
+    }
+
+    for (const filter of filters) {
+        const result = matchFilter(device, filter);
+        if (result) {
+            return result;
+        }
+    }
+    return false;
+}

package/tsconfig.build.json

@@ -6,18 +6,7 @@
             "DOM"
         ],
         "types": [
-            "w3c-web-usb",
+            "w3c-web-usb"
         ]
-    },
-    "references": [
-        {
-            "path": "../adb/tsconfig.build.json"
-        },
-        {
-            "path": "../stream-extra/tsconfig.build.json"
-        },
-        {
-            "path": "../struct/tsconfig.build.json"
-        },
-    ]
+    }
 }