@openstax/ts-utils 1.1.27 → 1.1.29

package/dist/esm/config/index.d.ts

@@ -0,0 +1,21 @@
+export declare type ConfigValue = string;
+export declare type Config = {
+    [key: string]: Config | ConfigValue;
+};
+export declare type ConfigValueProvider<V extends ConfigValue = ConfigValue> = (() => Promise<V> | V) | V;
+export declare type ConfigProvider = {
+    [key: string]: ConfigProvider | ConfigValueProvider;
+};
+export declare 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 declare type ConfigProviderForConfig<T> = T extends ConfigValue ? ConfigValueProvider<T> : T extends Config ? {
+    [key in keyof T]: ConfigProviderForConfig<T[key]>;
+} : never;
+export * from './resolveConfigValue';
+export declare const stubConfig: <V extends string>(configValue: V) => ConfigValueProvider<V>;
+export * from './envConfig';
+export * from './replaceConfig';
+export * from './awsAccountConfig';
+export * from './awsParameterConfig';
+export * from './lambdaParameterConfig';

package/dist/esm/config/index.js

@@ -0,0 +1,21 @@
+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
+ *
+ * eg:
+ *   const config = {
+ *     configValue: stubConfig('just-a-string'),
+ *   };
+ * */
+export const stubConfig = (configValue) => configValue;
+export * from './envConfig';
+export * from './replaceConfig';
+export * from './awsAccountConfig';
+export * from './awsParameterConfig';
+export * from './lambdaParameterConfig';

package/dist/esm/config/lambdaParameterConfig.d.ts

@@ -0,0 +1,2 @@
+import { ConfigValueProvider } from '.';
+export declare const lambdaParameterConfig: (parameterName: ConfigValueProvider<string>) => ConfigValueProvider<string>;

package/dist/esm/config/lambdaParameterConfig.js

@@ -0,0 +1,29 @@
+import fetch from 'node-fetch';
+import { assertDefined } from '../assertions';
+import { envConfig } from './envConfig';
+import { resolveConfigValue } from '.';
+const lambdaExtensionUrl = 'http://localhost:2773';
+let lambdaExtensionReadyPromise;
+// NOTE: Can only be used during in AWS Lambda
+// The AWS Parameters and Secrets Lambda Extension Layer must be included in the Lambda function
+export const lambdaParameterConfig = (parameterName) => async () => {
+    const token = await resolveConfigValue(envConfig('AWS_SESSION_TOKEN', 'runtime'));
+    const name = await resolveConfigValue(parameterName);
+    if (!lambdaExtensionReadyPromise) {
+        // This request will return 400 Bad Request,
+        // but we only care that it'll block until the extension is ready
+        lambdaExtensionReadyPromise = fetch(lambdaExtensionUrl);
+    }
+    await lambdaExtensionReadyPromise;
+    const resp = await fetch(
+    // Port 2773 is the default port for the extension
+    `${lambdaExtensionUrl}/systemsmanager/parameters/get?name=${name}&withDecryption=true`, { headers: { 'X-Aws-Parameters-Secrets-Token': token } });
+    if (resp.ok) {
+        const response = await resp.json();
+        const parameter = assertDefined(response.Parameter, `aws GetParameter response missing Parameter key for ${name}"`);
+        return assertDefined(parameter.Value, `aws GetParameter response missing Parameter.Value key for ${name}"`);
+    }
+    else {
+        throw new Error(`HTTP Error Response ${resp.status} ${resp.statusText} while fetching parameter ${name}`);
+    }
+};

package/dist/esm/config/replaceConfig.d.ts

@@ -0,0 +1,4 @@
+import { ConfigValueProvider } from '.';
+export declare const replaceConfig: (base: ConfigValueProvider<string>, replacements: {
+    [token: string]: ConfigValueProvider<string>;
+}) => ConfigValueProvider<string>;

package/dist/esm/config/replaceConfig.js

@@ -0,0 +1,8 @@
+import { resolveConfigValue } from './resolveConfigValue';
+export const replaceConfig = (base, replacements) => {
+    return async () => {
+        const resolved = await Promise.all(Object.entries(replacements)
+            .map(async ([token, replacement]) => [token, await resolveConfigValue(replacement)]));
+        return resolved.reduce((result, [token, replacement]) => result.replace(token, replacement), await resolveConfigValue(base));
+    };
+};

package/dist/esm/config/resolveConfigValue.d.ts

