feat: generate typescript types

[danielroe]

What does this change?

I'm loving microlighter!

this adds typescript types for consumers who use TS (like me).

if you prefer:

1. feel free to close this if you don't want to maintain this
2. I can also add TS as a dependency and generate types from the JSdoc with tsc --allowJs --declaration --emitDeclarationOnly, but I'd need to tweak the JSdoc to be more specific (than e.g. @param {*} / Object), and I thought you might prefer to avoid the build step

Important

update: I've refactored this to keep JSdoc as the source of truth except for declaration files that don't match any source

Checklist

• npm test passes locally
• The size budget still passes (note any size impact below)
• Added/updated tests or the demo (docs/index.html) if behavior changed
• For a new grammar/theme, followed the steps in CONTRIBUTING.md

Size impact

[davatron5000]

Hey awesome. I'll definitely add this. Do you think it's worth pulling this into JSDocs @typedef import in the main files just so things don't get too out of sync? Or do you think running tsc will be enough of a safeguard to catch it?

[danielroe]

if you're happy to add a typescript build step, I'll move it all into JSdoc to keep a single source of truth

[danielroe]

@davatron5000 I've updated this to use JSdoc as the source of truth and added typescript v7. check/emit time is fast and hopefully not inconvenient:

# emits declarations, run as part of the build
time npx tsc

real	0m0.472s
user	0m0.475s
sys	0m0.054s

# check types but don't emit declarations
time npm run typecheck

real	0m0.169s
user	0m0.189s
sys	0m0.035s

[davatron5000]

@danielroe Awesome! I think allowing JSDoc to leverage the types will be a big deal for maintenance long term.

I'm heading into work right now but I'll try to get this in tonight and cut a release. Appreciate it.

Do you have a favorite way of automating releases for your projects? Do you use changesets or anything like that?

[danielroe]

funny you should ask 😆

I wrote a github action (https://github.com/danielroe/uppt) that handles everything in a pure github actions + npm staged publishing workflow. it's very opinionated (for example, it works via conventional commits, requires staged publishing, etc.). it has been mythos-scanned (by someone else, for what that's worth) and I've done my best to embed best security practices into it - for example, the workflow that actually has access to your id token doesn't run any commands or install your deps.

I haven't used it for a project that doesn't do squash merging, so I'll take a look at whether I need to add support...

[davatron5000]

Oh that's great. I might just use this. I can also add squash merging by default. Then the flow is:

→ Merge work w/ conventional commit - breaking ! = major, feat = minor, else = patch?
→ GH Action runs on merge to main (or daily or whatever) - stages the publish on npm... i need a secret here I assume
→ Then you log into npm and approve publish?

[danielroe]

→ merge work w/ conventional commit - breaking ! = major, feat = minor, else = patch
→ GH Action runs on merge to main - and updates a draft 'release PR' showing what will be in the next release
→ when ready, you then merge the release PR - at that point, trusted publishing just magically works and stages it on npm, and the action automatically creates a GitHub release for you with what was in the release
→ then you log into npm and click 'approve publish'