feat: typescript definitions

[Julusian]

I need to give this another read through, and it needs a bit more work, but here is a draft version of typescript definitions for the library

[foxxyz]

Great! Not a huge typescript fan, but absolutely in favor of having definitions. The problem is that I need some way to maintain them, without actually using TS.

Is there a way to programmatically verify definition compliance with the actual API in case of future changes?

Or, would it be better to automatically generate the type definitions based on JSDoc comments instead?

Or, does it make more sense to submit the types to DefinitelyTyped?

Open to your suggestions!

[Julusian]

I haven't contributed typescript definitions anywhere before, so I am not familiar with any tooling that may help. I generally write everything in typescript, so the type definitions are done for me

Is there a way to programmatically verify definition compliance with the actual API in case of future changes?

Maybe for some of it, but I suspect tools like that will have severe limitations. For example, the on('connected', ...) calls would be close to impossible to detect, and even if it can, trying to verify the type of the data parameter for the touch events would require analysing the execution of that whole method.

Or, would it be better to automatically generate the type definitions based on JSDoc comments instead?

I've rarely used JSDoc (normally writing typescript directly), but in the one project it is being used in I am not impressed. While that project is a lot larger with many files, 90% of the time, it has no idea of what anything is. And that includes the times vscode suggests a method signature for something I am calling, but picked the wrong thing.

It might be possible to generate the definitions from jsdoc, but I also expect them to be lacking fine details. It could be worth exploring if there is any tooling for it.

Or, does it make more sense to submit the types to DefinitelyTyped?

Yeah, if you dont want to maintain them, then that might be a better idea. I thought it worth offering here first :)

[foxxyz]

I think my main requirement for accepting this PR would be a way that it can be "reasonably easily" maintained without actually needing to use TS (similar sentiment to this). What that means in practice is:

1. There are automated checks to warn me if there's a disconnect between the actual interface and the TS interface description
2. I can update the typings file and easily validate correctness if needed

If your PR includes tooling to achieve those two then I'm happy 🙂 . I looked around myself for a while and found check-dts and tsd that may be useful.

[Julusian]

There might be some tooling out there to achieve this, but I dont see how it can cover all the cases and let you not ever worry about the type definitions being wrong.

Simple things like new methods being added wont be detected by the tests, so at various points you will have to think about the definitions or accept that they will always be incomplete.

So I am thinking that the best route is either to give jsdoc a try, and see if that works well enough, or publish to DefinitelyTyped.