@openstax/ts-utils 1.21.11 → 1.23.0

package/dist/esm/routing/helpers.d.ts

@@ -0,0 +1,57 @@
+import type { HttpHeaders } from '.';
+/**
+ * Get the value of a header, case insensitive; note if there are multiple headers of the same
+ * value, this only returns the first value
+ *
+ * @param headers
+ * @param name the name of the header, case ignored
+ */
+export declare const getHeader: (headers: HttpHeaders, name: string) => string | undefined;
+/**
+ * Gets the body of a request
+ * @param request
+ * @throws InvalidRequestError if the content type is not application/json or not parsable
+ */
+export declare const getRequestBody: (request: {
+    headers: HttpHeaders;
+    body?: string | undefined;
+}) => any;
+/**
+ * stub validator because writing validators is annoying
+ */
+export declare const unsafePayloadValidator: <T>() => (input: any) => input is T;
+/**
+ * Middleware that validates the request payload and adds it to the middleware (with key `payload`)
+ * so it can be accessed downstream.
+ *
+ * This middleware accomplishes a few things:
+ *   - establishes type of payload for route body logic
+ *   - validates the payload for route logic
+ *   - establishes type of payload for client logic calling this route
+ *
+ * @param validator a guard function that takes the request payload and returns true if it is valid,
+ * narrowing the type of the payload to the correct type
+ * @throws InvalidRequestError if the payload is not valid
+ *
+ * @example
+ * export const exampleRoute = createRoute({
+ *   name: 'exampleRoute', method: METHOD.POST, path: '/example/:id',
+ *   requestServiceProvider: composeServiceMiddleware(
+ *     // here we are adding to previously composed middleware
+ *     requestServiceProvider,
+ *     requestPayloadProvider(validatePayload)
+ *   )},
+ *   async(params: {id: string}, services) => {
+ *     const result = await services.myDocumentStore.putItem({
+ *       ...services.payload,
+ *       id: params.id,
+ *     });
+ *     return apiJsonResponse(201, result);
+ *   }
+ * );
+ */
+export declare const requestPayloadProvider: <T>(validator: (input: any) => input is T) => () => <M extends {
+    request: Parameters<typeof getRequestBody>[0];
+}>(requestServices: M) => M & {
+    payload: T;
+};

package/dist/esm/routing/helpers.js

@@ -0,0 +1,83 @@
+import { assertErrorInstanceOf } from '../assertions';
+import { InvalidRequestError } from '../errors';
+import { isPlainObject } from '../guards';
+/**
+ * Get the value of a header, case insensitive; note if there are multiple headers of the same
+ * value, this only returns the first value
+ *
+ * @param headers
+ * @param name the name of the header, case ignored
+ */
+export const getHeader = (headers, name) => {
+    const key = Object.keys(headers).find(header => header.toLowerCase() === name.toLowerCase());
+    const value = key ? headers[key] : undefined;
+    return value instanceof Array
+        ? value[0]
+        : value;
+};
+/**
+ * Gets the body of a request
+ * @param request
+ * @throws InvalidRequestError if the content type is not application/json or not parsable
+ */
+export const getRequestBody = (request) => {
+    if (getHeader(request.headers, 'content-type') !== 'application/json') {
+        throw new InvalidRequestError('unknown content type: ' + getHeader(request.headers, 'content-type'));
+    }
+    if (!request.body) {
+        return {};
+    }
+    try {
+        return JSON.parse(request.body);
+    }
+    catch (error) {
+        // Since the body is provided by the user, invalid JSON in the body is an invalid request
+        // We return the message which tells them why the JSON is invalid, but no backtrace
+        throw new InvalidRequestError(assertErrorInstanceOf(error, SyntaxError).message);
+    }
+};
+/* utils and middleware for loading request payload (must follow this pattern for `PayloadForRoute` to work) */
+/**
+ * stub validator because writing validators is annoying
+ */
+export const unsafePayloadValidator = () => (input) => {
+    return isPlainObject(input) && Object.keys(input).length > 0;
+};
+/**
+ * Middleware that validates the request payload and adds it to the middleware (with key `payload`)
+ * so it can be accessed downstream.
+ *
+ * This middleware accomplishes a few things:
+ *   - establishes type of payload for route body logic
+ *   - validates the payload for route logic
+ *   - establishes type of payload for client logic calling this route
+ *
+ * @param validator a guard function that takes the request payload and returns true if it is valid,
+ * narrowing the type of the payload to the correct type
+ * @throws InvalidRequestError if the payload is not valid
+ *
+ * @example
+ * export const exampleRoute = createRoute({
+ *   name: 'exampleRoute', method: METHOD.POST, path: '/example/:id',
+ *   requestServiceProvider: composeServiceMiddleware(
+ *     // here we are adding to previously composed middleware
+ *     requestServiceProvider,
+ *     requestPayloadProvider(validatePayload)
+ *   )},
+ *   async(params: {id: string}, services) => {
+ *     const result = await services.myDocumentStore.putItem({
+ *       ...services.payload,
+ *       id: params.id,
+ *     });
+ *     return apiJsonResponse(201, result);
+ *   }
+ * );
+ */
+export const requestPayloadProvider = (validator) => () => (requestServices) => {
+    const payload = getRequestBody(requestServices.request);
+    // for more precise error messages, throw your own InvalidRequestError from your validator function
+    if (!validator(payload)) {
+        throw new InvalidRequestError();
+    }
+    return { ...requestServices, payload };
+};

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

