-
Notifications
You must be signed in to change notification settings - Fork 59
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This PR adds support for TS type check, .d.ts generations and docs from .d.ts
- Loading branch information
1 parent
bff4c44
commit f332803
Showing
15 changed files
with
523 additions
and
128 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| 'use strict' | ||
|
|
||
| const EPILOG = ` | ||
| Presets: | ||
| \`check\` Runs the type checker with your local config (without writing any files). . | ||
| \`types\` Emits type declarations for \`['src/**/*', 'package.json']\` to \`dist\` folder. | ||
| \`docs\` Generates documentation based on type declarations to the \`docs\` folder. | ||
| \`config\` Prints base config to stdout. | ||
| Note: | ||
| To provide users types declarations with 0-configuration add following to package.json: | ||
| \`\`\`json | ||
| "typesVersions": { | ||
| "*": { "src/*": ["dist/src/*", "dist/src/*/index"] } | ||
| }, | ||
| \`\`\` | ||
| Supports options forwarding with '--' for more info check https://www.typescriptlang.org/docs/handbook/compiler-options.html | ||
| ` | ||
| module.exports = { | ||
| command: 'ts', | ||
| desc: 'Typescript command with presets for specific tasks.', | ||
| builder: (yargs) => { | ||
| yargs | ||
| .epilog(EPILOG) | ||
| .example('aegir ts --preset config > tsconfig.json', 'Add a base tsconfig.json to the current repo.') | ||
| .options({ | ||
| preset: { | ||
| type: 'string', | ||
| choices: ['config', 'check', 'types', 'docs'], | ||
| describe: 'Preset to run', | ||
| alias: 'p' | ||
| }, | ||
| include: { | ||
| type: 'array', | ||
| describe: 'Values are merged into the local TS config include property.', | ||
| default: [] | ||
| } | ||
| }) | ||
| }, | ||
| handler (argv) { | ||
| const ts = require('../src/ts') | ||
| return ts(argv) | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| # Documentation for JSDoc based TS types | ||
|
|
||
| ## Getting Started | ||
|
|
||
| Add a `tsconfig.json` to your repo: | ||
| ```bash | ||
| aegir ts -p config > tsconfig.json | ||
| ``` | ||
|
|
||
| Add types configuration to your package.json: | ||
| ```json | ||
| "typesVersions": { | ||
| "*": { "src/*": ["dist/src/*", "dist/src/*/index"] } | ||
| }, | ||
| ``` | ||
| `types` will tell `tsc` where to look for the entry point type declarations and `typeVersions` for every other files inside the `src` folder. | ||
|
|
||
| > The `ts` command follows aegir folder conventions, source code inside `./src`, test inside `./test` and documentation inside `./docs`. | ||
|
|
||
| ## CLI `ts` command | ||
|
|
||
| Run `aegir ts --help` and check the help text. There's presets for common TS use cases. | ||
|
|
||
| ```md | ||
| Presets: | ||
| `check` Runs the type checker with your local config and doesn't not emit output. | ||
| `types` Emits type declarations for `['src/**/*', 'package.json']` to `dist` folder. | ||
| `docs` Generates documentation based on type declarations to the `docs` folder. | ||
| `config` Prints base config to stdout. | ||
| ``` | ||
|
|
||
|
|
||
| ## Adding types with JSDoc | ||
|
|
||
| Typescript can infere lots of the types without any help, but you can improve your code types by using just JSDoc for that follow the official TS documentation https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html. | ||
|
|
||
| ### Rules for optimal type declarations and documentation | ||
|
|
||
| This list is a WIP, more rules will be added as we identify them. | ||
|
|
||
| #### 1. Commonjs default exports | ||
| When using `commonjs` modules, only use default exports when exporting a single `class`. | ||
|
|
||
| ```js | ||
| // GOOD | ||
|
|
||
| class IPFS {} | ||
|
|
||
| module.exports = IPFS | ||
|
|
||
| // GOOD | ||
| IPFS.hash = ()=>{} | ||
|
|
||
| module.exports = IPFS | ||
|
|
||
| // BAD | ||
| function hash() {} | ||
|
|
||
| module.exports = hash | ||
|
|
||
| // REALLY BAD | ||
|
|
||
| function hash() {} | ||
| function hash2() {} | ||
|
|
||
| module.exports = hash | ||
| exports.hash2 = hash2 | ||
|
|
||
|
|
||
| ``` | ||
|
|
||
| #### 2. Commons js named exports | ||
| When using `commonjs` modules, always use named exports if you want to export multiple references. | ||
| ```js | ||
| // GOOD | ||
| function hash() {} | ||
| function hash2() {} | ||
| class IPFS {} | ||
| module.exports = { | ||
| IPFS | ||
| hash, | ||
| hash2, | ||
| ... | ||
| } | ||
|
|
||
| // BAD | ||
| exports.hash2 = hash2() {} | ||
| exports.hash = hash() {} | ||
| exports.IPFS = IPFS | ||
| ``` | ||
|
|
||
| #### 3. Use a `types.ts` file | ||
| When writing types sometimes JSDoc can be cumbersome, impossible, it can output weird type declarations or even broken documentation. Most of these problems can be solved by defining some complex types in typescript in a `types.ts` file. | ||
|
|
||
| ```ts | ||
| // types.ts | ||
| export type IntersectionType = Type1 & Type2 | ||
| ``` | ||
| ```js | ||
| // index.js | ||
| /** @type { import('./types').IntersectionType } */ | ||
| const list | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.