🚀 Feature: TypeScript .d.ts type declarations

[boneskull]

AFAIK, it's recommended by both the TypeScript team and DefinitelyTyped (the people that publish everything under the @types scope on npm) that packages ship their own type declarations (.d.ts files). I think this is essentially for two reasons:

1. It's tough to maintain types for a package you don't control
2. The package owners are the best people to understand what the types are

I was on the fence about this for awhile, because I wasn't interested in trying to manually maintain declarations.

Recently, TypeScript introduced support for generation of type declarations from JavaScript sources.

I've used this feature pretty extensively (see report-toolkit) and have had good success with it. The way it works is this:

1. Use JSDoc-style comment tags, where appropriate, which TS can understand.

   Mocha is already most of the way there, I think. Depending on the extent of the type inference, we may be able to restrict it to a subset the source code (initially, the user-facing, non-programmatic APIs), instead of needing to meticulously work through the entire codebase under lib/, but it's hard to say until we try it.

   Custom types (describing the shape of a plain object or the signature of a callback) are accomplished via @typedef. These are equivalent to TS' type keyword and subject to the same limitations.

   One place where we may get tripped up is that TS is unable to understand prototypal inheritance when not using the class keyword. So, though Test extends Runnable, we won't be able to illustrate that via the declaration--but if we focus on non-programmatic usage, this is moot.

   We need to make sure we're not breaking our API doc generation, though. I don't think this will be much of an issue, as that's mainly focused on the programmatic API. We can revisit the programmatic API at a later point.

2. Use tsc to generate a .d.ts artifact from the sources we care about. Make it part of the build process; it doubles as a "type linter", because if something is incorrectly typed, the build will fail.
   Publish the resulting file(s) and keep them out of VCS.

Comments? Hate the idea?

[DanielRosenwasser]

I'm super happy to see the enthusiasm here! I'd be a bit cautious though because depending on how your types differ, users may see some differences (at least initially) or have dependencies on how the types are declared. I think it's still worth trying to compare/contrast though!

I'd also heavily recommend using checkJs to validate that your types are correct as you do this too - not just using allowJs

[DanielRosenwasser]

(also we're looking for feedback!)

[weswigham]

You'd probably wanna try to make sure your API that's generated is compatible with the one exposed by @types/mocha, at least, since once you ship one, it'll override that one; so to make the transition easy, making the type names and structure the same as what's currently documented on DT would be useful.

[boneskull]

@weswigham Meaning that if someone has @types/mocha installed, and we start shipping declarations, TS will just ignore the @types/mocha ones?

[weswigham]

Yep. A design decision made a long time ago was that a package's own declarations take priority over declarations from the @types namespace - it's more of a fallback than an override.

[juergba]

I had a look at DefinitelyTyped - Mocha, it supports Mocha v5.2 and takes about 3000 lines.
To keep this file up to date seems to be a huge task.

We should start improving our JSDoc for that purpose, but not ship yet any mocha.d.ts file with our package or override @types/mocha.
The past few months it has been difficult enough to publish a release or just to get a review for a PR. So I'm afraid of paralyzing ourself with any additional task we are trying to fulfill.

If we start shipping @types, the quality has to be excellent, otherwise we get flooded by issues we are not able to handle.

@cspotcode was involved in @types/mocha. His point of view would be interesting.

[cspotcode]

Custom types (describing the shape of a plain object or the signature of a callback) are accomplished via @typedef.

We should also be able to sprinkle type-only .ts files into the code for convenience. We can declare types in these files using TS interface / type syntax, then import them elsewhere.

We can use the DefinitelyTyped tests to confirm compatibility. https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/mocha/mocha-tests.ts

Can mocha start shipping its own experimental .d.ts in an opt-in, non-automatic fashion? Consumers would choose to use mocha's bundled declaration if they want, but it would not override @types/mocha. This would be a good way to get feedback and squash bugs.

otherwise we get flooded by issues we are not able to handle.

The Mocha team should have a list of people interested in bugfixing the declarations. Whenever declaration bugs are filed, those people can be pinged and asked to write a PR. I can be on that list to start.

Is mocha's release process automated? If it's straightforward to publish patch releases, this'll be much easier.

[boneskull]

How would you ship “opt-in” types?

[boneskull]

@juergba

To keep this file up to date seems to be a huge task.

I don’t want to manually maintain a declaration file either.

That’s the idea: it’s generation would be automated from our jsdoc docstrings, of which we have quite a bit already.

but it’s also why this is labeled nice-to-have