@yume-chan/adb 2.0.1 → 2.3.1

package/src/banner.ts

@@ -66,7 +66,7 @@ export class AdbBanner {
         return this.#device;
     }
 
-    readonly #features: AdbFeature[] = [];
+    readonly #features: readonly AdbFeature[] = [];
     get features() {
         return this.#features;
     }
@@ -75,7 +75,7 @@ export class AdbBanner {
         product: string | undefined,
         model: string | undefined,
         device: string | undefined,
-        features: AdbFeature[],
+        features: readonly AdbFeature[],
     ) {
         this.#product = product;
         this.#model = model;

package/src/commands/subprocess/none/service.ts

@@ -28,7 +28,9 @@ export class AdbNoneProtocolSubprocessService extends AdbNoneProtocolSpawner {
         this.#adb = adb;
     }
 
-    async pty(command?: string | string[]): Promise<AdbNoneProtocolPtyProcess> {
+    async pty(
+        command?: string | readonly string[],
+    ): Promise<AdbNoneProtocolPtyProcess> {
         if (command === undefined) {
             command = "";
         } else if (Array.isArray(command)) {
@@ -36,7 +38,8 @@ export class AdbNoneProtocolSubprocessService extends AdbNoneProtocolSpawner {
         }
 
         return new AdbNoneProtocolPtyProcess(
-            await this.#adb.createSocket(`shell:${command}`),
+            // https://github.com/microsoft/typescript/issues/17002
+            await this.#adb.createSocket(`shell:${command as string}`),
         );
     }
 }

package/src/commands/subprocess/none/spawner.ts

@@ -28,13 +28,13 @@ export interface AdbNoneProtocolProcess {
 
 export class AdbNoneProtocolSpawner {
     readonly #spawn: (
-        command: string[],
+        command: readonly string[],
         signal: AbortSignal | undefined,
     ) => Promise<AdbNoneProtocolProcess>;
 
     constructor(
         spawn: (
-            command: string[],
+            command: readonly string[],
             signal: AbortSignal | undefined,
         ) => Promise<AdbNoneProtocolProcess>,
     ) {
@@ -42,7 +42,7 @@ export class AdbNoneProtocolSpawner {
     }
 
     spawn(
-        command: string | string[],
+        command: string | readonly string[],
         signal?: AbortSignal,
     ): Promise<AdbNoneProtocolProcess> {
         signal?.throwIfAborted();
@@ -54,12 +54,12 @@ export class AdbNoneProtocolSpawner {
         return this.#spawn(command, signal);
     }
 
-    async spawnWait(command: string | string[]): Promise<Uint8Array> {
+    async spawnWait(command: string | readonly string[]): Promise<Uint8Array> {
         const process = await this.spawn(command);
         return await process.output.pipeThrough(new ConcatBufferStream());
     }
 
-    async spawnWaitText(command: string | string[]): Promise<string> {
+    async spawnWaitText(command: string | readonly string[]): Promise<string> {
         const process = await this.spawn(command);
         return await process.output
             .pipeThrough(new TextDecoderStream())

package/src/commands/subprocess/shell/service.ts

@@ -32,7 +32,7 @@ export class AdbShellProtocolSubprocessService extends AdbShellProtocolSpawner {
     }
 
     async pty(options?: {
-        command?: string | string[] | undefined;
+        command?: string | readonly string[] | undefined;
         terminalType?: string;
     }): Promise<AdbShellProtocolPtyProcess> {
         let service = "shell,v2,pty";

package/src/commands/subprocess/shell/spawner.ts

@@ -26,13 +26,13 @@ export interface AdbShellProtocolProcess {
 
 export class AdbShellProtocolSpawner {
     readonly #spawn: (
-        command: string[],
+        command: readonly string[],
         signal: AbortSignal | undefined,
     ) => Promise<AdbShellProtocolProcess>;
 
     constructor(
         spawn: (
-            command: string[],
+            command: readonly string[],
             signal: AbortSignal | undefined,
         ) => Promise<AdbShellProtocolProcess>,
     ) {
@@ -40,7 +40,7 @@ export class AdbShellProtocolSpawner {
     }
 
     spawn(
-        command: string | string[],
+        command: string | readonly string[],
         signal?: AbortSignal,
     ): Promise<AdbShellProtocolProcess> {
         signal?.throwIfAborted();
@@ -53,7 +53,7 @@ export class AdbShellProtocolSpawner {
     }
 
     async spawnWait(
-        command: string | string[],
+        command: string | readonly string[],
     ): Promise<AdbShellProtocolSpawner.WaitResult<Uint8Array>> {
         const process = await this.spawn(command);
         const [stdout, stderr, exitCode] = await Promise.all([
@@ -65,7 +65,7 @@ export class AdbShellProtocolSpawner {
     }
 
     async spawnWaitText(
-        command: string | string[],
+        command: string | readonly string[],
     ): Promise<AdbShellProtocolSpawner.WaitResult<string>> {
         const process = await this.spawn(command);
         const [stdout, stderr, exitCode] = await Promise.all([

package/src/commands/sync/response.ts

@@ -4,7 +4,7 @@ import { decodeUtf8, string, struct, u32 } from "@yume-chan/struct";
 
 import { unreachable } from "../../utils/no-op.js";
 
-function encodeAsciiUnchecked(value: string): Uint8Array {
+function encodeAsciiUnchecked(value: string): Uint8Array<ArrayBuffer> {
     const result = new Uint8Array(value.length);
     for (let i = 0; i < value.length; i += 1) {
         result[i] = value.charCodeAt(i);

package/src/daemon/auth.ts

@@ -139,7 +139,7 @@ export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
     };
 };
 
-export const ADB_DEFAULT_AUTHENTICATORS: AdbAuthenticator[] = [
+export const ADB_DEFAULT_AUTHENTICATORS: readonly AdbAuthenticator[] = [
     AdbSignatureAuthenticator,
     AdbPublicKeyAuthenticator,
 ];

package/src/daemon/crypto.ts

@@ -140,7 +140,9 @@ export function adbGetPublicKeySize() {
     return 4 + 4 + ModulusLengthInBytes + ModulusLengthInBytes + 4;
 }
 
-export function adbGeneratePublicKey(privateKey: Uint8Array): Uint8Array;
+export function adbGeneratePublicKey(
+    privateKey: Uint8Array,
+): Uint8Array<ArrayBuffer>;
 export function adbGeneratePublicKey(
     privateKey: Uint8Array,
     output: Uint8Array,
@@ -287,7 +289,10 @@ export const SHA1_DIGEST_INFO = new Uint8Array([
 // encrypt the given data with its private key)
 // However SubtileCrypto.encrypt() doesn't accept 'RSASSA-PKCS1-v1_5' algorithm
 // So we need to implement the encryption by ourself
-export function rsaSign(privateKey: Uint8Array, data: Uint8Array): Uint8Array {
+export function rsaSign(
+    privateKey: Uint8Array,
+    data: Uint8Array,
+): Uint8Array<ArrayBuffer> {
     const [n, d] = rsaParsePrivateKey(privateKey);
 
     // PKCS#1 padding

package/src/daemon/transport.ts

@@ -49,7 +49,7 @@ export const ADB_DAEMON_DEFAULT_FEATURES = /* #__PURE__ */ (() =>
         "sendrecv_v2_zstd",
         "sendrecv_v2_dry_run_send",
         AdbFeature.DelayedAck,
-    ] as AdbFeature[])();
+    ] as readonly AdbFeature[])();
 export const ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE = 32 * 1024 * 1024;
 
 export type AdbDaemonConnection = ReadableWritablePair<
@@ -61,7 +61,7 @@ export interface AdbDaemonAuthenticationOptions {
     serial: string;
     connection: AdbDaemonConnection;
     credentialStore: AdbCredentialStore;
-    authenticators?: AdbAuthenticator[];
+    authenticators?: readonly AdbAuthenticator[];
     features?: readonly AdbFeature[];
 
     /**

package/src/server/client.ts

@@ -12,6 +12,7 @@ import type {
 import { AbortController } from "@yume-chan/stream-extra";
 
 import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
+import { Adb } from "../adb.js";
 import { AdbBanner } from "../banner.js";
 import type { DeviceObserver as DeviceObserverBase } from "../device-observer.js";
 import type { AdbFeature } from "../features.js";
@@ -36,7 +37,13 @@ export class AdbServerClient {
     static UnauthorizedError = _UnauthorizedError;
     static AlreadyConnectedError = _AlreadyConnectedError;
 
-    static parseDeviceList(value: string): AdbServerClient.Device[] {
+    static parseDeviceList(
+        value: string,
+        includeStates: readonly AdbServerClient.ConnectionState[] = [
+            "device",
+            "unauthorized",
+        ],
+    ): AdbServerClient.Device[] {
         const devices: AdbServerClient.Device[] = [];
         for (const line of value.split("\n")) {
             if (!line) {
@@ -45,8 +52,8 @@ export class AdbServerClient {
 
             const parts = line.split(" ").filter(Boolean);
             const serial = parts[0]!;
-            const status = parts[1]!;
-            if (status !== "device" && status !== "unauthorized") {
+            const state = parts[1]! as AdbServerClient.ConnectionState;
+            if (!includeStates.includes(state)) {
                 continue;
             }
 
@@ -76,7 +83,8 @@ export class AdbServerClient {
             }
             devices.push({
                 serial,
-                authenticating: status === "unauthorized",
+                state,
+                authenticating: state === "unauthorized",
                 product,
                 model,
                 device,
@@ -192,11 +200,16 @@ export class AdbServerClient {
      *
      * Equivalent ADB Command: `adb devices -l`
      */
-    async getDevices(): Promise<AdbServerClient.Device[]> {
+    async getDevices(
+        includeStates: readonly AdbServerClient.ConnectionState[] = [
+            "device",
+            "unauthorized",
+        ],
+    ): Promise<AdbServerClient.Device[]> {
         const connection = await this.createConnection("host:devices-l");
         try {
             const response = await connection.readString();
-            return AdbServerClient.parseDeviceList(response);
+            return AdbServerClient.parseDeviceList(response, includeStates);
         } finally {
             await connection.dispose();
         }
@@ -206,7 +219,7 @@ export class AdbServerClient {
      * Monitors device list changes.
      */
     async trackDevices(
-        options?: AdbServerClient.ServerConnectionOptions,
+        options?: AdbServerDeviceObserverOwner.Options,
     ): Promise<AdbServerClient.DeviceObserver> {
         return this.#observerOwner.createObserver(options);
     }
@@ -236,7 +249,7 @@ export class AdbServerClient {
      */
     async getDeviceFeatures(
         device: AdbServerClient.DeviceSelector,
-    ): Promise<{ transportId: bigint; features: AdbFeature[] }> {
+    ): Promise<{ transportId: bigint; features: readonly AdbFeature[] }> {
         // On paper, `host:features` is a host service (device features are cached in host),
         // so it shouldn't use `createDeviceConnection`,
         // which is used to forward the service to the device.
@@ -462,6 +475,11 @@ export class AdbServerClient {
 
         return transport;
     }
+
+    async createAdb(device: AdbServerClient.DeviceSelector) {
+        const transport = await this.createTransport(device);
+        return new Adb(transport);
+    }
 }
 
 export async function raceSignal<T>(
@@ -536,8 +554,12 @@ export namespace AdbServerClient {
         | { tcp: true }
         | undefined;
 
+    export type ConnectionState = "unauthorized" | "offline" | "device";
+
     export interface Device {
         serial: string;
+        state: ConnectionState;
+        /** @deprecated Use {@link state} instead */
         authenticating: boolean;
         product?: string | undefined;
         model?: string | undefined;

package/src/server/observer.ts

@@ -13,17 +13,28 @@ export function unorderedRemove<T>(array: T[], index: number) {
     array.length -= 1;
 }
 
+interface Observer {
+    includeStates: readonly AdbServerClient.ConnectionState[];
+    onDeviceAdd: EventEmitter<readonly AdbServerClient.Device[]>;
+    onDeviceRemove: EventEmitter<readonly AdbServerClient.Device[]>;
+    onListChange: EventEmitter<readonly AdbServerClient.Device[]>;
+    onError: EventEmitter<Error>;
+}
+
+function filterDeviceStates(
+    devices: readonly AdbServerClient.Device[],
+    states: readonly AdbServerClient.ConnectionState[],
+) {
+    return devices.filter((device) => states.includes(device.state));
+}
+
 export class AdbServerDeviceObserverOwner {
     current: readonly AdbServerClient.Device[] = [];
 
     readonly #client: AdbServerClient;
+
     #stream: Promise<AdbServerStream> | undefined;
-    #observers: {
-        onDeviceAdd: EventEmitter<readonly AdbServerClient.Device[]>;
-        onDeviceRemove: EventEmitter<readonly AdbServerClient.Device[]>;
-        onListChange: EventEmitter<readonly AdbServerClient.Device[]>;
-        onError: EventEmitter<Error>;
-    }[] = [];
+    #observers: Observer[] = [];
 
     constructor(client: AdbServerClient) {
         this.#client = client;
@@ -52,17 +63,33 @@ export class AdbServerDeviceObserverOwner {
 
         if (added.length) {
             for (const observer of this.#observers) {
-                observer.onDeviceAdd.fire(added);
+                const filtered = filterDeviceStates(
+                    added,
+                    observer.includeStates,
+                );
+                if (filtered.length) {
+                    observer.onDeviceAdd.fire(filtered);
+                }
             }
         }
         if (removed.length) {
             for (const observer of this.#observers) {
-                observer.onDeviceRemove.fire(removed);
+                const filtered = filterDeviceStates(
+                    removed,
+                    observer.includeStates,
+                );
+                if (filtered.length) {
+                    observer.onDeviceRemove.fire(removed);
+                }
             }
         }
 
         for (const observer of this.#observers) {
-            observer.onListChange.fire(this.current);
+            const filtered = filterDeviceStates(
+                this.current,
+                observer.includeStates,
+            );
+            observer.onListChange.fire(filtered);
         }
     }
 
@@ -104,10 +131,11 @@ export class AdbServerDeviceObserverOwner {
     }
 
     async createObserver(
-        options?: AdbServerClient.ServerConnectionOptions,
+        options?: AdbServerDeviceObserverOwner.Options,
     ): Promise<AdbServerClient.DeviceObserver> {
         options?.signal?.throwIfAborted();
 
+        let current: readonly AdbServerClient.Device[] = [];
         const onDeviceAdd = new EventEmitter<
             readonly AdbServerClient.Device[]
         >();
@@ -119,13 +147,27 @@ export class AdbServerDeviceObserverOwner {
         >();
         const onError = new StickyEventEmitter<Error>();
 
-        const observer = { onDeviceAdd, onDeviceRemove, onListChange, onError };
+        const includeStates = options?.includeStates ?? [
+            "device",
+            "unauthorized",
+        ];
+        const observer = {
+            includeStates,
+            onDeviceAdd,
+            onDeviceRemove,
+            onListChange,
+            onError,
+        } satisfies Observer;
         // Register `observer` before `#connect`.
         // So `#handleObserverStop` knows if there is any observer.
         this.#observers.push(observer);
 
+        // Read the filtered `current` value from `onListChange` event
+        onListChange.event((value) => (current = value));
+
         let stream: AdbServerStream;
         if (!this.#stream) {
+            // `#connect` will initialize `onListChange` and `current`
             this.#stream = this.#connect();
 
             try {
@@ -136,7 +178,8 @@ export class AdbServerDeviceObserverOwner {
             }
         } else {
             stream = await this.#stream;
-            onListChange.fire(this.current);
+            // Initialize `onListChange` and `current` ourselves
+            onListChange.fire(filterDeviceStates(this.current, includeStates));
         }
 
         const ref = new Ref(options);
@@ -156,17 +199,21 @@ export class AdbServerDeviceObserverOwner {
             options.signal.addEventListener("abort", () => void stop());
         }
 
-        // eslint-disable-next-line @typescript-eslint/no-this-alias
-        const _this = this;
         return {
             onDeviceAdd: onDeviceAdd.event,
             onDeviceRemove: onDeviceRemove.event,
             onListChange: onListChange.event,
             onError: onError.event,
             get current() {
-                return _this.current;
+                return current;
             },
             stop,
         };
     }
 }
+
+export namespace AdbServerDeviceObserverOwner {
+    export interface Options extends AdbServerClient.ServerConnectionOptions {
+        includeStates?: readonly AdbServerClient.ConnectionState[];
+    }
+}

package/src/server/transport.ts

@@ -30,7 +30,7 @@ export const ADB_SERVER_DEFAULT_FEATURES = /* #__PURE__ */ (() =>
         "sendrecv_v2_lz4",
         "sendrecv_v2_zstd",
         "sendrecv_v2_dry_run_send",
-    ] as AdbFeature[])();
+    ] as readonly AdbFeature[])();
 
 export class AdbServerTransport implements AdbTransport {
     #client: AdbServerClient;

package/src/utils/array-buffer.ts

@@ -0,0 +1,9 @@
+export function toLocalUint8Array(value: Uint8Array): Uint8Array<ArrayBuffer> {
+    if (value.buffer instanceof ArrayBuffer) {
+        return value as Uint8Array<ArrayBuffer>;
+    }
+
+    const copy = new Uint8Array(value.length);
+    copy.set(value);
+    return copy;
+}

package/src/utils/base64.ts

@@ -47,7 +47,7 @@ export function calculateBase64EncodedLength(
  * @param input The input buffer
  * @returns The encoded output buffer
  */
-export function encodeBase64(input: Uint8Array): Uint8Array;
+export function encodeBase64(input: Uint8Array): Uint8Array<ArrayBuffer>;
 /**
  * Encode the given input into base64 and write it to the output buffer.
  *
@@ -295,7 +295,7 @@ function encodeBackward(
     }
 }
 
-export function decodeBase64(input: string): Uint8Array {
+export function decodeBase64(input: string): Uint8Array<ArrayBuffer> {
     let padding: number;
     if (input[input.length - 2] === "=") {
         padding = 2;

package/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
+export * from "./array-buffer.js";
 export * from "./auto-reset-event.js";
 export * from "./base64.js";
 export * from "./hex.js";