refactor(#129): changes parsing extensions to pass through some hierarchical context

Author: joelgallant

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

@@ -15,7 +15,7 @@ class FailingSource extends ConfigSource {
   }
 }
 
-const flattenExtension: ParsingExtension = (value, [_, key]) => {
+const flattenExtension: ParsingExtension = (value, [[_, key]]) => {
   if (key === '$flatten') {
     return (parse) => parse(value, { shouldFlatten: true });
   }

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

@@ -42,7 +42,7 @@ describe('parseValue', () => {
     return (parse) => parse(value, { marked: true });
   };
 
-  const markKeyExtension: ParsingExtension = (value, [keyType, key]) => {
+  const markKeyExtension: ParsingExtension = (value, [[keyType, key]]) => {
     if (keyType === InObject && key === '$mark') {
       return (parse) => parse(value, { shouldFlatten: true, marked: true });
     }
@@ -60,23 +60,23 @@ describe('parseValue', () => {
     return false;
   };
 
-  const secretExtension: ParsingExtension = (_, [keyType, key]) => {
+  const secretExtension: ParsingExtension = (_, [[keyType, key]]) => {
     if (keyType === InObject && key === '$secret') {
       return (parse) => parse('revealed!', { shouldFlatten: true });
     }
 
     return false;
   };
 
-  const mergeExtension: ParsingExtension = (value, [keyType, key]) => {
+  const mergeExtension: ParsingExtension = (value, [[keyType, key]]) => {
     if (keyType === InObject && key === '$merge') {
       return (parse) => parse(value, { shouldMerge: true });
     }
 
     return false;
   };
 
-  const overrideExtension: ParsingExtension = (value, [keyType, key]) => {
+  const overrideExtension: ParsingExtension = (value, [[keyType, key]]) => {
     if (keyType === InObject && key === '$override') {
       return (parse) => parse(value, { shouldOverride: true });
     }

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

@@ -17,16 +17,19 @@ export type ParsingExtensionKey =
   | [typeof InArray, number]
   | [typeof Root];
 
-export type ParsingExtension = (
-  value: Json,
-  key: ParsingExtensionKey,
-  context: ParsingExtensionKey[],
-) => false | ParsingExtensionTransform;
+export type ParsingContext = Record<string, string>;
+
+export type ParsingExtension<T extends Json = Json> = (
+  value: T,
+  parentKeys: ParsingExtensionKey[],
+  context: ParsingContext,
+) => ParsingExtensionTransform | false;
 
 export type ParsingExtensionTransform = (
   parse: (
     value: Json,
     metadata?: ParsedValueMetadata,
+    context?: ParsingContext,
     source?: ConfigSource,
     extensions?: ParsingExtension[],
   ) => Promise<ParsedValue>,
@@ -339,23 +342,22 @@ 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: ParsingExtensionKey[],
+  context: ParsingContext = {},
+  parentKeys: ParsingExtensionKey[],
   root: Json,
   parent?: JsonObject | Json[],
   visitedExtensions: ParsingExtension[] = [],
 ): Promise<ParsedValue> {
-  const [currentKey] = context.slice(-1);
-  const contextualKeys = context.slice(0, context.length - 1);
-
   let applicableExtension: ParsingExtensionTransform | undefined;
 
   // before anything else, we check for parsing extensions that should be applied
@@ -369,7 +371,7 @@ async function parseValueInner(
     // we track visitedExtensions so that calling `parse` in an extension doesn't hit that same extension with the same value
     if (visitedExtensions.includes(extension)) continue;
 
-    const applicable = extension(value, currentKey, contextualKeys);
+    const applicable = extension(value, parentKeys, context);
 
     if (applicable && !applicableExtension) {
       applicableExtension = applicable;
@@ -378,18 +380,20 @@ async function parseValueInner(
   }
 
   if (applicableExtension) {
-    const parse = (
-      inner: Json,
-      metadataOverride?: ParsedValueMetadata,
-      sourceOverride?: ConfigSource,
-      extensionsOverride?: ParsingExtension[],
+    const parse: Parameters<ParsingExtensionTransform>[0] = (
+      inner,
+      metadataOverride,
+      contextOverride,
+      sourceOverride,
+      extensionsOverride,
     ) =>
       parseValueInner(
         inner,
         sourceOverride ?? source,
         extensionsOverride ?? extensions,
         { ...metadata, ...metadataOverride },
-        context,
+        { ...context, ...contextOverride },
+        parentKeys,
         root,
         parent,
         visitedExtensions,
@@ -407,7 +411,8 @@ async function parseValueInner(
           source,
           extensions,
           undefined,
-          context.concat([[InArray, index]]),
+          context,
+          [[InArray, index], ...parentKeys],
           root,
           value,
         );
@@ -432,7 +437,8 @@ async function parseValueInner(
           source,
           extensions,
           undefined,
-          context.concat([[InObject, key]]),
+          context,
+          [[InObject, key], ...parentKeys],
           root,
           value,
         );

app-config-default-extensions/tsconfig.json

@@ -6,8 +6,6 @@
   "include": ["src"],
   "exclude": ["node_modules"],
   "references": [
-    { "path": "../app-config-core" },
-    { "path": "../app-config-v1-compat" },
-    { "path": "../app-config-git" }
+    { "path": "../app-config-core" }
   ]
 }

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

@@ -1,13 +1,10 @@
-import type {
-  ParsingExtension,
-  ParsingExtensionKey,
-  ParsingExtensionTransform,
-} from '@app-config/core';
+import type { ParsingExtension, ParsingExtensionKey } from '@app-config/core';
 import { parseValue, Root, AppConfigError } from '@app-config/core';
+import { Json } from '@app-config/utils';
 import { SchemaBuilder } from '@serafin/schema-builder';
 
 export function composeExtensions(extensions: ParsingExtension[]): ParsingExtension {
-  return (value, [k]) => {
+  return (value, [[k]]) => {
     if (k !== Root) return false;
 
     return (_, __, source) => parseValue(value, source, extensions, { shouldFlatten: true });
@@ -28,9 +25,9 @@ export function forKey(
     return key === k;
   };
 
-  return (value, ctxKey, ctx) => {
-    if (shouldApply(ctxKey)) {
-      return parsingExtension(value, ctxKey, ctx);
+  return (value, parentKeys, context) => {
+    if (shouldApply(parentKeys[0])) {
+      return parsingExtension(value, parentKeys, context);
     }
 
     return false;
@@ -39,18 +36,14 @@ export function forKey(
 
 export class ParsingExtensionInvalidOptions extends AppConfigError {}
 
-export function validateOptions<T>(
+export function validateOptions<T extends Json>(
   builder: (builder: typeof SchemaBuilder) => SchemaBuilder<T>,
-  extension: (
-    value: T,
-    key: ParsingExtensionKey,
-    context: ParsingExtensionKey[],
-  ) => ParsingExtensionTransform | false,
+  extension: ParsingExtension<T>,
   { lazy = false }: { lazy?: boolean } = {},
 ): ParsingExtension {
   const validate: ValidationFunction<T> = validationFunction(builder);
 
-  return (value, ctxKey, ctx) => {
+  return (value, parentKeys, context) => {
     return async (parse, ...args) => {
       let valid: unknown;
 
@@ -60,9 +53,9 @@ export function validateOptions<T>(
         valid = (await parse(value)).toJSON();
       }
 
-      validate(valid, [...ctx, ctxKey]);
+      validate(valid, parentKeys);
 
-      const call = extension(valid, ctxKey, ctx);
+      const call = extension(valid, parentKeys, context);
 
       if (call) {
         return call(parse, ...args);
@@ -91,7 +84,8 @@ export function validationFunction<T>(
       const message = error instanceof Error ? error.message : 'unknown';
 
       const parents =
-        ctx
+        [...ctx]
+          .reverse()
           .map(([, k]) => k)
           .filter((v) => !!v)
           .join('.') || 'root';

app-config-extensions/src/index.ts

@@ -31,7 +31,7 @@ export function markAllValuesAsSecret(): ParsingExtension {
 
 /** When a key $$foo is seen, change it to be $foo and mark with meta property fromEscapedDirective */
 export function unescape$Directives(): ParsingExtension {
-  return (value, [_, key]) => {
+  return (value, [[_, key]]) => {
     if (typeof key === 'string' && key.startsWith('$$')) {
       return async (parse) => {
         return parse(value, { rewriteKey: key.slice(1), fromEscapedDirective: true });
@@ -141,9 +141,9 @@ export function extendsSelfDirective(): ParsingExtension {
     stringSchema(),
   );
 
-  return forKey('$extendsSelf', (input, key, ctx) => async (parse, _, __, ___, root) => {
+  return forKey('$extendsSelf', (input, parentKeys) => async (parse, _, __, ___, root) => {
     const value = (await parse(input)).toJSON();
-    validate(value, [...ctx, key]);
+    validate(value, parentKeys);
 
     // we temporarily use a ParsedValue literal so that we get the same property lookup semantics
     const selected = ParsedValue.literal(root).property(value.split('.'));
@@ -255,7 +255,7 @@ export function envVarDirective(
 ): ParsingExtension {
   const envType = environmentOverride ?? currentEnvironment(aliases, environmentSourceNames);
 
-  return forKey('$envVar', (value, key, ctx) => async (parse) => {
+  return forKey('$envVar', (value, parentKeys) => async (parse) => {
     let name: string;
     let parseInt = false;
     let parseFloat = false;
@@ -264,11 +264,11 @@ export function envVarDirective(
     if (typeof value === 'string') {
       name = value;
     } else {
-      validateObject(value, [...ctx, key]);
+      validateObject(value, parentKeys);
       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, [[InObject, 'name'], ...parentKeys]);
 
       parseInt = !!(await parse(value.parseInt)).toJSON();
       parseFloat = !!(await parse(value.parseFloat)).toJSON();
@@ -317,9 +317,9 @@ export function envVarDirective(
       const allowNull = (await parse(value.allowNull)).toJSON();
 
       if (allowNull) {
-        validateStringOrNull(fallback, [...ctx, key, [InObject, 'fallback']]);
+        validateStringOrNull(fallback, [[InObject, 'fallback'], ...parentKeys]);
       } else {
-        validateString(fallback, [...ctx, key, [InObject, 'fallback']]);
+        validateString(fallback, [[InObject, 'fallback'], ...parentKeys]);
       }
 
       return parse(fallback, { shouldFlatten: true });
@@ -337,17 +337,17 @@ export function substituteDirective(
 ): ParsingExtension {
   const envType = environmentOverride ?? currentEnvironment(aliases, environmentSourceNames);
 
-  return forKey(['$substitute', '$subs'], (value, key, ctx) => async (parse) => {
+  return forKey(['$substitute', '$subs'], (value, parentKeys) => async (parse) => {
     if (typeof value === 'string') {
       return parse(performAllSubstitutions(value, envType), { shouldFlatten: true });
     }
 
-    validateObject(value, [...ctx, key]);
+    validateObject(value, parentKeys);
     if (Array.isArray(value)) throw new AppConfigError('$substitute was given an array');
 
     const name = (await parse(value.name)).toJSON();
 
-    validateString(name, [...ctx, key, [InObject, 'name']]);
+    validateString(name, [[InObject, 'name'], ...parentKeys]);
 
     let resolvedValue = process.env[name];
 
@@ -396,9 +396,9 @@ export function substituteDirective(
       const allowNull = (await parse(value.allowNull)).toJSON();
 
       if (allowNull) {
-        validateStringOrNull(fallback, [...ctx, key, [InObject, 'fallback']]);
+        validateStringOrNull(fallback, [[InObject, 'fallback'], ...parentKeys]);
       } else {
-        validateString(fallback, [...ctx, key, [InObject, 'fallback']]);
+        validateString(fallback, [[InObject, 'fallback'], ...parentKeys]);
       }
 
       return parse(fallback, { shouldFlatten: true });

app-config-v1-compat/src/index.ts

@@ -7,7 +7,7 @@ import { logger } from '@app-config/logging';
 
 /** V1 app-config compatibility */
 export default function v1Compat(): ParsingExtension {
-  return (value, [_, key], context) => {
+  return (value, [[_, key], ...context]) => {
     // only apply in top-level app-config property
     if (context[context.length - 1]?.[0] !== Root) {
       return false;