What do you not like about DefinitelyTyped as a user and contributor?

[orta]

What do you not like about DefinitelyTyped as a user and contributor?

Hey folks, we, the TypeScript team at Microsoft, are interested in understanding pain points for people using and contributing to DefinitelyTyped.

About this time last year, we drastically changed the workflow for contributors to DefinitelyTyped (one of the most active repos on GitHub) to allow for self-serving Pull Requests. Since then, we've been refining that process and improving the automation to cover more cases and consolidated all of the DefinitelyTyped tooling into one monorepo and re-vamped the search. Now that these systems have matured, we're thinking about what the right things to look at next, and would love input from the folks who are writing definitions daily.

I've explicitly given an opening for users of @types to provide feedback here too, given that it's quite likely any requests as a user of DT will affect contributors too.

We've used a format for this before which worked well in #31983 which is for people to reply to this issue with a single idea per comment.

We've got a meeting booked on the 20th to go through feedback and see what's we can do 👍🏻

Please do: reply with 1 comment per issue. Add tags if you'd like to help with search for others and ease-of classification. If you have a link to an existing issue, that would be super useful too.

If you see that someone has already pitched your idea, please use the emoji reactions to +1 it, we will be deleting duplicates and off-topic replies. If you want to add more to a topic, see if it has an attached issue and leave more feedback there. If there isn't, come chat in the DefinitelyTyped chatroom in the TypeScript Community Discord.

Please do not use this thread for discussions about the TypeScript language itself, and as with all issues please conform to the code of conduct. We all want to see improvements.

Template - feel free to copy & paste

### [title]

[message]

Tags: `[tags]`

For example

One of mine:

---

There is no REPL for Type Definitions

I would like to use the Playground to work with .d.ts files to be able to share problems with others

Tags: playground

---

[orta]

There is no REPL for Type Definition writing

Making a good .d.ts file is kinda of a unique skill, the many ways in which your types are consumed can mean it's hard to know ahead of time what the right setup for a .d.ts file looks like.

It'd be good to have an environment where I could easily work with a set of projects that have different import options in order to test that the exports from my lib indeed work like expected.

Tags: playground

[dylang]

Link homepage in package.json to the exact page where the type source is located on Github.

Example type:
https://www.npmjs.com/package/@types/webpack-dev-middleware

Currently we see:

Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped#readme
Repository: https://github.com/DefinitelyTyped/DefinitelyTyped#readme

This makes it hard to see what the types look like before installing them, or where to find them if we want to make changes.

Ideally, homepage in the package.json would link to something like https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/webpack-dev-middleware - and perhaps an automatically generated README.md on that page specific to this project.

Tags: homepage, repository

[43081j]

More docs/guides on generating types for existing projects

Many authors of existing projects are afraid of the burden of having to maintain typescript types on top of what they already have to maintain.

I don't think there is actually much of a burden anymore as you can quite easily generate type definitions from JSDoc of an existing project without migrating it to typescript.

However IMO there's not enough official documentation on this, and not enough emphasis on it when introducing existing authors to typescript. This is what leads to them assuming it must be a huge job they won't have time for or a new skill they need to learn.

There should be a push to make DT smaller by sharing the knowledge of how to generate types in source repos, basically.

[dylang]

npm deprecate type package once the original package has types.

Unless we see an announcement in a changelog or release notes, it's difficult to know when we can remove an @types package from our repository.

Example: webpack@5 now includes types, so @types/webpack can be removed. The deprecation message would be something like Webpack now includes types starting at 5.0.0. You can safely remove @types/webpack.

npm deprecate allows deprecating of a version range, so we'd just deprecate @types/webpack@>=5.0.0

https://docs.npmjs.com/cli/v7/commands/npm-deprecate

Tags: deprecation, deprecate, old @types

[nirtamir2]

Update of @types packages with the corresponding library version

Ideally @types packages should be with the same minor version of the original package (and the latest patch) as described here.

When upgrading dependencies it can be easy to forget to upgrade the correlated @types to the same version too.

Also, because it is maintained separately from the library, the right version could not exist when updating - leading to a mismatched version.

Tags: update, version, dependency

[Pokute]

Issue and PR titles have too wide variety since there's no template for the issue titles.

