Solid Node.js with official type system support

[gengjiawen]

Is your feature request related to a problem? Please describe.

While js became more and more popular, typescript and flow appears to deal with stability and maintainability for large projects, yet we lack support for type definitions for Node.js core api. I think the needs goes strong and strong, one proof is that https://www.npmjs.com/package/@types/node has reached 23 million download weekly.

Community already has @type/node, should we really support it in core ?
I think we should, here are the reasons:

It's not reflect the api change quickly enough

For example, the wasi api takes some time added to the repo.
Apis like newly or changed takes time to get adopted, developers will has
to wait for this.

It's not related to Node.js version consistently

this package doesn't related Node.js versions. But we has lts, latest and other versions, this can be problematic and got surprised behavior. If we have
official support, developers can choose the related version and got precise result.

other

It's only for typescript. We can expand our official type system to flow or other newly solutions.
Also contribute to this package is too much pain.

Describe the solution you'd like

I am thinking we generate types file from our markdown doc or js source file (the libs folder ), not sure whether this eventually can work. Another solution is we invent a new dsl :)

Eventually we should make should publish types package when we release a new Node.js version.

[himself65]

jsdoc to typescript must a good one solution

example: https://www.npmjs.com/package/tsd-jsdoc

[tniessen]

Are you proposing a separate, officially maintained npm package, or bundling it with Node.js somehow?

[devsnek]

I would be against anything that requires node core maintainers to have knowledge of typescript (for example requiring us to update the types with our other core changes). Beyond that, I have no issues.

[ronag]

I'm a little sceptical about this kind of thing unless we actually write in e.g. TypeScript. From my experience this quickly becomes outdated and incorrect causing both confusion and a false sense of safety.

[tniessen]

From my experience this quickly becomes outdated and incorrect causing both confusion and a false sense of safety.

Isn't that the issue that @gengjiawen is trying to address with this proposal?

[ronag]

Isn't that the issue that @gengjiawen is trying to address with this proposal?

I'm sceptical about the proposed ways to address this.

generate types file from our markdown doc or js source file (the libs folder ), not sure whether this eventually can work. Another solution is we invent a new dsl.

Unless we actually write the code in e.g. TypeScript I don't believe they will ever be entirely correct, which for me defeats the purpose.

[jasnell]

I'd be much more in favor of bringing @types/node into the Node.js organization but maintaining it as a separate project. I would not want to bake it in to core. That said, we could be doing a lot better at documenting core types to make it easier to generate and maintain.

[tniessen]

Oh, that's what you mean. I agree, there's a tendency for types and code to diverge, whether it's in core or not.

I have been using @types/node for a long time, always using the most recently published version. Maybe it makes more sense for us to get involved there, than trying to achieve the same in Node.js core?

[Flarna]

I'm also skeptical that separate releases/repos can really solve this problem.

@types/node has just a handful of active maintainers continuously looking into it. There are quite some additional people raising PRs to fix something. Not sure if this would improve just by moving it into node organization.

DefinitelyTyped provides quite an infrastructure for testing and deployment to NPM for easy consumption. Decoupling node definitions from the >1000 dependent definitions there may easily result in breaking some of them even with simple changes.

fyi @SimonSchick

[SimonSchick]

@himself65 The last time I've seen a larger project (puppeteer) try to ship their own typings generated from typedoc it failed horribly as they were very inaccurate, didn't cover edge cases and don't even get me started on generics.
Suffice to say they rolled that back pretty quickly.

As a long time @types/nodejs maintainer I feel the pain though as I usually try to roll out new type versions relatively quickly to stay up to date.
I often have trouble translating changelogs into type definitions due to silly quirks (like assigning properties to function to export them, circular references etc.).
I also often miss changes as they aren't mentioned in the changelogs and going through the commits indivudually is a huge PITA.

I think making the contributors/maintainers write typings would often lead to highly consistent definitions and act as a double check for more sane design decisions (eg. if you can't model it in TS easily, you are likely doing something 'hacky').

I also concur with @Flarna though, moving the typings would be quite an effort.
It would probably be possible to move the type defs into node and then automate PRs into DT for checking/releases.
That adds quite a lot of work to releases and might cause all sorts of problems however.

[Mickael-van-der-Beek]

As a long time Node.js user, my experience with the @types/node type definitions was that they were decent for the common function arguments but quickly broke down for lesser known features.

e.g: the custom lookup function that can be passed to http.connect() and net.connect()
e.g2: exposed APIs like the HTTP parser (process.binding('http_parser').HTTPParser)

A lot of types are also not very strict, in the sense that an encoding option is a string and not say an enum type with utf8, binary, etc. as possible values.

Of course adding type definitions for internal bindings (which are technically public) and the level of strictness of the type definitions is subjective.

[mcollina]

I've put some thoughts into this for a long time. Let me list the current issues I've seen when using @types/node:

1. A user must select which version of Node.js they are targeting. This creates a barrier for most module authors as they likely need to support multiple version of Node.js.
2. The API changes are not kept up to date. Having them follow the usual Node.js LTS process would mean that they would land in master and be released and backported with the rest of the content.
3. The Node.js collaborators have no control on how a significant portion of their users use their work, as @types/node is not governed by the collaborators.
4. We could add some deliberate automated tests of the typescript experience.

There are however a few technical challenges of adding this to core:

a. We'd need to place our types within the Node.js install dir, and typescript (and all correlated tools, including VSCode) needs to be made aware that file exist and look it up.
b. Backward compatibility needs to be designed carefully so that we could land it as opt-in in v10 and v12, and possibly make it a default in v14 (or v15).
c. there should be no requirement that a PR into core adding an option or changing an API modify the types. Most core collaborators do not know typescript anyway, so this would be a significant blocker. It'd be kind of easy to add a need-types label or create good-first-issues to add the typings.

If we feel we should make this happen, I think the best path forward is:

1. Devise a plan with the typescript team, and see if they are onboard
2. Have a PR created that brings the most up-to-date version of @types/node into core as a basis
3. Create a typescript team or working group and onboard the interested maintainers of @types/node into it.

I'm happy to facilitate all the above.

[tniessen]

@mcollina What concerns me about shipping types with Node.js is that it will make it impossible or at least impractical to fix the types without upgrading Node.js to a newer version. That is one of the main reasons why I think it makes sense to maintain the types separately.