@yume-chan/adb 0.0.24 → 1.0.0

package/src/server/client.ts

@@ -1,34 +1,33 @@
 // cspell:ignore tport
 
+import type { MaybePromiseLike } from "@yume-chan/async";
 import { PromiseResolver } from "@yume-chan/async";
+import type { Event } from "@yume-chan/event";
+import { EventEmitter } from "@yume-chan/event";
 import { getUint64LittleEndian } from "@yume-chan/no-data-view";
 import type {
     AbortSignal,
+    MaybeConsumable,
     ReadableWritablePair,
     WritableStreamDefaultWriter,
 } from "@yume-chan/stream-extra";
 import {
     BufferedReadableStream,
-    MaybeConsumable,
-    WrapWritableStream,
+    tryCancel,
+    tryClose,
 } from "@yume-chan/stream-extra";
-import type { ValueOrPromise } from "@yume-chan/struct";
 import {
-    EMPTY_UINT8_ARRAY,
-    SyncPromise,
+    bipedal,
     decodeUtf8,
     encodeUtf8,
+    TextDecoder,
 } from "@yume-chan/struct";
 
 import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
 import { AdbBanner } from "../banner.js";
+import type { DeviceObserver as DeviceObserverBase } from "../device-observer.js";
 import type { AdbFeature } from "../features.js";
-import {
-    NOOP,
-    hexToNumber,
-    sequenceEqual,
-    write4HexDigits,
-} from "../utils/index.js";
+import { hexToNumber, sequenceEqual, write4HexDigits } from "../utils/index.js";
 
 import { AdbServerTransport } from "./transport.js";
 
@@ -46,44 +45,30 @@ class AdbServerStream {
         this.#writer = connection.writable.getWriter();
     }
 
