replicate-javascript icon indicating copy to clipboard operation
replicate-javascript copied to clipboard

Generate TypeScript definitions from source

Open aron opened this issue 5 months ago • 3 comments

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:

  1. Including all the documentation in the tsdoc comments in the typed output so we get better documentation in editors without duplication.
  2. 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.

aron avatar Jan 14 '24 22:01 aron