sinonjs
Suggestion: Convert to Typescript
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?
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:
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.
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 https://github.com/sinonjs/fake-timers/pull/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.
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.