MIT License
TLDR: skip to the Suggested Pattern
In the article Get the advantages of TypeScript without transpiling @segphault described how TypeScript and JSDocs annotations can be combined to provide type checking capabilities for vanilla JavaScript projects.
This repo takes this concept one step farther and demonstrates how to use TypeScript to provide validated high quality public APIs in a vanilla JavaScript project.
DefinitelyTyped is awesome as it allows "external" contributors to provide definitions for packages independently of the "internal" development of these packages.
This approach however, has three main disadvantages:
Yes and No.
It is possible to include definitions as part of a package using the @types property. This will indeed resolve the first two concerns, The problem however, is that in order to resolve the 3rd concern, that of validating the definitions match the implementation. The whole package would have had to be developed in TypeScript. Which may not be desired for various (and legitimate) reasons.
Luckily a new alternative is available since TypeScript 2.3
The basic premise is quite simple:
Define our public APIs as d.ts files.
Use JSDocs annotations in the JS implementations of our public APIs and reference the types defined in the d.ts files.
Configure the TS compiler via tsconfig.json to check JS files and not generate any code output.
Expose our d.ts definitions using the @types property in our package.json.
Pros
Cons
First run:
npm install
Secondly run:
npm run type_check
And verify no errors are detected.
Thirdly: Modify the definitions and/or the implementation in ways that should break their alignment. and re-run
npm run type_check
To inspect the error messages.