Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate TypeScript definitions from source #189

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

aron
Copy link
Contributor

@aron aron commented Jan 14, 2024

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 aron marked this pull request as ready for review January 15, 2024 20:42
@aron aron changed the title WIP: Generate TypeScript definitions from source Generate TypeScript definitions from source Jan 15, 2024
@aron aron force-pushed the typescript-definitions branch 2 times, most recently from 1195d8a to cac159f Compare January 23, 2024 12:13
@aron aron changed the base branch from single-instance-entrypoint to main January 23, 2024 12:13
@aron aron requested a review from mattt January 23, 2024 12:16
@aron
Copy link
Contributor Author

aron commented Jan 23, 2024

@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.

@aron
Copy link
Contributor Author

aron commented Jan 23, 2024

Gonna close and reopen to try and trigger the tests...

@aron aron closed this Jan 23, 2024
@aron aron reopened this Jan 23, 2024
@aron aron force-pushed the typescript-definitions branch 2 times, most recently from da24d4e to 207f0b9 Compare March 18, 2024 13:33
@aron
Copy link
Contributor Author

aron commented Mar 18, 2024

@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).

We now have basic and `:integration` flavors of the common commands
`lint` and `test` as well as an `:all` flavor that will run everything.

We also now ensure that the types are built before running integration
tests as well as part of the packaging workflow via `prepack`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant