Repository navigation
Solid Node.js with official type system support #32022
Description
Activity
jsdoctotypescriptmust a good one solutionAre you proposing a separate, officially maintained npm package, or bundling it with Node.js somehow?
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.
Reacted by mary marchini and Jayden SericI'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.
Reacted by Michał WadasReacted by Andrey GoncharovFrom 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?
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.
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.
Reacted by Tobias Nießen, mary marchini, Valentin Marchaud, Ruben Bridgewater, Lucas Holmquist, Michał Wadas and Feng YuOh, 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/nodefor 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?I'm also skeptical that separate releases/repos can really solve this problem.
@types/nodehas 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
@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/nodejsmaintainer 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.As a long time Node.js user, my experience with the
@types/nodetype definitions was that they were decent for the common function arguments but quickly broke down for lesser known features.e.g: the custom
lookupfunction that can be passed tohttp.connect()andnet.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
stringand not say an enum type withutf8,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.
I've put some thoughts into this for a long time. Let me list the current issues I've seen when using
@types/node:- 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.
- 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.
- The Node.js collaborators have no control on how a significant portion of their users use their work, as
@types/nodeis not governed by the collaborators. - 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 aneed-typeslabel or create good-first-issues to add the typings.If we feel we should make this happen, I think the best path forward is:
- Devise a plan with the typescript team, and see if they are onboard
- Have a PR created that brings the most up-to-date version of
@types/nodeinto core as a basis - Create a typescript team or working group and onboard the interested maintainers of
@types/nodeinto it.
I'm happy to facilitate all the above.
Reacted by Valentin Marchaud, Yosh, Robert Nagy, Chengzhong Wu, Tomas Della Vedova, James M Snell, Ruben Bridgewater, Denys Otrishko, Charlie Fish, Théo LUDWIG and 3 moreReacted by Yosh and Devin Rhode@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.
Reacted by Wesley Wigham and Kristjan27 remaining items
There has been no activity on this feature request for 5 months and it is unlikely to be implemented. It will be closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.
There has been no activity on this feature request and it is being closed. If you feel closing this issue is not the right thing to do, please leave a comment.
For more information on how the project manages feature requests, please consult the feature request management document.
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
wasiapi 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
libsfolder ), 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.