@openstax/ts-utils 1.21.11 → 1.23.0

package/dist/cjs/errors/index.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionExpiredError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.ValidationError = exports.InvalidRequestError = exports.isAppError = void 0;
+/*
+ * 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 = (t) => (e) => e instanceof Error
+    && e.constructor.TYPE === t.TYPE;
+/**
+ * Returns true if the error is defined in this library
+ */
+const isAppError = (e) => e instanceof Error
+    && typeof e.constructor.TYPE === 'string';
+exports.isAppError = isAppError;
+/**
+ * Invalid request error
+ *
+ * `InvalidRequestError.matches(error)` is a reliable way to check if an error is an
+ * `InvalidRequestError`; `instanceof` checks may not work if code is split into multiple bundles
+ */
+class InvalidRequestError extends Error {
+    constructor(message) {
+        super(message || InvalidRequestError.TYPE);
+    }
+}
+exports.InvalidRequestError = InvalidRequestError;
+InvalidRequestError.TYPE = 'InvalidRequestError';
+InvalidRequestError.matches = errorIsType(InvalidRequestError);
+/**
+ * Validation Error
+ *
+ * `ValidationError.matches(error)` is a reliable way to check if an error is an
+ * `ValidationError`; `instanceof` checks may not work if code is split into multiple bundles
+ */
+class ValidationError extends Error {
+    constructor(data) {
+        super(InvalidRequestError.TYPE);
+        this.data = data;
+    }
+    getData() { return this.data; }
+}
+exports.ValidationError = ValidationError;
+ValidationError.TYPE = 'ValidationError';
+ValidationError.matches = errorIsType(ValidationError);
+/**
+ * Unauthorized error
+ *
+ * `UnauthorizedError.matches(error)` is a reliable way to check if an error is an
+ * `UnauthorizedError`; `instanceof` checks may not work if code is split into multiple bundles
+ */
+class UnauthorizedError extends Error {
+    constructor(message) {
+        super(message || UnauthorizedError.TYPE);
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;
+UnauthorizedError.TYPE = 'UnauthorizedError';
+UnauthorizedError.matches = errorIsType(UnauthorizedError);
+/**
+ * Forbidden error
+ *
+ * `ForbiddenError.matches(error)` is a reliable way to check if an error is a
+ * `ForbiddenError`; `instanceof` checks may not work if code is split into multiple bundles
+ */
+class ForbiddenError extends Error {
+    constructor(message) {
+        super(message || ForbiddenError.TYPE);
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+ForbiddenError.TYPE = 'ForbiddenError';
+ForbiddenError.matches = errorIsType(ForbiddenError);
+/**
+ * Not found error
+ *
+ * `NotFoundError.matches(error)` is a reliable way to check if an error is a
+ * `NotFoundError`; `instanceof` checks may not work if code is split into multiple bundles
+ */
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message || NotFoundError.TYPE);
+    }
+}
+exports.NotFoundError = NotFoundError;
+NotFoundError.TYPE = 'NotFoundError';
+NotFoundError.matches = errorIsType(NotFoundError);
+/**
+ * Session expired error
+ *
+ * `SessionExpiredError.matches(error)` is a reliable way to check if an error is a
+ * `SessionExpiredError`; `instanceof` checks may not work if code is split into multiple bundles
+ */
+class SessionExpiredError extends Error {
+    constructor(message) {
+        super(message || SessionExpiredError.TYPE);
+    }
+}
+exports.SessionExpiredError = SessionExpiredError;
+SessionExpiredError.TYPE = 'SessionExpiredError';
+SessionExpiredError.matches = errorIsType(SessionExpiredError);

package/dist/cjs/fetch/fetchStatusRetry.d.ts

@@ -0,0 +1,7 @@
+import { RetryOptions } from '../misc/helpers';
+import { GenericFetch } from '.';
+interface Options extends RetryOptions {
+    status?: number[];
+}
+export declare const fetchStatusRetry: (base: GenericFetch, options: Options) => GenericFetch;
+export {};

package/dist/cjs/fetch/fetchStatusRetry.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchStatusRetry = void 0;
+const helpers_1 = require("../misc/helpers");
+const fetchStatusRetry = (base, options) => {
+    return (...params) => (0, helpers_1.retryWithDelay)(() => base(...params).then(r => {
+        var _a;
+        if ((_a = options.status) === null || _a === void 0 ? void 0 : _a.includes(r.status)) {
+            return r.text().then(text => {
+                throw new Error(`fetch failed ${params[0]} -- ${r.status}: ${text}`);
+            });
+        }
+        return r;
+    }), options);
+};
+exports.fetchStatusRetry = fetchStatusRetry;

package/dist/cjs/fetch/index.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/cjs/fetch/index.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stateHasError = exports.stateHasData = exports.fetchIdle = exports.fetchSuccess = exports.fetchError = exports.fetchLoading = exports.FetchStateType = void 0;
+/*
+ * 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.
+ * */
+var FetchStateType;
+(function (FetchStateType) {
+    FetchStateType["SUCCESS"] = "success";
+    FetchStateType["ERROR"] = "error";
+    FetchStateType["LOADING"] = "loading";
+    FetchStateType["IDLE"] = "idle";
+})(FetchStateType = exports.FetchStateType || (exports.FetchStateType = {}));
+/*
+ * keeps existing data but sets the new status
+ *
+ * const state = fetchLoading(previousState)
+ * */
+const fetchLoading = (previous) => ({ type: FetchStateType.LOADING, ...(previous && 'data' in previous ? { data: previous.data } : {}) });
+exports.fetchLoading = fetchLoading;
+/*
+ * keeps existing data but sets the new status and error value
+ *
+ * const state = fetchError(error, previousState)
+ * */
+const fetchError = (error, previous) => ({ ...previous, type: FetchStateType.ERROR, error });
+exports.fetchError = fetchError;
+/*
+ * formats data with success type
+ *
+ * const state = fetchSuccess(newData)
+ * */
+const fetchSuccess = (data) => ({ type: FetchStateType.SUCCESS, data });
+exports.fetchSuccess = fetchSuccess;
+/*
+ * formats data with idle type
+ *
+ * const state = fetchIdle(newData)
+ * */
+const fetchIdle = () => ({ type: FetchStateType.IDLE });
+exports.fetchIdle = fetchIdle;
+/*
+ * guard for checking if the state has result data, it might be true for any state type.
+ * */
+const stateHasData = (state) => 'data' in state;
+exports.stateHasData = stateHasData;
+/*
+ * guard for checking if the state has an error, it might be true for error or loading states.
+ * */
+const stateHasError = (state) => 'error' in state;
+exports.stateHasError = stateHasError;

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

@@ -0,0 +1,30 @@
+/**
+ * checks if a thing is defined. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<string>`.
+ *
+ * `const result = (array as Array<string | undefined>).filter(isDefined);`
+ */
+export declare const isDefined: <X>(x: X) => x is Exclude<X, undefined>;
+/**
+ * checks if a thing is a number. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<number>`.
+ *
+ * `const result = (array as Array<number | undefined>).filter(isNumber);`
+ */
+export declare const isNumber: (x: any) => x is 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 declare const isPlainObject: (thing: any) => thing is {
+    [key: string]: any;
+};
+/**
+ * if the first thing is defined it uses it, otherwise it returns the second thing. this isn't
+ * really a guard its just a way to provide a default value without creating a coverage branch.
+ *
+ * @example const valueWithDefault = ifDefined(thing, 'default value')
+ */
+export declare const ifDefined: <X, D>(x: X, d: D) => D | Exclude<X, undefined>;

package/dist/cjs/guards/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ifDefined = exports.isPlainObject = exports.isNumber = exports.isDefined = void 0;
+/**
+ * checks if a thing is defined. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<string>`.
+ *
+ * `const result = (array as Array<string | undefined>).filter(isDefined);`
+ */
+const isDefined = (x) => x !== undefined;
+exports.isDefined = isDefined;
+/**
+ * checks if a thing is a number. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<number>`.
+ *
+ * `const result = (array as Array<number | undefined>).filter(isNumber);`
+ */
+const isNumber = (x) => typeof x === 'number';
+exports.isNumber = isNumber;
+/**
+ * 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
+ */
+const isPlainObject = (thing) => thing instanceof Object && thing.__proto__.constructor.name === 'Object';
+exports.isPlainObject = isPlainObject;
+/**
+ * if the first thing is defined it uses it, otherwise it returns the second thing. this isn't
+ * really a guard its just a way to provide a default value without creating a coverage branch.
+ *
+ * @example const valueWithDefault = ifDefined(thing, 'default value')
+ */
+const ifDefined = (x, d) => (0, exports.isDefined)(x) ? x : d;
+exports.ifDefined = ifDefined;

package/dist/cjs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './misc/partitionSequence';
+export * from './misc/helpers';
+export * from './misc/merge';
+export * from './misc/hashValue';

package/dist/cjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./misc/partitionSequence"), exports);
+__exportStar(require("./misc/helpers"), exports);
+__exportStar(require("./misc/merge"), exports);
+__exportStar(require("./misc/hashValue"), exports);

package/dist/cjs/middleware/apiErrorHandler.d.ts

@@ -0,0 +1,24 @@
+import { ForbiddenError, InvalidRequestError, NotFoundError, SessionExpiredError, UnauthorizedError, ValidationError } from '../errors';
+import type { ApiResponse } from '../routing';
+import type { Logger } from '../services/logger';
+export declare type DefaultErrors = {
+    InvalidRequestError: InvalidRequestError;
+    UnauthorizedError: UnauthorizedError;
+    ForbiddenError: ForbiddenError;
+    NotFoundError: NotFoundError;
+    ValidationError: ValidationError;
+    SessionExpiredError: SessionExpiredError;
+};
+export declare type Handlers<E> = {
+    [T in keyof E]: (e: E[T], logger: Logger) => ApiResponse<number, any>;
+};
+export declare const defaultHandlers: Handlers<DefaultErrors>;
+/**
+ * Creates an error handler. Provides default handlers for `UnauthorizedError`,
+ * `SessionExpiredError`, `NotFoundError`, and `InvalidRequestError`. User-specified
+ * handlers can be added to these. If no handler is found, the error is logged and
+ * a 500 text response is returned.
+ *
+ * @param inputHandlers a map of errors to handler functions
+ */
+export declare const createErrorHandler: <Errors = DefaultErrors>(inputHandlers?: Handlers<Errors> | undefined) => (e: Error, logger: Logger) => Promise<ApiResponse<number, any>>;

package/dist/cjs/middleware/apiErrorHandler.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createErrorHandler = exports.defaultHandlers = void 0;
+const errors_1 = require("../errors");
+const routing_1 = require("../routing");
+const logger_1 = require("../services/logger");
+exports.defaultHandlers = {
+    InvalidRequestError: (e) => (0, routing_1.apiTextResponse)(400, `400 ${e.message}`),
+    UnauthorizedError: (e) => (0, routing_1.apiTextResponse)(401, `401 ${e.message}`),
+    ForbiddenError: (e) => (0, routing_1.apiTextResponse)(403, `403 ${e.message}`),
+    NotFoundError: (e) => (0, routing_1.apiTextResponse)(404, `404 ${e.message}`),
+    ValidationError: (e) => (0, routing_1.apiJsonResponse)(422, e.getData()),
+    SessionExpiredError: (e) => (0, routing_1.apiTextResponse)(440, `440 ${e.message}`),
+};
+/**
+ * Creates an error handler. Provides default handlers for `UnauthorizedError`,
+ * `SessionExpiredError`, `NotFoundError`, and `InvalidRequestError`. User-specified
+ * handlers can be added to these. If no handler is found, the error is logged and
+ * a 500 text response is returned.
+ *
+ * @param inputHandlers a map of errors to handler functions
+ */
+const createErrorHandler = (inputHandlers) => {
+    const handlers = { ...exports.defaultHandlers, ...inputHandlers };
+    return async (e, logger) => {
+        const name = (0, errors_1.isAppError)(e) ? e.constructor.TYPE : e.constructor.name;
+        const handler = handlers[name];
+        if (handler) {
+            // convincing typescript that this error is the right kind for the handler
+            // we looked up based on the errors name is very annoying
+            return handler(e, logger);
+        }
+        logger.logEvent(logger_1.Level.Error, {
+            name: e.name,
+            message: e.message,
+            stack: e.stack,
+        });
+        return (0, routing_1.apiTextResponse)(500, '500 Error');
+    };
+};
+exports.createErrorHandler = createErrorHandler;

package/dist/cjs/middleware/apiSlowResponseMiddleware.d.ts

@@ -0,0 +1,23 @@
+import type { ConfigProviderForConfig } from '../config';
+import type { ApiResponse } from '../routing';
+import type { Logger } from '../services/logger';
+declare type Config = {
+    logResponseSlowerThan: string;
+    timeoutResponseAfter: string;
+};
+/**
+ * Creates response middleware that logs slow responses and times out responses that take too long. lambda functions have a timeout setting, but when a lambda times out there is no way to log anything helpful before it exists. this middleware allows the logger context to show up for timeout requests. just make sure that the `timeoutResponseAfter` is set to something slightly shorter than the lambda timeout so that it has time to run.
+ *
+ * @param config
+ * @param config.logResponseSlowerThan the config that specifies the threshold for a slow response
+ * @param config.timeoutResponseAfter the config that specifies the timeout for a response
+ * @example
+ * createSlowResponseMiddleware({
+ *   logResponseSlowerThan: envConfig('LOG_SLOW_RESPONSE', 'runtime', '1000'),
+ *   timeoutResponseAfter: envConfig('RESPONSE_TIMEOUT', 'runtime', '28000'),
+ * });
+ */
+export declare const createSlowResponseMiddleware: (config: ConfigProviderForConfig<Config>) => () => (response: Promise<ApiResponse<number, any>> | undefined, { logger }: {
+    logger: Logger;
+}) => Promise<ApiResponse<number, string>> | undefined;
+export {};

package/dist/cjs/middleware/apiSlowResponseMiddleware.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSlowResponseMiddleware = void 0;
+const resolveConfigValue_1 = require("../config/resolveConfigValue");
+const helpers_1 = require("../misc/helpers");
+const routing_1 = require("../routing");
+const logger_1 = require("../services/logger");
+/**
+ * Creates response middleware that logs slow responses and times out responses that take too long. lambda functions have a timeout setting, but when a lambda times out there is no way to log anything helpful before it exists. this middleware allows the logger context to show up for timeout requests. just make sure that the `timeoutResponseAfter` is set to something slightly shorter than the lambda timeout so that it has time to run.
+ *
+ * @param config
+ * @param config.logResponseSlowerThan the config that specifies the threshold for a slow response
+ * @param config.timeoutResponseAfter the config that specifies the timeout for a response
+ * @example
+ * createSlowResponseMiddleware({
+ *   logResponseSlowerThan: envConfig('LOG_SLOW_RESPONSE', 'runtime', '1000'),
+ *   timeoutResponseAfter: envConfig('RESPONSE_TIMEOUT', 'runtime', '28000'),
+ * });
+ */
+const createSlowResponseMiddleware = (config) => {
+    const getSlowThreshold = (0, helpers_1.once)(() => (0, resolveConfigValue_1.resolveConfigValue)(config.logResponseSlowerThan).then(result => parseInt(result, 10)));
+    const getTimeoutAfter = (0, helpers_1.once)(() => (0, resolveConfigValue_1.resolveConfigValue)(config.timeoutResponseAfter).then(result => parseInt(result, 10)));
+    return () => (response, { logger }) => {
+        const start = Date.now();
+        if (!response) {
+            return response;
+        }
+        return Promise.all([getSlowThreshold(), getTimeoutAfter()]).then(([slowThreshold, timeoutAfter]) => {
+            let timeout = undefined;
+            const timeoutPromise = isNaN(timeoutAfter)
+                ? undefined
+                : new Promise(resolve => timeout = setTimeout(() => {
+                    logger.logEvent(logger_1.Level.Error, {
+                        message: 'request processing timed out',
+                    });
+                    resolve((0, routing_1.apiTextResponse)(504, '504 Gateway Timeout'));
+                }, timeoutAfter));
+            const requestPromise = response.finally(() => {
+                const time = Date.now() - start;
+                if (timeout !== undefined) {
+                    clearTimeout(timeout);
+                }
+                if (time > slowThreshold) {
+                    logger.logEvent(logger_1.Level.Warn, {
+                        message: 'slow response',
+                        time,
+                    });
+                }
+            });
+            return timeoutPromise ? Promise.race([timeoutPromise, requestPromise]) : requestPromise;
+        });
+    };
+};
+exports.createSlowResponseMiddleware = createSlowResponseMiddleware;

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

@@ -0,0 +1,47 @@
+import { TupleZip } from '../types';
+export declare type MiddlewareProvider<Sa, M, A extends any[], R> = (app: Sa, appBinder?: ((app: Sa, provider: MiddlewareProvider<Sa, M, A, R>) => (middleware: M, ...args: A) => R)) => (middleware: M, ...args: A) => R;
+export declare type MiddlewareTransformProvider<Sa, M, A extends any[], R> = (app: Sa) => (middleware: M, ...args: A) => Omit<M, keyof R> & R;
+export declare type MiddlewareInput<S> = S extends MiddlewareProvider<any, infer M, any, any> ? M : never;
+export declare type ServiceMiddlewareProviderResult<M, S> = [M] extends [never] ? never : [M] extends [MiddlewareInput<S>] ? S extends MiddlewareTransformProvider<any, M, any, infer R> ? (Omit<R, keyof M> & M) extends R ? Omit<R, keyof M> & M : R extends M ? R : Omit<M, keyof R> & R : S extends MiddlewareProvider<any, M, any, infer R> ? R : never : never;
+export declare type ServiceMiddlewareProviderArgs<S> = S extends MiddlewareProvider<any, any, infer A, any> ? A : never;
+export declare type ServiceMiddlewareProviderChainResult<C, M> = C extends [infer S1, ...infer S] ? S extends never[] ? ServiceMiddlewareProviderResult<M, S1> : ServiceMiddlewareProviderChainResult<S, ServiceMiddlewareProviderResult<M, S1>> : C extends unknown ? M : never;
+export declare type ServiceMiddlewareProviderChainArgs<C> = C extends [infer S1, ...infer S] ? S extends never[] ? ServiceMiddlewareProviderArgs<S1> : TupleZip<ServiceMiddlewareProviderChainArgs<S>, ServiceMiddlewareProviderArgs<S1>> : C extends unknown ? [] : never;
+/**
+ * Creates a middleware composer for given AppServices and input value types. The composer accepts a list of middleware
+ * that it assembles into a chain. The function returned by the composer takes a value of the given input value type,
+ * passes that value through the chain, and returns the result of the last element in the chain. The ending value will
+ * depend on the composed middleware.
+ *
+ * Examples:
+ *
+ * ```
+ * export const composeServiceMiddleware =
+ *   makeComposeMiddleware<AppServices, {request: ApiRouteRequest}>();
+ * export const composeResponseMiddleware =
+ *   makeComposeMiddleware<AppServices, Promise<ApiRouteResponse> | undefined>();
+ *
+ * // `requestServiceProvider` is a function that expects
+ * //`{request: ApiRouteRequest}` (specified in the call to
+ * //`makeComposeMiddleware`); for requestServiceProviders as part of routes in
+ * // particular, the request responder calls this when it resolves the routes.
+ *
+ * const requestServiceProvider = composeServiceMiddleware(
+ *   cookieAuthMiddleware, // expects `request` (from input), adds `authProvider`
+ *   myDocumentStoreMiddleware, // expects authProvider, adds the document store
+ *   myDocumentSearchMiddleware, // expects document store, adds search provider
+ * ); // if you try to specify them in the wrong order it'll yell at you
+ * ```
+ *
+ * WARNING: depending on how you use it, typescript _sometimes_ explodes on these recursive types. if you have problems in your build
+ * with memory, you will have to specify the expected result type when calling the middleware reducer. this is a little annoying,
+ * but it will still correctly error if the type you specify is wrong, so you've still got the type safety.
+ *
+ * ```
+ * // this might work, or it might make your compiler run out of memory
+ * eg: const myThing = makeComposeMiddleware()(...);
+ *
+ * // this helps typescript figure out what is going on
+ * eg: const myThing: myType = makeComposeMiddleware()(...);
+ * ```
+ */
+export declare const makeComposeMiddleware: <Sa, M>() => <C extends any[]>(...chain: C) => MiddlewareProvider<Sa, M, ServiceMiddlewareProviderChainArgs<C>, ServiceMiddlewareProviderChainResult<C, M>>;

package/dist/cjs/middleware/index.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeComposeMiddleware = void 0;
+/**
+ * Creates a middleware composer for given AppServices and input value types. The composer accepts a list of middleware
+ * that it assembles into a chain. The function returned by the composer takes a value of the given input value type,
+ * passes that value through the chain, and returns the result of the last element in the chain. The ending value will
+ * depend on the composed middleware.
+ *
+ * Examples:
+ *
+ * ```
+ * export const composeServiceMiddleware =
+ *   makeComposeMiddleware<AppServices, {request: ApiRouteRequest}>();
+ * export const composeResponseMiddleware =
+ *   makeComposeMiddleware<AppServices, Promise<ApiRouteResponse> | undefined>();
+ *
+ * // `requestServiceProvider` is a function that expects
+ * //`{request: ApiRouteRequest}` (specified in the call to
+ * //`makeComposeMiddleware`); for requestServiceProviders as part of routes in
+ * // particular, the request responder calls this when it resolves the routes.
+ *
+ * const requestServiceProvider = composeServiceMiddleware(
+ *   cookieAuthMiddleware, // expects `request` (from input), adds `authProvider`
+ *   myDocumentStoreMiddleware, // expects authProvider, adds the document store
+ *   myDocumentSearchMiddleware, // expects document store, adds search provider
+ * ); // if you try to specify them in the wrong order it'll yell at you
+ * ```
+ *
+ * WARNING: depending on how you use it, typescript _sometimes_ explodes on these recursive types. if you have problems in your build
+ * with memory, you will have to specify the expected result type when calling the middleware reducer. this is a little annoying,
+ * but it will still correctly error if the type you specify is wrong, so you've still got the type safety.
+ *
+ * ```
+ * // this might work, or it might make your compiler run out of memory
+ * eg: const myThing = makeComposeMiddleware()(...);
+ *
+ * // this helps typescript figure out what is going on
+ * eg: const myThing: myType = makeComposeMiddleware()(...);
+ * ```
+ */
+const makeComposeMiddleware = () => (...chain) => (app, appBinder) => {
+    const boundChain = chain.map(provider => appBinder ? appBinder(app, provider) : provider(app));
+    return (middleware, ...args) => {
+        return boundChain.reduce((result, provider) => provider(result, ...args), middleware);
+    };
+};
+exports.makeComposeMiddleware = makeComposeMiddleware;

package/dist/cjs/middleware/lambdaCorsResponseMiddleware.d.ts

@@ -0,0 +1,20 @@
+import { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { ConfigProviderForConfig } from '../config';
+import { ApiResponse } from '../routing';
+declare type Config = {
+    corsAllowedHostRegex: string;
+};
+/**
+ * Creates response middleware that adds CORS headers to responses from approved hosts.
+ *
+ * @param config the config object
+ * @param config.corsAllowedHostRegex the config that specifies the regex for allowed hosts
+ * @example
+ * createLambdaCorsResponseMiddleware({
+ *   corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'
+ * }),
+ */
+export declare const createLambdaCorsResponseMiddleware: (config: ConfigProviderForConfig<Config>) => () => (responsePromise: Promise<ApiResponse<number, any>> | undefined, { request }: {
+    request: APIGatewayProxyEventV2;
+}) => Promise<ApiResponse<number, any>> | undefined;
+export {};

package/dist/cjs/middleware/lambdaCorsResponseMiddleware.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLambdaCorsResponseMiddleware = void 0;
+const resolveConfigValue_1 = require("../config/resolveConfigValue");
+const routing_1 = require("../routing");
+/**
+ * Creates response middleware that adds CORS headers to responses from approved hosts.
+ *
+ * @param config the config object
+ * @param config.corsAllowedHostRegex the config that specifies the regex for allowed hosts
+ * @example
+ * createLambdaCorsResponseMiddleware({
+ *   corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'
+ * }),
+ */
+const createLambdaCorsResponseMiddleware = (config) => () => (responsePromise, { request }) => {
+    const cors = async () => {
+        const allowedHost = await (0, resolveConfigValue_1.resolveConfigValue)(config.corsAllowedHostRegex);
+        if (request.headers.origin && request.headers.origin !== 'null' && new URL(request.headers.origin).hostname.match(new RegExp(allowedHost))) {
+            return {
+                'Access-Control-Allow-Origin': request.headers.origin,
+                'Access-Control-Allow-Credentials': 'true',
+                'Access-Control-Allow-Headers': 'content-type',
+                'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
+            };
+        }
+    };
+    if (responsePromise) {
+        return responsePromise.then(async (response) => {
+            response.headers = {
+                ...await cors(),
+                ...response.headers
+            };
+            return response;
+        });
+    }
+    if (request.requestContext.http.method === 'OPTIONS') {
+        return cors().then(headers => (0, routing_1.apiTextResponse)(200, '', headers));
+    }
+    return responsePromise;
+};
+exports.createLambdaCorsResponseMiddleware = createLambdaCorsResponseMiddleware;