Merge pull request #73 from ubports/selectors

Typescript + major refactoring

.gitattributes

@@ -0,0 +1,20 @@
+# Automatically normalize line endings for all text-based files
+# http://git-scm.com/docs/gitattributes#_end_of_line_conversion
+* text=auto
+
+# For the following file types, normalize line endings to LF on
+# checkin and prevent conversion to CRLF when they are checked out
+# (this is required in order to prevent newline related issues like,
+# for example, after the build script is run)
+.*      text eol=lf
+*.css   text eol=lf
+*.html  text eol=lf
+*.jade  text eol=lf
+*.js    text eol=lf
+*.json  text eol=lf
+*.less  text eol=lf
+*.scss  text eol=lf
+*.md    text eol=lf
+*.sh    text eol=lf
+*.txt   text eol=lf
+*.xml   text eol=lf

.github/workflows/ci.yml

@@ -13,10 +13,10 @@ jobs:
 
     steps:
       - uses: actions/checkout@v1
-      - name: Use Node.js 16
+      - name: Use Node.js 18
         uses: actions/setup-node@v1
         with:
-          node-version: "16"
+          node-version: "18"
 
       - name: Cache node modules
         uses: actions/cache@v2
@@ -51,10 +51,10 @@ jobs:
 
     steps:
       - uses: actions/checkout@v1
-      - name: Use Node.js 16
+      - name: Use Node.js 18
         uses: actions/setup-node@v1
         with:
-          node-version: "16"
+          node-version: "18"
 
       - name: Cache node modules
         uses: actions/cache@v2

.gitignore

@@ -71,4 +71,4 @@ docs
 test
 
 # ignore playground
-example.js
+example.*s

CHANGELOG.md

@@ -6,8 +6,15 @@ promise-android-tools versioning started at 1.0.0, but this changelog was not ad
 
 ## [Unreleased]
 
