Tango

https://github.com/yume-chan/ya-webadb
Admin
Tango is a TypeScript re-implementation of ADB (Android Debugging Bridge) that enables debugging...
Tokens:6,681
Snippets:81
Trust Score:8.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Install all project dependencies using PNPM.

```sh
$ pnpm install
```

--------------------------------

### Quick Start: Define and use a struct

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/struct/README.md

Defines a struct with various field types (u8, u16, s32, buffer, string) and demonstrates synchronous and asynchronous deserialization and serialization. The example includes a custom reader and a custom buffer conversion.

```ts
import { struct, u8, u16, s32, buffer, string } from "@yume-chan/struct";

const Message = struct(
    {
        a: u8,
        b: u16,
        c: s32,
        d: buffer(4), // Fixed length Uint8Array
        e: buffer("b"), // Use value of `b` as length
        f: buffer(u32), // `u32` length prefix
        g: buffer(4, {
            // Custom conversion between `Uint8Array` and other types
            convert(value: Uint8Array) {
                return value[0];
            },
            back(value: number) {
                return new Uint8Array([value, 0, 0, 0]);
            },
        }),
        h: string(64), // `string` is an alias to `buffer` with UTF-8 string conversion
    },
    { littleEndian: true },
);

// Custom reader
const reader = {
    position: 0,
    readExactly(length) {
        const slice = new Uint8Array(100).slice(
            this.position,
            this.position + length,
        );
        this.position += length;
        return slice;
    },
};

const message1 = Message.deserialize(reader); // If `reader.readExactly` is synchronous, `deserialize` is also synchronous
const message2 = await Message.deserialize(reader); // If `reader.readExactly` is asynchronous, so do `deserialize`

const buffer: Uint8Array = Message.serialize(message1);
```

--------------------------------

### Initialize and play audio with Int16PcmPlayer

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/pcm-player/README.md

Demonstrates initializing an Int16PcmPlayer with a 44100Hz sample rate, starting the player, feeding it audio data, and stopping it. Note that stopping the player closes the AudioContext, preventing it from being restarted.

```ts
var player = Int16PcmPlayer(44100);
player.start();
player.feed(new Int16Array([0, 0, 0, 0, 0, 0, 0, 0]));
player.stop(); // `AudioContext` will be closed, so can't be restarted
```

--------------------------------

### Install PNPM globally

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Install the PNPM package manager globally on your system.

```sh
$ npm i -g pnpm
```

--------------------------------

### Install @yume-chan/struct with npm

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/struct/README.md

Install the package using npm. The command is shown in a shell code block.

```sh
$ npm i @yume-chan/struct
```

--------------------------------

### Bipedal: Synchronous or asynchronous helper

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/struct/README.md

Shows how to use the bipedal helper to create a function that can be called synchronously or asynchronously depending on the input. The example defines a function that prepends 'Hello, ' to a name and demonstrates both sync and async calls.

```ts
import { bipedal } from "@yume-chan/struct";

const fn = bipedal(function* (then, name: string | Promise<string>) {
    name = yield* then(name);
    return "Hello, " + name;
});

fn("Simon"); // "Hello, Simon"
await fn(Promise.resolve("Simon")); // "Hello, Simon"
```

--------------------------------

### EventEmitter usage example

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

Shows how to subscribe to an event, fire it, and unsubscribe. The returned unsubscribe function is both a function and a Disposable, so it can be used with AutoDisposable or DisposableList.

```ts
const emitter = new EventEmitter<void>();
const subscribe = emitter.event;
const unsubscribe = subscribe(() => {});
emitter.fire();
unsubscribe();
```

--------------------------------

### Custom field types: Define a custom field

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/struct/README.md

Shows how to create a custom field type by implementing the Field interface. The example defines a field with size, dynamicSize, serialize, and deserialize methods, then uses it in a struct.

```ts
import { Field, AsyncExactReadable, Struct, u8 } from "@yume-chan/struct";

const MyField: Field<number, never, never> = {
    size: 4, // `0` if dynamically sized,
    dynamicSize(value: number) {
        // Optional, return dynamic size for value
        return 0;
    },
    serialize(
        value: number,
        context: { buffer: Uint8Array; index: number; littleEndian: boolean },
    ) {
        // Serialize value to `context.buffer` at `context.index`
    },
    deserialize(context: {
        reader: AsyncExactReadable;
        littleEndian: boolean;
    }) {
        // Deserialize value from `context.reader`
        return 0;
    },
};

const Message2 = struct({
    a: u8,
    b: MyField,
});
```

--------------------------------

### AutoDisposable usage example

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

Example of using AutoDisposable as a base class. Derived classes must call super.dispose() in their own dispose method to trigger cleanup of registered disposables.

```ts
class MyObject extends AutoDisposable {
    private event1 = this.addDisposable(new EventEmitter<void>());

    private event2 = this.addDisposable(new EventEmitter<void>());

    public dispose() {
        // If the derived class has its own dispose logic
        // Don't forget to call super's `dispose`
        super.dispose();

        // Clean up itself.
    }
}
```

--------------------------------

