Type signature for JSON.stringify does not include undefined in the return type

Although calling JSON.stringify may return undefined (as documented here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description), it is not included in the type signature provided with TypeScript.

This is also true for Edge:

Values that do not have JSON representations, such as undefined, will not be converted.

https://docs.microsoft.com/en-us/scripting/javascript/reference/json-stringify-function-javascript

So we need a new overload for stringify(value: undefined, .....): undefined; ?

Thanks for the quick response!

That could work, please note that JSON.stringify(function() {}) also results in undefined.
Perhaps I should explain why this was a problem for me: I wrote an error handling function that would display JSON data

function showError(value: any): string {
    const json = JSON.stringify(value);
    // ...
    // Later in the code, a string function was used
    const lines = json.split('/n');
    // This is where I got the runtime exception
}

Would the overload catch this possible runtime error?

Something that would definitly work for me is a union return type that includes undefined, like so

stringify(value: any /* space, replacer, ... */): string | undefined

But of course I don't know conventions or guidelines for the type annotations very well, so this might be too broad.

PRs welcomed. You can find more information about contributing lib.d.ts fixes at https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md#contributing-libdts-fixes.

👍 Will do

lib.d.ts: Include undefined in return type of JSON.stringify()

Jonas Schürmann (@MazeChaZer)

I just discovered a production bug that this would have caught. Any updates on it Jonas Schürmann (@MazeChaZer)?

Mohamed Hegazy (@mhegazy)

Mohamed Hegazy (@mhegazy) I suggest having both return value string|undefined and additional overload for undefined|Function|symbol to catch issues at compile time.

Fix JSON.stringify return type (microsoft#18879), reduce usage of any…

Any progress on this one? (I got my fingers burned with this today)

Ryan Cavanaugh (@RyanCavanaugh)

Ryan Cavanaugh (@RyanCavanaugh) Can we triage this? There's no movement on the critical issue for 5 years.

Here's a PR for this issue: #51897
This is my first attempt at contributing to the TS repo, advice and/or corrections would, of course, be welcome

Here's a PR for this issue: #51897 This is my first attempt at contributing to the TS repo, advice and/or corrections would, of course, be welcome

Ready for review

Martin Johns (@MartinJohns)

Any updates?
Martin Johns (@MartinJohns) Is there anything I should be doing to advance this?

Nathan Shively-Sanders (@sandersn)

Nathan Shively-Sanders (@sandersn) can you reopen this bug since the PR got reverted ?

Having tried this and looked into it more, I don't think we're going to try this again. People can add this line to their project to opt into this behavior if they want it:

interface JSON { stringify(s: any): string | undefined; }

but if we add this today, there is no real way to opt back in to today's behavior.

However, if at some point we make a "stricter" version of the core lib, this would definitely be a change to consider in that feature

if at some point we make a "stricter" version of the core lib,

is there an open issue for this?

This is resolved in ts-reset here: Add strong types for JSON.stringify mattpocock/ts-reset#21

@sandersn can you reopen this bug since the PR got reverted ?

I agree, this should be reopened. Just because it "breaks code" is not a reason to not fix it.

https://github.com/Microsoft/TypeScript/wiki/FAQ#this-is-closed-but-should-be-open-or-vice-versa

Navigation Menu

Repository navigation

Type signature for JSON.stringify does not include undefined in the return type #18879

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Type signature for JSON.stringify does not include undefined in the return type #18879

Description

Activity

MazeChaZer commented on Oct 2, 2017

mhegazy commented on Oct 3, 2017

MazeChaZer commented on Oct 4, 2017

mhegazy commented on Oct 4, 2017

MazeChaZer commented on Oct 4, 2017

bradleyayers commented on Feb 6, 2018

NN--- commented on Apr 4, 2018

greyblake commented on Nov 22, 2022

reverofevil commented on Nov 26, 2022

ronyhe commented on Dec 14, 2022

ronyhe commented on Dec 19, 2022

ronyhe commented on Dec 21, 2022

ecyrbe commented on Jan 21, 2023

RyanCavanaugh commented on Jan 23, 2023

DetachHead commented on Mar 22, 2023

KotlinIsland commented on Mar 22, 2023

silverwind commented on Jul 31, 2025

RyanCavanaugh commented on Jul 31, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions