Fix return type for JSON.stringify(any) -> string

[Pieter Raubenheimer (jupiter)]

Fixes#18879

Problem
Current type definitions falsely assert that JSON.stringify(...) always returns a string. JSON.stringify(...) actually returns undefined whenever the input value is undefined, a Function, or a Symbol (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). It also returns undefined when a provided replacer function returns any of these types for the root value.

The fix
We provide overloads to ensure that when valid JSON values are provided, the return type is string. When an invalid value is provided, the return type is undefined as per runtime behaviour. When the input value type is any or when a replacer function is passed the return type is string | undefined.

[TypeScript Bot (typescript-bot)]

It looks like you've sent a pull request to update our 'lib' files. These files aren't meant to be edited by hand, as they consist of last-known good states of the compiler and are generated from 'src'. Unless this is necessary, consider closing the pull request and sending a separate PR to update 'src'.

[Microsoft Contribution License Agreements (msftclas)]

All CLA requirements met.

[Ryan Cavanaugh (RyanCavanaugh)]

TypeScript Bot (@typescript-bot) test this
TypeScript Bot (@typescript-bot) user test this

[TypeScript Bot (typescript-bot)]

Heya Ryan Cavanaugh (@RyanCavanaugh), I've started to run the parallelized community code test suite on this PR at f26c011. You can monitor the build here.

[TypeScript Bot (typescript-bot)]

Heya Ryan Cavanaugh (@RyanCavanaugh), I've started to run the extended test suite on this PR at f26c011. You can monitor the build here.

[TypeScript Bot (typescript-bot)]

The user suite test run you requested has finished and failed. I've opened a PR with the baseline diff from master.

[Pieter Raubenheimer (jupiter)]

True, perhaps there’s a compromise to be made. I’ll have a go at removing the `any` input overload, or at least make that also return `any`, so that it is at least not a falsehood.

[Pieter Raubenheimer (jupiter)]

Ryan Cavanaugh (@RyanCavanaugh) Can we see how the update does with user tests? I'm thinking that JSON.stringify(any) -> any will do much better. I'm thinking that JSON.stringify(any) -> string was probably a mistake originally due to the function name leading the type. A false type is worse than any.

[WJH (wongjiahau)]

Hopefully this can be merged soon, because this issue is bugging me a lot.

[Igor Adamenko (igoradamenko)]

Same here.

I've shot myself in the foot because of JSON.parse(JSON.stringify(variable)), where variable suddenly became undefined and the whole expression has thrown an error.

[Nate Higgins (nathggns)]

Is this not progressing due to conflicts/an issue with the fix, or has there just not been time to merge it yet? I.e, is the blocker with the author or with maintainers? Trying to evaluate whether to submit a PR myself or not as was just bitten by this bug. (Not trying to spam here – just wondering if I can assist)

[reverofevil]

Pieter Raubenheimer (@jupiter) Are you sure these types are correct?

I think it doesn't handle at least

JSON.stringify(() => {})
JSON.stringify({toJSON: () => {}})

Update. Found that rbuckton was first to point on this in comments, and why Function overload disappeared.

[reverofevil]

JSON.stringify({}, () => () => {})

uses this overload and returns string instead of undefined.

[reverofevil]

I think replacer shouldn't be optional here.

[reverofevil]

Why space is any here?

[reverofevil]

Funny enough, even the best types I could imagine are not enough. Due to some bugfeature in handling of overloaded functions, union of undefined-returning and string-returning argument types is typed incorrectly.

interface Json {
// two cases cover all types of values available in EcmaScript, except for bigint (intentionally omitted)
stringify(value: {toJSON: () => undefined | Symbol | Function}, replacer?: (number | string)[] | null, space?: string | number): undefined;
stringify(value: {toJSON: () => number | string | boolean | null | object}, replacer?: (number | string)[] | null, space?: string | number): string;
stringify(value: undefined | Symbol | Function, replacer?: (number | string)[] | null, space?: string | number): undefined;
stringify(value: number | string | boolean | null | object, replacer?: (number | string)[] | null, space?: string | number): string;
stringify(value: any, replacer: (this: any, key: string, value: any) => number | string | boolean | null | any[] | Record<string, any>, space?: string | number): string;
stringify(value: any, replacer: (this: any, key: string, value: any) => any, space?: string | number): string | undefined;
}
declare const Json: Json;
declare const x: (() => void) | 1;
const t4 = Json.stringify(x); // string

[Mahmoud Soltan (mtsoltan)]

Can this, or some other PR that fixes #18879 , get looked at again?

[Nathan Shively-Sanders (sandersn)]

Unfortunately, we never finished reviewing this PR. It is pretty old now, so I'm going to close it to reduce the number of open PRs.