+## [5.0.0]
+
+### Changed
+
+- Major refactoring and Typescript migration, see the [README.md](./README.md) upgrade guide ([#73](https://github.com/ubports/promise-android-tools/pull/73))
+
 ### Added
 
+- adb.connect() function to connect to network devices ([#65](https://github.com/ubports/promise-android-tools/pull/65))
 - Introduce a setPath option for tools ([#72](https://github.com/ubports/promise-android-tools/pull/72))
 
 ## [4.0.13] - 2022-09-07

README.md

@@ -1,21 +1,17 @@
 # promise-android-tools ![Continuous Integration](https://github.com/ubports/promise-android-tools/workflows/Continuous%20Integration/badge.svg) [![npm](https://img.shields.io/npm/v/promise-android-tools)](https://www.npmjs.com/package/promise-android-tools) [![codecov](https://codecov.io/gh/ubports/promise-android-tools/branch/master/graph/badge.svg?token=cEneFUUbgt)](https://codecov.io/gh/ubports/promise-android-tools/)
 
-A wrapper for Adb, Fastboot, and Heimall that returns convenient promises.
-
-## IMPORTANT NOTE
-
-This is still a work in progress. Not all functions have been added and API stability is not guaranteed. The package was originally developed for use in the [UBports Installer](https://devices.ubuntu-touch.io/installer/).
+A wrapper for Adb, Fastboot, and Heimall written in modern asynchronous TypeScript that provides convenient promises for interacting with Android and Ubuntu Touch devices. The package was originally developed for the [UBports Installer](https://devices.ubuntu-touch.io/installer/) but has since been expanded to cover all APIs of the included tools.
 
 ## Usage
 
-Install the package by running `npm i promise-android-tools`.
+Install the package by running `npm i promise-android-tools android-tools-bin`.
 
 ### Quick-start example
 
 The default settings should cover most usecases.
 
-```javascript
-const { DeviceTools } = require("promise-android-tools");
+```typescript
+import { DeviceTools } from "promise-android-tools";
 const dt = new DeviceTools();
 
 dt.wait() // wait for any device
@@ -26,12 +22,66 @@ dt.wait() // wait for any device
   );
 ```
 
+### Config, Env vars
+
+Global command-line flags for tools are configurable on the `<tool>.config` property and described using an `ArgsModel`. The `<tool>._withConfig()` function allows overriding options temporarily. Additionally, `<tool>.__<option>()` helper functions are provided for all options.
+
+```typescript
+import { Adb } from "promise-android-tools";
+const adb = new Adb();
+console.log(
+  adb.config.serialno, // null
+  adb._withConfig({ serialno: "1337" }).config.serialno, // "1337"
+  adb.__serialno("1337").config.serialno // "1337"
+);
+adb.hasAccess(); // will run command `adb devices`
+adb._withConfig({ serialno: "1337" }).hasAccess(); // will run command `adb -s 1337 devices`
+adb.__serialno("1337").hasAccess(); // will run command `adb -s 1337 devices`
+```
+
+### Aborting pending Promises
+
+Pending operations can be aborted using the standardized [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)/[AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) APIs. Every tool implements its own `HierarchicalAbortController` for this purpose.
+
+```typescript
+import { Adb, HierarchicalAbortController } from "promise-android-tools";
+const adb = new Adb();
+adb.wait(); // will resolve once a device is detected or reject on error/abort
+adb.abort(); // will abort ALL pending promises from the instance
+```
+
+Additional [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)s can be passed on the `signals` constructor parameter to listen to for aborting pending operations. The `<tool>._withSignals()` function returns a clone for the tool instance listening to additional abort signals.
+
+```typescript
+import {
+  Adb,
+  Fastboot,
+  HierarchicalAbortController
+} from "promise-android-tools";
+const controller = new HierarchicalAbortController();
+const adb = new Adb({ signals: [controller.signal] });
+const fastboot = new Fastboot({ signals: [controller.signal] });
+Promise.all([adb.wait(), fastboot.wait()]);
+controller.abort(); // will abort ALL pending promises from both instances
+```
+
+A clone that will time out after a specified amount of time can be created using the `<tool>._withTimeout()` function.
+
+```typescript
+import { Adb, HierarchicalAbortController } from "promise-android-tools";
+const adb = new Adb();
+adb._withTimeout(1000).wait(); // will resolve if a device is detected or automatically reject after the timeout of one second
+const controller = new HierarchicalAbortController();
+adb._withSignals(controller.signal).wait(); // will be pending until aborted
+controller.abort(); // will abort only this promise, not the instance overall
+```
+
 ### Log execution events
 
 Events are available to log or introspect tool executions.
 
-```javascript
-const { DeviceTools } = require("promise-android-tools");
+```typescript
+import { DeviceTools } from "promise-android-tools";
 const dt = new DeviceTools();
 
 dt.on("exec", r => console.log("exec", r));
@@ -54,10 +104,10 @@ dt.adb.shell("echo", "test");
 
 ### Complex example
 
-The library provides most features of the eponymous command-line utilities wrapped in the available classes. This example only serves as a demonstration, confer to the documenation to discover the full power of this library.
+The library provides most features of the eponymous command-line utilities wrapped in the available classes. This example only serves as a demonstration - please consult the documenation to discover the full power of this library.
 
-```javascript
-const { DeviceTools } = require("promise-android-tools");
+```typescript
+import { DeviceTools } from "promise-android-tools";
 const dt = new DeviceTools();
 
 db.adb
@@ -91,10 +141,20 @@ function progress(p) {
 
 ### Documentation
 
-When using the library with modern editors like VScode/VScodium or Atom, you can make use of IntelliSense. Run `npm run docs` to build html from JSdoc documentation for all API functions.
+Typescript types are bundled and IntelliSense is supported. Run `npm run docs` to build html from JSdoc/Typedoc comments for all methods and types.
 
 ## API Changes, Deprecation Notices, Upgrade Guide
 
+### Upgrading to 5.x
+
+For version 5.0.0, the library has been migrated to typescript for increased stability and type safety. Many under-the-hood components have been redesigned for more efficient abstraction and ease of use.
+
+- CancelablePromise has been replaced by the the native [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) interface. The `<tool>.kill()` method has been renamed to `<tool>.abort()`.
+- Error handling has been restructured. Tools now throw `AdbError`, `FastbootError`, or `HeimdallError` objects implementing the `ToolError` interface and providing the original unaltered error in the `cause` property. Current standardized error messages include `"aborted" | "no device" | "more than one device" | "unauthorized" | "device offline" | "bootloader locked" | "enable unlocking" | "low battery" | "failed to boot"`.
+- Dependencies have been re-evaluated and many external libraries have been replaced with more solid solutions from modern NodeJS built-ins.
+- Global command-line options for tools are now configurable on the `<tool>.config` property.
+- The execOptions parameter has been removed in favor of `extraArgs` and `extraEnv` properties and their respective helper functions.
+
 ### Upgrading to 4.x
 
 Version 4.0.0 includes a major re-factoring effort that touched almost every function. The APIs of most functions remained intact, but in most cases you will have to make changes to your code. This has been done to correct some early design decisions.