Correct types for JSON.stringify

package.json

@@ -44,6 +44,11 @@
       "import": "./dist/json-parse.mjs",
       "default": "./dist/json-parse.js"
     },
+    "./json-stringify": {
+      "types": "./dist/json-stringify.d.ts",
+      "import": "./dist/json-stringify.mjs",
+      "default": "./dist/json-stringify.js"
+    },
     "./fetch": {
       "types": "./dist/fetch.d.ts",
       "import": "./dist/fetch.mjs",

src/entrypoints/json-stringify.d.ts

@@ -0,0 +1,36 @@
+interface JSON {
+  /**
+   * Converts a JavaScript value to a JavaScript Object Notation (JSON) string or undefined.
+   * @param value A JavaScript value, usually an object or array, to be converted.
+   * @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<T>(
+    value: T,
+    replacer?: (this: any, key: string, value: any) => any,
+    space?: string | number,
+  ): T extends {} | null
+    ? T extends (..._: any) => void
+      ? undefined
+      : string
+    : T extends undefined
+    ? undefined
+    : string | undefined;
+  /**
+   * Converts a JavaScript value to a JavaScript Object Notation (JSON) string or undefined.
+   * @param value A JavaScript value, usually an object or array, to be converted.
+   * @param replacer An array of strings and numbers that acts as an 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<T>(
+    value: T,
+    replacer?: (number | string)[] | null,
+    space?: string | number,
+  ): T extends {} | null
+    ? T extends (..._: any) => void
+      ? undefined
+      : string
+    : T extends undefined
+    ? undefined
+    : string | undefined;
+}

src/entrypoints/recommended.d.ts

@@ -2,6 +2,7 @@
 /// <reference path="filter-boolean.d.ts" />
 /// <reference path="is-array.d.ts" />
 /// <reference path="json-parse.d.ts" />
+/// <reference path="json-stringify.d.ts" />
 /// <reference path="array-includes.d.ts" />
 /// <reference path="set-has.d.ts" />
 /// <reference path="map-has.d.ts" />

src/tests/json-stringify.ts

@@ -0,0 +1,63 @@
+import { doNotExecute, Equal, Expect } from "./utils";
+
+doNotExecute(() => {
+  const result = JSON.stringify({});
+
+  type tests = [Expect<Equal<typeof result, string>>];
+});
+
+doNotExecute(() => {
+  const result = JSON.stringify(null);
+
+  type tests = [Expect<Equal<typeof result, string>>];
+});
+
+doNotExecute(() => {
+  const result = JSON.stringify(undefined);
+
+  type tests = [Expect<Equal<typeof result, undefined>>];
+});
+
+doNotExecute(() => {
+  // create a something that is either an object or null
+  let toBeStringified: {} | null = Math.random() > 0.5 ? {} : null;
+  const result = JSON.stringify(toBeStringified);
+
+  type tests = [Expect<Equal<typeof result, string>>];
+});
+
+doNotExecute(() => {
+  // create a something that is either an object or undefined
+  let toBeStringified: {} | undefined = Math.random() > 0.5 ? {} : undefined;
+  const result = JSON.stringify(toBeStringified);
+
+  type tests = [Expect<Equal<typeof result, string | undefined>>];
+});
+
+doNotExecute(() => {
+  // create a something that is a function
+  const result = JSON.stringify(function () {});
+
+  type tests = [Expect<Equal<typeof result, undefined>>];
+});
+
+doNotExecute(() => {
+  // create a something that is a function
+  const result = JSON.stringify(function (hello: any, world: any) {});
+
+  type tests = [Expect<Equal<typeof result, undefined>>];
+});
+
+doNotExecute(() => {
+  // create a something that is of type any
+  let toBeStringified: any;
+  const result = JSON.stringify(toBeStringified);
+
+  type tests = [Expect<Equal<typeof result, string | undefined>>];
+});
+
+doNotExecute(() => {
+  const result = JSON.stringify("undefined");
+
+  type tests = [Expect<Equal<typeof result, string>>];
+});