From b8de6b70d84f1f45d0a2bd163c0216c0c4059ee2 Mon Sep 17 00:00:00 2001 From: Simon Chan <1330321+yume-chan@users.noreply.github.com> Date: Mon, 24 May 2021 11:12:12 +0800 Subject: [PATCH] doc: add README for ts-package-builder --- libraries/adb/src/commands/shell/index.ts | 8 +- libraries/adb/src/commands/shell/types.ts | 6 +- toolchain/ts-package-builder/README.md | 128 ++++++++++++++++++ toolchain/ts-package-builder/package.json | 3 + toolchain/ts-package-builder/src/index.js | 1 - .../ts-package-builder/tsconfig.base.json | 2 +- 6 files changed, 140 insertions(+), 8 deletions(-) create mode 100644 toolchain/ts-package-builder/README.md diff --git a/libraries/adb/src/commands/shell/index.ts b/libraries/adb/src/commands/shell/index.ts index 7d5d97a4..b3ccfa49 100644 --- a/libraries/adb/src/commands/shell/index.ts +++ b/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. diff --git a/libraries/adb/src/commands/shell/types.ts b/libraries/adb/src/commands/shell/types.ts index c920c04d..0a6455a4 100644 --- a/libraries/adb/src/commands/shell/types.ts +++ b/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; @@ -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; @@ -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; diff --git a/toolchain/ts-package-builder/README.md b/toolchain/ts-package-builder/README.md new file mode 100644 index 00000000..dab51766 --- /dev/null +++ b/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: ['/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 +``` diff --git a/toolchain/ts-package-builder/package.json b/toolchain/ts-package-builder/package.json index d47dfece..d6687682 100644 --- a/toolchain/ts-package-builder/package.json +++ b/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" } } diff --git a/toolchain/ts-package-builder/src/index.js b/toolchain/ts-package-builder/src/index.js index 7046f71e..3dd54079 100644 --- a/toolchain/ts-package-builder/src/index.js +++ b/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'); diff --git a/toolchain/ts-package-builder/tsconfig.base.json b/toolchain/ts-package-builder/tsconfig.base.json index 7491f041..24d78758 100644 --- a/toolchain/ts-package-builder/tsconfig.base.json +++ b/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. */