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

[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]

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'.

[msftclas]

All CLA requirements met.

[RyanCavanaugh]

@typescript-bot test this
@typescript-bot user test this

[typescript-bot]

Heya @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]

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

[typescript-bot]

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

[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.

[jupiter]

@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.

[wongjiahau]

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

[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.

[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]

@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

[mtsoltan]

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

[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.