Make API Typescript friendly

[riverrun-git]

It would not take much to make the API Typescript friendly.

The steps would be:

• Add typescript as a dev dependency
• Run the typescript compiler on the Javascript code.
• Optionally add JSDoc comments to the Javascript code to improve the type definitions generated
• (Possible, but not required: convert the Javascript code to Typescript)

Running the typescript compiler would generate files with typed function signatures for each Javascript file.
These signatures help modern code editors (e.g. vscode) with code completion even when using Javascript, not Typescript.
The Typescript compiler will also generate a copy of the Javascript files with some added code to make the library usable with both old-style 'require' and modern 'import' statements. This is a big advantage in my opinion.
The signature files and slightly changed Javascript files would be generated in a separate directory (e.g. 'dist').
The deployment of the library as an npm would change slightly (generated from 'dist/src' folder, not 'src' folder).
This approach would need no changes to the codebase (except, optionally, addition of some comments).
The generated files (apart from the type definitions) would still be (almost unchanged) Javascript.

I have implemented this approach in a fork and could supply a pull request.
I'd prefer this to be a part of this repository rather than having to maintain a separate one (and keep it up-to-date).
Is this desired? Should we discuss?

[spdermn02]

i'm all for community contribution! so sure throw out a pull request, that would be fantastic.

[riverrun-git]

Pull request submitted.
Any comments or questions - let me know.
With this pull request, the API would be usable from Typescript, but the type definitions are not as good as they should be.
A further step of adding type annotation comments to the Javascript code would be required.
You will be able to claim Typescript support though. 😃

[spdermn02]

Thanks, changes look good - I'll see about running some tests with this as well. Appreciate the Contribution!

[riverrun-git]

More to come 😃

[spdermn02]

I merged your latest typescript changes into master testing seems good

[riverrun-git]

Excellent.

That leaves adding better type declarations (right now everything is 'any')
There are two ways of doing this:

1. Add JSDoc comments with type annotations
   Pro: Leaves the source code unchanged (apart from the comments). Can be done in easy stages.
   Con: Not the prettiest way to add types. Quite bloated.

2. Convert Javascript to Typescript
   Pro: Typescript all the way (generated files are still Javascript)
   Con: Slightly more involved, though modern tools (migrate-ts) help a lot. The original code is no longer Javascript (some would say that's a plus)

Any preference? I can do either, but am more familiar with 2)

[spdermn02]

i'm cool with 2 - i'm comfortable enough with Typescript to just have it converted completely

[riverrun-git]

Done 2) and submitted a pull request.
Mostly untested, but still works with import and require I believe.

Making it work with both is a right pain though and very fragile.
import has been Javascript standard since 2015. Just saying.