Got: Add TypeScript and Flow type definitions

[gajus]

Having Flowtype static typings would help to catch configuration errors.

Happy to contribute the typings.

Of note, I would recommend using Flowtype to validate the project itself. It would add an extra layer of bug-proofness at a cost of additional build step.

If you need an example of how integration would look, my GitHub profile includes a number of projects using Flowtype, e.g. https://github.com/gajus/roarr.

[szmarczak]

Having Flowtype static typings would help to catch configuration errors.

Can you elaborate on the configuration errors? I don't know what these mean, but I'm happy to know :)

It would add an extra layer of bug-proofness at a cost of additional build step.

Is it really necessary? As for now, got works very well with no bugs (excluding upstream).

[gajus]

Can you elaborate on the configuration errors? I don't know what these mean, but I'm happy to know :)

Referring to API contract validation, e.g.

got('http://gajus.com/', {
  followRedirects: true,
  payload: Buffer.from('test')
});

The above contains two errors that are hard to notice for a user and will not be caught by the program until runtime validation.

If there were static typings, e.g.

type HttpClientConfiguration = {|
  +body?: string,
  +followRedirect?: boolean
|};

type HttpClient = (url: string, configuration: HttpClientConfiguration) => Promise<any>;

const got: HttpClient = async (url, configuration) => {}

Then the above code example would throw the following errors at a compilation step:

10: got('http://gajus.com/', {                             ^ Cannot call `got` with object literal bound to `configuration` because property `followRedirects` is missing in `HttpClientConfiguration` [1] but exists in object literal [2].
References:
6: type HttpClient = (url: string, configuration: HttpClientConfiguration) => Promise<any>;
                                                  ^ [1]
10: got('http://gajus.com/', {                             ^ [2]
10: got('http://gajus.com/', {                             ^ Cannot call `got` with object literal bound to `configuration` because property `payload` is missing in `HttpClientConfiguration` [1] but exists in object literal [2].
References:
6: type HttpClient = (url: string, configuration: HttpClientConfiguration) => Promise<any>;
                                                  ^ [1]
10: got('http://gajus.com/', {                             ^ [2]

https://flow.org/try/#0C4TwDgpgBAEsxgMIBsCWEB2xEHsMDNUBzAVwCcBDYVPKAXigG8AfAKCigGoAjHAExAB+AFxQAzsDKoMRADTsu+HMmQ4A7gCUIfVGQgBjYCKi9lEChlbMAvgG5WrUJFjwkaTMHpQAFOWSiJKRlZKH08QlJKajxROAQUdCxcAmJyKhoMAEp6AD4oAAUyHABbVDEIAB4LEBz7VjCMCSgiHGBY1wSPLwoxEAx9Hz8Qhoi06KzcpmsHFuBvAHIAC1dhAHpVogoAKxIxADow4tX5kMYFJRV1LR09QzFRSRIIeQ4wChBVCj5ReeAICXmrGsmVsQA

I am maintaining projects with dozens of freelancers working and literally thousands of individual scripts. It would be near impossible to code at this scale without static type checking. We can definitely wrap got internally with our own types (we are going to do that anyway to restrict some features), but a type-safe project would definitely be a huge incentive for me to choose got over the other available alternatives.

[sindresorhus]

Yeah, happy to have support for Flow if you're willing to do the work to add it.

[szmarczak]

It would be near impossible to code at this scale without static type checking.

There are many projects that don't use flow. But yeah, strict typing would be nice. :+1:

[sindresorhus]

I have a style guide for TypeScript now, which should also mostly apply to Flow: https://github.com/sindresorhus/typescript-definition-style-guide

[sindresorhus]

Just to clarify, by "have support for Flow", I mean adding a Flow definition file, not to rewrite Got in Flow.

[gajus]

Just to clarify, by "have support for Flow", I mean adding a Flow definition file, not to rewrite Got in Flow.

Yeah, I realised that. Thats why I quietly backed away.

I personally think that this is a fragile approach: you end up replicating changes in 2 different places (with TS support: 3 different places). However, thats better than nothing from the consumer's perspective.

[sindresorhus]

Yes, but if I were to rewrite Got, I would do it in TypeScript, not Flow, as that's what I'm familiar with and prefer.

[sindresorhus]

Closing in favor of #700.