[heft-config-file] Let null reset properties

Author: dmichon-msft

common/changes/@rushstack/heft-config-file/config-file-null_2025-04-16-00-37.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-config-file",
+      "comment": "Allow use of the value `null` to discard any value set for the property from a parent config file..",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-config-file"
+}

libraries/heft-config-file/src/ConfigurationFileBase.ts

@@ -16,6 +16,8 @@ interface IConfigurationJson {
  * @beta
  *
  * The set of possible mechanisms for merging properties from parent configuration files.
+ * If a child configuration file sets a property value to `null`, that will always delete the value
+ * specified in the parent configuration file, regardless of the inheritance type.
  */
 const InheritanceType = {
   /**
@@ -251,6 +253,7 @@ export interface ICustomPropertyInheritance<TObject> extends IPropertyInheritanc
    * Provides a custom inheritance function. This function takes two arguments: the first is the
    * child file's object, and the second is the parent file's object. The function should return
    * the resulting combined object.
+   * This function will not be invoked if the current value is `null`, the property will simply be deleted.
    */
   inheritanceFunction: PropertyInheritanceCustomFunction<TObject>;
 }
@@ -1085,7 +1088,15 @@ export abstract class ConfigurationFileBase<TConfigurationFile, TExtraOptions ex
         newValue = parentPropertyValue;
       };
 
-      if (propertyValue !== undefined && parentPropertyValue === undefined) {
+      if (propertyValue === null) {
+        if (parentPropertyValue !== undefined) {
+          resultAnnotation.originalValues[propertyName] = this.getPropertyOriginalValue({
+            parentObject: parentObject,
+            propertyName: propertyName
+          });
+        }
+        newValue = undefined;
+      } else if (propertyValue !== undefined && parentPropertyValue === undefined) {
         usePropertyValue();
       } else if (parentPropertyValue !== undefined && propertyValue === undefined) {
         useParentPropertyValue();
@@ -1207,7 +1218,10 @@ export abstract class ConfigurationFileBase<TConfigurationFile, TExtraOptions ex
         }
       }
 
-      result[propertyName] = newValue;
+      if (newValue !== undefined) {
+        // Don't attach the key for undefined values so that they don't enumerate.
+        result[propertyName] = newValue;
+      }
     }
 
     return result;

libraries/heft-config-file/src/test/ConfigurationFile.test.ts

@@ -251,6 +251,7 @@ describe('ConfigurationFile', () => {
       things: string[];
       thingsObj: { A: { B: string }; D: { E: string } };
       booleanProp: boolean;
+      stringProp?: string;
     }
 
     it('Correctly loads the config file', () => {
@@ -266,7 +267,8 @@ describe('ConfigurationFile', () => {
       const expectedConfigFile: ISimpleConfigFile = {
         things: ['A', 'B', 'C'],
         thingsObj: { A: { B: 'C' }, D: { E: 'F' } },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -284,7 +286,8 @@ describe('ConfigurationFile', () => {
       const expectedConfigFile: ISimpleConfigFile = {
         things: ['A', 'B', 'C'],
         thingsObj: { A: { B: 'C' }, D: { E: 'F' } },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -317,7 +320,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(__dirname, configFileFolderName, 'C') },
           D: { E: nodeJsPath.resolve(__dirname, configFileFolderName, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -350,7 +354,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(__dirname, configFileFolderName, 'C') },
           D: { E: nodeJsPath.resolve(__dirname, configFileFolderName, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -383,7 +388,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(projectRoot, 'C') },
           D: { E: nodeJsPath.resolve(projectRoot, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -416,7 +422,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(projectRoot, 'C') },
           D: { E: nodeJsPath.resolve(projectRoot, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -435,6 +442,7 @@ describe('ConfigurationFile', () => {
       things: string[];
       thingsObj: { A: { B?: string; D?: string }; D?: { E: string }; F?: { G: string } };
       booleanProp: boolean;
+      stringProp?: string;
     }
 
     it('Correctly loads the config file with default config meta', () => {

libraries/heft-config-file/src/test/simpleConfigFile/simpleConfigFile.json

@@ -9,5 +9,7 @@
       "E": "F"
     }
   },
-  "booleanProp": true
+  "booleanProp": true,
+
+  "stringProp": "someValue"
 }

libraries/heft-config-file/src/test/simpleConfigFile/simpleConfigFile.schema.json

@@ -24,6 +24,10 @@
 
     "booleanProp": {
       "type": "boolean"
+    },
+
+    "stringProp": {
+      "type": "string"
     }
   }
 }

libraries/heft-config-file/src/test/simpleConfigFileWithExtends/simpleConfigFileWithExtends.json

@@ -13,5 +13,7 @@
     }
   },
 
-  "booleanProp": false
+  "booleanProp": false,
+
+  "stringProp": null
 }