@openstax/ts-utils 1.34.0 → 1.35.0

package/README.md

@@ -1,90 +1,118 @@
-<!-- spell-checker: ignore creds lastsync -->
-## Project Template
+# @openstax/ts-utils
 
-SPA React frontend with a serverless lambda backend, supported by aws data stores. fullstack typescript.
+A collection of utilities typescript applications. browser and server support.
 
-features:
-- monorepo for frontend, lambda functions, deployment scripts
-- strong fullstack typescript support even across api calls
-- one command development server script
-- one command deployment script
-- production ready with error handling, logging, alerting
-- established paradigms for common issues like routing, middleware, pagination, configs, dependency injection, plug-able service drivers per environment
-- service providers for versioned document storage, file storage, document search, openstax accounts auth
-- 100% test coverage using jest in both frontend and lambda modules
-- CI checks for unit tests, spell checking, code linting, code coverage
+## Libraries
+overviews of the libraries provided and their purposes, for more specific information check out the comments in the source code.
 
-## Design Goals
+### [types.ts](./types.ts)
+utility types, no javascript functionality in here. A dumping ground for commonly used utility types or sorcery copied of stack overflow.
 
-### Easy and Full Featured
+### [guards.ts](./guards.ts)
+generic [type guards](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards). most of this isn't super interesting its just annoying to have to re-define these in every project.
 
-Setting up a new project or microservice using raw libraries or tools like SAM is pretty easy, but leaves a lot of problems unsolved. developers end up having to solve a lot of problems over and over again, or cutting corners. There are, surprisingly, not a lot of software frameworks designed to work in a serverless environment, so every time you need to figure out how do error logging, or routing. maybe there is a lot of copy/paste there once you've done it a few times, but not everyone has done it a few times, and its still a project if you have. Sometimes you think you can quickly bang out a service that does xyz, and it doesn't need any frills, but then it turns out it sure would have been nice to have a data store, or an admin interface, and it doesn't send any alerts when it has errors, and that takes the project into a whole new problem space.
+### [assertions.ts](./assertions.ts)
+like a guard but throws if the condition fails. you can use an assertion if you're extra sure that something is true but typescript isn't so sure, its possible that a bug might exist but normally your expected case should always be the case. these assertions allow you to have useful errors/messages for the exceptional bug, without generating conditional logic in your application code. this is almost entirely driven by not wanting to create code branches that will then need unit tests.
 
-This project aims to provide a baseline level of production-readiness, in addition to easily accessible prebuilt functionality for common problems.
+### [index.ts](./index.ts)
+basic array/object access/manipulation utilities
 
-### Cohesive
+### [errors.ts](./errors.ts)
+a set of common application errors for the other libraries to use
 
-A big problem in the javascript world is lack of cohesive systems. for any given problem there are a thousand npm modules that could help you, but given a set of problems, finding solutions that can work well together is a challenge.
+### [fetch.ts](./fetch.ts)
+utilities for working with `fetch` and fetching data. mostly there are constructors and guards for working with response objects that capture both a request status and associated data. the actual fetch api only throws if there is a connection errors, so most data access utilities need a way to communicate application layer failures back to the client in a discernible way. you can _almost_ do this with regular response objects, but then you're forcing all of the response processing down into user-land, and this system provides an additional loading state for UIs.
 
-This project aims to provide a full stack developer experience using similar tools and patterns across the project, and typescript support as strong as we can make it.
+### [config.ts](./config.ts)
+defines ConfigProvider as an arbitrarily nested object where leaves must be ConfigValueProviders. ConfigValueProviders are strings, promises of strings, functions without arguments that return strings, or promises of strings. the library has a utility to resolve a ConfigValueProvider to a string, and a few re-usable providers.
 
+### [middleware.ts](./middleware.ts)
+middleware are chains of functions, with shared access to a parent application or services, that modify or decorate a result. middleware chains are used to pre-process requests before they reach routing, post-process results after routing, and compose service providers for the routes to use.
 
-## Getting Started with the Project Template
+### [routing.ts](./routing.ts)
+a flexible routing library with utils for defining routes, matching requests to routes, and rendering urls for routes. strong typing for route params, request bodies, response bodies. reverse routing asserts not only that the correct route and params are given, but that the route is composed in the application. built to be implementation agnostic and support both browser SPA routing and server side API routing.
 
