@openstax/ts-utils 1.33.1 → 1.34.0

package/packages/utils/src/assertions/index.spec.ts

@@ -0,0 +1,126 @@
+import { assertDefined, assertErrorInstanceOf, assertFalse, assertInstanceOf, assertNotNaN, assertString, assertTrue } from '.';
+
+describe('assertNotNaN', () => {
+  it('throws when NaN', () => {
+    expect(() => assertNotNaN(NaN)).toThrow();
+  });
+  it('returns thing when not NaN', () => {
+    expect(() => assertNotNaN('asdf')).not.toThrow();
+    expect(assertNotNaN('asdf')).toBe('asdf');
+  });
+});
+
+describe('assertDefined', () => {
+  it('returns value', () => {
+    expect(assertDefined('foo', 'error')).toBe('foo');
+  });
+
+  it('throws on undefined', () => {
+    expect(() =>
+      assertDefined(undefined, 'error')
+    ).toThrowErrorMatchingInlineSnapshot('"error"');
+  });
+});
+
+describe('assertTrue', () => {
+  it('returns value', () => {
+    expect(assertTrue(true, 'error')).toBe(true);
+  });
+
+  it('throws on not true', () => {
+    expect(() =>
+      assertTrue(undefined, 'error')
+    ).toThrowErrorMatchingInlineSnapshot('"error"');
+    expect(() =>
+      assertTrue(3, 'error')
+    ).toThrowErrorMatchingInlineSnapshot('"error"');
+    expect(() =>
+      assertTrue(false, 'error')
+    ).toThrowErrorMatchingInlineSnapshot('"error"');
+  });
+});
+
+describe('assertFalse', () => {
+  it('returns value', () => {
+    expect(assertFalse(false, 'error')).toBe(false);
+  });
+
+  it('throws on not false', () => {
+    expect(() =>
+      assertFalse(undefined, 'error')
+    ).toThrowErrorMatchingInlineSnapshot('"error"');
+    expect(() =>
+      assertFalse(3, 'error')
+    ).toThrowErrorMatchingInlineSnapshot('"error"');
+    expect(() =>
+      assertFalse(true, 'error')
+    ).toThrowErrorMatchingInlineSnapshot('"error"');
+  });
+});
+
+describe('assertString', () => {
+  it('returns value', () => {
+    expect(assertString('string')).toBe('string');
+  });
+
+  it('throws on undefined', () => {
+    expect(() =>
+      assertString(undefined, new Error('cool error'))
+    ).toThrowErrorMatchingInlineSnapshot('"cool error"');
+  });
+
+  it('throws on not a string', () => {
+    expect(() =>
+      assertString(5, () => { throw new Error('cool error'); })
+    ).toThrowErrorMatchingInlineSnapshot('"cool error"');
+  });
+});
+
+describe('assertInstanceOf', () => {
+  it('returns value cast to the correct type, or throws if the value is not an instanceof the constructor', () => {
+    class A {}
+    class B extends A {
+      // This property makes it so type A cannot be assigned to type B
+      someProp = true;
+    }
+
+    const a = new A;
+    const b = new B;
+
+    // We call these methods just to verify the returned types are correct
+    const acceptsA = (a: A) => a;
+    const acceptsB = (b: B) => b;
+
+    expect(acceptsA(assertInstanceOf(a, A, 'not instanceof'))).toBe(a);
+    expect(acceptsA(assertInstanceOf(b, A, 'not instanceof'))).toBe(b);
+    expect(acceptsA(assertInstanceOf(b as A, A, 'not instanceof'))).toBe(b);
+    expect(() => acceptsA(assertInstanceOf(a, B, 'not instanceof'))).toThrow('not instanceof');
+    expect(acceptsA(assertInstanceOf(b, B, 'not instanceof'))).toBe(b);
+    expect(acceptsA(assertInstanceOf(b as A, B, 'not instanceof'))).toBe(b);
+
+    expect(() => acceptsB(assertInstanceOf(a, B, 'not instanceof'))).toThrow('not instanceof');
+    expect(acceptsB(assertInstanceOf(b, B, 'not instanceof'))).toBe(b);
+    expect(acceptsB(assertInstanceOf(b as A, B, 'not instanceof'))).toBe(b);
+  });
+});
+
+describe('assertErrorInstanceOf', () => {
+  it('works with Error and subclasses, rethrows original argument if check fails', () => {
+    const syntaxError = new SyntaxError;
+    const error = new Error;
+    expect(assertErrorInstanceOf(syntaxError, SyntaxError)).toBe(syntaxError);
+    expect(() => assertErrorInstanceOf(error, SyntaxError)).toThrow(error);
+  });
+
+  it('throws an Error if original argument is not an instance of Error', () => {
+    const error = 'I am Error';
+    expect(() => assertErrorInstanceOf(error, SyntaxError)).toThrow(
+      `assertErrorInstanceOf received non-Error argument of type "${
+        typeof error}" and string representation "${error}"`
+    );
+    expect(() => assertErrorInstanceOf(error as unknown, SyntaxError)).toThrow(
+      `assertErrorInstanceOf received non-Error argument of type "${
+        typeof error}" and string representation "${error}"`
+    );
+  });
+});