### getInt8 example

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/no-data-view/README.md

Shows that assigning -1 to a Uint8Array element stores 255, and that getInt8 reads the signed value correctly. Use this to understand why setInt8 is not provided.

```ts
import { getInt8 } from "@yume-chan/no-data-view";

const array = new Uint8Array(1);
array[0] = -1;
console.log(array[0]); // 255
console.log(new Int8Array(array.buffer)[0]); // -1
console.log(getInt8(array, 0)); // -1
```

--------------------------------

### Build all packages

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Build all packages within the monorepo.

```sh
$ pnpm build
```

--------------------------------

### Run ESLint and Prettier

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Run linting and formatting checks across the project.

```sh
$ pnpm lint
```

--------------------------------

### CLI usage and commands

Source: https://github.com/yume-chan/ya-webadb/blob/main/apps/cli/README.md

Shows the command-line usage and available commands for the @yume-chan/adb-cli tool. It requires a native Google ADB server running on the host machine. The options include -H for server host (default 127.0.0.1) and -P for port (default 5037). Commands include devices, shell, logcat, reboot, usb, tcpip, kill-server, and help.

```txt
Usage: tango-cli [options] [command]

Options:
  -H <host>                                                   name of adb server host (default: "127.0.0.1")
  -P <port>                                                   port of adb server (default: 5037)
  -h, --help                                                  display help for command

Commands:
  devices [-l]                                                list connected devices (-l for long output)
  shell [options] [-- <args...>]                              run remote shell command (interactive shell if no command
                                                              given). `--` is required before command name.
  logcat [-- <args...>                                        show device log (logcat --help for more)
  reboot [bootloader|recovery|sideload|sideload-auto-reboot]  reboot the device; defaults to booting system image but
                                                              supports bootloader and recovery too. sideload reboots
                                                              into recovery and automatically starts sideload mode,
                                                              sideload-auto-reboot is the same but reboots after
                                                              sideloading.
  usb                                                         restart adbd listening on USB
  tcpip port                                                  restart adbd listening on TCP on PORT
  kill-server                                                 kill the server if it is running
  help [command]                                              display help for command
```

--------------------------------

### Clone and enter the repository

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Clone the ya-webadb repository and navigate into the project directory.

```sh
git clone https://github.com/yume-chan/ya-webadb.git
cd ya-webadb
```

--------------------------------

### Add a new changelog

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Use the changeset command to document changes for a pull request.

```sh
$ pnpm changeset
```

--------------------------------

### Run all tests

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Execute the test suite using the Node.js built-in test runner.

```sh
$ pnpm test
```

--------------------------------

### Release new versions

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Commands to version the packages, commit the changes, and push tags to trigger the release workflow.

```sh
pnpm changeset version
git add -A
git commit -m "chore: release new version"
git push
git tag vX.Y.Z
git push --tags
```

--------------------------------

### Wrap native ReadableStream to pipe to polyfill WritableStream

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/stream-extra/README.md

Demonstrates using WrapReadableStream to enable piping a native ReadableStream to a web-streams-polyfill WritableStream. Native pipeTo checks for native WritableStream instances and throws an error with a polyfill, but WrapReadableStream bypasses this.

```TypeScript
import { WrapReadableStream } from "@yume-chan/stream-extra";
import { WritableStream as PolyfillWritableStream } from "web-streams-polyfill";

const nativeReadable = new globalThis.ReadableStream();
const wrappedReadable = new WrapReadableStream(new globalThis.ReadableStream());

nativeReadable.pipeTo(new PolyfillWritableStream()); // Error
wrappedReadable.pipeTo(new PolyfillWritableStream()); // OK
```

--------------------------------

### Update dependencies

Source: https://github.com/yume-chan/ya-webadb/blob/main/CONTRIBUTING.md

Update project dependencies to their latest versions and deduplicate the lockfile.

```sh
$ pnpm recursive update --latest --interactive
$ pnpm dedupe
```

--------------------------------

### BigInt masking with & 0xFFn

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/no-data-view/README.md

Illustrates why setBigUint64 must mask with & 0xFFn: BigInt values can be too large for Number conversion without masking.

```ts
const value = (BigInt(Number.MAX_SAFE_INTEGER) + 2n) << 8n;
console.log((value >> 8n) & 0xffn); // 1n
console.log(Number(value >> 8n) & 0xff); // 0
```

--------------------------------

### Disposable interface

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

Represents anything that needs cleanup before the garbage collector recycles it.

```APIDOC
## Disposable

### Description
Represents anything that needs cleanup before the garbage collector recycles it.

### Interface
```ts
interface Disposable {
    dispose(): void;
}
```

### Methods
- **dispose()** - Releases resources held by the object.
```

--------------------------------

### EventEmitter/Event

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

Provides a strongly-typed event emitter for a single event type. Only the emitter can fire events, while consumers can subscribe via the Event interface.

```APIDOC
## EventEmitter/Event

### Description
Provides a strongly-typed event emitter for a single event type. Only the emitter can fire events, while consumers can subscribe via the Event interface.

### Interfaces
```ts
interface EventListener<TEvent, TThis, TArgs extends unknown[], TResult> {
    (this: TThis, e: TEvent, ...args: TArgs): TResult;
}