@@ -0,0 +1,2 @@
+import { ConfigValueProvider } from '.';
+export declare const resolveConfigValue: <V extends string>(provider: ConfigValueProvider<V>) => Promise<V>;

package/dist/esm/config/resolveConfigValue.js

@@ -0,0 +1,8 @@
+/*
+ * resolves a config value into a string, to be used inside of things that are provided configurations
+ * */
+export const resolveConfigValue = async (provider) => {
+    return typeof provider === 'function'
+        ? await provider()
+        : provider;
+};

package/dist/esm/config.d.ts

@@ -0,0 +1,27 @@
+export declare type ConfigValue = string;
+export declare type Config = {
+    [key: string]: Config | ConfigValue;
+};
+export declare type ConfigValueProvider<V extends ConfigValue = ConfigValue> = (() => Promise<V> | V) | V;
+export declare type ConfigProvider = {
+    [key: string]: ConfigProvider | ConfigValueProvider;
+};
+export declare 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 declare type ConfigProviderForConfig<T> = T extends ConfigValue ? ConfigValueProvider<T> : T extends Config ? {
+    [key in keyof T]: ConfigProviderForConfig<T[key]>;
+} : never;
+export declare const resolveConfigValue: <V extends string>(provider: ConfigValueProvider<V>) => Promise<V>;
+export declare const ENV_BUILD_CONFIGS: string[];
+export declare const envConfig: (name: string, type?: 'build' | 'runtime', defaultValue?: string | undefined) => ConfigValueProvider<string>;
+export declare const stubConfig: <V extends string>(configValue: V) => ConfigValueProvider<V>;
+export declare const replaceConfig: (base: ConfigValueProvider<string>, replacements: {
+    [token: string]: ConfigValueProvider<string>;
+}) => ConfigValueProvider<string>;
+export declare const awsAccountConfig: <C extends string>(config: {
+    sandbox: ConfigValueProvider<C>;
+    production: ConfigValueProvider<C>;
+}) => ConfigValueProvider<C>;
+export declare const awsParameterConfig: (parameterName: ConfigValueProvider<string>) => ConfigValueProvider<string>;
+export declare const lambdaParameterConfig: (parameterName: ConfigValueProvider<string>) => ConfigValueProvider<string>;

package/dist/esm/config.js