I'm not sure if GitHub allows issue/PR titles templates it, but having them unified would be nice. For example, react as a search term gives a lot of packages, while [@types/react], with more uniform titles, would drop a lot of noise.

On the other hand, above example might miss something like react-dom and that might be a minus.

Tags: issue, pr, title

[Maxim-Mazurok]

Make automatically generated types for Google APIs first-class citizens on DT

I auto-generate types for Google APIs, and there's no way to properly sync them to DT.

I used to create PRs from one account and approve them from another, using GitHub API (DefinitelyTyped/dt-mergebot#98). That was a beautiful piece of automation but was considered bad (DefinitelyTyped/DefinitelyTyped#49235).

Now I publish generated types to npm (example) and reference them in the corresponding DT package (example). This still has a challenge of syncing new and obsolete APIs (Maxim-Mazurok/google-api-typings-generator#401) which currently is manual and results in huge PRs (DefinitelyTyped/DefinitelyTyped#52618). Also, it's bad for versioning (DT package version stays the same), but this can be managed through lock-file, so I guess it's fine. But could be better :)

I have some ideas on how to solve this if anyone is interested. Please, find my contacts at https://maxim.mazurok.com

Tags: automation, generation, google APIs

[eps1lon]

Queue for PRs

I know you mentioned that the boards are one but it's either bugged or I don't understand how it works.
PRs above my PR are sometimes older, sometimes newer. It would remove a lot of frustration if I could check how many more PRs need review (think about traffic lights displaying a timer next to the lights). Right now I'm just idly waiting for 20+ days PRs to get attention (and I even had 40+ days once I believen) and I don't want to ping people constantly (which I also don't think is fair to put on PR authors as a burden).

[peterblazejewicz]

Solo owner package support to avoid backbenching

There is a lot of folks and/or organization using DT power to publish content (both for the benefit of the community and, obviously, the published project). see @Maxim-Mazurok comment for one of those scenarios.

There is a lot of those, say a single person working on TS types for interesting JS topics and publishing through DT or organization, that adopted JS, but maintain or publish .d.ts files through DT. Because those are large ('huuuge' in old american), usually non one helps those solo projects until eventually DT maintainer arrives. This impacts consumption of changes of those packages (DT package can be for a Google api or for well known UI projects, say open sourced IBM effort, NPM native code already published literally weeks ago).
Sometimes those DT types are for upcoming JS features (schemas and backing types for non-released apis), so literally, the audience that know DT topic is sparse. This delegates PR to backbanches.

We could have solo owners txt on tooling, that would bypass required DT steps, after all checks passed.

Thx!

Tags: pr, owner

[AlCalzone]

Lack of maintainer assistance on critical packages / false negative CI checks from other packages

I usually have a good experience with the types I own. Create a PR, get someone to review, done!

Nearly all my negative experience comes from the interaction around this PR. I tried to improve the promisify typings in node by using conditional types after being asked to do so by @DanielRosenwasser (which lead me to believe there was some interest by the TS team). That package has a particular difficult structure to support different TS versions, which made the following interaction even more painful.

It took 3 weeks to get a maintainer review, which I addressed within a day. In the following 6 months (!) I never got another review despite asking for it, but multiple pings from @typescript-bot because:
a) some dependent package broke their typings (which caused my PR to fail its build)
b) other node PRs got merged that required me to fix complicated conflicts
c) or simply because nothing happened in that PR in a few days

As you may infer from my comments in the PR, I got frustrated and gave up on it (although I still think the change is good). In the end I'd hope for a bit more drive and team support behind the "core" typings.

Tags: review process, critical package

[BendingBender]

CLI tool to consume @types packages

It would be very nice to have a CLI tool that uses the list of packages in package.json to install all the missing but available type definitions. Probably with a couple of flags, like for example only for dependencies or only for devDependencies with possibilities to include/exclude specific packages.

Maybe even better: a replacement tool for npm install [--save|--save-dev] packageName - types-install [--save|--save-dev] packageName that would be able to install a package along with the corresponding definition (if available) in a compatible version. So running types-install --save-dev webpack@4 would install webpack@4 along with @types/webpack@4.

