feat(#129): adds parsing context in parsing extensions

Author: joelgallant

app-config-core/src/config-source.ts

@@ -4,7 +4,7 @@ import { safeLoad as parseYAML, safeDump as stringifyYAML } from 'js-yaml';
 import { parse as parseJSON5, stringify as stringifyJSON5 } from 'json5';
 import { Json, JsonObject } from '@app-config/utils';
 import { logger } from '@app-config/logging';
-import { ParsedValue, ParsingExtension } from './parsed-value';
+import { ParsedValue, ParsingContext, ParsingExtension } from './parsed-value';
 import { AppConfigError, NotFoundError, ParsingError, BadFileType } from './errors';
 
 export enum FileType {
@@ -30,15 +30,15 @@ export abstract class ConfigSource {
   }
 
   /** Reads the contents of the source into a full ParsedValue (not the raw JSON, like readValue) */
-  async read(extensions?: ParsingExtension[]): Promise<ParsedValue> {
+  async read(extensions?: ParsingExtension[], context?: ParsingContext): Promise<ParsedValue> {
     const rawValue = await this.readValue();
 
-    return ParsedValue.parse(rawValue, this, extensions);
+    return ParsedValue.parse(rawValue, this, extensions, undefined, context);
   }
 
   /** Ergonomic helper for chaining `source.read(extensions).then(v => v.toJSON())` */
-  async readToJSON(extensions?: ParsingExtension[]): Promise<Json> {
-    const parsed = await this.read(extensions);
+  async readToJSON(extensions?: ParsingExtension[], context?: ParsingContext): Promise<Json> {
+    const parsed = await this.read(extensions, context);
 
     return parsed.toJSON();
   }
@@ -82,8 +82,10 @@ export class CombinedSource extends ConfigSource {
   }
 
   // override so that ParsedValue is directly from the originating ConfigSource
-  async read(extensions?: ParsingExtension[]): Promise<ParsedValue> {
-    const values = await Promise.all(this.sources.map((source) => source.read(extensions)));
+  async read(extensions?: ParsingExtension[], context?: ParsingContext): Promise<ParsedValue> {
+    const values = await Promise.all(
+      this.sources.map((source) => source.read(extensions, { ...context })),
+    );
 
     const merged = values.reduce<ParsedValue | undefined>((acc, parsed) => {
       if (!acc) return parsed;
@@ -137,11 +139,11 @@ export class FallbackSource extends ConfigSource {
   }
 
   // override so that ParsedValue is directly from the originating ConfigSource
-  async read(extensions?: ParsingExtension[]): Promise<ParsedValue> {
+  async read(extensions?: ParsingExtension[], context?: ParsingContext): Promise<ParsedValue> {
     // take the first value that comes back without an error
     for (const source of this.sources) {
       try {
-        const value = await source.read(extensions);
+        const value = await source.read(extensions, context);
         logger.verbose(`FallbackSource found successful source`);
 
         return value;

app-config-core/src/parsed-value.ts

@@ -17,10 +17,17 @@ export type ParsingExtensionKey =
   | [typeof InArray, number]
   | [typeof Root];
 
+export interface ParsingContext {
+  [k: string]: string | string[] | undefined | ParsingContext;
+}
+
 export interface ParsingExtension {
-  (value: Json, key: ParsingExtensionKey, parentKeys: ParsingExtensionKey[]):
-    | ParsingExtensionTransform
-    | false;
+  (
+    value: Json,
+    key: ParsingExtensionKey,
+    parentKeys: ParsingExtensionKey[],
+    context: ParsingContext,
+  ): ParsingExtensionTransform | false;
 
   /**
    * A globally unique string that identifies what parsing extension this is.
@@ -36,6 +43,7 @@ export type ParsingExtensionTransform = (
     metadata?: ParsedValueMetadata,
     source?: ConfigSource,
     extensions?: ParsingExtension[],
+    context?: ParsingContext,
   ) => Promise<ParsedValue>,
   parent: JsonObject | Json[] | undefined,
   source: ConfigSource,
@@ -73,8 +81,9 @@ export class ParsedValue {
     source: ConfigSource,
     extensions?: ParsingExtension[],
     metadata?: ParsedValueMetadata,
+    context?: ParsingContext,
   ): Promise<ParsedValue> {
-    return parseValue(raw, source, extensions, metadata);
+    return parseValue(raw, source, extensions, metadata, context);
   }
 
   /** Parses (with extensions) from a plain JSON object */
@@ -346,15 +355,17 @@ export async function parseValue(
   source: ConfigSource,
   extensions: ParsingExtension[] = [],
   metadata: ParsedValueMetadata = {},
+  context: ParsingContext = {},
 ): Promise<ParsedValue> {
-  return parseValueInner(value, source, extensions, metadata, [[Root]], value);
+  return parseValueInner(value, source, extensions, metadata, context, [[Root]], value);
 }
 
 async function parseValueInner(
   value: Json,
   source: ConfigSource,
   extensions: ParsingExtension[],
   metadata: ParsedValueMetadata = {},
+  context: ParsingContext = {},
   parentKeys: ParsingExtensionKey[],
   root: Json,
   parent?: JsonObject | Json[],
@@ -377,7 +388,7 @@ async function parseValueInner(
     if (visitedExtensions.has(extension)) continue;
     if (extension.extensionName && visitedExtensions.has(extension.extensionName)) continue;
 
-    const applicable = extension(value, currentKey, parentKeysNext);
+    const applicable = extension(value, currentKey, parentKeysNext, context);
 
     if (applicable) {
       applicableExtension = applicable;
@@ -397,12 +408,14 @@ async function parseValueInner(
       metadataOverride?: ParsedValueMetadata,
       sourceOverride?: ConfigSource,
       extensionsOverride?: ParsingExtension[],
+      contextOverride?: ParsingContext,
     ) =>
       parseValueInner(
         inner,
         sourceOverride ?? source,
         extensionsOverride ?? extensions,
         { ...metadata, ...metadataOverride },
+        { ...context, ...contextOverride },
         parentKeys,
         root,
         parent,
@@ -421,6 +434,7 @@ async function parseValueInner(
           source,
           extensions,
           undefined,
+          context,
           parentKeys.concat([[InArray, index]]),
           root,
           value,
@@ -446,6 +460,7 @@ async function parseValueInner(
           source,
           extensions,
           undefined,
+          context,
           parentKeys.concat([[InObject, key]]),
           root,
           value,

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

@@ -1,4 +1,5 @@
 import type {
+  ParsingContext,
   ParsingExtension,
   ParsingExtensionKey,
   ParsingExtensionTransform,
@@ -7,7 +8,7 @@ import { parseValue, Root, AppConfigError } from '@app-config/core';
 import { SchemaBuilder } from '@serafin/schema-builder';
 
 export function composeExtensions(extensions: ParsingExtension[]): ParsingExtension {
-  const composed: ParsingExtension = (value, [k]) => {
+  const composed: ParsingExtension = (value, [k], _, context) => {
     // only applies to the root - override the parsing extensions
     if (k !== Root) return false;
 
@@ -19,6 +20,7 @@ export function composeExtensions(extensions: ParsingExtension[]): ParsingExtens
         // ensures that a recursion doesn't happen
         baseExtensions.concat(extensions).filter((v) => v !== composed),
         { shouldFlatten: true },
+        context,
       );
   };
 
@@ -45,9 +47,9 @@ export function forKey(
     return key === k;
   };
 
-  return (value, ctxKey, ctx) => {
-    if (shouldApply(ctxKey)) {
-      return parsingExtension(value, ctxKey, ctx);
+  return (value, currentKey, parentKeys, context) => {
+    if (shouldApply(currentKey)) {
+      return parsingExtension(value, currentKey, parentKeys, context);
     }
 
     return false;
@@ -73,12 +75,13 @@ export function validateOptions<T>(
     value: T,
     key: ParsingExtensionKey,
     parentKeys: ParsingExtensionKey[],
+    context: ParsingContext,
   ) => ParsingExtensionTransform | false,
   { lazy = false }: { lazy?: boolean } = {},
 ): ParsingExtension {
   const validate: ValidationFunction<T> = validationFunction(builder);
 
-  return (value, ctxKey, ctx) => {
+  return (value, key, parentKeys, context) => {
     return async (parse, ...args) => {
       let valid: unknown;
 
@@ -88,9 +91,9 @@ export function validateOptions<T>(
         valid = (await parse(value)).toJSON();
       }
 
-      validate(valid, [...ctx, ctxKey]);
+      validate(valid, [...parentKeys, key]);
 
-      const call = extension(valid, ctxKey, ctx);
+      const call = extension(valid, key, parentKeys, context);
 
       if (call) {
         return call(parse, ...args);
@@ -103,7 +106,10 @@ export function validateOptions<T>(
   };
 }
 
-export type ValidationFunction<T> = (value: any, ctx: ParsingExtensionKey[]) => asserts value is T;
+export type ValidationFunction<T> = (
+  value: any,
+  parentKeys: ParsingExtensionKey[],
+) => asserts value is T;
 
 export function validationFunction<T>(
   builder: (builder: typeof SchemaBuilder) => SchemaBuilder<T>,
@@ -112,14 +118,14 @@ export function validationFunction<T>(
 
   schema.cacheValidationFunction();
 
-  return (value, ctx): asserts value is T => {
+  return (value, parentKeys): asserts value is T => {
     try {
       schema.validate(value);
     } catch (error) {
       const message = error instanceof Error ? error.message : 'unknown';
 
       throw new ParsingExtensionInvalidOptions(
-        `Validation failed in "${keysToPath(ctx)}": ${message}`,
+        `Validation failed in "${keysToPath(parentKeys)}": ${message}`,
       );
     }
   };

app-config-extensions/src/env-directive.ts

@@ -2,7 +2,7 @@ import type { ParsingExtension } from '@app-config/core';
 import { AppConfigError } from '@app-config/core';
 import { named, forKey, keysToPath, validateOptions } from '@app-config/extension-utils';
 import {
-  currentEnvironment,
+  currentEnvFromContext,
   defaultAliases,
   asEnvOptions,
   EnvironmentAliases,
@@ -15,17 +15,19 @@ export function envDirective(
   environmentSourceNames?: string[] | string,
 ): ParsingExtension {
   const metadata = { shouldOverride: true };
-  const environment = currentEnvironment(
-    asEnvOptions(environmentOverride, aliases, environmentSourceNames),
-  );
 
   return named(
     '$env',
     forKey(
       '$env',
       validateOptions(
         (SchemaBuilder) => SchemaBuilder.emptySchema().addAdditionalProperties(),
-        (value, _, ctx) => (parse) => {
+        (value, _, parentKeys, context) => (parse) => {
+          const environment = currentEnvFromContext(
+            context,
+            asEnvOptions(environmentOverride, aliases, environmentSourceNames),
+          );
+
           if (!environment) {
             if ('none' in value) {
               return parse(value.none, metadata);
@@ -35,10 +37,10 @@ export function envDirective(
               return parse(value.default, metadata);
             }
 
+            const path = keysToPath(parentKeys);
+
             throw new AppConfigError(
-              `An $env directive was used (in ${keysToPath(
-                ctx,
-              )}), but current environment (eg. NODE_ENV) is undefined`,
+              `An $env directive was used (in ${path}), but current environment (eg. NODE_ENV) is undefined`,
             );
           }
 
@@ -53,11 +55,10 @@ export function envDirective(
           }
 
           const found = Object.keys(value).join(', ');
+          const path = keysToPath(parentKeys);
 
           throw new AppConfigError(
-            `An $env directive was used (in ${keysToPath(
-              ctx,
-            )}), but none matched the current environment (wanted ${environment}, saw [${found}])`,
+            `An $env directive was used (in ${path}), but none matched the current environment (wanted ${environment}, saw [${found}])`,
           );
         },
         // $env is lazy so that non-applicable envs don't get evaluated

app-config-extensions/src/env-var-directive.ts

@@ -3,7 +3,7 @@ import { named, forKey, validationFunction, ValidationFunction } from '@app-conf
 import { AppConfigError, InObject } from '@app-config/core';
 import {
   asEnvOptions,
-  currentEnvironment,
+  currentEnvFromContext,
   defaultAliases,
   EnvironmentAliases,
 } from '@app-config/node';
@@ -15,13 +15,14 @@ export function envVarDirective(
   environmentOverride?: string,
   environmentSourceNames?: string[] | string,
 ): ParsingExtension {
-  const environment = currentEnvironment(
-    asEnvOptions(environmentOverride, aliases, environmentSourceNames),
-  );
-
   return named(
     '$envVar',
-    forKey('$envVar', (value, key, ctx) => async (parse) => {
+    forKey('$envVar', (value, key, parentKeys, context) => async (parse) => {
+      const environment = currentEnvFromContext(
+        context,
+        asEnvOptions(environmentOverride, aliases, environmentSourceNames),
+      );
+
       let name: string;
       let parseInt = false;
       let parseFloat = false;
@@ -30,11 +31,11 @@ export function envVarDirective(
       if (typeof value === 'string') {
         name = value;
       } else {
-        validateObject(value, [...ctx, key]);
+        validateObject(value, [...parentKeys, key]);
         if (Array.isArray(value)) throw new AppConfigError('$envVar was given an array');
 
         const resolved = (await parse(value.name)).toJSON();
-        validateString(resolved, [...ctx, key, [InObject, 'name']]);
+        validateString(resolved, [...parentKeys, key, [InObject, 'name']]);
 
         parseInt = !!(await parse(value.parseInt)).toJSON();
         parseFloat = !!(await parse(value.parseFloat)).toJSON();
@@ -111,9 +112,9 @@ export function envVarDirective(
           const allowNull = (await parse(value.allowNull)).toJSON();
 
           if (allowNull) {
-            validateStringOrNull(fallback, [...ctx, key, [InObject, 'fallback']]);
+            validateStringOrNull(fallback, [...parentKeys, key, [InObject, 'fallback']]);
           } else {
-            validateString(fallback, [...ctx, key, [InObject, 'fallback']]);
+            validateString(fallback, [...parentKeys, key, [InObject, 'fallback']]);
           }
 
           return parseValue(fallback);