Generate Type Declarations

[avivkeller]

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

[flakey5]

@ovflowd and I reached out to them just over a year ago regarding this: DefinitelyTyped/DefinitelyTyped#70298

[AugustinMauroy]

So it's mean release static assets will contain types defined ?

[flakey5]

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/node are 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]

iirc at least some of the types in @types/node are maintained manually

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/node and see what ideas they have

[avivkeller]

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]

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]

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 Buffer in 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]

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 Buffer in 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,

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]

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.

This can all be discussed in a meeting, but it'd be nice to at least generate the node: module types without requiring manual documenting

To be honest, there's very little of the Node.js documentation that is amenable to automated consumption by @types/node as it is.

We 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]

Which slack? I'm in only one and it's not JS related 😅

[avivkeller]

Which slack? I'm in only one and it's not JS related 😅

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]

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)