doc: add README for ts-package-builder

libraries/adb/src/commands/shell/index.ts

@@ -1,4 +1,4 @@
-import { Adb } from '../../adb';
+import type { Adb } from '../../adb';
 import { AdbLegacyShell } from './legacy';
 import { AdbShellProtocol } from './protocol';
 import type { AdbShell, AdbShellConstructor } from './types';
@@ -10,8 +10,10 @@ export * from './utils';
 
 export interface AdbChildProcessOptions {
     /**
-     * A list of `AdbShellConstructor`s that can be used.
-     * Different `AdbShell`s have different capabilities. Please check the documentation for each `AdbShell`
+     * A list of `AdbShellConstructor`s to be used.
+     *
+     * Different `AdbShell` has different capabilities, thus requires specific adaptations.
+     * Check each `AdbShell`'s documentation for details.
      *
      * The first one whose `isSupported` returns `true` will be used.
      * If no `AdbShell` is supported, an error will be thrown.

libraries/adb/src/commands/shell/types.ts

@@ -12,7 +12,7 @@ export interface AdbShell {
     /**
      * Notifies that new data has been written into the `stderr` stream.
      *
-     * The current shell may not support splitting output streams
+     * Some `AdbShell`s may not support separate output streams
      * and will always fire the `onStdout` event instead.
      */
     readonly onStderr: Event<ArrayBuffer>;
@@ -21,7 +21,7 @@ export interface AdbShell {
      * Notifies that the current process has exited.
      *
      * The event arg is the exit code.
-     * The current shell may not support returning exit code and will always return `0` instead.
+     * Some `AdbShell`s may not support returning exit code and will always return `0` instead.
      */
     readonly onExit: Event<number>;
 
@@ -33,7 +33,7 @@ export interface AdbShell {
     /**
      * Resizes the current shell.
      *
-     * The current shell may not support resizing and will always ignore calls to this method.
+     * Some `AdbShell`s may not support resizing and will always ignore calls to this method.
      */
     resize(rows: number, cols: number): ValueOrPromise<void>;
 

toolchain/ts-package-builder/README.md

@@ -0,0 +1,128 @@
+# TypeScript NPM Package Builder (for myself)
+
+## Installation
+
+(This package is not yet published to NPM registry, so presumably)
+
+```shell
+$ npm install --dev @yume-chan/ts-package-builder typescript
+```
+
+TypeScript is a peer dependency that must be installed separately (so you can use any version you want).
+
+```shell
+$ npm install tslib
+```
+
+The default configuration has `"importHelpers": true`, so `tslib` is required (and it is a production dependency, not dev dependency).
+
+## Config
+
+A `tsconfig.json` file at package root is required for both this builder and editors.
+
+```jsonc
+{
+    // Extends default configurations.
+    "extends": "./node_modules/@yume-chan/ts-package-builder/tsconfig.base.json",
+
+    // (Optional) Add override configurations.
+    "compilerOptions": {
+        // All TypeScript configurations are allowed.
+        "target": "ES2016",
+
+        // Add extra ambient types.
+        // Don't forget to include "jest" unless you don't write unit tests.
+        // The default is `[ "jest" ]`
+        "types": [
+            "w3c-web-usb",
+            "jest",
+            "node"
+        ]
+    },
+    // (Optional) Specify types that's only used in tests.
+    // They will be excluded in ESModule build,
+    // to make sure library code doesn't accidentally use them.
+    // (for example, a browser targeted libraries should not use types from `@types/node`)
+    "testTypes": [
+        "jest",
+        "node"
+    ],
+    // (Optional) Add project references to improve editing experience.
+    // However, because the builder is intended to be used with some monorepo manager
+    // (lerna, yarn workspace, rush, etc.), and they all have good built-in support
+    // for building all packages following dependency graph, it **does not** use
+    // project references when building.
+    "references": [
+        {
+            "path": "../dependency-a/tsconfig.json"
+        },
+        {
+            "path": "../dependency-b/tsconfig.json"
+        }
+    ]
+}
+```
+
+## Building
+
+```shell
+$ npx build-ts-package
+```
+
+Or add a script to `package.json`
+
+```json
+{
+    "scripts": {
+        "build": "build-ts-package",
+    },
+}
+```
+
+The builder compiles for both CommonJS and ESModule, also generates source maps, TypeScript declarations, and declaration maps.
+
+| Module             | Output Directory | Excluded Files | Excluded Types |
+| ------------------ | ---------------- | -------------- | -------------- |
+| CommonJS           | `cjs`            | -              | -              |
+| ESModule           | `esm`            | `*.spec.ts`    | `@types/jest`  |
+| Declaration (d.ts) | `dts`            | `*.spec.ts`    | `@types/jest`  |
+
+Example `package.json`:
+
+```json
+{
+    "main": "cjs/index.js",
+    "module": "esm/index.js",
+    "types": "dts/index.d.ts",
+}
+```
+
+## Unit test with Jest
+
+Test file convention: put `.spec.ts` files inside `src`, alongside the source file that will be tested.
+
+Like this:
+
+- src
+  - index.ts
+  - index.spec.ts
+
+The `.spec.ts` files will be compiled to CommonJS for Jest (so no `ts-jest` required).
+
+Use the following `jest.config.js` file to find them:
+
+```js
+module.exports = {
+    testMatch: ['<rootDir>/cjs/**/*.spec.js'],
+};
+```
+
+## Publishing
+
+Because `.spec.ts` files have been compiled to CommonJS, you can exclude them using `.npmignore`:
+
+```gitignore
+**/*.spec.ts
+**/*.spec.js
+**/*.spec.js.map
+```

toolchain/ts-package-builder/package.json

@@ -18,5 +18,8 @@
   "dependencies": {
     "json5": "2.2.0",
     "@types/jest": "26.0.23"
+  },
+  "peerDependencies": {
+    "typescript": "^4.0.0"
   }
 }

toolchain/ts-package-builder/src/index.js

@@ -10,7 +10,6 @@ fs.mkdirSync(temp, { recursive: true });
 fs.rmSync(path.resolve(cwd, 'cjs'), { force: true, recursive: true });
 fs.rmSync(path.resolve(cwd, 'esm'), { force: true, recursive: true });
 fs.rmSync(path.resolve(cwd, 'dts'), { force: true, recursive: true });
-fs.rmSync(path.resolve(cwd, 'tsconfig.tsbuildinfo'), { force: true, recursive: true });
 
 const tsconfigPath = path.resolve(cwd, 'tsconfig.json');
 const tsconfigValue = JSON5.parse(fs.readFileSync(tsconfigPath), 'utf8');

toolchain/ts-package-builder/tsconfig.base.json

@@ -27,7 +27,7 @@
         // "noUnusedParameters": true,            /* Report errors on unused parameters. */
         "noImplicitReturns": true, //             /* Report error when not all code paths in function return a value. */
         "noFallthroughCasesInSwitch": true, //    /* Report errors for fallthrough cases in switch statement. */
-        "forceConsistentCasingInFileNames": true, /*	 Disallow inconsistently-cased references to the same file. */
+        "forceConsistentCasingInFileNames": true, /* Disallow inconsistently-cased references to the same file. */
         /* Module Resolution Options */
         "moduleResolution": "node", //            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
         // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */