replicate
Generate TypeScript definitions from source
Currently our types are hand written. They differ from the jsdoc types in the source code in that a) they're missing documentation and b) the types are often inconsistent. Rather than manually sync the two it felt simpler to use tsc to generate the types for us from the JS source code and reduce the burden of manually keeping the types up-to-date with the source code.
This PR now uses the type annotations found in the jsdoc for all of the files and generates a ./dist/types directory. This has the benefits of:
- Including all the documentation in the tsdoc comments in the typed output so we get better documentation in editors without duplication.
- Ensures that the types are in sync with the source code. There were a number of areas where these were out of sync.
The drawbacks are mostly that it's very easy to mess up the type annotations which will then fail silently and default to any, which is about on par with handwriting them anyway.
To mitigate this we do our best to unit test the types in the ./integrations/typescript/types.test.ts file which creates typed instances of the main primitives and will cause tsc errors if the types become out of sync. The AssertFalse helper allows us to catch cases where we've accidentally messed up the @typedef export in index.js.
@mattt I've rebased this on main to remove the dependency on the singleton branch. The only files I'm not 100% sure about is the changes to jsconfig.json I'm not even sure this file is used honestly so it can probably be removed.
@mattt spent some time getting this up-to-date, would be good to get it in before we make any further API changes (like the deployments branch).