-### Set up your repo
-- clone this repo
-- delete packages/utils (it'll pull it from npm)
-- run `git rev-parse head > .lastsync` so that future updates can be patched in
-- reset the git history (delete .git and run `git init; git commit -am "initial commit"` again)
-- follow the [development](#development) instructions to start your local environment
+### [pagination.ts](./pagination.ts)
+utilities for interpreting pagination requests and generating pagination responses for both 'load more' and 'page number' style pagination. included middleware for working with the routing library.
 
-### Get into the Code
-- start checking out the api code from the [routes file](./packages/lambda/src/functions/serviceApi/versions/v0/example/routes.ts). this example provides basic entity data storage, there are lots of comments in there.
-- start checking out the frontend code from the [homepage](./packages/frontend/src/example/screens/Home.tsx), there are a few pages that integrate with the example api routes.
-- more info about the libraries and utils used in the [utils module](./packages/utils/README.md)
+## Services
+Services differ from the rest of the libraries in that they have a single discrete interface and support multiple implementations of that interface.
 
-### your first deployment
-- change the `APPLICATION` in [the deployment constants file](./deploy/constants.env). the first time you run the deployment it'll
-walk you through some one-time setup stuff. it'll output the deployed url when it finishes.
-- upload some secrets to the parameter store with `AccountsBase=SOMETHING CookieName=SOMETHING EncryptionPrivateKey=SOMETHING SignaturePublicKey=SOMETHING yarn ts-utils upload-params <environment-name>`.
-- (optional) set PagerDuty params with `yarn -s ts-utils upload-pager-duty-endpoints`
+### [apiGateway](./services/apiGateway/index.ts)
+dynamically generates an api client from route configuration. if you're using the routing library in the api, this allows you to import your route types directly into your client and have very strong typing on your api calls for free. includes error handling, filtering responses by status code, and narrowing the expected data type by given status code.
 
-## Development
+### [authProvider](./services/authProvider)
+integrates with openstax.org/accounts, includes several implementations for both browser and server side integrations.
 
-install [nvm](https://github.com/creationix/nvm#installation)
+### [lrsGateway](./services/lrsGateway/index.ts)
+handles authentication and payload formatting for interacting with the LRS
 
-```
+### [versionedDocumentStore](./services/versionedDocumentStore)
+a key/value document store with integrated audit logging. all writes are done as new versions of documents and version history can be fetched. includes implementations for dynamodb and local file system.
 
-# use the right version of node
-nvm install
+### [searchProvider](./services/searchProvider/index.ts)
+allows filtering and open text search for documents. has strong typing for filterable values based on the document type definition. interface is based on elasticsearch options, but currently we only have an in memory filtering implementation. works out of the box with versionedDocumentStore.
 
-# install yarn, skip if you have it already
-npm install -g yarn
+## Notes
 
-# install dependencies
-yarn install
+### Service drivers and configuration
+Service providers are defined in a little bit of a weird nested way, this is supposed to help separate driver specific and instance specific configurations, and let you swap drivers in different application entry points without too many application dependencies.
 
-# start
-#  run this from the project root, it builds the utils and lambda packages,
-#  sets up build watchers for them, and then starts the react app.
-#  changes in any package are built and visible in the app immediately.
-yarn start
-```
+an entry point is the file you point to when you build or run the application. the idea is that you make a different entry point files for different environments or contexts. so you have one for launching local development and one for launching an all-in-one stack on a testing server and another one for launching a production environment. in order to reduce environment specific issues you reduce your entry point to be as small as possible and just assemble the required bits for that environment to work. in the recommended setup, one of the main things the entry point does is choose which service provider drivers to use. there are two main benefits of using entry points, its more declarative than using downstream conditional logic with some kind of `driver: fs` flag in the config, and it allows bundled javascript to only include the dependencies relevant for the drivers that are being used in that build.
 
-### to fix scary untrusted cert warning in chrome
+the idea is that you may have some entities you're putting in a VersionedDocumentStore and maybe some others in a RelationalEntityStore but you're for sure not putting some versioned entities in dynamo and some in a local json file. so in your development environment entry point you provide your config for `versionedDocumentStore: fileSystemVersionedDocumentStore` and in the deployed environment entry point you put `versionedDocumentStore: dynamoVersionedDocumentStore`.
 
-*note:* you must do this for login to work
+there are two levels the drivers are configured at, one is the driver level and the other is the instance level. for the VersionedDocumentStore the fileSystem driver takes a path to the directory to store the files in. the instance level may vary based on the usage of that driver, for example if you're storing 4 different entities in VersionedDocumentStores, you need to provide different table names to the driver to configure each store to create separate instances of that store. it just happens that for VersionedDocumentStore the fileSystem and dynamo implementations use the same instance config, this isn't always the case. once you get into your application logic you won't know which entry point was used to bootstrap your application, so you'll just know the driver is _one of_ the possible versions, typescript will recognize this and throw an error unless you provide a config that would work for any of the possible drivers. in order to make this more legible (and separate key collisions), most of the services can be set up in the entry point with a config prefix, so when you get into application-land it looks more like you're providing two discrete configs.
 
-#### trust the certificate
-- run `./packages/frontend/script/trust-localhost.bash` after starting the server
+for example:
 
-## Deployment
+```typescript
+// entry/anEntryPoint.ts
+export const lambdaServices = {
+  // in this entry we provide the dynamo driver
+  versionedDocumentStore: dynamoVersionedDocumentStore({configSpace: 'dynamodb'}),
+};
 
-dependencies: aws-sdk, jq
+// entry/anotherEntryPoint.ts
+export const localServices = {
+  // in this entry we provide the fileSystem driver, it has a different config prefix
+  versionedDocumentStore: fileSystemVersionedDocumentStore({dataDir, configSpace: 'fileSystem'}),
+};
 
-```
-# if you don't have https://github.com/openstax/ox-bin set up you can call this directly from
-# your local https://github.com/openstax/aws-access/blob/main/scripts/set_aws_creds
-. ox set_aws_creds -i assume-role -r sandbox:full-admin
-yarn -s ts-utils deploy my-cool-environment
+// core/types.ts
+
+// there is other wiring up that happens with the app services on the request responder, if
+// you made a new entrypoint and tried to use a different format of services without registering it
+// here it would yell at you.
+export type AppServices = LambdaServices | LocalServices;
+
+// myCoolDocumentStoreMiddleware.ts
+
+// this config satisfies both config drivers with separate sections for each one.
+// the envConfig is defined here, but it wouldn't try to actually resolve that value
+// unless it was being used.
+const config = {
+  fileSystem: {
+    tableName: 'coolDocument'
+  },
+  dynamodb: {
+    tableName: envConfig('TestDocumentTableName', 'runtime'),
+  }
+};
+
+export const myCoolDocumentStoreMiddleware = <M extends {}>(app: AppServices) => {
+  // providing the document interface and the config prepares the driver to work for this entity in particular.
+  // the extra function call in this line is to work around some typescript quirkiness with generic type inference.
+  // this line is only run once when the app is wired up, doing this call here allows the driver to do internal memory caching
+  // if it wants to.
+  const makeCoolDocumentStore = app.versionedDocumentStore<CoolDocument>()(config);
+
+  return (middleware: M) => ({
+    ...middleware,
+    // this part is run for every api request processed. in this case there it could have been combined with the call above,
+    // but most of the time you'll want to pull in the authProvider and hook up automatic audit logging, and that will be different on 
+    // each request. look at the VersionedDocumentStore documentation for details.
+    coolDocumentStore: makeCoolDocumentStore('id'),
+  })
+};
 ```

package/dist/cjs/assertions/index.d.ts

@@ -0,0 +1,89 @@
+export type AssertionFailed = string | Error | (() => never) | undefined;
+export declare const doThrow: (failed: AssertionFailed) => never;
+/**
+ * Asserts that the given value is true.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyTrue = assertTrue(randomThing, new Error('thing was not true'));
+ * @returns the value that was asserted
+ */
+export declare const assertTrue: <X>(x: X, failed?: AssertionFailed) => X & true;
+/**
+ * Asserts that the given value is false.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyFalse = assertFalse(randomThing, new Error('thing was not false'));
+ * @returns the value that was asserted
+ */
+export declare const assertFalse: <X>(x: X, failed?: AssertionFailed) => X & false;
+/**
+ * Asserts that the given value is defined.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyDefined = assertDefined(randomThing, new Error('thing was undefined'));
+ * @returns the value that was asserted, with a type that excludes undefined
+ */
+export declare const assertDefined: <X>(x: X, failed?: AssertionFailed) => Exclude<X, undefined>;
+/**
+ * Asserts that the given value is a string.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyAString = assertString(randomThing, new Error('thing is not a string'));
+ * @returns the value that was asserted
+ */
+export declare const assertString: <X>(x: X, failed?: AssertionFailed) => string;
+/**
+ * Asserts that the given value is not `NaN`. Does not assert that the value is a number.
+ *
+ * @param thing The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyNotNotANumber = assertNotNaN(randomThing, new Error('thing was NaN'));
+ * @returns the value that was asserted
+ */
+export declare const assertNotNaN: <T>(thing: T, failed?: AssertionFailed) => T;
+/**
+ * @deprecated use assertNotNaN instead
+ */
+export declare const notNaN: <T>(thing: T, failed?: AssertionFailed) => T;
+/**
+ * Asserts that the first argument is an instance of the second.
+ *
+ * @param thing The value to assert.
+ * @param constructable The class to check against.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelySyntaxError = assertInstanceOf(error, SyntaxError, new Error('argument was not a SyntaxError'));
+ * @returns the value that was asserted
+ */
+export declare const assertInstanceOf: <T>(thing: any, constructable: Function & {
+    new (...args: any[]): T;
+}, failed?: AssertionFailed) => T;
+/**
+ * Asserts that the error in the first argument is an instance of the error given as the
+ * second argument
+ *
+ * @param thing The value to assert.
+ * @param constructable The error class to check against.
+ * @example const definitelySyntaxError = assertInstanceOf(error, SyntaxError);
+ * @returns the value that was asserted
+ * @throws the original error if the check fails
+ * @see assertInstanceOf
+ */
+export declare const assertErrorInstanceOf: <T extends Error>(thing: unknown, constructable: Function & {
+    new (...args: any[]): T;
+}) => T;

package/dist/cjs/assertions/index.js

@@ -0,0 +1,157 @@
+"use strict";
+/*
+ * all of these assertions take either a string, throw function, or nothing
+ * for the second argument. its STRONGLY encouraged to provide some error
+ * or message that explains the reason for the assertion
+ *
+ * eg:
+ *   assertDefined(user, new UnauthorizedException())
+ *   assertDefined(thing.otherThing, 'otherThing should be guaranteed to exist, but is missing')
+ *
+ * passing an Error instead of a string makes the first element of the resulting
+ * stack trace more useful, and allows you to use specific error types
+ * that might be handled differently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertErrorInstanceOf = exports.assertInstanceOf = exports.notNaN = exports.assertNotNaN = exports.assertString = exports.assertDefined = exports.assertFalse = exports.assertTrue = exports.doThrow = void 0;
+const doThrow = (failed) => {
+    if (typeof failed === 'string') {
+        throw new Error(failed);
+    }
+    if (failed instanceof Error) {
+        throw failed;
+    }
+    if (!failed) {
+        throw new Error();
+    }
+    return failed();
+};
+exports.doThrow = doThrow;
+/**
+ * Asserts that the given value is true.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyTrue = assertTrue(randomThing, new Error('thing was not true'));
+ * @returns the value that was asserted
+ */
+const assertTrue = (x, failed) => {
+    if (typeof x !== 'boolean' || x !== true) {
+        return (0, exports.doThrow)(failed);
+    }
+    return x;
+};
+exports.assertTrue = assertTrue;
+/**
+ * Asserts that the given value is false.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyFalse = assertFalse(randomThing, new Error('thing was not false'));
+ * @returns the value that was asserted
+ */
+const assertFalse = (x, failed) => {
+    if (typeof x !== 'boolean' || x !== false) {
+        return (0, exports.doThrow)(failed);
+    }
+    return x;
+};
+exports.assertFalse = assertFalse;
+/**
+ * Asserts that the given value is defined.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyDefined = assertDefined(randomThing, new Error('thing was undefined'));
+ * @returns the value that was asserted, with a type that excludes undefined
+ */
+const assertDefined = (x, failed) => {
+    if (x === undefined) {
+        return (0, exports.doThrow)(failed);
+    }
+    return x;
+};
+exports.assertDefined = assertDefined;
+/**
+ * Asserts that the given value is a string.
+ *
+ * @param x The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyAString = assertString(randomThing, new Error('thing is not a string'));
+ * @returns the value that was asserted
+ */
+const assertString = (x, failed) => {
+    if (typeof x !== 'string') {
+        return (0, exports.doThrow)(failed);
+    }
+    return x;
+};
+exports.assertString = assertString;
+/**
+ * Asserts that the given value is not `NaN`. Does not assert that the value is a number.
+ *
+ * @param thing The value to assert.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelyNotNotANumber = assertNotNaN(randomThing, new Error('thing was NaN'));
+ * @returns the value that was asserted
+ */
+const assertNotNaN = (thing, failed) => {
+    if (typeof thing === 'number' && isNaN(thing)) {
+        return (0, exports.doThrow)(failed);
+    }
+    return thing;
+};
+exports.assertNotNaN = assertNotNaN;
+/**
+ * @deprecated use assertNotNaN instead
+ */
+exports.notNaN = exports.assertNotNaN;
+/**
+ * Asserts that the first argument is an instance of the second.
+ *
+ * @param thing The value to assert.
+ * @param constructable The class to check against.
+ * @param failed The error to throw if the assertion fails. It is STRONGLY encouraged
+ *  to provide some value for this for traceability. Passing an Error instead of a string
+ *  makes the stack trace more useful and allows you to handle assertion failures differently.
+ * @example const definitelySyntaxError = assertInstanceOf(error, SyntaxError, new Error('argument was not a SyntaxError'));
+ * @returns the value that was asserted
+ */
+const assertInstanceOf = (thing, constructable, failed) => {
+    if (thing instanceof constructable) {
+        return thing;
+    }
+    return (0, exports.doThrow)(failed);
+};
+exports.assertInstanceOf = assertInstanceOf;
+/**
+ * Asserts that the error in the first argument is an instance of the error given as the
+ * second argument
+ *
+ * @param thing The value to assert.
+ * @param constructable The error class to check against.
+ * @example const definitelySyntaxError = assertInstanceOf(error, SyntaxError);
+ * @returns the value that was asserted
+ * @throws the original error if the check fails
+ * @see assertInstanceOf
+ */
+const assertErrorInstanceOf = (thing, constructable) => {
+    if (thing instanceof Error) {
+        return (0, exports.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}"`);
+    }
+};
+exports.assertErrorInstanceOf = assertErrorInstanceOf;

