Add TypeScript definitions

[karol-majewski]

Solves #99.

• Used module class template from TypeScript documentation
• Included @types/webpack so the library consumers won't have to install them manually as a peer dependency (as recommended here)
• I took the liberty of using the comments from README.md – I hope that's okay?

[mrsteele]

@karol-majewski you rock! I have been waiting for someone brave enough to take on this as I am not the least-bit talented enough to do the typescript side of this.

I'm going to have to do a bit a research to make sure this is good to use and once I am educated enough I will be happy and excited to merge this in!

In the meantime have this:🏅(you deserve it!)

[DanielRosenwasser]

I generally believe that as a library author, you shouldn't accept declaration files into your repo unless you feel entirely confident using TypeScript, maintaining them, and publishing patches whenever the file changes. It is definitely a burden if you're not familiar with the toolset.

DefinitelyTyped has better infrastructure for testing against changes (both on the package itself, as well as downstream changes on depending @types packages), for publishing, and has dramatically improved the process for reviewing (which you could help out on if you're up for it!).

So that's my 2 cents. I've worked with our community for a few years now and the last thing I want is the maintainer of a library to be unhappy over something that was done in good faith for the TypeScript community. It's unfair to all parties involved.

[karol-majewski]

@DanielRosenwasser Thank you for your advice. I'm very happy to contribute to DefinitelyTyped, if @mrsteele also finds it the best way to go in this situation.

As to the research, @mrsteele — you can start with typings for webpack-dotenv-plugin. It exposes a very similar API.

[mrsteele]

@DanielRosenwasser I noticed that the definitions @karol-majewski wrote here normally exist exclusively in DefinitelyTyped and not in the webpack-dotenv-plugin. Are you suggesting that we do a PR over there with these definitions so that our repo can remain agnostic to the dev env (typed vs not)?

If you are, I actually would prefer that if you guys think that would be better. I don't use typescript personally but I recognize it as a growing community and would love for them to benefit.

[DanielRosenwasser]

I was asked about this topic recently over Twitter as well. To reiterate, I think the benefits are marginal to host .d.ts files in your package (especially considering the maintenance issues) rather than on DefinitelyTyped. If you'd like to help out, you can offer to be consulted on PRs to the TypeScript declarations on DefinitelyTyped, which I think would be totally awesome.

[karol-majewski]

Done — a pull request to DefinitelyTyped has been opened.

@DanielRosenwasser What do you think about sharing your recommendation in DefinitelyTyped README? Currently it says:

If you are the library author, or can make a pull request to the library, bundle types instead of publishing to DefinitelyTyped.

Also, the PULL_REQUEST_TEMPLATE.md seems to support this approach by making sure the pull request is opened after the contributor made sure the definitions couldn't be bundled.

• The package does not provide its own types, and you can not add them.

[mrsteele]

@karol-majewski Thats an interesting quote from the README. The fact that they would state that explicitly begs the question of why we wouldn't just put it in this repo...

[DanielRosenwasser]

Because back then the community didn't realize it was opening a can of worms by doing that. 😅