Repository navigation
Generate Type Declarations #437
Description
Currently, when a new Node.js release occurs, https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node/scripts/generate-docs has to be run and/or updated with anything that changes. It would be nice for the Node.js Project to provide it's own types, immediately after a given release is published.
I'm going to reach out to the DefinitelyTyped folks to see if there is an ideal way for the Node.js project and DefinitelyTyped to work together to create type definitions.
cc @ovflowd
Metadata
Metadata
Assignees
Labels
No labels
Activity
flakey5 commentedon Sep 9, 2025
@ovflowd and I reached out to them just over a year ago regarding this: DefinitelyTyped/DefinitelyTyped#70298
AugustinMauroy commentedon Sep 9, 2025
So it's mean release static assets will contain types defined ?
flakey5 commentedon Sep 9, 2025
I think this is overall a good idea to at least explore, would probably benefit from being based off the new json generator. However I'm not exactly sure if there's any nuances with maintaining types that would make typegen difficult. For instance iirc at least some of the types in
@types/nodeare maintained manually, there are bound to be breaking changes between what we generate vs what's been written by hand (this example could be solved by just aliasing probably, but still something to consider)avivkeller commentedon Sep 9, 2025
I'd like to work with the team there to determine how we can minimize the number of types that must be maintained manually. I imagine a mix of changes there, here, and in core, will allow us to achieve this. I'm going to try and set up a meeting with the maintainers of
@types/nodeand see what ideas they haveavivkeller commentedon Sep 9, 2025
cc @jakebailey @Renegade334 - I'd love to set up a meeting with you / have you pop into a web team meeting to discuss this?
jakebailey commentedon Sep 9, 2025
I don't mind meeting about this, but we have to do so much surgery on the types and hacks to make things work over time that I'm not sure that generating it from Node's side is going to work out very well. Types that seem simple turn into a mess when we realize we have to also support DOM types being loaded, etc etc. So I'm not totally sure what all would be generated and not then modified.
Renegade334 commentedon Sep 9, 2025
Thanks Aviv.
To be honest, there's very little of the Node.js documentation that is amenable to automated consumption by @types/node as it is. The actual API documentation, whether the markdown or the JSON generated from it, is on the whole simply far too loose (and, in many cases, barn-door inaccurate) to use as a base for automated tooling. The only two sources that we really use are the description blocks (for generating docblocks, which is the script you've linked to – it doesn't touch the types), and the inspector PDL (which we use to fully generate the inspector types).
As Jake has alluded to, probably the main constraint for @types/node isn't actually the Node API itself – there are inevitably some inaccuracies that get ironed out over time, but in general, it's fairly straightfoward to maintain alignment with Node.js, albeit with some human input.
The main complexities come from compatibility with the TypeScript compiler, its core definition libraries, and version-specific changes to these. (As just one example, a type of
Bufferin the Node.js documentation will need to be converted to one of several possible type representations depending on the exact context it appears in, and the representation also differs based on what version of TypeScript is being run by the consumer!) I feel like the nuances of these interactions are only ever really going to be consistent with human maintenance,ovflowd commentedon Sep 9, 2025
I think this meeting would be really helpful as the way how we are even internally generating representations of methods on our API docs is changing, example: https://api-docs-tooling-openjs.vercel.app/buffer.html#new-bufferblobsources-options
avivkeller commentedon Sep 10, 2025
This can all be discussed in a meeting, but it'd be nice to at least generate the
node:module types without requiring manual documentingWe want to make our new JSON format as easy for consumers to use, so this meeting would be extremely helpful in identifying what we need to do to help automate this process.
@jakebailey I've sent you the information for our next monthly meeting on Slack. Feel free to pop-in. If you aren't available, we can also schedule a different time.
@Renegade334 I've sent you the information for our next monthly meeting via email. Feel free to pop-in. If you aren't available, we can also schedule a different time.
jakebailey commentedon Sep 10, 2025
Which slack? I'm in only one and it's not JS related 😅
avivkeller commentedon Sep 10, 2025
Hmm, it looks like your in the OpenJS slack, perhaps you used to be and left. If you email me (me@aviv.sh) / reply to this comment with a preferred contact method, I'll give you the information.
avivkeller commentedon Sep 10, 2025
Okay, invites went out. Please note that the meeting is 3:00PM Pacific time, September 29th.
An agenda issue will be created one week prior (which you will be pinged on, as invitees)
ovflowd commentedon Sep 13, 2025
I haven't gotten the invitation, I think.
avivkeller commentedon Sep 13, 2025
@ovflowd it's in your LFX portal. Invites were only for the guests.
avivkeller commentedon Sep 29, 2025
Superseded by #441