chore: add TypeScript definition file for most API

[eventualbuddha]

No description provided.

[alangpierce]

This all looks good to me. Did you end up basically reading through all the code and translating it to type definitions, or was there a way or automating it? (Or did you find these definitions somewhere?)

Also, as I understand it, a mistake here could potentially cause runtime errors, but then we can just go and fix the type declarations, so it's not such a huge deal if this isn't 100% correct. Is that how you're thinking about it as well? It would require an npm publish and version bump on every change, right? My original vision for this fork was for it to be a small set of patches that are easy to read and understand, although I also don't feel too strongly about that, and this types stuff is pretty isolated from the actual CoffeeScript code anyway.

Also, did you consider making these type definitions external rather than in this repo? That's what we'd need to do for libraries we don't have control over, right? I guess one advantage of keeping type definitions with the source code is that it makes versioning easier?

Also, TypeScript has a way of importing a library where everything is the any type so you don't have to bother with type definitions, right? (Like flow does by default.) TBH this commit seems like a lot of up-front work to use an external library. But I guess it especially makes sense for things like AST traversals that it's nice to have real types.

[eventualbuddha]

Did you end up basically reading through all the code and translating it to type definitions?

Yeah, basically by hand.

…a mistake here could potentially cause runtime errors…

Nothing in the type declaration file itself is part of the runtime, but if the type declaration doesn't match reality and someone codes against it then yes, it could cause errors.

Also, did you consider making these type definitions external rather than in this repo?

Yeah. I don't have a strong opinion about that. Could put it into the DefinitelyTyped repo for decaffeinate-coffeescript.

But I guess it especially makes sense for things like AST traversals that it's nice to have real types.

Yeah, that's what I'm aiming for. We'll see if it's actually worth it.

[eventualbuddha]

I'll wait to merge this until you state your preferences on external vs. embedded types, @alangpierce.

[alangpierce]

No strong opinion from me either, this seems fine, so feel free to merge. Thanks!

[eventualbuddha]

Still need to figure out importing non-main files for e.g. nodes.