Merge pull request #2696 from dmichon-msft/json-file-undefined

[node-core-library] Add `ignoreUndefinedValues` option to JsonFile serialization APIs

Author: iclanton

common/changes/@rushstack/node-core-library/json-file-undefined_2021-05-13-21-25.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/node-core-library",
+      "comment": "Add `ignoreUndefinedValues` option to JsonFile to discard keys with undefined values during serialization; this is the standard behavior of `JSON.stringify()` and other JSON serializers.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/node-core-library",
+  "email": "[email protected]"
+}

common/reviews/api/node-core-library.api.md

@@ -425,6 +425,7 @@ export interface IJsonFileSaveOptions extends IJsonFileStringifyOptions {
 // @public
 export interface IJsonFileStringifyOptions {
     headerComment?: string;
+    ignoreUndefinedValues?: boolean;
     newlineConversion?: NewlineKind;
     prettyFormatting?: boolean;
 }

libraries/node-core-library/src/JsonFile.ts

@@ -49,6 +49,12 @@ export interface IJsonFileStringifyOptions {
    */
   newlineConversion?: NewlineKind;
 
+  /**
+   * If true, conforms to the standard behavior of JSON.stringify() when a property has the value `undefined`.
+   * Specifically, the key will be dropped from the emitted object.
+   */
+  ignoreUndefinedValues?: boolean;
+
   /**
    * If true, then the "jju" library will be used to improve the text formatting.
    * Note that this is slightly slower than the native JSON.stringify() implementation.
@@ -230,7 +236,10 @@ export class JsonFile {
       options = {};
     }
 
-    JsonFile.validateNoUndefinedMembers(newJsonObject);
+    if (!options.ignoreUndefinedValues) {
+      // Standard handling of `undefined` in JSON stringification is to discard the key.
+      JsonFile.validateNoUndefinedMembers(newJsonObject);
+    }
 
     let stringified: string;
 

libraries/node-core-library/src/test/JsonFile.test.ts

@@ -27,4 +27,24 @@ describe('JsonFile tests', () => {
       )
     ).toMatchSnapshot();
   });
+  it('allows undefined values when asked', () => {
+    expect(
+      JsonFile.stringify(
+        { abc: undefined },
+        {
+          ignoreUndefinedValues: true
+        }
+      )
+    ).toMatchSnapshot();
+
+    expect(
+      JsonFile.stringify(
+        { abc: undefined },
+        {
+          ignoreUndefinedValues: true,
+          prettyFormatting: true
+        }
+      )
+    ).toMatchSnapshot();
+  });
 });

libraries/node-core-library/src/test/__snapshots__/JsonFile.test.ts.snap

@@ -15,3 +15,13 @@ exports[`JsonFile tests adds an empty header comment 1`] = `
 }
 "
 `;
+
+exports[`JsonFile tests allows undefined values when asked 1`] = `
+"{}
+"
+`;
+
+exports[`JsonFile tests allows undefined values when asked 2`] = `
+"{}
+"
+`;