Sinon: TypeScript definitions

[43081j]

We currently have typescript definitions for sinon at @types/sinon.

What do you think about moving these into sinon directly? We can specify types in package.json to reference our d.ts file.

The TS maintainers recommend this IIRC.

Couple of reasons this is beneficial:

• It can become part of sinon's release process (if possible) to ensure types match the implementation
• The two will no longer fall out of sync (they do very often right now)
• TS support is automatic, no need for an extra types package
• TS is pretty popular by now, good to support that "officially"
• sinon maintainer(s) have tighter control over the definitions (helps avoid people adding types which are unofficially supported)

I wouldn't mind doing a PR to introduce them, and what I can to help keep them up to date. Plus the people who have been maintaining the ones in @types will likely be happy to do PRs here instead.

From what I remember, there's a documented method of testing types too so we could potentially introduce that to the build process.

What are your thoughts on this?

cc @mroderick

[mroderick]

Sinon is a JavaScript library written in ES5.1, supporting JavaScript from ES5.1 onwards. Our goal is to make testing JavaScript a little bit better.

It is great to see there is a community solution for making Sinon easier to use with TypeScript. I see that there is also a community effort to make it easier to use Sinon with Flow (flow-typed).

What you're proposing will move the burden of supporting TypeScript, a whole different language with it's own roadmap, into Sinon, and onto the stewards of this organisation. This will increase the maintenance burden, without any direct benefit towards our primary goal. The increased maintenance will detract from our other work on features, documentation and bugs. I think that for now, it would be better for Sinon, if we keep our focus on our primary goal.

There is absolutely value in providing convenience.
However, I think that cost of that convenience should be paid by the community that benefit from it.

If there is a way that we can make it easier to keep the type definitions up to date, then I am sure we will be glad to discuss it.

[43081j]

that's fair enough.

if the extra responsibility would be too much to take on, it'll just have to stay in the definitelytyped repo.

as for keeping the definitions up to date, its an odd one really. we can't expect you to open an issue at DT every time you push a breaking change. right now, the community type definitions can pass their "tests" but be completely wrong in relation to sinon's actual implementation (they have been many times).

the best we can do really is keep a close eye on your version bumps and put some effort into cleaning up the types we already have (they are too lenient right now).

[greg-md]

I think it's time to support typescript by default. @types/sinon is out of date by 2 major versions.

[43081j]

in the mean time if there's missing or wrong types in there, @greg-md, please do open an issue at DT and mention me. i usually update them pretty quickly.

[greg-md]

@43081j there are many. For example SinonFakeTimers doesn't have *Async methods.

[fatso83]

I think it's time to support typescript by default.

Sure. Put in the work to make it happen :smile_cat: The thing is, this project is not going to be rewritten in TypeScript, so these are basically the alternatives (that we know of):

1. Manually keep a definitions file up to date.
2. Auto-generate a definitions file from the source.

Doing the first option is what happens today using the @types project. That could easily get out of sync, of course, but is relatively low-effort. The second option is of course "nicer", but it would require a bit of tooling support. What we have discussed here, but not done anything about, is generating Typescript definition files from JSDoc comments. @mroderick has done some work on that.

[fatso83]

@43081j Regarding the timer definitions, maybe it's possible to reuse the definitions from @types/lolex? That would save a lot of effort.

P.S. Lolex and Nise has been renamed, btw.

[43081j]

@fatso83 there's a PR in progress now to do exactly that 👍

typescript definitions should live here instead of DT, in an ideal world. but that means rewrite in typescript or try generate them from jsdoc. until then, DT is fine

ill have a look but if @mroderick has done so already, would be useful to share the progress