feat: separates "validationFunction" for "lazy" validation of parsing extensions

Author: joelgallant

app-config-extension-utils/src/index.ts

@@ -1,4 +1,6 @@
+import type { Json } from '@app-config/utils';
 import type {
+  ParsedValue,
   ParsingExtension,
   ParsingExtensionKey,
   ParsingExtensionTransform,
@@ -48,33 +50,19 @@ export function validateOptions<T>(
   ) => ParsingExtensionTransform | false,
   { lazy = false }: { lazy?: boolean } = {},
 ): ParsingExtension {
-  const schema = builder(SchemaBuilder);
-
-  schema.cacheValidationFunction();
+  const validate: ValidationFunction<T> = validationFunction(builder);
 
   return (value, ctxKey, ctx) => {
     return async (parse, ...args) => {
-      let valid: T;
+      let valid: unknown;
 
       if (lazy) {
-        valid = (value as unknown) as T;
+        valid = value;
       } else {
-        valid = ((await parse(value)).toJSON() as unknown) as T;
+        valid = (await parse(value)).toJSON();
       }
 
-      try {
-        schema.validate(valid);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : 'unknown';
-
-        const parents =
-          [...ctx, ctxKey]
-            .map(([, k]) => k)
-            .filter((v) => !!v)
-            .join('.') || 'root';
-
-        throw new ParsingExtensionInvalidOptions(`Validation failed in "${parents}": ${message}`);
-      }
+      validate(valid, [...ctx, ctxKey]);
 
       const call = extension(valid, ctxKey, ctx);
 
@@ -88,3 +76,29 @@ export function validateOptions<T>(
     };
   };
 }
+
+export type ValidationFunction<T> = (value: any, ctx: ParsingExtensionKey[]) => asserts value is T;
+
+export function validationFunction<T>(
+  builder: (builder: typeof SchemaBuilder) => SchemaBuilder<T>,
+): ValidationFunction<T> {
+  const schema = builder(SchemaBuilder);
+
+  schema.cacheValidationFunction();
+
+  return (value, ctx): asserts value is T => {
+    try {
+      schema.validate(value);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'unknown';
+
+      const parents =
+        ctx
+          .map(([, k]) => k)
+          .filter((v) => !!v)
+          .join('.') || 'root';
+
+      throw new ParsingExtensionInvalidOptions(`Validation failed in "${parents}": ${message}`);
+    }
+  };
+}

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

@@ -722,6 +722,22 @@ describe('$substitute directive', () => {
 
     expect(parsed.toJSON()).toEqual({ foo: 'bar' });
   });
+
+  it('doesnt visit fallback if name is defined', async () => {
+    const failDirective = forKey('$fail', () => () => {
+      throw new Error();
+    });
+
+    process.env.FOO = 'foo';
+
+    const source = new LiteralSource({
+      foo: { $substitute: { $name: 'FOO', $fallback: { $fail: true } } },
+    });
+
+    const parsed = await source.read([environmentVariableSubstitution(), failDirective]);
+
+    expect(parsed.toJSON()).toEqual({ foo: 'foo' });
+  });
 });
 
 describe('$timestamp directive', () => {

app-config-extensions/src/index.ts

@@ -1,12 +1,18 @@
 import { join, dirname, resolve, isAbsolute } from 'path';
-import { forKey, validateOptions } from '@app-config/extension-utils';
+import {
+  forKey,
+  validateOptions,
+  validationFunction,
+  ValidationFunction,
+} from '@app-config/extension-utils';
 import {
   ParsedValue,
   ParsedValueMetadata,
   ParsingExtension,
   AppConfigError,
   NotFoundError,
   FailedToSelectSubObject,
+  InObject,
 } from '@app-config/core';
 import {
   currentEnvironment,
@@ -46,26 +52,27 @@ export function extendsDirective(): ParsingExtension {
 
 /** Lookup a property in the same file, and "copy" it */
 export function extendsSelfDirective(): ParsingExtension {
-  return forKey(
-    '$extendsSelf',
-    validateOptions(
-      (SchemaBuilder) => SchemaBuilder.stringSchema(),
-      (value) => async (parse, _, __, ___, root) => {
-        // we temporarily use a ParsedValue literal so that we get the same property lookup semantics
-        const selected = ParsedValue.literal(root).property(value.split('.'));
+  const validate: ValidationFunction<string> = validationFunction(({ stringSchema }) =>
+    stringSchema(),
+  );
 
-        if (selected === undefined) {
-          throw new AppConfigError(`$extendsSelf selector was not found (${value})`);
-        }
+  return forKey('$extendsSelf', (input, key, ctx) => async (parse, _, __, ___, root) => {
+    const value = (await parse(input)).toJSON();
+    validate(value, [...ctx, key]);
 
-        if (selected.asObject() !== undefined) {
-          return parse(selected.toJSON(), { shouldMerge: true });
-        }
+    // we temporarily use a ParsedValue literal so that we get the same property lookup semantics
+    const selected = ParsedValue.literal(root).property(value.split('.'));
 
-        return parse(selected.toJSON(), { shouldFlatten: true });
-      },
-    ),
-  );
+    if (selected === undefined) {
+      throw new AppConfigError(`$extendsSelf selector was not found (${value})`);
+    }
+
+    if (selected.asObject() !== undefined) {
+      return parse(selected.toJSON(), { shouldMerge: true });
+    }
+
+    return parse(selected.toJSON(), { shouldFlatten: true });
+  });
 }
 
 /** Looks up an environment-specific value ($env) */
@@ -108,6 +115,7 @@ export function envDirective(
           `An $env directive was used, but none matched the current environment (wanted ${environment}, saw [${found}])`,
         );
       },
+      // $env is lazy so that non-applicable envs don't get evaluated
       { lazy: true },
     ),
   );
@@ -158,36 +166,44 @@ export function environmentVariableSubstitution(
 ): ParsingExtension {
   const envType = environmentOverride ?? currentEnvironment(aliases, environmentSourceNames);
 
-  return forKey(
-    ['$substitute', '$subs'],
-    validateOptions(
-      (SchemaBuilder) =>
-        SchemaBuilder.oneOf(
-          SchemaBuilder.stringSchema(),
-          SchemaBuilder.emptySchema().addString('$name').addString('$fallback', {}, false),
-        ),
-      (value) => (parse) => {
-        if (typeof value === 'object') {
-          const { $name: variableName, $fallback: fallback } = value;
-          const resolvedValue = process.env[variableName];
+  const validateObject: ValidationFunction<
+    Record<string, any>
+  > = validationFunction(({ emptySchema }) => emptySchema().addAdditionalProperties());
 
-          if (fallback !== undefined) {
-            return parse(resolvedValue || fallback, { shouldFlatten: true });
-          }
+  const validateString: ValidationFunction<string> = validationFunction(({ stringSchema }) =>
+    stringSchema(),
+  );
 
-          if (!resolvedValue) {
-            throw new AppConfigError(
-              `$substitute could not find ${variableName} environment variable`,
-            );
-          }
+  return forKey(['$substitute', '$subs'], (value, key, ctx) => async (parse) => {
+    if (typeof value === 'string') {
+      return parse(performAllSubstitutions(value, envType), { shouldFlatten: true });
+    }
 
-          return parse(resolvedValue, { shouldFlatten: true });
-        }
+    validateObject(value, [...ctx, key]);
+    if (Array.isArray(value)) throw new AppConfigError('$substitute was given an array');
 
-        return parse(performAllSubstitutions(value, envType), { shouldFlatten: true });
-      },
-    ),
-  );
+    const { $name: variableName, $fallback: fallback } = value;
+    validateString(variableName, [...ctx, key, [InObject, '$name']]);
+
+    const resolvedValue = process.env[variableName];
+
+    if (resolvedValue) {
+      return parse(resolvedValue, { shouldFlatten: true });
+    }
+
+    if (fallback !== undefined) {
+      const fallbackValue = (await parse(fallback)).toJSON();
+      validateString(fallbackValue, [...ctx, key, [InObject, '$fallback']]);
+
+      return parse(fallbackValue, { shouldFlatten: true });
+    }
+
+    if (!resolvedValue) {
+      throw new AppConfigError(`$substitute could not find ${variableName} environment variable`);
+    }
+
+    return parse(resolvedValue, { shouldFlatten: true });
+  });
 }
 
 // common logic for $extends and $override
@@ -206,7 +222,7 @@ function fileReferenceDirective(keyName: string, meta: ParsedValueMetadata): Par
 
         return SchemaBuilder.oneOf(reference, SchemaBuilder.arraySchema(reference));
       },
-      (value) => async (parse, _, context, extensions) => {
+      (value) => async (_, __, context, extensions) => {
         const retrieveFile = async (filepath: string, subselector?: string, isOptional = false) => {
           let resolvedPath = filepath;