feat: adds $try directive

Author: joelgallant

app-config-core/src/errors.ts

@@ -1,8 +1,11 @@
 /** Any generic error that comes directly from this package */
 export class AppConfigError extends Error {}
 
+/** An error that can be recovered using $try */
+export class Fallbackable extends AppConfigError {}
+
 /** When a ConfigSource cannot be found */
-export class NotFoundError extends AppConfigError {}
+export class NotFoundError extends Fallbackable {}
 
 /** Could not parse a string from a config source */
 export class ParsingError extends AppConfigError {}

app-config-default-extensions/index.js

@@ -14,12 +14,13 @@ module.exports = {
     environmentSourceNames,
   ) {
     const {
+      unescape$Directives,
+      tryDirective,
       envDirective,
       extendsDirective,
       extendsSelfDirective,
       overrideDirective,
       timestampDirective,
-      unescape$Directives,
       environmentVariableSubstitution,
     } = require('@app-config/extensions');
 
@@ -28,30 +29,43 @@ module.exports = {
     const { default: gitRefDirectives } = require('@app-config/git');
 
     return [
+      unescape$Directives(),
+      tryDirective(),
       v1Compat(),
       envDirective(aliases, environmentOverride, environmentSourceNames),
       extendsDirective(),
       extendsSelfDirective(),
       overrideDirective(),
       encryptedDirective(symmetricKey),
       timestampDirective(),
-      unescape$Directives(),
       environmentVariableSubstitution(aliases, environmentOverride, environmentSourceNames),
       gitRefDirectives(),
     ];
   },
   defaultEnvExtensions() {
-    const { unescape$Directives, markAllValuesAsSecret } = require('@app-config/extensions');
+    const {
+      unescape$Directives,
+      tryDirective,
+      markAllValuesAsSecret,
+    } = require('@app-config/extensions');
 
-    return [unescape$Directives(), markAllValuesAsSecret()];
+    return [unescape$Directives(), tryDirective(), markAllValuesAsSecret()];
   },
   defaultMetaExtensions() {
     const {
+      unescape$Directives,
+      tryDirective,
       extendsDirective,
       extendsSelfDirective,
       overrideDirective,
     } = require('@app-config/extensions');
 
-    return [extendsDirective(), extendsSelfDirective(), overrideDirective()];
+    return [
+      unescape$Directives(),
+      tryDirective(),
+      extendsDirective(),
+      extendsSelfDirective(),
+      overrideDirective(),
+    ];
   },
 };

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

@@ -1,8 +1,9 @@
 import { withTempFiles } from '@app-config/test-utils';
