Generate typescript definitions from JSDoc

[dchiquito]

It would be nice if cabal-core exposed some Typescript definition files (*.d.ts) that define the shape of the API. These types make cabal-core usable in other Typescript projects, and provide useful autocomplete information for IDEs like VSCode.

Typescript can generate these files automatically using a combination of type inference and JSDoc. I have a branch that fixes most of the typing errors and includes some some .d.ts files generated by running tsc. Ideally, we would have a simple script npm run generate-types or something that would regenerate the definition files ( inform the user of any type errors, another bonus!) and we would just run that script before releasing to keep the types up to date.

Sadly, the Cabal class is defined as a function which recognizes when it is being called as a function instead of a constructor and corrects that. However, this is too clever for Typescript to automatically recognize while also recognizing that Cabal extends EventEmitter.

One solution is to declare Cabal as a normal ES6 class instead of a constructor: class Cabal extends EventEmitter {...}. However, since the canonical way to instantiate a new Cabal is therefore Cabal(...) instead of new Cabal(...), this would be a breaking API change, which is a lot to ask just to add some typing support.