@@ -0,0 +1,127 @@
+import { GetParameterCommand } from '@aws-sdk/client-ssm';
+import { GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import fetch from 'node-fetch';
+import { assertDefined } from './assertions';
+import { securityTokenService } from './aws/securityTokenService';
+import { ssmService } from './aws/ssmService';
+import { ifDefined } from './guards';
+/*
+ * resolves a config value into a string, to be used inside of things that are provided configurations
+ * */
+export const resolveConfigValue = async (provider) => {
+    return typeof provider === 'function'
+        ? await provider()
+        : provider;
+};
+/*
+ * ===========
+ * re-usable config providers
+ * ===========
+ * */
+/*
+ * uses a config from the process environment.
+ *
+ * there are two modes for this, by default it expects the value to be provided at build time,
+ * and there is access built in here for webpack to provide the configs. if you pass `runtime`
+ * as the second argument it skips the build logic and will try to literally pull it from
+ * `process.env` when the config is used at runtime
+ *
+ * the value is read from the environment when something tries to use it, not when `envConfig` is called.
+ *
+ * eg:
+ *   const config = {
+ *     configValue: envConfig('environment_variable_name'),
+ *   };
+ * */
+export const ENV_BUILD_CONFIGS = [];
+export const envConfig = (name, type = 'build', defaultValue) => {
+    if (type === 'build') {
+        ENV_BUILD_CONFIGS.push(name);
+    }
+    return () => {
+        /*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
+        const envs = { ...process.env, ...(typeof __PROCESS_ENV !== 'undefined' ? __PROCESS_ENV : {}) };
+        return assertDefined(ifDefined(envs[name], defaultValue), `expected to find environment variable with name: ${name}`);
+    };
+};
+/*
+ * 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
+ *
+ * eg:
+ *   const config = {
+ *     configValue: stubConfig('just-a-string'),
+ *   };
+ * */
+export const stubConfig = (configValue) => configValue;
+export const replaceConfig = (base, replacements) => {
+    return async () => {
+        const resolved = await Promise.all(Object.entries(replacements)
+            .map(async ([token, replacement]) => [token, await resolveConfigValue(replacement)]));
+        return resolved.reduce((result, [token, replacement]) => result.replace(token, replacement), await resolveConfigValue(base));
+    };
+};
+/*
+ * uses a different given value depending on which aws account the code is deployed in.
+ * this resolves the given value recursively, so its composable with more configProviders in the
+ * conditional cases.
+ *
+ * eg:
+ *   const config = {
+ *     configValue: awsAccountConfig({sandbox: 'inTheSandboxConfig', production: 'inProductionConfig'}),
+ *     configValue: awsAccountConfig({sandbox: envConfig('an_environment_variable'), production: 'inProductionConfig'}),
+ *   };
+ * */
+export const awsAccountConfig = (config) => {
+    const production = envConfig('PRODUCTION_AWS');
+    const sandbox = envConfig('SANDBOX_AWS');
+    return async () => {
+        const identity = await securityTokenService().send(new GetCallerIdentityCommand({}));
+        switch (identity.Account) {
+            case await resolveConfigValue(sandbox):
+                return await resolveConfigValue(assertDefined(config.sandbox, 'a sandbox config was not provided'));
+            case await resolveConfigValue(production):
+                return await resolveConfigValue(assertDefined(config.production, 'a production config was not provided'));
+            default:
+                throw new Error('unknown aws account');
+        }
+    };
+};
+export const awsParameterConfig = (parameterName) => {
+    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}"`);
+    };
+};
+const lambdaExtensionUrl = 'http://localhost:2773';
+let lambdaExtensionReadyPromise;
+// NOTE: Can only be used during in AWS Lambda
+// The AWS Parameters and Secrets Lambda Extension Layer must be included in the Lambda function
+export const lambdaParameterConfig = (parameterName) => async () => {
+    const token = await resolveConfigValue(envConfig('AWS_SESSION_TOKEN', 'runtime'));
+    const name = await resolveConfigValue(parameterName);
+    if (!lambdaExtensionReadyPromise) {
+        // This request will return 400 Bad Request,
+        // but we only care that it'll block until the extension is ready
+        lambdaExtensionReadyPromise = fetch(lambdaExtensionUrl);
+    }
+    await lambdaExtensionReadyPromise;
+    const resp = await fetch(
+    // Port 2773 is the default port for the extension
+    `${lambdaExtensionUrl}/systemsmanager/parameters/get?name=${name}&withDecryption=true`, { headers: { 'X-Aws-Parameters-Secrets-Token': token } });
+    if (resp.ok) {
+        const response = await resp.json();
+        const parameter = assertDefined(response.Parameter, `aws GetParameter response missing Parameter key for ${name}"`);
+        return assertDefined(parameter.Value, `aws GetParameter response missing Parameter.Value key for ${name}"`);
+    }
+    else {
+        throw new Error(`HTTP Error Response ${resp.status} ${resp.statusText} while fetching parameter ${name}`);
+    }
+};

package/dist/esm/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class InvalidRequestError extends Error {
+    static readonly TYPE = "InvalidRequestError";
+    static matches: (e: any) => e is typeof InvalidRequestError;
+}
+export declare class UnauthorizedError extends Error {
+    static readonly TYPE = "UnauthorizedError";
+    static matches: (e: any) => e is typeof UnauthorizedError;
+}
+export declare class NotFoundError extends Error {
+    static readonly TYPE = "NotFoundError";
+    static matches: (e: any) => e is typeof NotFoundError;
+}

package/dist/esm/errors.js

@@ -0,0 +1,26 @@
+/*
+ * if code is split into multiple bundles, sometimes each bundle
+ * will get its own definition of this module and then instanceof checks
+ * are unreliable, this provides a way to reliably check the error types
+ *
+ * eg this will always work:
+ *   InvalidRequestError.matches(error);
+ *
+ * eg this might not work if you have code splitting:
+ *   error instanceof InvalidRequestError
+ *
+ */
+const errorIsType = ({ TYPE }) => (e) => e instanceof Error
+    && e.constructor.TYPE === TYPE;
+export class InvalidRequestError extends Error {
+}
+InvalidRequestError.TYPE = 'InvalidRequestError';
+InvalidRequestError.matches = errorIsType(InvalidRequestError);
+export class UnauthorizedError extends Error {
+}
+UnauthorizedError.TYPE = 'UnauthorizedError';
+UnauthorizedError.matches = errorIsType(UnauthorizedError);
+export class NotFoundError extends Error {
+}
+NotFoundError.TYPE = 'NotFoundError';
+NotFoundError.matches = errorIsType(NotFoundError);

package/dist/esm/fetch.d.ts

@@ -0,0 +1,64 @@
+import { METHOD } from './routing';
+export declare enum FetchStateType {
+    SUCCESS = "success",
+    ERROR = "error",
+    LOADING = "loading",
+    IDLE = "idle"
+}
+export declare type FetchState<D, E> = FetchStateLoading<D> | FetchStateError<D, E> | FetchStateSuccess<D> | FetchStateIdle;
+declare type FetchStateLoading<D> = {
+    type: FetchStateType.LOADING;
+    data?: D;
+};
+declare type FetchStateError<D, E> = {
+    type: FetchStateType.ERROR;
+    data?: D;
+    error: E;
+};
+declare type FetchStateSuccess<D> = {
+    type: FetchStateType.SUCCESS;
+    data: D;
+};
+declare type FetchStateIdle = {
+    type: FetchStateType.IDLE;
+};
+export declare const fetchLoading: <D, E>(previous?: FetchState<D, E> | undefined) => FetchStateLoading<D>;
+export declare const fetchError: <D, E>(error: E, previous?: FetchState<D, E> | undefined) => FetchStateError<D, E>;
+export declare const fetchSuccess: <D>(data: D) => FetchStateSuccess<D>;
+export declare const fetchIdle: () => FetchStateIdle;
+export declare const stateHasData: <D, E>(state: {
+    type: FetchStateType;
+    data?: D | undefined;
+    error?: E | undefined;
+}) => state is {
+    type: FetchStateType;
+    data: D;
+};
+export declare const stateHasError: <D, E>(state: {
+    type: FetchStateType;
+    data?: D | undefined;
+    error?: E | undefined;
+}) => state is {
+    type: FetchStateType;
+    error: E;
+};
+export declare type FetchConfig = {
+    credentials?: 'include' | 'omit' | 'same-origin';
+    method?: METHOD;
+    body?: string;
+    headers?: {
+        [key: string]: string;
+    };
+};
+declare type Headers = {
+    get: (name: string) => string | null;
+};
+export declare type Response = {
+    status: number;
+    headers: Headers;
+    json: () => Promise<any>;
+    text: () => Promise<string>;
+};
+export declare type GenericFetch<C extends FetchConfig = FetchConfig, R extends Response = Response> = (url: string, fetchConfig?: C) => Promise<R>;
+export declare type ConfigForFetch<F> = F extends GenericFetch<infer C, any> ? C : never;
+export {};

package/dist/esm/fetch.js

@@ -0,0 +1,46 @@
+/*
+ * these are just helpers for formatting responses, they don't actually do any loading. especially in UI development they
+ * help with continuity over loading, reloading, saving, and errors. this is pretty nice in typescript because you have to deal
+ * with the possibility that the result state is in a loading or error state. if you avoid dealing with those states you need
+ * to write very clear code to ignore them, which easily presents missing functionality like errors that are not being messaged
+ * to the user.
+ * */
+export var FetchStateType;
+(function (FetchStateType) {
+    FetchStateType["SUCCESS"] = "success";
+    FetchStateType["ERROR"] = "error";
+    FetchStateType["LOADING"] = "loading";
+    FetchStateType["IDLE"] = "idle";
+})(FetchStateType || (FetchStateType = {}));
+/*
+ * keeps existing data but sets the new status
+ *
+ * const state = fetchLoading(previousState)
+ * */
+export const fetchLoading = (previous) => ({ type: FetchStateType.LOADING, ...(previous && 'data' in previous ? { data: previous.data } : {}) });
+/*
+ * keeps existing data but sets the new status and error value
+ *
+ * const state = fetchError(error, previousState)
+ * */
+export const fetchError = (error, previous) => ({ ...previous, type: FetchStateType.ERROR, error });
+/*
+ * formats data with success type
+ *
+ * const state = fetchSuccess(newData)
+ * */
+export const fetchSuccess = (data) => ({ type: FetchStateType.SUCCESS, data });
+/*
+ * formats data with idle type
+ *
+ * const state = fetchIdle(newData)
+ * */
+export const fetchIdle = () => ({ type: FetchStateType.IDLE });
+/*
+ * guard for checking if the state has result data, it might be true for any state type.
+ * */
+export const stateHasData = (state) => 'data' in state;
+/*
+ * guard for checking if the state has an error, it might be true for error or loading states.
+ * */
+export const stateHasError = (state) => 'error' in state;

package/dist/esm/guards.d.ts

@@ -0,0 +1,6 @@
+export declare const isDefined: <X>(x: X) => x is Exclude<X, undefined>;
+export declare const isNumber: (x: any) => x is number;
+export declare const isPlainObject: (thing: any) => thing is {
+    [key: string]: any;
+};
+export declare const ifDefined: <X, D>(x: X, d: D) => D | Exclude<X, undefined>;

package/dist/esm/guards.js

@@ -0,0 +1,29 @@
+/*
+ * checks if a thing is defined. this is often easy to do with a simple if statement, but in certain
+ * situations the guard is required and its nice to have one pre-defined.
+ *
+ * eg this filters the array but doesn't fix the array type:
+ *   const result = (array as Array<string | undefined>).filter(thing => !!thing);
+ *
+ * eg this does the right thing:
+ *   const result = (array as Array<string | undefined>).filter(isDefined);
+ *
+ * eg because writing this is annoying:
+ *   const result = (array as Array<string | undefined>).filter(<X>(x: X): x is Exclude<X, undefined> => x !== undefined);
+ */
+export const isDefined = (x) => x !== undefined;
+export const isNumber = (x) => typeof x === 'number';
+/*
+ * a guard for plain old javascript objects that are not based on some other prototype,
+ * for example making them safe to JSON stringify and stuff
+ * */
+export const isPlainObject = (thing) => thing instanceof Object && thing.__proto__.constructor.name === 'Object';
+/*
+ * this isn't really a guard its just a way to provide a default value without creating a coverage branch.
+ *
+ * if the first thing is defined it uses it, otherwise it returns the second thing.
+ *
+ * eg:
+ *   const valueWithDefault = ifDefined(thing, 'default value')
+ */
+export const ifDefined = (x, d) => isDefined(x) ? x : d;

package/dist/esm/index.d.ts

@@ -0,0 +1,29 @@
+import { UnionToIntersection } from './types';
+export declare const getKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O) => O[K];
+export declare const getKeyValueOr: <K extends string, V, Od extends { [key in K]?: any; } = { [key_1 in K]?: any; }>(key: K, defaultValue: V) => <O extends Od extends undefined ? { [key_2 in K]?: any; } : Od>(obj: O) => V | NonNullable<O[K]>;
+export declare const putKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O, value: O[K]) => O;
+export declare const coerceArray: <T>(thing: T | T[] | undefined) => T[];
+declare type FlowFn<A, R> = (...args: [A]) => R;
+declare type AnyFlowFn = FlowFn<any, any>;
+declare type FlowFnResult<F, A> = F extends FlowFn<A, infer R> ? R : never;
+declare type FlowResult<C, A> = C extends [infer F1, ...infer Cr] ? F1 extends AnyFlowFn ? Cr extends never[] ? FlowFnResult<F1, A> : FlowResult<Cr, FlowFnResult<F1, A>> : never : never;
+declare type FlowChainArg<C> = C extends [infer F1, ...infer _] ? F1 extends FlowFn<infer A, any> ? A : never : never;
+export declare const flow: <C extends AnyFlowFn[]>(...chain: C) => (param: FlowChainArg<C>) => FlowResult<C, FlowChainArg<C>>;
+export declare const fnIf: <T1, T2>(condition: boolean, trueValue: T1, falseValue: T2) => T1 | T2;
+export declare const mapFind: <I, R>(array: I[], mapper: (item: I) => R, predicate?: (result: R) => boolean) => R | undefined;
+declare type HashValue = string | number | boolean | null | HashCompoundValue;
+declare type HashCompoundValue = Array<HashValue> | {
+    [key: string]: HashValue;
+};
+export declare const hashValue: (value: HashValue) => string;
+export declare const once: <F extends (...args: any[]) => any>(fn: F) => F;
+export declare const partitionSequence: <T, P>(getPartition: (thing: T, previous?: P | undefined) => {
+    matches?: boolean | undefined;
+    value: P;
+}, sequence: T[]) => [P, T[]][];
+export declare const memoize: <F extends (...args: any[]) => any>(fn: F) => F;
+export declare const roundToPrecision: (num: number, places: number) => number;
+export declare const getCommonProperties: <T1 extends {}, T2 extends {}>(thing1: T1, thing2: T2) => (keyof T1 & keyof T2)[];
+export declare const merge: <T extends {}[]>(...[thing1, ...tail]: T) => UnionToIntersection<T[number]>;
+export declare const tuple: <A extends any[]>(...args: A) => A;
+export {};