@yume-chan/adb 0.0.24 → 1.0.0

package/src/daemon/dispatcher.ts

@@ -16,7 +16,7 @@ import {
     Consumable,
     WritableStream,
 } from "@yume-chan/stream-extra";
-import { EMPTY_UINT8_ARRAY, decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
+import { EmptyUint8Array, decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
 
 import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
 
@@ -259,7 +259,7 @@ export class AdbPacketDispatcher implements Closeable {
             AdbCommand.Close,
             packet.arg1,
             packet.arg0,
-            EMPTY_UINT8_ARRAY,
+            EmptyUint8Array,
         );
     }
 
@@ -271,7 +271,7 @@ export class AdbPacketDispatcher implements Closeable {
             payload = new Uint8Array(4);
             setUint32LittleEndian(payload, 0, ackBytes);
         } else {
-            payload = EMPTY_UINT8_ARRAY;
+            payload = EmptyUint8Array;
         }
 
         return this.sendPacket(AdbCommand.Okay, localId, remoteId, payload);
@@ -312,7 +312,7 @@ export class AdbPacketDispatcher implements Closeable {
                 AdbCommand.Close,
                 0,
                 remoteId,
-                EMPTY_UINT8_ARRAY,
+                EmptyUint8Array,
             );
             return;
         }
@@ -334,12 +334,12 @@ export class AdbPacketDispatcher implements Closeable {
                 remoteId,
                 this.options.initialDelayedAckBytes,
             );
-        } catch (e) {
+        } catch {
             await this.sendPacket(
                 AdbCommand.Close,
                 0,
                 remoteId,
-                EMPTY_UINT8_ARRAY,
+                EmptyUint8Array,
             );
         }
     }

package/src/daemon/packet.ts

@@ -1,32 +1,43 @@
 import { Consumable, TransformStream } from "@yume-chan/stream-extra";
-import Struct from "@yume-chan/struct";
+import type { StructInit, StructValue } from "@yume-chan/struct";
+import { buffer, s32, struct, u32 } from "@yume-chan/struct";
 
-export enum AdbCommand {
-    Auth = 0x48545541, // 'AUTH'
-    Close = 0x45534c43, // 'CLSE'
-    Connect = 0x4e584e43, // 'CNXN'
-    Okay = 0x59414b4f, // 'OKAY'
-    Open = 0x4e45504f, // 'OPEN'
-    Write = 0x45545257, // 'WRTE'
-}
+export const AdbCommand = {
+    Auth: 0x48545541, // 'AUTH'
+    Close: 0x45534c43, // 'CLSE'
+    Connect: 0x4e584e43, // 'CNXN'
+    Okay: 0x59414b4f, // 'OKAY'
+    Open: 0x4e45504f, // 'OPEN'
+    Write: 0x45545257, // 'WRTE'
+} as const;
+
+export type AdbCommand = (typeof AdbCommand)[keyof typeof AdbCommand];
 
-export const AdbPacketHeader = new Struct({ littleEndian: true })
-    .uint32("command")
-    .uint32("arg0")
-    .uint32("arg1")
-    .uint32("payloadLength")
-    .uint32("checksum")
-    .int32("magic");
+export const AdbPacketHeader = struct(
+    {
+        command: u32,
+        arg0: u32,
+        arg1: u32,
+        payloadLength: u32,
+        checksum: u32,
+        magic: s32,
+    },
+    { littleEndian: true },
+);
 
-export type AdbPacketHeader = (typeof AdbPacketHeader)["TDeserializeResult"];
+export type AdbPacketHeader = StructValue<typeof AdbPacketHeader>;
 
-type AdbPacketHeaderInit = (typeof AdbPacketHeader)["TInit"];
+type AdbPacketHeaderInit = StructInit<typeof AdbPacketHeader>;
 
-export const AdbPacket = new Struct({ littleEndian: true })
-    .concat(AdbPacketHeader)
-    .uint8Array("payload", { lengthField: "payloadLength" });
+export const AdbPacket = struct(
+    /* #__PURE__ */ (() => ({
+        ...AdbPacketHeader.fields,
+        payload: buffer("payloadLength"),
+    }))(),
+    { littleEndian: true },
+);
 
-export type AdbPacket = (typeof AdbPacket)["TDeserializeResult"];
+export type AdbPacket = StructValue<typeof AdbPacket>;
 
 /**
  * `AdbPacketData` contains all the useful fields of `AdbPacket`.
@@ -39,11 +50,11 @@ export type AdbPacket = (typeof AdbPacket)["TDeserializeResult"];
  * so `AdbSocket#writable#write` only needs `AdbPacketData`.
  */
 export type AdbPacketData = Omit<
-    (typeof AdbPacket)["TInit"],
+    StructInit<typeof AdbPacket>,
     "checksum" | "magic"
 >;
 