It could install @types packages when available, simply skip installing @types packages if a package has types bundled and propose to create new types for packages that don't already have types on DT along with first instructions on how to do it.

Tags: tooling, cli

[ExE-Boss]

Using GitHub’s discussions feature

I feel like enabling GitHub’s Discussions feature would be beneficial, with this issue being a decent candidate for migration.

Tags: meta

[eteeselink]

Encourage contributors to send typedefs to library repo first

While plenty of library authors want little to do with TypeScript, even more simply don't know how to ship or maintain good TypeScript bindings. For the latter category, it would be much more useful if someone contributes a TS typedef to the core repo instead of to DefinitelyTyped. In a way, DefinitelyTyped is a bit of a cop-out, a plan B. A necessary plan B, but a plan B nevertheless.

For example, I feel like it's weird that the How can I contribute guide appears to actively discourage communicating with the author of the open source package at hand. Or, well, not actively discourage, but it's simply not even presented as an option. Isn't that weird? Wouldn't the home repo be the best place for the typedefs to live?

I think it should be a goal of DefinitelyTyped to one day not be necessary anymore. Sure, it'll never happen, because TS will never have 100% penetration, but it should be the direction. But right now, it's more like DefinitelyTyped is poised to be an ever-expanding mountain of half-maintained typedefs that continuously run the risk of lagging behind their JS packages. It's better than no typedefs, but way worse than what it should be.

Therefore, I think the TS/DT teams could do more to help library authors and/or contributors ship types directly. Eg:

• Write HOWTOs for various common scenarios (generate from JSDoc, hand-write, generate from actual typescript sources, etc etc)
• Add/link these in the contributing guide.
• Have the contributing guide actively encourage communicating with the library author instead of going behind their backs.
• Come up with a simple, noob-proof mechanism that lets library authors pull an existing DT typedef into their main repo (and have the @types/somelib package somehow stay compatible - maybe an export ... from "somelib" oneliner? or just unpublish from npm? I'm not even sure, and I doubt a non-TS-expert library author will find this easier)

Tags: meta

[BendingBender]

Notifications on minor/major releases

It would be great if the DT bot would watch the npm index for minor/major releases of packages that have typings on DT and automatically notify the maintainers on updates.

I don't really have a good idea on how to notify the maintainers, an obvious choice would be to create issue tickets but that would pollute the issue backlog even more. Maybe such automatically created tickets should be then closed automatically after some time if no one contributes and they should definitely be closed automatically after someone updates the typings in question.

There should also be possibilities for typings packages maintainers to be able to close such tickets without making pull requests in cases the library updates don't introduce API changes (which happens quite often, major releases often are made when compatibility with older Node versions is broken, for example).

Tags: update, version, automation, repository

[sgravrock]

npm run test-all could be highlighted and better documented

test-all checks the packages I changed as well as the packages that depend on them. That's great! It's exactly what I want. I get confidence that my changes are correct without having to wait for the tools to check thousands of unrelated packages. But it's only mentioned in passing in the README, it's not part of the steps for preparing a PR, and I haven't found any documentation that explains that what you have to do to make it work correctly. (IIRC: have your fork's master branch and the current branch up to date with the main repo, and check everything in.) I bet more PRs would land cleanly the first time if this were better documented and recommended as part of the process for preparing a PR.

Tags: documentation

[peterblazejewicz]

Composing prettier configuration

Completely overlooked this huuuge (3xu) PITA: the DT disallows composing .prettierrc, which forces organizations/individuals/teams, to swap one style into another style. It's like gold exchange standard, whcih never worked well.

This would allow to compose:

