Suggestion: Convert to Typescript

[fatso83]

Throwing this out here. Looking at the commit log since 2016, the maintainers that have been adding code to fake timers seem to be me, @benjamingr and @SimenB . All of us have either expressed a desire to add Typescript or at least a lack of antipathy (as in "it works either way"). For me, Typescript shines for libraries as it gives our users great developer experience out of the box: intellisense and types that are always up to date for consumers. There are types available in DTS today: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/sinonjs__fake-timers/index.d.ts

These could be integrated with minimal effort. It also helps when working with the internals of the project. We would not need to rewrite tests, these could stay JS (for now) - it is mostly tooling.

Thoughts?

[mantoni]

Many projects opt for TypeScript types generated by JSDoc these days. I use it this way extensively and I'm not missing anything.

The benefits of that approach:

• No transpiration: Source code ships as is + generated .d.ts files, no source maps needed.
• No rewrite required: Types can be added incrementally, also to tests where beneficial.
• Documentation: Since JSDoc is already in place, adding documentation is extremely easy and integrates with TypeScript tooling (documentation shown in completion hints).

Some popular projects using this approach:

• Prettier
• ESLint
• Svelte

This is how I would do it. However, given that I currently can't afford the luxury of working much on open source, it's not my call and I'm not standing in the way of whatever changes you want to make to the project.

[fatso83]

We already tried the JSDoc -> TS approach in 2021 with version 7 and we had to revert that work after some months (gone by version 8) as the results were much poorer than what they already had through DT. This is the conclusion I wrote in #386 about that effort and why we had to revert:

When adding JSDoc to our functions our main points were

Give us documentation, API docs
Give autocomplete and type suggestions in supporting IDEs

As an added bonus, we found that it was possible to generate
TypeScript definition files directly from the JSDoc definitions.
There were already community efforts at DefinitelyTyped for
both sinon and its sub-projects, like fake-timers, but as
external projects they suffered from being out-of-sync
with the projects they were supposed to describe. Our thoughts
were then that by generating these directly from the source
that we could in time catch up with the DT efforts and
be the main source of up-to-date .d.ts files.

Unfortunately, there were some aspects of our types that
were hard to describe statically using JSDoc, such as those
where TypeScript would utilize its typeof type operator.
That resulted in contributions that used the
fact that TSC ignored invalid type definitions to describe
types using those TypeScript features. The result was valid
d.ts files, but invalid JSDoc, meaning our two main points
were unmet. JSDoc simply is not powerful enough to generate
the types expected by the users of the DefinitelyTyped
types. So, in order to get back to what we mainly want, we
stop shipping TypeScript definitions and continue to let this be a
community maintained effort at DT (as it was). This should
result in less friction (as experienced in the last few
months), but will, of course, have the downside of always
lagging a bit behind.

[mantoni]

JSDoc simply is not powerful enough to generate
the types expected by the users of the DefinitelyTyped
types

This might have been true in 2021, but it's definitely not anymore. There is really nothing you cannot do with JSDoc, because you can use "TypeScript" mode which allows you to use arbitrary TypeScript expressions.