interface RemoveEventListener extends Disposable {
    (): void;
}

interface Event<TEvent, TResult = unknown> {
    (listener: EventListener<TEvent, unknown, [], TResult>): RemoveEventListener;
    <TThis, TArgs extends unknown[]>(listener: EventListener<TEvent, TThis, TArgs, TResult>, thisArg: TThis, ...args: TArgs): RemoveEventListener;
}
```

### Class
```ts
class EventEmitter<TEvent, TResult = unknown> implements Disposable {
    protected readonly listeners: EventListenerInfo<TEvent, TResult>[];
    constructor();
    protected addEventListener(info: EventListenerInfo<TEvent, TResult>): RemoveEventListener;
    event: Event<TEvent, TResult>;
    fire(e: TEvent): void;
    dispose(): void;
}
```

### Methods
- **event: Event<TEvent, TResult>** - The Event interface for subscribing to the event.
- **fire(e: TEvent): void** - Emits the event to all subscribed listeners.
- **dispose(): void** - Cleans up the emitter and its listeners.

### Usage Example
```ts
const emitter = new EventEmitter<void>();
const subscribe = emitter.event;
const unsubscribe = subscribe(() => {});
emitter.fire();
unsubscribe();
```
```

--------------------------------

### DisposableList class

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

An AutoDisposable that can be used alone (i.e., not as a base class).

```APIDOC
## DisposableList

### Description
An AutoDisposable that can be used alone (i.e., not as a base class).

### Class
```ts
class DisposableList extends AutoDisposable {
    add<T extends Disposable>(disposable: T): T;
}
```

### Methods
- **add<T extends Disposable>(disposable: T): T** - Adds a Disposable to be disposed when this list is disposed. Returns the same disposable.
```

--------------------------------

### DisposableList class declaration

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

An AutoDisposable that can be used standalone (not as a base class) to manage multiple disposables.

```ts
class DisposableList extends AutoDisposable {
    add<T extends Disposable>(disposable: T): T;
}
```

--------------------------------

### Disposable interface

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

Defines the contract for objects that require cleanup before garbage collection. Any class implementing this interface must provide a dispose() method.

```ts
interface Disposable {
    dispose(): void;
}
```

--------------------------------

### AutoDisposable class

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

A base class for objects that need to manage multiple Disposables. Calling dispose will automatically dispose all Disposables added via addDisposable.

```APIDOC
## AutoDisposable

### Description
A base class for objects that need to manage multiple Disposables. Calling dispose will automatically dispose all Disposables added via addDisposable.

### Class
```ts
class AutoDisposable implements Disposable {
    private disposables;
    constructor();
    protected addDisposable<T extends Disposable>(disposable: T): T;
    dispose(): void;
}
```

### Methods
- **addDisposable<T extends Disposable>(disposable: T): T** - Adds a Disposable to be disposed when this object is disposed. Returns the same disposable.
- **dispose(): void** - Disposes all added Disposables and performs cleanup.
```

--------------------------------

### Uint8Array stores lowest 8 bits

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/no-data-view/README.md

Demonstrates that Uint8Array stores only the lowest 8 bits, so masking with & 0xFF is unnecessary for setIntXX methods.

```ts
const array = new Uint8Array(2);
array[0] = 0x1234;
console.log(array[0]); // 52 (0x34)
console.log(array[1]); // 0
```

--------------------------------

### EventEmitter and Event type declarations

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

Core EventEmitter/Event types. EventEmitter is strongly-typed, supports only one event type per instance, and only trusted sources can emit events. The Event interface is exposed for subscription while fire() remains internal.

```ts
interface EventListener<TEvent, TThis, TArgs extends unknown[], TResult> {
    (this: TThis, e: TEvent, ...args: TArgs): TResult;
}

interface RemoveEventListener extends Disposable {
    (): void;
}

interface Event<TEvent, TResult = unknown> {
    (listener: EventListener<TEvent, unknown, [], TResult>): RemoveEventListener;
    <TThis, TArgs extends unknown[]>(listener: EventListener<TEvent, TThis, TArgs, TResult>, thisArg: TThis, ...args: TArgs): RemoveEventListener;
}

class EventEmitter<TEvent, TResult = unknown> implements Disposable {
    protected readonly listeners: EventListenerInfo<TEvent, TResult>[];
    constructor();
    protected addEventListener(info: EventListenerInfo<TEvent, TResult>): RemoveEventListener;
    event: Event<TEvent, TResult>;
    fire(e: TEvent): void;
    dispose(): void;
}
```

--------------------------------

### AutoDisposable class declaration

Source: https://github.com/yume-chan/ya-webadb/blob/main/libraries/event/README.md

Base class for managing multiple Disposable instances. Calling dispose() automatically disposes all disposables added via addDisposable().

```ts
class AutoDisposable implements Disposable {
    private disposables;
    constructor();
    protected addDisposable<T extends Disposable>(disposable: T): T;
    dispose(): void;
}
```
Tokens:
Raw