feat: adds $allowNull option for $substitute

Author: joelgallant

app-config-extensions/src/index.test.ts

@@ -723,6 +723,24 @@ describe('$substitute directive', () => {
     expect(parsed.toJSON()).toEqual({ foo: 'bar' });
   });
 
+  it('allows null value when $allowNull', async () => {
+    const source = new LiteralSource({
+      foo: { $substitute: { $name: 'FOO', $fallback: null, $allowNull: true } },
+    });
+
+    const parsed = await source.read([environmentVariableSubstitution()]);
+
+    expect(parsed.toJSON()).toEqual({ foo: null });
+  });
+
+  it('does not allow number even when $allowNull', async () => {
+    const source = new LiteralSource({
+      foo: { $substitute: { $name: 'FOO', $fallback: 42, $allowNull: true } },
+    });
+
+    await expect(source.read([environmentVariableSubstitution()])).rejects.toThrow();
+  });
+
   it('doesnt visit fallback if name is defined', async () => {
     const failDirective = forKey('$fail', () => () => {
       throw new Error();

app-config-extensions/src/index.ts

@@ -174,6 +174,10 @@ export function environmentVariableSubstitution(
     stringSchema(),
   );
 
+  const validateStringOrNull: ValidationFunction<string> = validationFunction(
+    ({ fromJsonSchema }) => fromJsonSchema({ type: ['null', 'string'] } as const),
+  );
+
   return forKey(['$substitute', '$subs'], (value, key, ctx) => async (parse) => {
     if (typeof value === 'string') {
       return parse(performAllSubstitutions(value, envType), { shouldFlatten: true });
@@ -182,7 +186,7 @@ export function environmentVariableSubstitution(
     validateObject(value, [...ctx, key]);
     if (Array.isArray(value)) throw new AppConfigError('$substitute was given an array');
 
-    const { $name: variableName, $fallback: fallback } = value;
+    const { $name: variableName, $fallback: fallback, $allowNull: allowNull } = value;
     validateString(variableName, [...ctx, key, [InObject, '$name']]);
 
     const resolvedValue = process.env[variableName];
@@ -193,7 +197,12 @@ export function environmentVariableSubstitution(
 
     if (fallback !== undefined) {
       const fallbackValue = (await parse(fallback)).toJSON();
-      validateString(fallbackValue, [...ctx, key, [InObject, '$fallback']]);
+
+      if (allowNull) {
+        validateStringOrNull(fallbackValue, [...ctx, key, [InObject, '$fallback']]);
+      } else {
+        validateString(fallbackValue, [...ctx, key, [InObject, '$fallback']]);
+      }
 
       return parse(fallbackValue, { shouldFlatten: true });
     }