-export type AdbPacketInit = (typeof AdbPacket)["TInit"];
+export type AdbPacketInit = StructInit<typeof AdbPacket>;
 
 export function calculateChecksum(payload: Uint8Array): number {
     return payload.reduce((result, item) => result + item, 0);
@@ -61,9 +72,10 @@ export class AdbPacketSerializeStream extends TransformStream<
                     const init = chunk as AdbPacketInit & AdbPacketHeaderInit;
                     init.payloadLength = init.payload.length;
 
+                    AdbPacketHeader.serialize(init, headerBuffer);
                     await Consumable.ReadableStream.enqueue(
                         controller,
-                        AdbPacketHeader.serialize(init, headerBuffer),
+                        headerBuffer,
                     );
 
                     if (init.payloadLength) {

package/src/daemon/socket.ts

@@ -7,7 +7,7 @@ import type {
     WritableStreamDefaultController,
 } from "@yume-chan/stream-extra";
 import { MaybeConsumable, PushReadableStream } from "@yume-chan/stream-extra";
-import { EMPTY_UINT8_ARRAY } from "@yume-chan/struct";
+import { EmptyUint8Array } from "@yume-chan/struct";
 
 import type { AdbSocket } from "../adb.js";
 
@@ -138,20 +138,7 @@ export class AdbDaemonSocketController
     }
 
     async enqueue(data: Uint8Array) {
-        // Consumers can `cancel` the `readable` if they are not interested in future data.
-        // Throw away the data if that happens.
-        if (this.#readableController.abortSignal.aborted) {
-            return;
-        }
-
-        try {
-            await this.#readableController.enqueue(data);
-        } catch (e) {
-            if (this.#readableController.abortSignal.aborted) {
-                return;
-            }
-            throw e;
-        }
+        await this.#readableController.enqueue(data);
     }
 
     public ack(bytes: number) {
@@ -177,28 +164,18 @@ export class AdbDaemonSocketController
             AdbCommand.Close,
             this.localId,
             this.remoteId,
-            EMPTY_UINT8_ARRAY,
+            EmptyUint8Array,
         );
     }
 
     dispose() {
-        try {
-            this.#readableController.close();
-        } catch {
-            // ignore
-        }
-
+        this.#readableController.close();
         this.#closedPromise.resolve();
     }
 }
 
 /**
  * A duplex stream representing a socket to ADB daemon.
- *
- * To close it, call either `socket.close()`,
- * `socket.readable.cancel()`, `socket.readable.getReader().cancel()`,
- * `socket.writable.abort()`, `socket.writable.getWriter().abort()`,
- * `socket.writable.close()` or `socket.writable.getWriter().close()`.
  */
 export class AdbDaemonSocket implements AdbDaemonSocketInfo, AdbSocket {
     #controller: AdbDaemonSocketController;

package/src/daemon/transport.ts

@@ -1,3 +1,4 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
 import { PromiseResolver } from "@yume-chan/async";
 import type { ReadableWritablePair } from "@yume-chan/stream-extra";
 import {
@@ -5,7 +6,6 @@ import {
     Consumable,
     WritableStream,
 } from "@yume-chan/stream-extra";
-import type { ValueOrPromise } from "@yume-chan/struct";
 import { decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
 
 import type {
@@ -28,27 +28,28 @@ import { AdbCommand, calculateChecksum } from "./packet.js";
 export const ADB_DAEMON_VERSION_OMIT_CHECKSUM = 0x01000001;
 // https://android.googlesource.com/platform/packages/modules/adb/+/79010dc6d5ca7490c493df800d4421730f5466ca/transport.cpp#1252
 // There are some other feature constants, but some of them are only used by ADB server, not devices (daemons).
-export const ADB_DAEMON_DEFAULT_FEATURES = [
-    AdbFeature.ShellV2,
-    AdbFeature.Cmd,
-    AdbFeature.StatV2,
-    AdbFeature.ListV2,
-    AdbFeature.FixedPushMkdir,
-    "apex",
-    AdbFeature.Abb,
-    // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
-    // No special handling required.
-    "fixed_push_symlink_timestamp",
-    AdbFeature.AbbExec,
-    "remount_shell",
-    "track_app",
-    AdbFeature.SendReceiveV2,
-    "sendrecv_v2_brotli",
-    "sendrecv_v2_lz4",
-    "sendrecv_v2_zstd",
-    "sendrecv_v2_dry_run_send",
-    AdbFeature.DelayedAck,
-] as AdbFeature[];
+export const ADB_DAEMON_DEFAULT_FEATURES = /* #__PURE__ */ (() =>
+    [
+        AdbFeature.ShellV2,
+        AdbFeature.Cmd,
+        AdbFeature.StatV2,
+        AdbFeature.ListV2,
+        AdbFeature.FixedPushMkdir,
+        "apex",
+        AdbFeature.Abb,
+        // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
+        // No special handling required.
+        "fixed_push_symlink_timestamp",
+        AdbFeature.AbbExec,
+        "remount_shell",
+        "track_app",
+        AdbFeature.SendReceiveV2,
+        "sendrecv_v2_brotli",
+        "sendrecv_v2_lz4",
+        "sendrecv_v2_zstd",
+        "sendrecv_v2_dry_run_send",
+        AdbFeature.DelayedAck,
+    ] as AdbFeature[])();
 export const ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE = 32 * 1024 * 1024;
 
 export type AdbDaemonConnection = ReadableWritablePair<
@@ -114,13 +115,15 @@ interface AdbDaemonSocketConnectorConstructionOptions {
 
     /**
      * The number of bytes the device can send before receiving an ack packet.
-     * Using delayed ack can improve the throughput,
-     * especially when the device is connected over Wi-Fi (so the latency is higher).
+     *
+     * On Android 14 and newer, the Delayed Acknowledgement feature is added to
+     * improve performance, especially for high-latency connections like ADB over Wi-Fi.
      *
      * When `features` doesn't include `AdbFeature.DelayedAck`, it must be set to 0. Otherwise,
-     * the value must be in the range of unsigned 32-bit integer. If the device enabled
-     * delayed ack but the client didn't, the device will throw an error when the client sends
-     * the first data packet. And vice versa.
+     * the value must be in the range of unsigned 32-bit integer.
+     *
+     * If the device enabled delayed ack but the client didn't, the device will throw an error
+     * when the client sends the first data packet. And vice versa.
      */
     initialDelayedAckBytes: number;
 
@@ -146,14 +149,12 @@ interface AdbDaemonSocketConnectorConstructionOptions {
     readTimeLimit?: number | undefined;
 }
 
+/**
+ * An ADB Transport that connects to ADB Daemons directly.
+ */
 export class AdbDaemonTransport implements AdbTransport {
     /**
-     * Authenticates the connection and creates an `AdbDaemonTransport` instance
-     * that can be used by `Adb` class.
-     *
-     * If an authentication process failed,
-     * no matter which value the `preserveConnection` option has,
-     * the `connection` is always kept open, so it can be used in another `authenticate` call.
+     * Authenticate with the ADB Daemon and create a new transport.
      */
     static async authenticate({
         serial,
@@ -364,7 +365,7 @@ export class AdbDaemonTransport implements AdbTransport {
         this.#protocolVersion = version;
     }
 
-    connect(service: string): ValueOrPromise<AdbSocket> {
+    connect(service: string): MaybePromiseLike<AdbSocket> {
         return this.#dispatcher.createSocket(service);
     }
 
@@ -388,7 +389,7 @@ export class AdbDaemonTransport implements AdbTransport {
         this.#dispatcher.clearReverseTunnels();
     }
 
-    close(): ValueOrPromise<void> {
+    close(): MaybePromiseLike<void> {
         return this.#dispatcher.close();
     }
 }

package/src/device-observer.ts

@@ -0,0 +1,10 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type { Event } from "@yume-chan/event";
+
+export interface DeviceObserver<T> {
+    onDeviceAdd: Event<T[]>;
+    onDeviceRemove: Event<T[]>;
+    onListChange: Event<T[]>;
+    current: T[];
+    stop(): MaybePromiseLike<void>;
+}

package/src/features.ts

@@ -1,13 +1,15 @@
 // The order follows
 // https://cs.android.com/android/platform/superproject/+/master:packages/modules/adb/transport.cpp;l=77;drc=6d14d35d0241f6fee145f8e54ffd77252e8d29fd
-export enum AdbFeature {
-    ShellV2 = "shell_v2",
-    Cmd = "cmd",
-    StatV2 = "stat_v2",
-    ListV2 = "ls_v2",
-    FixedPushMkdir = "fixed_push_mkdir",
-    Abb = "abb",
-    AbbExec = "abb_exec",
-    SendReceiveV2 = "sendrecv_v2",
-    DelayedAck = "delayed_ack",
-}
+export const AdbFeature = {
+    ShellV2: "shell_v2",
+    Cmd: "cmd",
+    StatV2: "stat_v2",
+    ListV2: "ls_v2",
+    FixedPushMkdir: "fixed_push_mkdir",
+    Abb: "abb",
+    AbbExec: "abb_exec",
+    SendReceiveV2: "sendrecv_v2",
+    DelayedAck: "delayed_ack",
+} as const;
+
+export type AdbFeature = (typeof AdbFeature)[keyof typeof AdbFeature];

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./adb.js";
 export * from "./banner.js";
 export * from "./commands/index.js";
 export * from "./daemon/index.js";
+export * from "./device-observer.js";
 export * from "./features.js";
 export * from "./server/index.js";
 export * from "./utils/index.js";