• tab vs space (obvious one)
• single vs double quote (less frequent, but happens, especially now when large projects are shipped via DT infrastructure
• let people spend time away from keyboard

/cc @fedemp @pkuczynski

Tags: prettier, format, spaces vs tabs

[orta]

Hey folks - we had the meeting and here's our general notes and the list of outcomes at the bottom for TLDRing. I'll keep this issue open for a week or so and then close and lock it out 👍🏻 - thanks for the feedback!

Improvements to DT Publishing

• @dylang - Link homepage in package.json to the subfolder in DT
  • Orta shipped this today
• @dylang - npm deprecate a deprecated package
  • Orta will look into feasibility

Improvements to DT Infra

• @nirtamir2 - Update of @types packages with the corresponding library

  • It's hard to know when app changes should trigger .d.ts work
  • We can't think of a reasonable way to notify folks which won't be spammy
  • The people who want to know can subscribe to the releases for the packages on GitHub, we probably don't want to do this.

• @Pokute - Be more vigilant on PR and issue titles, provide templates

  • Underlaying issue: GH search isn't great and it's hard to keep on top of any DT types you own

  • Can we remove issues completely?

    • Thinking about conceptual issue bankruptcy at least
    • We think most issues aren't very useful, people write them with the expectation others will fix their .d.ts issues but it rarely happens
    • We'd like to make DT issues be only about DT-level questions ( e.g. don't make DefinitelyTyped-tools be the source for those issues ) and discussions can be for DT module stuff.

  • Can the Bot can control PR titles more?

    • We think the super popular modules don't want that probably
    • As maintainers we don't really look at titles, mainly at the cards, so it's hard to say if we're good people to make this call

  • We should take a fresh look at the PR template regardless

