Support declaring @types as the supported route for typings dependencies in the package.json

[orta]

Search Terms

package json types field types types module

Suggestion

Allow libraries written in JavaScript to be able to declare that they have types in DT (or other modules), and that they support a certain version of it.

For example:

Express does not support TypeScript but trusts that the DefinitelyTyped express maintainers know what they are doing generally. They want to declare that DT is the way for TypeScript users to get types out of the box. Today that's not really possible.

Examples

Two potential routes:

1. Override the "types" parameter to support: "types": "@types/express:^3.0" in a package.json

2. Recommend a new field in the package.json: "typesModule": "@types/express:^3.0" - then when TypeScript normally offers a 'no types found', then it can offer the command to install with the correct semver range.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

/cc @wesleytodd @isaacs @ljharb

[DanielRosenwasser]

They want to declare that DT is the way for TypeScript users to get types out of the box.

I guess I'm not sure what that means since that's already the default assumption if there's no index.d.ts or types field, with or without an explicit declaration from a package author.

However, this sounds like it's useful for package managers more than anything. I think there's a lot of potential for improving the TypeScript workflow and I've been meaning to follow up with @ethomson about it.

Does that sound accurate? Is there something I might've missed?

[ljharb]

If someone is using TS, and installs a foo that has a @types/foo package, it's a huge amount of friction to figure out if @types/foo exists, at the right version, and then install it, and then keep both in sync.

It would be much nicer if that could be automated somehow - it perhaps doesn't even need cooperation from package authors :-)

[orta]

In yarn 2, the TypeScript plugin's behavior is to automatically grab @types for corresponding modules during the add dependency command. This could be used during that phase that to provide the @types dependency version too. E.g. you install an older version express - you get an older copy of the types too.

[ljharb]

Good to know, but that doesn't help the majority of the ecosystem (npm + yarn v1 + pnpm + etc) :-/

[wesleytodd]

As @orta is pointing out above, the issue this might help solve is the version skew. We have seen users opening issues on Express saying the types are out of date or wrong. Well we don't maintain them, so if we publish a new version and they don't, that is not our issue.

If on the other hand, we could specify a coordinate of the last known good corresponding types (with a semver range like in the OP), we should be able to reduce this friction. Also, if the TS tooling thinks there is an error, it could point users to DT instead of the express repo, because we just telling them "sorry, not our problem", and that is not a satisfactory UX either.

[DanielRosenwasser]

So I think discussing through this is good to understand some sort of ideal workflows, but I think there are a couple of issues that aren't getting solved given the current ideas. For example:

We have seen users opening issues on Express saying the types are out of date or wrong. Well we don't maintain them, so if we publish a new version and they don't, that is not our issue.

I think that a blessed last-known-good version has all the same problems as before (the .d.ts files don't reflect new APIs in the .js files) while introducing a new one: the user got the wrong .d.ts files because the JS package authors specified a too-old LKG version.

This is definitely a concern I hold because most JS package authors I've spoken to say that they don't have the resources to maintain .d.ts files and then get really frustrated if they end up trying. There are also packages with no active maintainer. This is why we've told users to keep things on DefinitelyTyped unless the package itself is authored in a way that generates .d.ts files. If package authors want to be involved with packages on DefinitelyTyped, they can list themselves as DT authors, but from my point of view the decoupling really is intentional.

Also, if the TS tooling thinks there is an error, it could point users to DT instead of the express repo

I understand the frustration here, but saying "If this is a mistake, send a pull request to DefinitelyTyped" could be very noisy in our error messages. Maybe there's some room for UX in the editors, but I think you're just better off adding a TypeScript Types Issue button that links to the types under the New Issue area.

We've been able to cut out a lot of noise on our repo by doing something similar:

• See our .github/ISSUE_TEMPLATE/config.yml
• See our New Issue area

It would be much nicer if that could be automated somehow

I definitely agree with this, but I don't think TypeScript will get in the business of installing types on its own. Our hope is to continue deferring to existing package managers like we do for automatic type acquisition or Install Missing @types Packages.

That said, there's unfortunately a lot of friction around figuring our which @types packages get installed and when. When @types was first being rolled out, I recall one idea I had was to provide a tool to automatically grab the corresponding @types packages. I think there was resistance because the whole idea was that we were trying to just get down from 2 tools (typings + npm) to 1 tool (npm). Looking back I'm still a bit split.

[ljharb]

A separate tool would be perfectly fine.

[orta]

@ThisIsMissEm wondered about using types: { package: "@types/thing" } as an option to describe a package based types in npm/rfcs#126