@@ -0,0 +1,272 @@
+import { Logger } from '../services/logger';
+/** HTTP query parameters */
+export declare type QueryParams = Record<string, string | undefined | string[] | null>;
+/**
+ * The type for a map of string substitutions to use when building route paths, e.g. a route may
+ * be defined as `'/api/:id'` and then rendered as `'/api/123'` when the `id` route param is set
+ * to `'123'`
+ */
+export declare type RouteParams = {
+    [key: string]: string;
+};
+/** A type that is compatible with any `Route` type */
+export declare type AnyRoute<R> = R extends Route<infer N, infer P, infer Sa, infer Sr, infer Ri, infer Ro> ? Route<N, P, Sa, Sr, Ri, Ro> : never;
+export declare type AnySpecificRoute<R, Sa, Ri, Ro> = R extends Route<infer N, infer P, Sa, infer Sr, Ri, Ro> & infer E ? Route<N, P, Sa, Sr, Ri, Ro> & E : never;
+/** The inferred "route output" (`Ro`) type for a given route */
+export declare type OutputForRoute<R> = R extends Route<any, any, any, any, any, infer Ro> ? Ro : never;
+/** The inferred type for the params of the provided route type, `R`; may be undefined */
+export declare type ParamsForRoute<R> = R extends Route<any, infer P, any, any, any, any> ? P : never;
+/** The inferred type for the request services of the provided route type, `R`. */
+export declare type RequestServicesForRoute<R> = R extends Route<any, any, any, infer Sr, any, any> ? Sr : never;
+/** The type for the params of the provided route type, `R`; will be `{}` if undefined */
+export declare type ParamsForRouteOrEmpty<R> = ParamsForRoute<R> extends undefined ? {} : Exclude<ParamsForRoute<R>, undefined>;
+/** derives the route match type for this route, which includes the route itself and the matching params. */
+export declare type RouteMatchRecord<R> = R extends AnyRoute<R> ? {
+    route: R;
+    params: ParamsForRoute<R>;
+} : never;
+/**
+ * The conditional type for the payload for a given route, `R`. This isn't a route structure, its
+ * a convention based on the request middleware
+ */
+export declare type PayloadForRoute<R> = RequestServicesForRoute<R> extends {
+    payload: any;
+} ? RequestServicesForRoute<R>['payload'] : undefined;
+declare type RequestServiceProvider<Sa, Sr, Ri> = (app: Sa) => <R>(middleware: {
+    request: Ri;
+    logger: Logger;
+}, match: RouteMatchRecord<R>) => Sr;
+declare type RouteHandler<P, Sr, Ro> = (params: P, request: Sr) => Ro;
+declare type Route<N extends string, P extends RouteParams | undefined, Sa, Sr, Ri, Ro> = (Sr extends undefined ? {
+    requestServiceProvider?: RequestServiceProvider<Sa, Sr, Ri> | undefined;
+} : {
+    requestServiceProvider: RequestServiceProvider<Sa, Sr, Ri>;
+}) & {
+    name: N;
+    path: string;
+    handler: (params: P, request: Sr) => Ro;
+};
+declare type CreateRouteConfig<Sa, Sr, Ri, N extends string, Ex> = (Sr extends undefined ? {
+    requestServiceProvider?: RequestServiceProvider<Sa, Sr, Ri> | undefined;
+} : {
+    requestServiceProvider: RequestServiceProvider<Sa, Sr, Ri>;
+}) & {
+    name: N;
+    path: string;
+} & Ex;
+/**
+ * Interface for a function that creates a route. There are two overloaded signatures, because
+ * sometimes typescript can't figure out the value of `Sr` between the handler and the service
+ * provider. Forcing it through the provider types first by putting the handler in a subsequent
+ * argument seems to help.
+ */
+export interface CreateRoute<Sa, Ri, Ex> {
+    <N extends string, Ro, Sr extends unknown | undefined = undefined, P extends RouteParams | undefined = undefined>(config: CreateRouteConfig<Sa, Sr, Ri, N, Ex> & {
+        handler: RouteHandler<P, Sr, Ro>;
+    }): Route<N, P, Sa, Sr, Ri, Ro> & Ex;
+    <N extends string, Ro, Sr extends unknown | undefined, P extends RouteParams | undefined = undefined>(config: CreateRouteConfig<Sa, Sr, Ri, N, Ex>, handler: RouteHandler<P, Sr, Ro>): Route<N, P, Sa, Sr, Ri, Ro> & Ex;
+}
+/**
+ * Makes a createRoute function that can be used to create routes (this is a factory factory). The
+ * `makeCreateRoute` function is typically called once in the backend and once in the frontend to
+ * set the types for the resulting `createRoute` function -- that latter function is called once
+ * per route. E.g. for the backend, the call could look like:
+ *
+ * ```
+ * export const createRoute = makeCreateRoute<AppServices, ApiRouteRequest, {
+ *   method: METHOD;
+ * }>();
+ * ```
+ *
+ * Notes:
+ * * The `{method: METHOD}` defines the `Ex` extension type; here, the `method` property is only
+ *   relevant to backend routes.
+ * * when defining the `createRoute` method, only the request input format is defined, the output
+ *   format is derived from the routes.
+ *
+ * When calling the resulting `createRoute` function, the only required params of the route are the
+ * name, path, and handler. Other params can be added to the type and then later used in the
+ * routeMatcher.
+ *
+ * eg when defining requestServiceProvider in line, the types have a hard time, it helps to put in another argument:
+ * ```
+ * export const exampleRoute = createRoute({
+ *   name: 'exampleRoute', method: METHOD.GET, path: '/api/example/:key',
+ *   requestServiceProvider: composeServiceMiddleware({
+ *     cookieAuthMiddleware,
+ *     documentStoreMiddleware,
+ *   }},
+ *   async(params: {key: string}, services) => {
+ *     const result = await services.myDocumentStore.getItem(params.key);
+ *
+ *     if (!result) {
+ *       throw new NotFoundError('requested item not found');
+ *     }
+ *
+ *     return apiJsonResponse(200, result);
+ *   }
+ * );
+ * ```
+ * eg when using a pre-existing provider variable the types work better:
+ * ```
+ * export const exampleRoute = createRoute({
+ *   name: 'exampleRoute', method: METHOD.GET, path: '/api/example/:key',
+ *   requestServiceProvider,
+ *   handler: async(params: {key: string}, services) => {
+ *     const result = await services.myDocumentStore.getItem(params.key);
+ *
+ *     if (!result) {
+ *       throw new NotFoundError('requested item not found');
+ *     }
+ *
+ *     return apiJsonResponse(200, result);
+ *   }
+ * });
+ * ```
+ */
+export declare const makeCreateRoute: <Sa, Ri, Ex = {}>() => CreateRoute<Sa, Ri, Ex>;
+/**
+ * Makes a renderRouteUrl function that can be used to render route paths (this is a factory
+ * factory). The returned function takes a `route`, `params`, and `query` and returns a string
+ * with the params and query substituted into the route path.
+ *
+ * this function is initialized using the Ru type which indicates the specific routes wired into
+ * the application, which means that if you try to build a url with a route which is not wired
+ * into the router you will get a type error. this is a feature to prevent referencing routes that
+ * don't exist or aren't handling requests properly.
+ *
+ * if you are making a helper function or need to render a route outside your application, you
+ * can use the `renderAnyRouteUrl` function
+ */
+export declare const makeRenderRouteUrl: <Ru extends {
+    path: string;
+}>() => <R extends Ru>(route: R, params: ParamsForRoute<R>, query?: QueryParams) => string;
+/**
+ * A pre-made result from `makeRenderRouteUrl`, this function interpolates parameter and query
+ * arguments into a route path.
+ *
+ * prefer using `renderRouteUrl` initialized with your applications route union
+ * when possible to help catch improperly initialized routes.
+ *
+ * @param route the route that has a `path` to be interpolated
+ * @param params the parameters to interpolate into the route path
+ * @param query the query parameters to add to the route path
+ * @returns the interpolated route path
+ */
+export declare const renderAnyRouteUrl: <R extends any>(route: R, params: ParamsForRoute<R>, query?: QueryParams) => string;
+declare type RequestPathExtractor<Ri> = (request: Ri) => string;
+declare type RequestLogExtractor<Ri> = (request: Ri) => JsonCompatibleStruct;
+declare type RequestRouteMatcher<Ri, R> = (request: Ri, route: R) => boolean;
+declare type CompatibleServices<T1> = keyof T1 extends 'logger' ? T1 extends {
+    logger: Logger;
+} ? T1 : never : T1 & {
+    logger?: Logger;
+};
+declare type RequestResponder<Sa, Ri, Ro> = {
+    (services: CompatibleServices<Sa>): (request: Ri) => Ro | undefined;
+    <RoF>(services: CompatibleServices<Sa>, responseMiddleware: (app: Sa) => (response: Ro | undefined, request: {
+        request: Ri;
+        logger: Logger;
+    }) => RoF): (request: Ri) => RoF;
+};
+/**
+ * A factory factory for creating request responders (functions that take a request and return a
+ * response -- these functions let us implement Lambda `handler` functions).
+ *
+ * Use it in two steps. First, call it with the general business logic that defines routes, logs,
+ * errors, etc:
+ * ```
+ * const getRequestResponder = makeGetRequestResponder<
+ *    AppServices, TRoutes, ApiRouteRequest, Promise<ApiRouteResponse>
+ *   >()  // this empty invocation helps typescript mix defined and inferred types
+ *   ({
+ *     routes: apiRoutes, // the route definitions
+ *     pathExtractor,     // how to get the path out of the request format
+ *     routeMatcher,      // logic for matching route (beyond path matching, optional)
+ *     errorHandler,      // any special error handling
+ *   });
+ * ```
+ * Note here that among other things we're specifying a generic response format that the response
+ * and error handling middleware can use, if any routes have responses that don't adhere to this
+ * it'll complain about it.
+ *
+ * Next, we use the `getRequestResponder` to create a responder for a specific lambda entrypoint:
+ * ```
+ * export const handler: (request: APIGatewayProxyEventV2): Promise<ApiRouteResponse> =>
+ *   getRequestResponder(
+ *     lambdaServices,  // the AppServices for this entrypoint
+ *     lambdaMiddleware // environment specific response middleware (like cors)
+ *   );
+ * ```
+ */
+export declare const makeGetRequestResponder: <Sa, Ru, Ri, Ro>() => ({ routes, pathExtractor, routeMatcher, errorHandler, logExtractor }: {
+    routes: () => AnySpecificRoute<Ru, Sa, Ri, Ro>[];
+    pathExtractor: RequestPathExtractor<Ri>;
+    logExtractor?: RequestLogExtractor<Ri> | undefined;
+    routeMatcher?: RequestRouteMatcher<Ri, AnySpecificRoute<Ru, Sa, Ri, Ro>> | undefined;
+    errorHandler?: ((e: Error, logger: Logger) => Ro) | undefined;
+}) => RequestResponder<Sa, Ri, Ro>;
+/** HTTP Headers */
+export declare type HttpHeaders = {
+    [key: string]: string | undefined | string[];
+};
+/** A type that works in JSON */
+export declare type JsonCompatibleValue = string | number | null | undefined | boolean;
+/** A JSON array type */
+export declare type JsonCompatibleArray = Array<JsonCompatibleValue | JsonCompatibleStruct | JsonCompatibleStruct>;
+/** A JSON object type */
+export declare type JsonCompatibleStruct = {
+    [key: string]: JsonCompatibleStruct | JsonCompatibleValue | JsonCompatibleArray;
+};
+/** The type for an API response */
+export declare type ApiResponse<S extends number, T> = {
+    isBase64Encoded?: boolean;
+    statusCode: S;
+    data: T;
+    body: string;
+    headers?: {
+        [key: string]: string;
+    };
+};
+/**
+ * Returns a JSON response. Handles serializing the data to JSON and setting the content-type header.
+ * @param statusCode e.g. 201
+ * @param data the object to be serialized to JSON
+ * @param headers HTTP headers
+ * @example
+ * return apiJsonResponse(
+ *   200, {
+ *     message: "hello, world!",
+ *     foo: "bar",
+ *   },
+ *   { 'X-Frame-Options': 'DENY' }
+ * );
+ */
+export declare const apiJsonResponse: <S extends number, T extends JsonCompatibleStruct>(statusCode: S, data: T, headers?: HttpHeaders | undefined) => ApiResponse<S, T>;
+/**
+ * Returns a plain text response. Handles setting the content-type header.
+ * @param statusCode e.g. 201
+ * @param data some string
+ * @param headers HTTP headers
+ * @example return apiTextResponse(200, 'some text')
+ */
+export declare const apiTextResponse: <S extends number>(statusCode: S, data: string, headers?: HttpHeaders | undefined) => ApiResponse<S, string>;
+/**
+ * Returns an HTML response. Handles setting the content-type header.
+ * @param statusCode e.g. 201
+ * @param data some string
+ * @param headers HTTP headers
+ * @example return apiHtmlResponse(200, '<b>some text</b>')
+ */
+export declare const apiHtmlResponse: <S extends number>(statusCode: S, data: string, headers?: HttpHeaders | undefined) => ApiResponse<S, string>;
+/** HTTP method enum */
+export declare enum METHOD {
+    GET = "GET",
+    HEAD = "HEAD",
+    POST = "POST",
+    PUT = "PUT",
+    PATCH = "PATCH",
+    DELETE = "DELETE",
+    OPTIONS = "OPTIONS"
+}
+export * from './helpers';

