Overrides for TypeScript definition generation from JSG RTTI

[mrbbot]

Hey! 👋 This is a follow-up PR to cloudflare/workers-types#113, enabling auto-generated TypeScript definitions to be customised with "overrides". These are based on how autodecl used to work, however overrides are now written alongside the original C++ definitions using macros. This should mean overrides don't get out-of-sync with the original definitions.

In particular, 6 new macros have been added:

• JSG_(STRUCT_)TS_ROOT: start visiting types for inclusion from this type
• JSG_(STRUCT_)TS_OVERRIDE: customise the generated definition for this type by merging or replacing it with a partial TypeScript definition
• JSG_(STRUCT_)TS_DEFINE: insert additional handwritten TypeScript next to the generated definition for this type

See the documentation in src/workerd/jsg/jsg.h for more explanation on each.

Arguments to these macros are stored verbatim in the encoded RTTI Cap'n Proto file, and are parsed using the TypeScript Compiler API in the generation scripts. This approach means any TypeScript is valid in overrides (e.g. we can now use the & type operator).

I've tested this PR against the internal test suite and no additional changes were required for it to pass.

A copy of the generated types can be found here.

This PR also fixes a number of workers-types issues related to incorrect overrides:

• HtmlRewriter ElementHandler methods can only accept strings (not general Content) workers-types#312
• The fetch() request parameter's type is not correct workers-types#277
• KVNamespaceListResult more specific types workers-types#264
• Type error when providing an argument of (value: unknown) => void to setTimeout workers-types#239
• Where is WebAssembly type? workers-types#192
• Generic stream interfaces workers-types#117

Notably, #294 has not yet been fixed.

Closes cloudflare/workers-types#304.

[jasnell]

Looks good to me. I'll hold off giving it the stamp tho as it would be good to give it some time for others to review.

Namely, it would be great to get some of the DO and R2 folks to review the overrides specific to those apis.

[xortive]

Some DO things (I reviewed the generated output linked in the PR description).

• We should hide the ActorState type
• DurableObjectStorageOperationsGetAlarmOptions should be called DurableObjectGetAlarmOptions. Same for SetAlarmOptions
• setAlarm() is missing param names, and should accept number | Date for scheduledTime
• Seems like several 1-param methods are missing param names but most of them seem to be "unnecessary" to figure out how to use the type. It's unfortunate to lose the nice names we have now and see param0 though, but I guess it's a lot of work to put overrides for all of them?
• Looks like deleteAll() on DurableObjectTransaction should be never according to the override, but the generated type still has it defined?

[mrbbot]

@xortive

We should hide the ActorState type

DurableObjectStorageOperationsGetAlarmOptions should be called DurableObjectGetAlarmOptions. Same for SetAlarmOptions

...should accept number | Date for scheduledTime

Done ✅ Updated the generated definitions gist.

setAlarm() is missing param names

Seems like several 1-param methods are missing param names but most of them seem to be "unnecessary" to figure out how to use the type.

We're working on including parameter names in a separate PR. 👍

Looks like deleteAll() on DurableObjectTransaction should be never according to the override, but the generated type still has it defined?

Hmmm, I can only see one instance of deleteAll in DurableObjectStorage?

[mrbbot]

@jasnell, @Frederik-Baetens approved the R2 bindings after pointing out R2HTTPMetdata was incorrectly named (now fixed). I've also applied @xortive's DO fixes, so I think we should be good to merge. 👍

[Frederik-Baetens]

Confirm that I've reviewed this on behalf of the R2 team. 👍 from me

[jasnell]

@mrbbot ... I'll land this now. If there is a corresponding internal PR, please be sure to get that landed also :-)