Add options to customize parsing/stringifying JSON

[Giotino]

Custom function to parse JSON responses.

Checklist

• I have read the documentation.
• I have included a pull request description of my changes.
• I have included some tests.
• If it's a new feature, I have included documentation updates.

Fixes #1274

[szmarczak]

@Giotino Can you also do stringifyJson? Actually that's not needed as people can pass JSON.stringify(object, stringifier) as a body option. We should keep the complexity minimum.

[szmarczak]

IMO this is good to merge.

[szmarczak]

Actually I'm having second thoughts. This also adds more complexity. What's against having

const {body} = await got(...);
const parsed = JSON.parse(body, parser);

---

I don't think like this change is really necessary.

[Giotino]

I thought so, but with parseJson you can have an extended got that always behave the same without having to explicitly use your parser every time.

It's not a "must have" feature, but since someone showed interest in that it means that it might be nice to have. Also I don't think it adds that much complexity.

[Giotino]

Maybe we should ear more opinions before proceeding.

[kirillgroshkov]

Actually I'm having second thoughts. This also adds more complexity. What's against having

const {body} = await got(...);
const parsed = JSON.parse(body, parser);

In our case we have ~50 methods that call API via got(...).json(). To add a reviver to them right now means adding it to 50 places and risking that we forget to add it to newly added methods. Having it built in the extended got means the change in only 1 place and safety to add more methods.

Same thinking as why got.extend function and hooks exist in the first place. Without it - it'll need copy/pasting the hooks to every usage.

[szmarczak]

Hmm... @kirillgroshkov is right. So stringifyJson is also welcome, but unnecessary. It's up to you :)

[Giotino]

Examples needs to be fixed/improved.

@sindresorhus @szmarczak
While working on the documentation I noted that the examples are incosistent.
Examples of examples :)

const got = require('got');

await got();

const got = require('got');

(async () => {
  await got();
})();

await got();

I think that const got = require('got'); and the async wrapper are not needed, I can work on a PR normalizing all the examples.

[szmarczak]

I think that const got = require('got'); and the async wrapper are not needed

@sindresorhus has said a while ago that these examples should be 100% functional. Copy-paste and it should work.

[sindresorhus]

https://github.com/sindresorhus/got/pull/1298/files#r433074774 still needs to be resolved.

[sindresorhus]

I think that const got = require('got'); and the async wrapper are not needed, I can work on a PR normalizing all the examples.

That would be great as a separate PR. We should normalize to always require Got and always use the async IIFE.

[Giotino]

https://github.com/sindresorhus/got/pull/1298/files#r433074774 still needs to be resolved.

Yeah, I'm aware of it, I was kinda busy so I delayed it a bit.

[sindresorhus]

Excellent 👌