-    readExactly(length: number): ValueOrPromise<Uint8Array> {
+    readExactly(length: number): MaybePromiseLike<Uint8Array> {
         return this.#buffered.readExactly(length);
     }
 
-    readString() {
-        return SyncPromise.try(() => this.readExactly(4))
-            .then((buffer) => {
-                const length = hexToNumber(buffer);
-                if (length === 0) {
-                    return EMPTY_UINT8_ARRAY;
-                } else {
-                    return this.readExactly(length);
+    readString = bipedal(function* (this: AdbServerStream, then) {
+        const data = yield* then(this.readExactly(4));
+        const length = hexToNumber(data);
+        if (length === 0) {
+            return "";
+        } else {
+            const decoder = new TextDecoder();
+            let result = "";
+            const iterator = this.#buffered.iterateExactly(length);
+            while (true) {
+                const { done, value } = iterator.next();
+                if (done) {
+                    break;
                 }
-            })
-            .then((buffer) => {
-                // TODO: Investigate using stream mode `TextDecoder` for long strings.
-                // Because concatenating strings uses rope data structure,
-                // which only points to the original strings and doesn't copy the data,
-                // it's more efficient than concatenating `Uint8Array`s.
-                //
-                // ```
-                // const decoder = new TextDecoder();
-                // let result = '';
-                // for await (const chunk of stream.iterateExactly(length)) {
-                //     result += decoder.decode(chunk, { stream: true });
-                // }
-                // result += decoder.decode();
-                // return result;
-                // ```
-                //
-                // Although, it will be super complex to use `SyncPromise` with async iterator,
-                // `stream.iterateExactly` need to return an
-                // `Iterator<Uint8Array | Promise<Uint8Array>>` instead of a true async iterator.
-                // Maybe `SyncPromise` should support async iterators directly.
-                return decodeUtf8(buffer);
-            })
-            .valueOrPromise();
-    }
+                result += decoder.decode(yield* then(value), { stream: true });
+            }
+            result += decoder.decode();
+            return result;
+        }
+    });
 
     async writeString(value: string): Promise<void> {
         // TODO: investigate using `encodeUtf8("0000" + value)` then modifying the length
@@ -123,26 +108,97 @@ class AdbServerStream {
     }
 
     async dispose() {
-        await this.#buffered.cancel().catch(NOOP);
-        await this.#writer.close().catch(NOOP);
-        try {
-            await this.#connection.close();
-        } catch {
-            // ignore
-        }
+        void tryCancel(this.#buffered);
+        void tryClose(this.#writer);
+        await this.#connection.close();
     }
 }
 
+/**
+ * Client for the ADB Server.
+ */
 export class AdbServerClient {
     static readonly VERSION = 41;
 
+    static parseDeviceList(value: string): AdbServerClient.Device[] {
+        const devices: AdbServerClient.Device[] = [];
+        for (const line of value.split("\n")) {
+            if (!line) {
+                continue;
+            }
+
+            const parts = line.split(" ").filter(Boolean);
+            const serial = parts[0]!;
+            const status = parts[1]!;
+            if (status !== "device" && status !== "unauthorized") {
+                continue;
+            }
+
+            let product: string | undefined;
+            let model: string | undefined;
+            let device: string | undefined;
+            let transportId: bigint | undefined;
+            for (let i = 2; i < parts.length; i += 1) {
+                const [key, value] = parts[i]!.split(":");
+                switch (key) {
+                    case "product":
+                        product = value;
+                        break;
+                    case "model":
+                        model = value;
+                        break;
+                    case "device":
+                        device = value;
+                        break;
+                    case "transport_id":
+                        transportId = BigInt(value!);
+                        break;
+                }
+            }
+            if (!transportId) {
+                throw new Error(`No transport id for device ${serial}`);
+            }
+            devices.push({
+                serial,
+                authenticating: status === "unauthorized",
+                product,
+                model,
+                device,
+                transportId,
+            });
+        }
+        return devices;
+    }
+
+    static formatDeviceService(
+        device: AdbServerClient.DeviceSelector,
+        command: string,
+    ) {
+        if (!device) {
+            return `host:${command}`;
+        }
+        if ("transportId" in device) {
+            return `host-transport-id:${device.transportId}:${command}`;
+        }
+        if ("serial" in device) {
+            return `host-serial:${device.serial}:${command}`;
+        }
+        if ("usb" in device) {
+            return `host-usb:${command}`;
+        }
+        if ("tcp" in device) {
+            return `host-local:${command}`;
+        }
+        throw new TypeError("Invalid device selector");
+    }
+
     readonly connector: AdbServerClient.ServerConnector;
 
     readonly wireless = new AdbServerClient.WirelessCommands(this);
     readonly mDns = new AdbServerClient.MDnsCommands(this);
 
-    constructor(connection: AdbServerClient.ServerConnector) {
-        this.connector = connection;
+    constructor(connector: AdbServerClient.ServerConnector) {
+        this.connector = connector;
     }
 
     async createConnection(
@@ -214,118 +270,79 @@ export class AdbServerClient {
         }
     }
 
-    parseDeviceList(value: string): AdbServerClient.Device[] {
-        const devices: AdbServerClient.Device[] = [];
-        for (const line of value.split("\n")) {
-            if (!line) {
-                continue;
-            }
-
-            const parts = line.split(" ").filter(Boolean);
-            const serial = parts[0]!;
-            const status = parts[1]!;
-            if (status !== "device" && status !== "unauthorized") {
-                continue;
-            }
-
-            let product: string | undefined;
-            let model: string | undefined;
-            let device: string | undefined;
-            let transportId: bigint | undefined;
-            for (let i = 2; i < parts.length; i += 1) {
-                const [key, value] = parts[i]!.split(":");
-                switch (key) {
-                    case "product":
-                        product = value;
-                        break;
-                    case "model":
-                        model = value;
-                        break;
-                    case "device":
-                        device = value;
-                        break;
-                    case "transport_id":
-                        transportId = BigInt(value!);
-                        break;
-                }
-            }
-            if (!transportId) {
-                throw new Error(`No transport id for device ${serial}`);
-            }
-            devices.push({
-                serial,
-                authenticating: status === "unauthorized",
-                product,
-                model,
-                device,
-                transportId,
-            });
-        }
-        return devices;
-    }
-
     /**
-     * `adb devices -l`
+     * Get a list of connected devices from ADB Server.
+     *
+     * Equivalent ADB Command: `adb devices -l`
      */
     async getDevices(): Promise<AdbServerClient.Device[]> {
         const connection = await this.createConnection("host:devices-l");
         try {
             const response = await connection.readString();
-            return this.parseDeviceList(response);
+            return AdbServerClient.parseDeviceList(response);
         } finally {
             await connection.dispose();
         }
     }
 
     /**
-     * Track the device list.
-     *
-     * @param signal An optional `AbortSignal` to stop tracking
-     *
-     * When `signal` is aborted, `trackDevices` will return normally, instead of throwing `signal.reason`.
+     * Monitors device list changes.
      */
-    async *trackDevices(
-        signal?: AbortSignal,
-    ): AsyncGenerator<AdbServerClient.Device[], void, void> {
+    async trackDevices(): Promise<AdbServerClient.DeviceObserver> {
         const connection = await this.createConnection("host:track-devices-l");
-        try {
-            while (true) {
-                const response = await raceSignal(
-                    async () => await connection.readString(),
-                    signal,
-                );
-                const devices = this.parseDeviceList(response);
-                yield devices;
-            }
-        } catch (e) {
-            if (e === signal?.reason) {
-                return;
+
+        let current: AdbServerClient.Device[] = [];
+        const onError = new EventEmitter<Error>();
+        const onDeviceAdd = new EventEmitter<AdbServerClient.Device[]>();
+        const onDeviceRemove = new EventEmitter<AdbServerClient.Device[]>();
+        const onListChange = new EventEmitter<AdbServerClient.Device[]>();
+
+        void (async () => {
+            try {
+                while (true) {
+                    const response = await connection.readString();
+                    const next = AdbServerClient.parseDeviceList(response);
+
+                    const added: AdbServerClient.Device[] = [];
+                    for (const nextDevice of next) {
+                        const index = current.findIndex(
+                            (device) =>
+                                device.transportId === nextDevice.transportId,
+                        );
+                        if (index === -1) {
+                            added.push(nextDevice);
+                            continue;
+                        }
+
+                        current[index] = current[current.length - 1]!;
+                        current.length -= 1;
+                    }
+
+                    if (added.length) {
+                        onDeviceAdd.fire(added);
+                    }
+                    if (current.length) {
+                        onDeviceRemove.fire(current);
+                    }
+
+                    current = next;
+                    onListChange.fire(current);
+                }
+            } catch (e) {
+                onError.fire(e as Error);
             }
-        } finally {
-            await connection.dispose();
-        }
-    }
+        })();
 
-    formatDeviceService(
-        device: AdbServerClient.DeviceSelector,
-        command: string,
-    ) {
-        if (!device) {
-            return `host:${command}`;
-        }
-        if ("transportId" in device) {
-            return `host-transport-id:${device.transportId}:${command}`;
-        }
-        if ("serial" in device) {
-            return `host-serial:${device.serial}:${command}`;
-        }
-        if ("usb" in device) {
-            return `host-usb:${command}`;
-        }
-        if ("tcp" in device) {
-            return `host-local:${command}`;
-        }
-        throw new TypeError("Invalid device selector");
+        return {
+            onError: onError.event,
+            onDeviceAdd: onDeviceAdd.event,
+            onDeviceRemove: onDeviceRemove.event,
+            onListChange: onListChange.event,
+            get current() {
+                return current;
+            },
+            stop: () => connection.dispose(),
+        };
     }
 
     /**
@@ -335,7 +352,7 @@ export class AdbServerClient {
         const connection = await this.createConnection(
             device === "offline"
                 ? "host:reconnect-offline"
-                : this.formatDeviceService(device, "reconnect"),
+                : AdbServerClient.formatDeviceService(device, "reconnect"),
         );
         try {
             await connection.readString();
@@ -437,9 +454,7 @@ export class AdbServerClient {
                 transportId,
                 service,
                 readable: socket.readable,
-                writable: new WrapWritableStream(
-                    socket.writable,
-                ).bePipedThroughFrom(new MaybeConsumable.UnwrapStream()),
+                writable: socket.writable,
                 get closed() {
                     return socket.closed;
                 },
@@ -485,7 +500,7 @@ export class AdbServerClient {
 
         // `waitFor` can't use `connectDevice`, because the device
         // might not be available yet.
-        const service = this.formatDeviceService(
+        const service = AdbServerClient.formatDeviceService(
             device,
             `wait-for-${type}-${state}`,
         );
@@ -498,6 +513,9 @@ export class AdbServerClient {
         }
     }
 
+    /**
+     * Creates an ADB Transport for the specified device.
+     */
     async createTransport(
         device: AdbServerClient.DeviceSelector,
     ): Promise<AdbServerTransport> {
@@ -562,7 +580,7 @@ export namespace AdbServerClient {
     }
 
     export interface ServerConnection
-        extends ReadableWritablePair<Uint8Array, Uint8Array>,
+        extends ReadableWritablePair<Uint8Array, MaybeConsumable<Uint8Array>>,
             Closeable {
         get closed(): Promise<void>;
     }
@@ -570,22 +588,25 @@ export namespace AdbServerClient {
     export interface ServerConnector {
         connect(
             options?: ServerConnectionOptions,
-        ): ValueOrPromise<ServerConnection>;
+        ): MaybePromiseLike<ServerConnection>;
 
         addReverseTunnel(
             handler: AdbIncomingSocketHandler,
             address?: string,
-        ): ValueOrPromise<string>;
+        ): MaybePromiseLike<string>;
 
-        removeReverseTunnel(address: string): ValueOrPromise<void>;
+        removeReverseTunnel(address: string): MaybePromiseLike<void>;
 
-        clearReverseTunnels(): ValueOrPromise<void>;
+        clearReverseTunnels(): MaybePromiseLike<void>;
     }
 
     export interface Socket extends AdbSocket {
         transportId: bigint;
     }
 
+    /**
+     * A union type for selecting a device.
+     */
     export type DeviceSelector =
         | { transportId: bigint }
         | { serial: string }
@@ -732,4 +753,8 @@ export namespace AdbServerClient {
             }
         }
     }
+
+    export interface DeviceObserver extends DeviceObserverBase<Device> {
+        onError: Event<Error>;
+    }
 }

package/src/server/transport.ts

@@ -1,6 +1,6 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
 import { PromiseResolver } from "@yume-chan/async";
 import { AbortController } from "@yume-chan/stream-extra";
-import type { ValueOrPromise } from "@yume-chan/struct";
 
 import type {
     AdbIncomingSocketHandler,
@@ -76,9 +76,7 @@ export class AdbServerTransport implements AdbTransport {
 
     async connect(service: string): Promise<AdbSocket> {
         return await this.#client.createDeviceConnection(
-            {
-                transportId: this.transportId,
-            },
+            { transportId: this.transportId },
             service,
         );
     }
@@ -98,7 +96,7 @@ export class AdbServerTransport implements AdbTransport {
         await this.#client.connector.clearReverseTunnels();
     }
 
-    close(): ValueOrPromise<void> {
+    close(): MaybePromiseLike<void> {
         this.#closed.resolve();
         this.#waitAbortController.abort();
     }

package/src/utils/base64.ts

@@ -1,23 +1,31 @@
-// Array is faster than object literal or `Map`
-const charToIndex: number[] = [];
-const indexToChar: number[] = [];
-const paddingChar = "=".charCodeAt(0);
-
-function addRange(start: string, end: string) {
-    const charCodeStart = start.charCodeAt(0);
-    const charCodeEnd = end.charCodeAt(0);
-
-    for (let charCode = charCodeStart; charCode <= charCodeEnd; charCode += 1) {
-        charToIndex[charCode] = indexToChar.length;
-        indexToChar.push(charCode);
+const [charToIndex, indexToChar, paddingChar] = /* #__PURE__ */ (() => {
+    // Array is faster than object literal or `Map`
+    const charToIndex: number[] = [];
+    const indexToChar: number[] = [];
+    const paddingChar = "=".charCodeAt(0);
+
+    function addRange(start: string, end: string) {
+        const charCodeStart = start.charCodeAt(0);
+        const charCodeEnd = end.charCodeAt(0);
+
+        for (
+            let charCode = charCodeStart;
+            charCode <= charCodeEnd;
+            charCode += 1
+        ) {
+            charToIndex[charCode] = indexToChar.length;
+            indexToChar.push(charCode);
+        }
     }
-}
 
-addRange("A", "Z");
-addRange("a", "z");
-addRange("0", "9");
-addRange("+", "+");
-addRange("/", "/");
+    addRange("A", "Z");
+    addRange("a", "z");
+    addRange("0", "9");
+    addRange("+", "+");
+    addRange("/", "/");
+
+    return [charToIndex, indexToChar, paddingChar];
+})();
 
 /**
  * Calculate the required length of the output buffer for the given input length.

package/src/utils/no-op.ts

@@ -1,3 +1,4 @@
+/* #__NO_SIDE_EFFECTS__ */
 export const NOOP = () => {
     // no-op
 };

package/tsconfig.build.json

@@ -1,14 +1,3 @@
 {
-    "extends": "./node_modules/@yume-chan/tsconfig/tsconfig.base.json",
-    "references": [
-        {
-            "path": "../event/tsconfig.build.json"
-        },
-        {
-            "path": "../stream-extra/tsconfig.build.json"
-        },
-        {
-            "path": "../struct/tsconfig.build.json"
-        }
-    ]
+    "extends": "./node_modules/@yume-chan/tsconfig/tsconfig.base.json"
 }