package/dist/esm/routing/index.js

@@ -0,0 +1,232 @@
+import * as pathToRegexp from 'path-to-regexp';
+import queryString from 'query-string';
+import { mapFind, memoize } from '../misc/helpers';
+import { createConsoleLogger } from '../services/logger/console';
+/**
+ * Makes a createRoute function that can be used to create routes (this is a factory factory). The
+ * `makeCreateRoute` function is typically called once in the backend and once in the frontend to
+ * set the types for the resulting `createRoute` function -- that latter function is called once
+ * per route. E.g. for the backend, the call could look like:
+ *
+ * ```
+ * export const createRoute = makeCreateRoute<AppServices, ApiRouteRequest, {
+ *   method: METHOD;
+ * }>();
+ * ```
+ *
+ * Notes:
+ * * The `{method: METHOD}` defines the `Ex` extension type; here, the `method` property is only
+ *   relevant to backend routes.
+ * * when defining the `createRoute` method, only the request input format is defined, the output
+ *   format is derived from the routes.
+ *
+ * When calling the resulting `createRoute` function, the only required params of the route are the
+ * name, path, and handler. Other params can be added to the type and then later used in the
+ * routeMatcher.
+ *
+ * eg when defining requestServiceProvider in line, the types have a hard time, it helps to put in another argument:
+ * ```
+ * export const exampleRoute = createRoute({
+ *   name: 'exampleRoute', method: METHOD.GET, path: '/api/example/:key',
+ *   requestServiceProvider: composeServiceMiddleware({
+ *     cookieAuthMiddleware,
+ *     documentStoreMiddleware,
+ *   }},
+ *   async(params: {key: string}, services) => {
+ *     const result = await services.myDocumentStore.getItem(params.key);
+ *
+ *     if (!result) {
+ *       throw new NotFoundError('requested item not found');
+ *     }
+ *
+ *     return apiJsonResponse(200, result);
+ *   }
+ * );
+ * ```
+ * eg when using a pre-existing provider variable the types work better:
+ * ```
+ * export const exampleRoute = createRoute({
+ *   name: 'exampleRoute', method: METHOD.GET, path: '/api/example/:key',
+ *   requestServiceProvider,
+ *   handler: async(params: {key: string}, services) => {
+ *     const result = await services.myDocumentStore.getItem(params.key);
+ *
+ *     if (!result) {
+ *       throw new NotFoundError('requested item not found');
+ *     }
+ *
+ *     return apiJsonResponse(200, result);
+ *   }
+ * });
+ * ```
+ */
+export const makeCreateRoute = () => (...args) => {
+    return (args.length === 1
+        ? args[0]
+        : { ...args[0], handler: args[1] });
+};
+/* begin reverse routing utils */
+/**
+ * Makes a renderRouteUrl function that can be used to render route paths (this is a factory
+ * factory). The returned function takes a `route`, `params`, and `query` and returns a string
+ * with the params and query substituted into the route path.
+ *
+ * this function is initialized using the Ru type which indicates the specific routes wired into
+ * the application, which means that if you try to build a url with a route which is not wired
+ * into the router you will get a type error. this is a feature to prevent referencing routes that
+ * don't exist or aren't handling requests properly.
+ *
+ * if you are making a helper function or need to render a route outside your application, you
+ * can use the `renderAnyRouteUrl` function
+ */
+export const makeRenderRouteUrl = () => (route, params, query = {}) => {
+    const getPathForParams = pathToRegexp.compile(route.path, { encode: encodeURIComponent });
+    const search = queryString.stringify(query);
+    const path = getPathForParams(params) + (search ? `?${search}` : '');
+    return path;
+};
+/**
+ * A pre-made result from `makeRenderRouteUrl`, this function interpolates parameter and query
+ * arguments into a route path.
+ *
+ * prefer using `renderRouteUrl` initialized with your applications route union
+ * when possible to help catch improperly initialized routes.
+ *
+ * @param route the route that has a `path` to be interpolated
+ * @param params the parameters to interpolate into the route path
+ * @param query the query parameters to add to the route path
+ * @returns the interpolated route path
+ */
+export const renderAnyRouteUrl = makeRenderRouteUrl();
+const bindRoute = (services, appBinder, pathExtractor, matcher) => (route) => {
+    const getParamsFromPath = pathToRegexp.match(route.path, { decode: decodeURIComponent });
+    const boundServiceProvider = route.requestServiceProvider && appBinder(services, route.requestServiceProvider);
+    return (request, logger) => {
+        const path = pathExtractor(request);
+        const match = getParamsFromPath(path);
+        if ((!matcher || matcher(request, route)) && match) {
+            return () => route.handler(match.params, boundServiceProvider ? boundServiceProvider({ request, logger }, { route, params: match.params }) : undefined);
+        }
+    };
+};
+/**
+ * A factory factory for creating request responders (functions that take a request and return a
+ * response -- these functions let us implement Lambda `handler` functions).
+ *
+ * Use it in two steps. First, call it with the general business logic that defines routes, logs,
+ * errors, etc:
+ * ```
+ * const getRequestResponder = makeGetRequestResponder<
+ *    AppServices, TRoutes, ApiRouteRequest, Promise<ApiRouteResponse>
+ *   >()  // this empty invocation helps typescript mix defined and inferred types
+ *   ({
+ *     routes: apiRoutes, // the route definitions
+ *     pathExtractor,     // how to get the path out of the request format
+ *     routeMatcher,      // logic for matching route (beyond path matching, optional)
+ *     errorHandler,      // any special error handling
+ *   });
+ * ```
+ * Note here that among other things we're specifying a generic response format that the response
+ * and error handling middleware can use, if any routes have responses that don't adhere to this
+ * it'll complain about it.
+ *
+ * Next, we use the `getRequestResponder` to create a responder for a specific lambda entrypoint:
+ * ```
+ * export const handler: (request: APIGatewayProxyEventV2): Promise<ApiRouteResponse> =>
+ *   getRequestResponder(
+ *     lambdaServices,  // the AppServices for this entrypoint
+ *     lambdaMiddleware // environment specific response middleware (like cors)
+ *   );
+ * ```
+ */
+export const makeGetRequestResponder = () => ({ routes, pathExtractor, routeMatcher, errorHandler, logExtractor }) => (services, responseMiddleware) => {
+    const appBinderImpl = (app, middleware) => middleware(app, appBinder);
+    const appBinder = memoize(appBinderImpl);
+    const boundRoutes = routes().map(bindRoute(services, appBinder, pathExtractor, routeMatcher));
+    const boundResponseMiddleware = responseMiddleware ? responseMiddleware(services) : undefined;
+    const appLogger = services.logger || createConsoleLogger();
+    // *note* this opaque promise guard is less generic than i hoped so
+    //   i'm leaving it here instead of the guards file.
+    //
+    // its less than ideal because it enforces that the handlers return
+    // the same type as the parent promise, usually a handler can be either a
+    // promise or a non-promise value and the promise figures it out, but those
+    // types are getting complicated quickly here.
+    const isPromise = (thing) => thing instanceof Promise;
+    return (request) => {
+        const logger = appLogger.createSubContext();
+        if (logExtractor) {
+            logger.setContext(logExtractor(request));
+        }
+        try {
+            const executor = mapFind(boundRoutes, (route) => route(request, logger));
+            if (executor) {
+                const result = boundResponseMiddleware ?
+                    boundResponseMiddleware(executor(), { request, logger }) : executor();
+                if (isPromise(result) && errorHandler) {
+                    const errorHandlerWithMiddleware = (e) => boundResponseMiddleware ?
+                        boundResponseMiddleware(errorHandler(e, logger), { request, logger }) : errorHandler(e, logger);
+                    return result.catch(errorHandlerWithMiddleware);
+                }
+                else {
+                    return result;
+                }
+            }
+            else if (boundResponseMiddleware) {
+                return boundResponseMiddleware(undefined, { request, logger });
+            }
+        }
+        catch (e) {
+            if (errorHandler && e instanceof Error) {
+                return boundResponseMiddleware
+                    ? boundResponseMiddleware(errorHandler(e, logger), { request, logger })
+                    : errorHandler(e, logger);
+            }
+            throw e;
+        }
+        return undefined;
+    };
+};
+/**
+ * Returns a JSON response. Handles serializing the data to JSON and setting the content-type header.
+ * @param statusCode e.g. 201
+ * @param data the object to be serialized to JSON
+ * @param headers HTTP headers
+ * @example
+ * return apiJsonResponse(
+ *   200, {
+ *     message: "hello, world!",
+ *     foo: "bar",
+ *   },
+ *   { 'X-Frame-Options': 'DENY' }
+ * );
+ */
+export const apiJsonResponse = (statusCode, data, headers) => ({ statusCode, data, body: JSON.stringify(data), headers: { ...headers, 'content-type': 'application/json' } });
+/**
+ * Returns a plain text response. Handles setting the content-type header.
+ * @param statusCode e.g. 201
+ * @param data some string
+ * @param headers HTTP headers
+ * @example return apiTextResponse(200, 'some text')
+ */
+export const apiTextResponse = (statusCode, data, headers) => ({ statusCode, data, body: data, headers: { ...headers, 'content-type': 'text/plain' } });
+/**
+ * Returns an HTML response. Handles setting the content-type header.
+ * @param statusCode e.g. 201
+ * @param data some string
+ * @param headers HTTP headers
+ * @example return apiHtmlResponse(200, '<b>some text</b>')
+ */
+export const apiHtmlResponse = (statusCode, data, headers) => ({ statusCode, data, body: data, headers: { ...headers, 'content-type': 'text/html' } });
+/** HTTP method enum */
+export var METHOD;
+(function (METHOD) {
+    METHOD["GET"] = "GET";
+    METHOD["HEAD"] = "HEAD";
+    METHOD["POST"] = "POST";
+    METHOD["PUT"] = "PUT";
+    METHOD["PATCH"] = "PATCH";
+    METHOD["DELETE"] = "DELETE";
+    METHOD["OPTIONS"] = "OPTIONS";
+})(METHOD || (METHOD = {}));
+export * from './helpers';

package/dist/esm/routing/validators/zod.d.ts

@@ -0,0 +1,4 @@
+import type { z } from 'zod';
+export declare const zodPayloadValidator: <T>(validator: z.ZodType<T, z.ZodTypeDef, T>) => (input: {
+    [key: string]: any;
+}) => input is T;

package/dist/esm/routing/validators/zod.js

@@ -0,0 +1,8 @@
+import { ValidationError } from '../../errors';
+export const zodPayloadValidator = (validator) => (input) => {
+    const result = validator.safeParse(input);
+    if (result.success) {
+        return true;
+    }
+    throw new ValidationError(result.error.format());
+};