package/dist/cjs/aws/ssmService.d.ts

@@ -0,0 +1,5 @@
+import { SSM } from '@aws-sdk/client-ssm';
+/**
+ * A memoized instance of the AWS SSM client.
+ */
+export declare const ssmService: () => SSM;

package/dist/cjs/aws/ssmService.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ssmService = void 0;
+const client_ssm_1 = require("@aws-sdk/client-ssm");
+const __1 = require("..");
+/**
+ * A memoized instance of the AWS SSM client.
+ */
+exports.ssmService = (0, __1.once)(() => new client_ssm_1.SSM({ apiVersion: '2012-08-10' }));

package/dist/cjs/config/awsParameterConfig.d.ts

@@ -0,0 +1,10 @@
+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 declare const awsParameterConfig: (parameterName: ConfigValueProvider<string>) => ConfigValueProvider<string>;

package/dist/cjs/config/awsParameterConfig.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.awsParameterConfig = void 0;
+const client_ssm_1 = require("@aws-sdk/client-ssm");
+const assertions_1 = require("../assertions");
+const ssmService_1 = require("../aws/ssmService");
+const resolveConfigValue_1 = require("./resolveConfigValue");
+/**
+ * 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
+ */
+const awsParameterConfig = (parameterName) => {
+    return async () => {
+        const command = new client_ssm_1.GetParameterCommand({ Name: await (0, resolveConfigValue_1.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 (0, ssmService_1.ssmService)().send(command);
+        const parameter = (0, assertions_1.assertDefined)(response.Parameter, `aws GetParameter response missing Parameter key for ${parameterName}"`);
+        return (0, assertions_1.assertDefined)(parameter.Value, `aws GetParameter response missing Parameter.Value key for ${parameterName}"`);
+    };
+};
+exports.awsParameterConfig = awsParameterConfig;

package/dist/cjs/config/envConfig.d.ts

@@ -0,0 +1,24 @@
+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 declare 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 declare const envConfig: (name: string, type?: "build" | "runtime", defaultValue?: ConfigValueProvider<string>) => ConfigValueProvider<string>;

package/dist/cjs/config/envConfig.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envConfig = exports.ENV_BUILD_CONFIGS = void 0;
+const resolveConfigValue_1 = require("./resolveConfigValue");
+/**
+ * A list of environment variables that were requested at build time. Used by webpack to
+ * capture build-time environment variables values.
+ */
+exports.ENV_BUILD_CONFIGS = [];
+/**
+ * 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') };
+ */
+const envConfig = (name, type, defaultValue) => {
+    // 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 !== null && type !== void 0 ? type : (type = 'build');
+    if (type === 'build') {
+        exports.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
+        // also, spread operator not supported in cloudfront functions
+        const envs = 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 (0, resolveConfigValue_1.resolveConfigValue)(defaultValue);
+            }
+        }
+        else {
+            return value;
+        }
+    };
+};
+exports.envConfig = envConfig;

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

@@ -2,62 +2,46 @@
  * 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 const stubConfig = <V extends ConfigValue>(configValue: V): ConfigValueProvider<V> => configValue;
-
+export declare const stubConfig: <V extends ConfigValue>(configValue: V) => ConfigValueProvider<V>;
 export * from './envConfig';
 export * from './replaceConfig';
 export * from './awsParameterConfig';