-import { LiteralSource, NotFoundError } from '@app-config/core';
+import { LiteralSource, NotFoundError, Fallbackable } from '@app-config/core';
 import { FileSource } from '@app-config/node';
 import { forKey } from '@app-config/extension-utils';
 import {
+  tryDirective,
   envDirective,
   extendsDirective,
   extendsSelfDirective,
@@ -11,6 +12,88 @@ import {
   environmentVariableSubstitution,
 } from './index';
 
+describe('$try directive', () => {
+  it('uses main value', async () => {
+    const source = new LiteralSource({
+      $try: {
+        $value: 'foobar',
+        $fallback: 'barfoo',
+      },
+    });
+
+    expect(await source.readToJSON([tryDirective()])).toEqual('foobar');
+  });
+
+  it('uses fallback value', async () => {
+    const failDirective = forKey('$fail', () => () => {
+      throw new Fallbackable();
+    });
+
+    const source = new LiteralSource({
+      $try: {
+        $value: {
+          $fail: true,
+        },
+        $fallback: 'barfoo',
+      },
+    });
+
+    expect(await source.readToJSON([tryDirective(), failDirective])).toEqual('barfoo');
+  });
+
+  it('doesnt evaluate fallback if value works', async () => {
+    const failDirective = forKey('$fail', () => () => {
+      throw new Fallbackable();
+    });
+
+    const source = new LiteralSource({
+      $try: {
+        $value: 'barfoo',
+        $fallback: {
+          $fail: true,
+        },
+      },
+    });
+
+    expect(await source.readToJSON([tryDirective(), failDirective])).toEqual('barfoo');
+  });
+
+  it('doesnt swallow plain errors', async () => {
+    const failDirective = forKey('$fail', () => () => {
+      throw new Error();
+    });
+
+    const source = new LiteralSource({
+      $try: {
+        $value: {
+          $fail: true,
+        },
+        $fallback: 'barfoo',
+      },
+    });
+
+    await expect(source.readToJSON([tryDirective(), failDirective])).rejects.toThrow(Error);
+  });
+
+  it('swallows plain errors with "unsafe" option', async () => {
+    const failDirective = forKey('$fail', () => () => {
+      throw new Error();
+    });
+
+    const source = new LiteralSource({
+      $try: {
+        $value: {
+          $fail: true,
+        },
+        $fallback: 'barfoo',
+        $unsafe: true,
+      },
+    });
+
+    expect(await source.readToJSON([tryDirective(), failDirective])).toEqual('barfoo');
+  });
+});
+
 describe('$extends directive', () => {
   it('fails if file is missing', async () => {
     const source = new LiteralSource({
@@ -874,4 +957,21 @@ describe('extension combinations', () => {
       expect(parsed.toJSON()).toEqual({ foo: 'bar' });
     });
   });
+
+  it('combines $try and $extends', async () => {
+    const source = new LiteralSource({
+      $try: {
+        $value: {
+          $extends: './test-file.json',
+        },
+        $fallback: {
+          fellBack: true,
+        },
+      },
+    });
+
+    await expect(source.readToJSON([extendsDirective(), tryDirective()])).resolves.toEqual({
+      fellBack: true,
+    });
+  });
 });

app-config-extensions/src/index.ts

@@ -12,6 +12,7 @@ import {
   AppConfigError,
   NotFoundError,
   FailedToSelectSubObject,
+  Fallbackable,
   InObject,
 } from '@app-config/core';
 import {
@@ -40,6 +41,35 @@ export function unescape$Directives(): ParsingExtension {
   };
 }
 
+/** Try an operation, with a fallback ($try, $value and $fallback) */
+export function tryDirective(): ParsingExtension {
+  return forKey(
+    '$try',
+    validateOptions(
+      (SchemaBuilder) =>
+        SchemaBuilder.emptySchema()
+          .addProperty('$value', SchemaBuilder.fromJsonSchema({}))
+          .addProperty('$fallback', SchemaBuilder.fromJsonSchema({}))
+          .addBoolean('$unsafe', {}, false),
+      (value) => async (parse) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const { $value, $fallback, $unsafe } = value;
+
+        try {
+          return await parse($value, { shouldFlatten: true });
+        } catch (error) {
+          if (error instanceof Fallbackable || $unsafe) {
+            return parse($fallback, { shouldFlatten: true });
+          }
+
+          throw error;
+        }
+      },
+      { lazy: true },
+    ),
+  );
+}
+
 /** Uses another file as overriding values, layering them on top of current file */
 export function overrideDirective(): ParsingExtension {
   return fileReferenceDirective('$override', { shouldOverride: true });

app-config-git/src/index.ts

@@ -1,7 +1,9 @@
 import simpleGit from 'simple-git';
-import { ParsingExtension, AppConfigError } from '@app-config/core';
+import { ParsingExtension, AppConfigError, Fallbackable } from '@app-config/core';
 import { forKey, validateOptions } from '@app-config/extension-utils';
 
+class GitError extends Fallbackable {}
+
 /** Access to the git branch and commit ref */
 export default function gitRefDirectives(
   getStatus: typeof gitStatus = gitStatus,
@@ -53,13 +55,18 @@ interface GitStatus {
 
 async function gitStatus(): Promise<GitStatus> {
   const git = simpleGit({});
-  const rev = await git.revparse(['HEAD']);
-  const branch = await git.revparse(['--abbrev-ref', 'HEAD']);
-  const tag = await git.tag(['--points-at', 'HEAD']);
 
-  return {
-    commitRef: rev,
-    branchName: branch,
-    tag: (tag.trim() || undefined)?.split(' ')[0],
-  };
+  try {
+    const rev = await git.revparse(['HEAD']);
+    const branch = await git.revparse(['--abbrev-ref', 'HEAD']);
+    const tag = await git.tag(['--points-at', 'HEAD']);
+
+    return {
+      commitRef: rev,
+      branchName: branch,
+      tag: (tag.trim() || undefined)?.split(' ')[0],
+    };
+  } catch (error) {
+    throw new GitError(error.message);
+  }
 }