.d.ts typings

[downace]

Added TypeScript typings

[watson]

Thanks for the contribution @downace. There's a big risk that these will not be kept in sync with the code-base. How do projects that isn't developed in TypeScript normally ensure this doesn't happen?

[downace]

It should be done manually by contributors of the project when major/minor version releases (according to semver - interface is not changing on patch release). Or by somebody else who uses this package in TypeScript code (like me) using PRs. I think there is no more reliable way

There is an alternative: I can PR this typings to the DefinitelyTyped repository. Of course, desync is possible too, but you can not worry about it because there is huge community that will do all the job for you (I think 😄)

[boyanio]

This is indeed an interesting discussion. What I have seen as a typical solution is:

• if the project is developed in TypeScript, it is easy - the typings come along
• if the project isn't developed in TypeScript, typings usually go to DefinitelyTyped.

I would argue that typings on DT are actively maintained. The bigger the community for the project, the bigger the chance someone will use TypeScript, the better the maintenance for the typings.

[pmuellr]

Is there some easy test that can be run to ensure the .d.ts file matches the .js file? I've been interested in trying something like this as well, but would want that tester before actually doing it.

[trivikr]

@pmuellr That would be a good question to ask to DefinitelyTyped or TypeScript community. The feature would be very helpful.

Is there some easy test that can be run to ensure the .d.ts file matches the .js file? I've been interested in trying something like this as well, but would want that tester before actually doing it.

Btw, we'd recent discussion about the same topic at fastify/fastify/issues/649

[appsforartists]

DT has some rad tooling to automatically ping former contributors to code review new PRs and automatically merge-and-push to npm.

If your project is comfortable committing to update your d.ts file when your public API changes, including the d.ts file in your npm module is convenient.

If not, DT is a really good alternative. It's only slightly more inconvenient because dependents need to know to yarn add @types/your-package on top of yarn add your-package.

[trivikr]

Thanks @appsforartists for the information
The DynamicallyTyped email updates seem very helpful.

That way the maintainers of the JavaScript projects can put their time/efforts in making their package better, while TypeScript maintainers can just worry about updating the type definitions when main package has major updates.

[appsforartists]

To be clear, those notifications are for changes to DT.

So, if your-package publishes v3, nobody on DT will be notified.

However, if someone opens a PR on DT for @types/your-package@3, the person who wrote @types/your-package@2 will be pinged for a review.

[garthk]

The advantage of DT is more ready access to a community of TypeScript developers who don’t use your package, but who might plausibly help fix your typings.

The disadvantage of DT is that it’s a terrible way of relating to TypeScript developers who do use your package. You ship API changes, and your users don’t get them until one goes to the effort of filing a PR. You don't ship API changes, but your users' builds break because someone decided to rename an interface because they prefer or don’t prefer a leading I, and for some reason that always seems to ship as a semver patch update to the typings. Your users lock the version so their builds don’t break, and then they don’t notice the great new feature in a semver minor change.

DT is better than nothing, but you can do a lot better than DT. Add a .d.ts file. Use your type names in your JSDoc strings. Add a jsconfig.json. Any VS Code user editing your code or their code using your code will then see typing mismatches, even if all the code is JavaScript. Unit test by transpiling a single .ts file that uses your API. It’s not much effort, and the results are much better for your users.