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

JSON.stringify() may return undefined if the given input value is undefined or if the input value is not serializable (like `function(){}`).
See microsoft#18879

Author: Jonas Schürmann

src/lib/es5.d.ts

@@ -943,14 +943,14 @@ interface JSON {
       * @param replacer A function that transforms the results.
       * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
       */
-    stringify(value: any, replacer?: (key: string, value: any) => any, space?: string | number): string;
+    stringify(value: any, replacer?: (key: string, value: any) => any, space?: string | number): string | undefined;
     /**
       * Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
       * @param value A JavaScript value, usually an object or array, to be converted.
       * @param replacer An array of strings and numbers that acts as a approved list for selecting the object properties that will be stringified.
       * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
       */
-    stringify(value: any, replacer?: (number | string)[] | null, space?: string | number): string;
+    stringify(value: any, replacer?: (number | string)[] | null, space?: string | number): string | undefined;
 }
 
 /**

tests/baselines/reference/json.stringify.types

@@ -4,50 +4,50 @@ var value = null;
 >null : null
 
 JSON.stringify(value, undefined, 2);
->JSON.stringify(value, undefined, 2) : string
->JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>JSON.stringify(value, undefined, 2) : string | undefined
+>JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >JSON : JSON
->stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >value : null
 >undefined : undefined
 >2 : 2
 
 JSON.stringify(value, null, 2);
->JSON.stringify(value, null, 2) : string
->JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>JSON.stringify(value, null, 2) : string | undefined
+>JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >JSON : JSON
->stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >value : null
 >null : null
 >2 : 2
 
 JSON.stringify(value, ["a", 1], 2);
->JSON.stringify(value, ["a", 1], 2) : string
->JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>JSON.stringify(value, ["a", 1], 2) : string | undefined
+>JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >JSON : JSON
->stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >value : null
 >["a", 1] : (string | number)[]
 >"a" : "a"
 >1 : 1
 >2 : 2
 
 JSON.stringify(value, (k) => undefined, 2);
->JSON.stringify(value, (k) => undefined, 2) : string
->JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>JSON.stringify(value, (k) => undefined, 2) : string | undefined
+>JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >JSON : JSON
->stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >value : null
 >(k) => undefined : (k: string) => undefined
 >k : string
 >undefined : undefined
 >2 : 2
 
 JSON.stringify(value, undefined, 2);
->JSON.stringify(value, undefined, 2) : string
->JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>JSON.stringify(value, undefined, 2) : string | undefined
+>JSON.stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >JSON : JSON
->stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string; }
+>stringify : { (value: any, replacer?: ((key: string, value: any) => any) | undefined, space?: string | number | undefined): string | undefined; (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string | undefined; }
 >value : null
 >undefined : undefined
 >2 : 2