Handshake/Bcoin - Add typescript type linter support #841
Description
Motivation
bcoin-org and handshake-org dependencies actively use JSDocs to document types in the codebase. Unfortunately, they don't provide anything more useful than the documentation, they are not used for the type checking. In the end documentation sometimes becomes incorrect and goes out of sync and there's no easy way to detect those.
TypeScript support for the JSdoc but with several differences. It can allow us to check the code for the proper types and detect when either types go out of sync. It can also help with code analyses in some cases and catch when something does not have proper type etc. It is not all powerful but is an improvement over what we have.
In general, bcoin-org/handshake-org projects don't want to introduce dependencies to the projects if possible and especially not the another step in development process (e.g. transpiling). But what we can use are external tools to verify the code quality (linter).
This is a proposal to use tsc externally as a type linter, but don't use it for anything more. Developers don't have any strict requirement to install them locally (similar to linter) and can just rely on the CI to lint them.
This change was inspired by the svelte: sveltejs/svelte#8569
Relationship with jsdoc reference
Some syntax in TypeScript is not supported by the jsdoc reference generator, for that purpose we can remove them in the jsdoc reference generator.
Here's a fix for the typedef imports: pinheadmz/bsdoc#1
Implementation
TypeScript needs types for the builtin nodejs types which are not built into it. This in general is provided by: https://github.com/DefinitelyTyped/DefinitelyTyped To avoid extra dependencies to the project the necessary type aliases are
vendored here: https://github.com/bcoin-org/bts-type-deps
There are already several PRs that have these changes, but are not merged yet to allow for the feedback. Here's the short list of them (Some of them have linter on ci failing, because dependencies are not published)
Goal is not to fully fix everything in one go, but to allow slow incremental improvements. Current list of PRs do mostly minimal work to suppress or fix types in the dependencies. Slowly we can iterate and fix these.
Handshake and bcoin both can enable type lints slowly starting from simpler modules (e.g. primitives) and slowly expand the tsc-lint support everywhere.
Here's the list of current PRs:
- bcfg - pkg: add type lints using tsc. bcoin-org/bcfg#11
- bcurl - pkg: add type lints. bcoin-org/bcurl#22
- bdb - pkg: add type lints. bcoin-org/bdb#19
- bdns - pkg: add type lints. bcoin-org/bdns#3
- bevent - pkg: add type lints. bcoin-org/bevent#2
- bfile - pkg: add type lints. bcoin-org/bfile#5
- bheep - pkg: add lint-types and tsconfig to the project. bcoin-org/bheep#2
- binet - pkg: add type lints. bcoin-org/binet#12
- blgr - pkg: add type lints. bcoin-org/blgr#12
- blru - pkg: add type lints. bcoin-org/blru#2
- blst - pkg: add type lints. bcoin-org/blst#2
- bmutex - pkg: add type lints. bcoin-org/bmutex#2
- brq - pkg: add type lints. bcoin-org/brq#14
- bs32 - pkg: add type lints. bcoin-org/bs32#2
- bsert - No ts-lint but suppress issues (@ts-ignore some lines).
- bsock - pkg: add type lints. bcoin-org/bsock#9
- bsocks - pkg: add type defs for type lints. bcoin-org/bsocks#3
- btcp - pkg: add type lints. bcoin-org/btcp#2
- bufio - pkg: add lint-types and tsconfig to the project. bcoin-org/bufio#6
- bcrypto - needs a fork (no npm access)
- bfilter - needs a fork (bfilter uses git links)
- bns
- budp
- buffer-map - needs a fork (no github access)
- bupnp
- bval
- bweb
- goosig
- loady
- mrmr - update to new bfilter - dropping this dependency.
- n64 OR Rewrite ScriptNum with BigInt #822
- unbound
- urkel