package/{dist/esm/assertions/index.js → packages/utils/src/assertions/index.ts}

@@ -11,18 +11,22 @@
  * stack trace more useful, and allows you to use specific error types
  * that might be handled differently.
  */
-export const doThrow = (failed) => {
-    if (typeof failed === 'string') {
-        throw new Error(failed);
-    }
-    if (failed instanceof Error) {
-        throw failed;
-    }
-    if (!failed) {
-        throw new Error();
-    }
-    return failed();
+
+export type AssertionFailed = string | Error | (() => never) | undefined;
+
+export const doThrow = (failed: AssertionFailed): never => {
+  if (typeof failed === 'string') {
+    throw new Error(failed);
+  }
+  if (failed instanceof Error) {
+    throw failed;
+  }
+  if (!failed) {
+    throw new Error();
+  }
+  return failed();
 };
+
 /**
  * Asserts that the given value is true.
  *
@@ -33,12 +37,14 @@ export const doThrow = (failed) => {
  * @example const definitelyTrue = assertTrue(randomThing, new Error('thing was not true'));
  * @returns the value that was asserted
  */
-export const assertTrue = (x, failed) => {
-    if (typeof x !== 'boolean' || x !== true) {
-        return doThrow(failed);
-    }
-    return x;
+export const assertTrue = <X>(x: X, failed?: AssertionFailed) => {
+  if (typeof x !== 'boolean' || x !== true) {
+    return doThrow(failed);
+  }
+
+  return x;
 };
+
 /**
  * Asserts that the given value is false.
  *
@@ -49,12 +55,14 @@ export const assertTrue = (x, failed) => {
  * @example const definitelyFalse = assertFalse(randomThing, new Error('thing was not false'));
  * @returns the value that was asserted
  */
-export const assertFalse = (x, failed) => {
-    if (typeof x !== 'boolean' || x !== false) {
-        return doThrow(failed);
-    }
-    return x;
+export const assertFalse = <X>(x: X, failed?: AssertionFailed) => {
+  if (typeof x !== 'boolean' || x !== false) {
+    return doThrow(failed);
+  }
+
+  return x;
 };
+
 /**
  * Asserts that the given value is defined.
  *
@@ -65,12 +73,14 @@ export const assertFalse = (x, failed) => {
  * @example const definitelyDefined = assertDefined(randomThing, new Error('thing was undefined'));
  * @returns the value that was asserted, with a type that excludes undefined
  */
-export const assertDefined = (x, failed) => {
-    if (x === undefined) {
-        return doThrow(failed);
-    }
-    return x;
+export const assertDefined = <X>(x: X, failed?: AssertionFailed) => {
+  if (x === undefined) {
+    return doThrow(failed);
+  }
+
+  return x as Exclude<X, undefined>;
 };
+
 /**
  * Asserts that the given value is a string.
  *
@@ -81,12 +91,14 @@ export const assertDefined = (x, failed) => {
  * @example const definitelyAString = assertString(randomThing, new Error('thing is not a string'));
  * @returns the value that was asserted
  */
-export const assertString = (x, failed) => {
-    if (typeof x !== 'string') {
-        return doThrow(failed);
-    }
-    return x;
+export const assertString = <X>(x: X, failed?: AssertionFailed): string => {
+  if (typeof x !== 'string') {
+    return doThrow(failed);
+  }
+
+  return x;
 };
+
 /**
  * Asserts that the given value is not `NaN`. Does not assert that the value is a number.
  *
@@ -97,16 +109,18 @@ export const assertString = (x, failed) => {
  * @example const definitelyNotNotANumber = assertNotNaN(randomThing, new Error('thing was NaN'));
  * @returns the value that was asserted
  */
-export const assertNotNaN = (thing, failed) => {
-    if (typeof thing === 'number' && isNaN(thing)) {
-        return doThrow(failed);
-    }
-    return thing;
+export const assertNotNaN = <T>(thing: T, failed?: AssertionFailed): T => {
+  if (typeof thing === 'number' && isNaN(thing)) {
+    return doThrow(failed);
+  }
+  return thing;
 };
+
 /**
  * @deprecated use assertNotNaN instead
  */
 export const notNaN = assertNotNaN;
+
 /**
  * Asserts that the first argument is an instance of the second.
  *
@@ -118,12 +132,13 @@ export const notNaN = assertNotNaN;
  * @example const definitelySyntaxError = assertInstanceOf(error, SyntaxError, new Error('argument was not a SyntaxError'));
  * @returns the value that was asserted
  */
-export const assertInstanceOf = (thing, constructable, failed) => {
-    if (thing instanceof constructable) {
-        return thing;
-    }
-    return doThrow(failed);
+export const assertInstanceOf = <T>(thing: any, constructable: Function & { new(...args: any[]): T }, failed?: AssertionFailed): T => {
+  if (thing instanceof constructable) {
+    return thing;
+  }
+  return doThrow(failed);
 };
+
 /**
  * Asserts that the error in the first argument is an instance of the error given as the
  * second argument
@@ -135,12 +150,12 @@ export const assertInstanceOf = (thing, constructable, failed) => {
  * @throws the original error if the check fails
  * @see assertInstanceOf
  */
-export const assertErrorInstanceOf = (thing, constructable) => {
-    if (thing instanceof Error) {
-        return assertInstanceOf(thing, constructable, thing);
-    }
-    else {
-        // this separate branch prevents an unknown non-Error thing from being passed to the assertion as an AssertionFailed
-        throw new Error(`assertErrorInstanceOf received non-Error argument of type "${typeof thing}" and string representation "${thing}"`);
-    }
+export const assertErrorInstanceOf = <T extends Error>(thing: unknown, constructable: Function & { new(...args: any[]): T }): T => {
+  if (thing instanceof Error) {
+    return assertInstanceOf(thing, constructable, thing);
+  } else {
+    // this separate branch prevents an unknown non-Error thing from being passed to the assertion as an AssertionFailed
+    throw new Error(`assertErrorInstanceOf received non-Error argument of type "${
+      typeof thing}" and string representation "${thing}"`);
+  }
 };

package/packages/utils/src/aws/ssmService.ts

@@ -0,0 +1,7 @@
+import {SSM} from '@aws-sdk/client-ssm';
+import { once } from '..';
+
+/**
+ * A memoized instance of the AWS SSM client.
+ */
+export const ssmService = once(() => new SSM({apiVersion: '2012-08-10'}));

package/packages/utils/src/config/awsParameterConfig.ts

@@ -0,0 +1,24 @@
+import {GetParameterCommand} from '@aws-sdk/client-ssm';
+import { assertDefined } from '../assertions';
+import { ssmService } from '../aws/ssmService';
+import { resolveConfigValue } from './resolveConfigValue';
+import { ConfigValueProvider } from '.';
+
+/**
+ * Returns a value from the AWS Parameter Store.
+ *
+ * @param parameterName the name of the parameter; can be a literal name (string) or can itself
+ * be accessed via another parameter by giving a configuration value provider.
+ * @example const someValue = resolveConfig(awsParameterConfig('some-parameter-name'));
+ * @returns the configuration value provider for the value
+ */
+export const awsParameterConfig = (parameterName: ConfigValueProvider<string>): ConfigValueProvider<string> => {
+  return async() => {
+    const command = new GetParameterCommand({Name: await resolveConfigValue(parameterName), WithDecryption: true});
+    // send() throws ParameterNotFound if the parameter is missing,
+    // so it's not clear what missing Parameter or Value mean
+    const response = await ssmService().send(command);
+    const parameter = assertDefined(response.Parameter, `aws GetParameter response missing Parameter key for ${parameterName}"`);
+    return assertDefined(parameter.Value, `aws GetParameter response missing Parameter.Value key for ${parameterName}"`);
+  };
+};

package/packages/utils/src/config/envConfig.ts

@@ -0,0 +1,58 @@
+import { resolveConfigValue } from './resolveConfigValue';
+import type { ConfigValueProvider } from '.';
+
+/**
+ * A list of environment variables that were requested at build time. Used by webpack to
+ * capture build-time environment variables values.
+ */
+export const ENV_BUILD_CONFIGS: string[] = [];
+
+/**
+ * Returns an environment variable from the process environment. Depending on the `type` in the
+ * call to get the variable, the variable's value may be what it was at build time, not at runtime.
+ * The return value is not the variable value itself, but rather a provider that has to be called
+ * to read the variable value (meaning, this is safe to call even if the variable doesn't exist,
+ * because someone else later needs to call the provider to get the value -- that call may explode,
+ * but this one won't).
+ *
+ * @param name The name of the environment variable to retrieve.
+ * @param type The mode for accessing the variable. Defaults to `'build'`, i.e. getting the
+ * variable as it was set at build time (webpack is connected here to make this possible). This
+ * argument can also be `'runtime'` in which case the value at build time is ignored and the
+ * variable is pulled live from `process.env`.
+ * @param [defaultValue] The default value to use if the variable is not found.
+ *
+ * @example const config = { configValue: envConfig('environment_variable_name') };
+ */
+export const envConfig = (
+  name: string, type?: 'build' | 'runtime', defaultValue?: ConfigValueProvider<string>
+): ConfigValueProvider<string> => {
+  // this doesn't use a default parameter value because of a:
+  //   "Regular parameters should not come after default parameters."
+  // error that occurs when the defaultValue optional default of `undefined`
+  // gets optimized out, causing a problem in cloudfront functions.
+  type ??= 'build';
+
+  if (type === 'build') {
+    ENV_BUILD_CONFIGS.push(name);
+  }
+  return (): string | Promise<string> => {
+    /*global __PROCESS_ENV*/
+    // @ts-ignore - hack to get around the way webpack/define works
+    // - https://github.com/webpack/webpack/issues/14800
+    // - https://github.com/webpack/webpack/issues/5392
+    // also, spread operator not supported in cloudfront functions
+    const envs: typeof process.env = Object.assign({}, process.env, typeof __PROCESS_ENV !== 'undefined' ? __PROCESS_ENV : {});
+    const value = envs[name];
+
+    if (value === undefined) {
+      if (defaultValue === undefined) {
+        throw new Error(`expected to find environment variable with name: ${name}`);
+      } else {
+        return resolveConfigValue(defaultValue);
+      }
+    } else {
+      return value;
+    }
+  };
+};

package/packages/utils/src/config/index.spec.ts

@@ -0,0 +1,165 @@
+import { ParameterNotFound, SSM } from '@aws-sdk/client-ssm';
+import fetch from 'node-fetch';
+import { awsParameterConfig, ENV_BUILD_CONFIGS, envConfig, lambdaParameterConfig, replaceConfig, resolveConfigValue, stubConfig } from '.';
+
+jest.mock('@aws-sdk/client-ssm', () => {
+  const sendSpy = jest.fn(() => Promise.resolve()) as any;
+  return {
+    ...jest.requireActual('@aws-sdk/client-ssm'),
+    SSM: class {
+      static sendSpy = sendSpy;
+      send(...a: any[]) { return sendSpy(...a); }
+    }
+  };
+});
+
+jest.mock('node-fetch', jest.fn);
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('envConfig', () => {
+  it('collects build configs', () => {
+    envConfig('build config');
+    expect(ENV_BUILD_CONFIGS).toContain('build config');
+  });
+
+  it('ignores runtime configs', () => {
+    envConfig('runtime config', 'runtime');
+    expect(ENV_BUILD_CONFIGS).not.toContain('runtime config');
+  });
+
+  it('returns config value', async() => {
+    process.env.MY_COOL_CONFIG = 'cool';
+    expect(await resolveConfigValue(envConfig('MY_COOL_CONFIG'))).toBe('cool');
+  });
+
+  it('uses __PROCESS_ENV', async() => {
+    (global as any).__PROCESS_ENV = {MY_COOL_CONFIG_2: 'cool2'};
+    expect(await resolveConfigValue(envConfig('MY_COOL_CONFIG_2'))).toBe('cool2');
+  });
+
+  it('returns defaultValue if env variable is absent', async() => {
+    expect(
+      await resolveConfigValue(envConfig('MY_COOL_CONFIG_3', 'runtime', 'cool3'))
+    ).toBe('cool3');
+  });
+
+  it('works with any ConfigValueProvider<string> as a defaultValue', async() => {
+    expect(
+      await resolveConfigValue(envConfig('MY_COOL_CONFIG_3', 'runtime', () => Promise.resolve('cool4')))
+    ).toBe('cool4');
+  });
+
+  it('throws an error if the env variable is undefined and there is no defaultValue', async() => {
+    await expect(resolveConfigValue(envConfig('MY_UNCOOL_CONFIG', 'runtime'))).rejects.toThrow(
+      'expected to find environment variable with name: MY_UNCOOL_CONFIG'
+    );
+  });
+});
+
+describe('resolveConfigValue', () => {
+  it('resolves string', async() => {
+    expect(await resolveConfigValue('asdf')).toBe('asdf');
+  });
+  it('resolves function', async() => {
+    expect(await resolveConfigValue(() => 'asdf')).toBe('asdf');
+  });
+  it('resolves promise function', async() => {
+    expect(await resolveConfigValue(() => Promise.resolve('asdf'))).toBe('asdf');
+  });
+});
+
+describe('awsParameterConfig', () => {
+  const sendSpy: jest.SpyInstance = (SSM as any).sendSpy;
+
+  it('resolves parameter', async() => {
+    sendSpy.mockReturnValueOnce(Promise.resolve({Parameter: {Value: 'parameterValue'}}));
+    expect(await resolveConfigValue(awsParameterConfig('parameterName'))).toBe('parameterValue');
+    expect(sendSpy).toHaveBeenCalledWith(
+      expect.objectContaining({input: {Name: 'parameterName', WithDecryption: true}})
+    );
+  });
+
+  it('throws when parameter is not found', async() => {
+    sendSpy.mockImplementationOnce(async() => {throw new ParameterNotFound({$metadata: {}});});
+    await expect(
+      resolveConfigValue(awsParameterConfig('parameterName'))
+    ).rejects.toThrow(ParameterNotFound);
+    expect(sendSpy).toHaveBeenCalledWith(
+      expect.objectContaining({input: {Name: 'parameterName', WithDecryption: true}})
+    );
+  });
+});
+
+describe('lambdaParameterConfig', () => {
+  const fetchSpy = fetch as unknown as jest.SpyInstance;
+
+  beforeAll(() => {
+    fetchSpy.mockReturnValueOnce(Promise.resolve());
+    process.env['AWS_SESSION_TOKEN'] = 'someToken';
+  });
+
+  afterAll(() => delete process.env['AWS_SESSION_TOKEN']);
+
+  it('resolves parameter', async() => {
+    fetchSpy.mockReturnValueOnce(
+      Promise.resolve(
+        { ok: true, json: () => Promise.resolve({ Parameter: { Value: 'parameterValue' } }) }
+      )
+    );
+    expect(
+      await resolveConfigValue(lambdaParameterConfig(async() => 'parameterName'))
+    ).toBe('parameterValue');
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'http://localhost:2773/systemsmanager/parameters/get?name=parameterName&withDecryption=true',
+      { headers: { 'X-Aws-Parameters-Secrets-Token': 'someToken' } }
+    );
+  });
+
+  it('throws when parameter is not found', async() => {
+    fetchSpy.mockReturnValueOnce(
+      Promise.resolve({ ok: false, status: 404, statusText: 'Not Found' })
+    );
+    await expect(
+      resolveConfigValue(lambdaParameterConfig(async() => 'parameterName'))
+    ).rejects.toThrow('HTTP Error Response');
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'http://localhost:2773/systemsmanager/parameters/get?name=parameterName&withDecryption=true',
+      { headers: { 'X-Aws-Parameters-Secrets-Token': 'someToken' } }
+    );
+  });
+});
+
+describe('stubConfig', () => {
+  it('stubs', async() => {
+    expect(await resolveConfigValue(stubConfig('stubbed'))).toBe('stubbed');
+  });
+});
+
+describe('replaceConfig', () => {
+  it('replaces string', async() => {
+    const result = replaceConfig('base [token] value', {
+      '[token]': 'replaced'
+    });
+
+    expect(await resolveConfigValue(result)).toBe('base replaced value');
+  });
+
+  it('replaces with async values', async() => {
+    const result = replaceConfig('base [token] value', {
+      '[token]': stubConfig('replaced')
+    });
+
+    expect(await resolveConfigValue(result)).toBe('base replaced value');
+  });
+
+  it('replaces with async base', async() => {
+    const result = replaceConfig(stubConfig('base [token] value'), {
+      '[token]': stubConfig('replaced')
+    });
+
+    expect(await resolveConfigValue(result)).toBe('base replaced value');
+  });
+});

package/{dist/esm/config/index.d.ts → packages/utils/src/config/index.ts}

@@ -2,46 +2,62 @@
  * A simple type alias for a string that represents a configuration value. Currently only string values are supported to maintain compatibility with environment variables, but this type is future proofing against allowing other types like `number` as possible config values.
  */
 export type ConfigValue = string;
+
 /**
  * A configuration object that may contain nested configuration objects or configuration values.
  */
-export type Config = {
-    [key: string]: Config | ConfigValue;
-};
+export type Config = {[key: string]: Config | ConfigValue};
+
 /**
  * Either a function that returns a `ConfigValue` or a `Promise` that resolves to a `ConfigValue`,
  * or just a `ConfigValue`.
  */
 export type ConfigValueProvider<V extends ConfigValue = ConfigValue> = (() => Promise<V> | V) | V;
+
 /**
  * A configuration object that may contain nested configuration objects or configuration value providers.
  */
-export type ConfigProvider = {
-    [key: string]: ConfigProvider | ConfigValueProvider;
-};
+export type ConfigProvider = {[key: string]: ConfigProvider | ConfigValueProvider};
+
 /**
  * Conditional type that resolves to the type of configuration object for the given configuration
  * provider. Also resolves to a config value type if the given type is a config value.
  */
-export type ConfigForConfigProvider<T> = T extends ConfigValue ? T : T extends ConfigProvider ? {
-    [key in keyof T]: ConfigForConfigProvider<T[key]>;
-} : T extends ConfigValueProvider<infer R> ? R : never;
+export type ConfigForConfigProvider<T> = T extends ConfigValue
+  ? T
+  : T extends ConfigProvider
+    ? {[key in keyof T]: ConfigForConfigProvider<T[key]>}
+    : T extends ConfigValueProvider<infer R>
+      ? R
+      : never;
+
 /**
  * Conditional type that resolves to the `ConfigProvider` type for the given configuration
  * type (`ConfigValue` or `Config`). The resulting type is either a `ConfigValueProvider` or
  * a `ConfigProvider`.
  */
-export type ConfigProviderForConfig<T> = T extends ConfigValue ? ConfigValueProvider<T> : T extends Config ? {
-    [key in keyof T]: ConfigProviderForConfig<T[key]>;
-} : never;
+export type ConfigProviderForConfig<T> = T extends ConfigValue
+  ? ConfigValueProvider<T>
+  : T extends Config
+    ? {[key in keyof T]: ConfigProviderForConfig<T[key]>}
+    : never;
+
 export * from './resolveConfigValue';
+
+/*
+ * ===========
+ * re-usable config providers
+ * ===========
+ * */
+
 /**
  * stub, mostly for testing. sometimes it helps please typescript to use this if you have
  * two configs you want to have the same type but one is a fixed string and one is a complicated provider
  *
  * @example const config = { configValue: stubConfig('just-a-string') };
  */
-export declare const stubConfig: <V extends ConfigValue>(configValue: V) => ConfigValueProvider<V>;
+export const stubConfig = <V extends ConfigValue>(configValue: V): ConfigValueProvider<V> => configValue;
+
 export * from './envConfig';
 export * from './replaceConfig';
 export * from './awsParameterConfig';