• @Maxim-Mazurok - Make it possible for me to ship Google's types

  • Maxim used to automate PRs, but started to ship lots of small PRs which were basically NOOPs (because it updated every hour) and we asked to move that off-DT
  • e.g [gapi.client.classroom] automatic update DefinitelyTyped/DefinitelyTyped#49226
  • Now deploys on own npm org, and the @types version depends on it: e.g. @types/gapi.client.sheets -> @maxim_mazurok/gapi.client.sheets
  • Request is: Can DT folks re-think about a process for people who are automatically publishing types?
    • We do this with a few clients (some in MS, like office, but they are still reviewed by other authors)
    • We think moving back to @types to a slower cadence could be ok, 1 automated PR per week
    • It's a reasonable cadence from our perspective, I'm sure there's value in being bleeding edge, but probably not for the vast majority
    • Today consuming @types/gapi.client.sheets has a potential security expectations mis-match
      • User expectations on DT are that they are more secure (e.g. for ATA we use "no scripts" etc but most consumers are TS folks who won't have that on)
      • Better to have in-house for us, but we'll see if cadence is an issue

• @peterblazejewicz - Can we declare certain DT packages as being solo owned and have less process on them?

  • We think solo packages go slower than we want
  • We don't want to make it suck going from 1 maintainer to 2 maintainers, so making 1 maintainer get 'easier PR review' means making it harder for 2
  • Can we change the queuing algorithm to speed up 1 maintainer PRs?
  • It's now much easier to merge whenever you are ready - we think some recent dt mergebot changes will amke that easier
  • We should give bless @peterblazejewicz collab access regardless - there are existing folks who aren't in the TS team
    • Can we make another tier on the bot? E.g. Low risk, anyone with collaborators - Orta to explore
  • We think the answer for this lays in the DT queuing responses below

• @BendingBender - DT module owners should be able to close issues relating to DT packages

  • If we're closing issues, this probably isn't a thing. Worth thinking about for discussions in the future, maybe anyone can close a discussion with the right keyword?

• @peterblazejewicz - Support composing prettier settings

  • Orta wrote build: Revert force double quotes through prettier DefinitelyTyped/DefinitelyTyped#52946 (comment)
  • General agreement for banning changing the root configs, general agreement for saying "OK" to prettier configs in subfolders as they only affect tooling. They would be considered DT infra, so PRs adding them would still be DT maintainer reviewed.

DT Admins

• @eps1lon - Can we make a queue for DT PRs?

  • Since the bot alread has the computation of activity, and we checkedd that you can re-order from the API

  • We can make the dt-mergebot 6 hour run sort the activity date

  • We could also make views to easily see the things that are closer to nagging and timeout etc

  • How do we sort? How do we decide what to do

    • Used to be an easy bucket and a hard bucket for DT
    • Now both on each side are basically hard because easy ones are automated
    • How could 'solo and new' be sorted vs 'un-reviewed by others for a week' ?
    • Could there be a better columns ideas?

  • Critical packages are hard. We don't have a great answer. We're very conservative on both merging and saying 'this isn't going to happen'. E.g. a jest PR with a bunch of DT maintainers saying 'we won't make this call'

  • Can we be more upfront on how conservative we are as DT maintainers

    • e.g. we do this pretty well with lib.dom.d.ts ?

  • Can we find better ways to test breaky things

    • e.g. an actual real-world test suite for the big ones like react/jest etc
    • we can just make a set of RWC runner stuff
    • Can we make ad-hoc packages of existing PRs?
    • We have the DT Review Playground plugin shipping this week

• @AlCalzone - OP had hoped that a comment on a TS issue from Daniel would mean he would support him through a DT PR to node which the node maintainers seemed mostly OKish on.

  • This fell through the gaps because it became a failed CI / merge conflicts quickly and never ended up on the DT admins TODO lists, node maintainers got pinged a few times but no-one committed. Hit the same issues as above ^
  • Better testing infra might have de-risked the PR and got more folks into their idea

Docs

• @sgravrock - Do a better job telling people npm run test is what you want to use

  • Agree (especially for react types)

• @eteeselink - Encourage contributors to send typedefs to library repo first

  • Our general opinion is that you should only really ship .d.ts files from your package if they're generated from your codebase
  • we don't want to add a maintenance burden (and to put off people from eventually checking out TypeScript)
  • Almost everyone is bad at writing .d.ts files (including us, maybe not Nathan)
  • The people who have the least experience are the folks who suddenly got a .d.ts that they don't understand a dep
  • Lots of us have recent stories of interacting with npm modules which are JS focused and the .d.ts is out of date or hard for the maintainers to grok PRs for
  • We think the reasoning for 'dt first' then 'a .d.ts in your project' is still valid in 2021

• @43081j - More guides on generating types for existing JS projects

  • Agree

Misc

• @BendingBender - CLI tool to consume @types packages locally

  • We're probably not getting into the dependency management business
  • Yarn 2 has a plugin which does this
  • Someone could do the npm RFC, not Orta, he is cursed in the npm RFC system

• @ExE-Boss - Turn on GH Discussions

  • We probably will

Action Items

• Look at the npm deprecate infra
• Figure a good way to move issues to discussions and re-frame what to expect from them
• General docs improvements in the DT README and JavaScript section on the site
• Get a list of all the critical DT packages, look into making a RWC testing suite for those packages
• Look at generating PR DT releases
• Explore sorting the DT maintainers columns
• Look at changing the columns in the project to be simpler and logical from the outside
• Write down somewhere about the DT maintainers being conservative and for critical packages it need enthusiastic support for DT module owners
• Write down our opinions on the occasional formatting wars which breaks out so we can just refer to it when someone wants to make DT-level code formatting
• Explore the idea of deputize some folks without giving the write access to the repo but giving them DT maintainer level access on the bot
• Look at the PR template with fresh eyes
• Make the bot say to not make changes to the root editor config files

[Maxim-Mazurok]

Hello, @orta, thank you for your feedback regarding "Make it possible for me to ship Google's types".

There are ~200 packages/APIs right now, so it's potentially 200 PRs per week. And there's no guarantee that they'll be reviewed and merged within one week. Actually, there's a pretty solid chance that they'll be stuck there for months :)

One hour cadence was chosen because these types are used with the front-end JS APIs that are only available in CDN-style, without version binding. People add <script src="https://apis.google.com/js/api.js"/> to their page, which loads the latest API schema and generates functions from it on the fly. So, ideally types have to match the same cadence: be generated on the fly every time you, which is not feasible. I did tests and monitored APIs for changes, came to the conclusion that hourly updates are reasonable and would very much like to keep it that way.

Regarding security, I have branch protection rules in the repo, I have tests and linting set up as well. I have dependabot updating dependencies weekly (currently on pause because dependabot/dependabot-core#3132). So, my typings are more secure.

Also, my users depend on https://apis.google.com/js/api.js, which can be a security issue if it gets hacked and the script is replaced with something malicious. One way they can mitigate this - is by manually copy-pasting content of this script to some local file, and doing review of the compiled JS code (something like this Maxim-Mazurok/gapi), which realistically no-one does and it's not recommended.
So, if they trust api.js, why would they not trust my typings?
In case if they don't want to take any chances - they can do the same thing as I've described for api.js - they can copy-paste types, review them and only update manually. Even more, they can use my generator repo to generate their own typings.
There's no magic and nothing is happening behind the curtains, all the sources are on GitHub, generation, tests and publishing to NPM is happening on GitHub Actions.

I was hoping that generated types will become first-class citizens.
Now I just hope that they won't loose their citizenship (again) 😢

[orta]

Yeah, I know any dependency is a security risk but the point is that the potential contents of the npm package are different - someone cannot ship a preinstall script in an @types package, but one that just depends on another package can. It's not about your settings, process and dependabot etc - that doesn't really matter for the security of consumers for your package. A types package is just a few dts files, license and repo with nothing executable. Any other package can contain other stuff.

The point is that DT has a security model which allows people to trust arbitrary @types modules to do nothing, and this has the potential to undermine it. Every one of these is a gap in that security model.

Realistically, I think you'd be better off talking to google and getting these types auto-generated and deployed on their own npm
scope. Then have that be recommended officially with typesRoot to get picked up automatically. Or even better, re-use how VS Code extensions work and pull the latest as a preinstall hook on a module so that someone doesn't need to think about versioning (and can trivially update).

Given your response, I don't think there's a reasonable answer here that doesn't hammer DT's infra again, or mean these changes are waiting on a DT reviewer every week for multiple package changes on a weekly cadence. I thought we were going to be looking at a much smaller amount of changes from those types, but I think what we have today is the best in the set of trade-offs which still allows for them to exist on @types but also be as up-to-date as you want. So, basically how it is now is probably how it will stay.

[Maxim-Mazurok]

Yeah, I know any dependency is a security risk but the point is that the potential contents of the npm package are different - someone cannot ship a preinstall script in an @types package, but one that just depends on another package can. It's not about your settings, process and dependabot etc - that doesn't really matter for the security of consumers for your package. A types package is just a few dts files, license and repo with nothing executable. Any other package can contain other stuff.

The point is that DT has a security model which allows people to trust arbitrary @types modules to do nothing, and this has the potential to undermine it. Every one of these is a gap in that security model.

Yeah, I understand. Perhaps, we can create DT bot that would pull and re-publish another NPM package with stripped preinstall script? Or, this can be the responsibility of some enterprise NPM, such as ProGet.

Realistically, I think you'd be better off talking to google and getting these types auto-generated and deployed on their own npm scope. Then have that be recommended officially ...

Yes, that's definitely in the roadmap. I want to test it in the wild and add more tests before bothering folks at Google. By the way, if anyone knows someone at Google who might be interested - please, let them or me know (max@mazurok.com).

... with typesRoot to get picked up automatically. Or even better, re-use how VS Code extensions work and pull the latest as a preinstall hook on a module so that someone doesn't need to think about versioning (and can trivially update).

I don't know how VS Code extensions work, but one thing to keep in mind is that there's no NPM package to go with front-end Google APIs. It's not installed from NPM, so we can't ship types with the code. Code is shipped from CDN.

Given your response, I don't think there's a reasonable answer here that doesn't hammer DT's infra again, or mean these changes are waiting on a DT reviewer every week for multiple package changes on a weekly cadence. I thought we were going to be looking at a much smaller amount of changes from those types, but I think what we have today is the best in the set of trade-offs which still allows for them to exist on @types but also be as up-to-date as you want.

Yeah, all solutions that I can think of, require pretty big rework on the DT side, there's no easy fix here.

One more potential solution is to create some sort of API or environment to run generation scripts or consume their results.
For example, I publish my generation code into DT repo instead of typings. DT bot runs this code periodically and publishes typings. This potentially has a lot of security issues, if I can eval any code that I can download from the network, I probably can use DT bot to DDOS some website, etc.

Another option is to create a DT API endpoint, where I can send updated index.d.ts. I'll be still generating types on my side, and then send the result to DT API, which may or may not be automatically published to the repo, but definitely should be published to @types NPM.

That's probably too much work for DT to support just one "package"... But perhaps, if automatic generation will be easier - more people will do it? In any case, I'll be happy to help with this.

So, basically how it is now is probably how it will stay.

Otherwise, I'm ok with leaving it as it is for now.