@openstax/ts-utils 1.1.34 → 1.1.35

package/dist/cjs/routing.d.ts

@@ -1,107 +0,0 @@
-import { Track } from './profile';
-export declare type QueryParams = Record<string, string | undefined | string[] | null>;
-export declare type RouteParams = {
-    [key: string]: string;
-};
-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;
-export declare type OutputForRoute<R> = R extends Route<any, any, any, any, any, infer Ro> ? Ro : never;
-export declare type ParamsForRoute<R> = R extends Route<any, infer P, any, any, any, any> ? P : never;
-export declare type RequestServicesForRoute<R> = R extends Route<any, any, any, infer Sr, any, any> ? Sr : never;
-export declare type ParamsForRouteOrEmpty<R> = ParamsForRoute<R> extends undefined ? {} : Exclude<ParamsForRoute<R>, undefined>;
-export declare type RouteMatchRecord<R> = R extends AnyRoute<R> ? {
-    route: R;
-    params: ParamsForRoute<R>;
-} : never;
-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;
-    profile: Track;
-}, 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;
-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;
-}
-export declare const makeCreateRoute: <Sa, Ri, Ex = {}>() => CreateRoute<Sa, Ri, Ex>;
-export declare const makeRenderRouteUrl: <Ru extends {
-    path: string;
-}>() => <R extends Ru>(route: R, params: ParamsForRoute<R>, query?: QueryParams) => string;
-export declare const renderAnyRouteUrl: <R extends any>(route: R, params: ParamsForRoute<R>, query?: QueryParams) => string;
-declare type RequestPathExtractor<Ri> = (request: Ri) => string;
-declare type RequestRouteMatcher<Ri, R> = (request: Ri, route: R) => boolean;
-declare type RequestResponder<Sa, Ri, Ro> = {
-    (services: Sa): (request: Ri) => Ro | undefined;
-    <RoF>(services: Sa, responseMiddleware: (app: Sa) => (response: Ro | undefined, request: {
-        request: Ri;
-        profile: Track;
-    }) => RoF): (request: Ri) => RoF;
-};
-export declare const makeGetRequestResponder: <Sa, Ru, Ri, Ro>() => ({ routes, pathExtractor, routeMatcher, errorHandler }: {
-    routes: () => AnySpecificRoute<Ru, Sa, Ri, Ro>[];
-    pathExtractor: RequestPathExtractor<Ri>;
-    routeMatcher?: RequestRouteMatcher<Ri, AnySpecificRoute<Ru, Sa, Ri, Ro>> | undefined;
-    errorHandler?: ((e: Error) => Ro) | undefined;
-}) => RequestResponder<Sa, Ri, Ro>;
-export declare type HttpHeaders = {
-    [key: string]: string | undefined | string[];
-};
-export declare type JsonCompatibleValue = string | number | null | undefined | boolean;
-export declare type JsonCompatibleArray = Array<JsonCompatibleValue | JsonCompatibleStruct | JsonCompatibleStruct>;
-export declare type JsonCompatibleStruct = {
-    [key: string]: JsonCompatibleStruct | JsonCompatibleValue | JsonCompatibleArray;
-};
-export declare type ApiResponse<S extends number, T> = {
-    isBase64Encoded?: boolean;
-    statusCode: S;
-    data: T;
-    body: string;
-    headers?: {
-        [key: string]: string;
-    };
-};
-export declare const apiJsonResponse: <S extends number, T extends JsonCompatibleStruct>(statusCode: S, data: T, headers?: HttpHeaders | undefined) => ApiResponse<S, T>;
-export declare const apiTextResponse: <S extends number>(statusCode: S, data: string, headers?: HttpHeaders | undefined) => ApiResponse<S, string>;
-export declare const apiHtmlResponse: <S extends number>(statusCode: S, data: string, headers?: HttpHeaders | undefined) => ApiResponse<S, string>;
-export declare enum METHOD {
-    GET = "GET",
-    HEAD = "HEAD",
-    POST = "POST",
-    PUT = "PUT",
-    PATCH = "PATCH",
-    DELETE = "DELETE",
-    OPTIONS = "OPTIONS"
-}
-export declare const getHeader: (headers: HttpHeaders, name: string) => string | undefined;
-export declare const getRequestBody: (request: {
-    headers: HttpHeaders;
-    body?: string | undefined;
-}) => any;
-export declare const unsafePayloadValidator: <T>() => (input: any) => input is T;
-export declare const requestPayloadProvider: <T>(validator: (input: any) => input is T) => () => <M extends {
-    request: Parameters<typeof getRequestBody>[0];
-}>(requestServices: M) => M & {
-    payload: T;
-};
-export {};

package/dist/cjs/routing.js

@@ -1,247 +0,0 @@
-"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.requestPayloadProvider = exports.unsafePayloadValidator = exports.getRequestBody = exports.getHeader = exports.METHOD = exports.apiHtmlResponse = exports.apiTextResponse = exports.apiJsonResponse = exports.makeGetRequestResponder = exports.renderAnyRouteUrl = exports.makeRenderRouteUrl = exports.makeCreateRoute = void 0;
-const pathToRegexp = __importStar(require("path-to-regexp"));
-const query_string_1 = __importDefault(require("query-string"));
-const assertions_1 = require("./assertions");
-const errors_1 = require("./errors");
-const guards_1 = require("./guards");
-const profile_1 = require("./profile");
-const _1 = require(".");
-/*
- * route definition helper. 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. when defining the `createRoute` method, only
- * the request input format is defined, the result format is derived from the routes.
- *
- * eg:
- *   export const createRoute = makeCreateRoute<AppServices, ApiRouteRequest, {
- *     method: METHOD;
- *   }>();
- *
- * 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: requestServiceProvider({
- *       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);
- *     }
- *   });
- */
-const makeCreateRoute = () => (...args) => {
-    return (args.length === 1
-        ? args[0]
-        : { ...args[0], handler: args[1] });
-};
-exports.makeCreateRoute = makeCreateRoute;
-/* begin reverse routing utils */
-const makeRenderRouteUrl = () => (route, params, query = {}) => {
-    const getPathForParams = pathToRegexp.compile(route.path, { encode: encodeURIComponent });
-    const search = query_string_1.default.stringify(query);
-    const path = getPathForParams(params) + (search ? `?${search}` : '');
-    return path;
-};
-exports.makeRenderRouteUrl = makeRenderRouteUrl;
-exports.renderAnyRouteUrl = (0, exports.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, profile) => {
-        const path = pathExtractor(request);
-        const match = getParamsFromPath(path);
-        if ((!matcher || matcher(request, route)) && match) {
-            return profile.track(route.name, routeProfile => () => route.handler(match.params, boundServiceProvider ? boundServiceProvider({ request, profile: routeProfile }, { route, params: match.params }) : undefined));
-        }
-    };
-};
-/*
- * here 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.
- *
- * eg:
- *   export const getRequestResponder = makeGetRequestResponder<AppServices, TRoutes, ApiRouteRequest, Promise<ApiRouteResponse>>()({
- *     routes: apiRoutes, // the route definitions
- *     pathExtractor, // how to get the path out of the request format
- *     routeMatcher, // logic for matching route (if there is any in addition to the path matching)
- *     errorHandler, // any special error handling
- *   });
- *
- * eg an lambda entrypoint:
- *   export const handler: (request: APIGatewayProxyEventV2) => Promise<ApiRouteResponse> =
- *     getRequestResponder(
- *       lambdaServices, // the AppServices for this entrypoint
- *       lambdaMiddleware // environment specific response middleware (like cors)
- *     );
- */
-const makeGetRequestResponder = () => ({ routes, pathExtractor, routeMatcher, errorHandler }) => (services, responseMiddleware) => {
-    const appBinderImpl = (app, middleware) => middleware(app, appBinder);
-    const appBinder = (0, _1.memoize)(appBinderImpl);
-    const boundRoutes = routes().map(bindRoute(services, appBinder, pathExtractor, routeMatcher));
-    const boundResponseMiddleware = responseMiddleware ? responseMiddleware(services) : undefined;
-    // *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 { end, ...profile } = (0, profile_1.createProfile)(new Date().toISOString()).start();
-        try {
-            const executor = (0, _1.mapFind)(boundRoutes, (route) => route(request, profile));
-            if (executor) {
-                const result = boundResponseMiddleware ?
-                    boundResponseMiddleware(executor(), { request, profile }) : executor();
-                if (isPromise(result) && errorHandler) {
-                    const errorHandlerWithMiddleware = (e) => boundResponseMiddleware ?
-                        boundResponseMiddleware(errorHandler(e), { request, profile }) : errorHandler(e);
-                    return result.catch(errorHandlerWithMiddleware);
-                }
-                else {
-                    return result;
-                }
-            }
-            else if (boundResponseMiddleware) {
-                return boundResponseMiddleware(undefined, { request, profile });
-            }
-        }
-        catch (e) {
-            if (errorHandler && e instanceof Error) {
-                return boundResponseMiddleware ? boundResponseMiddleware(errorHandler(e), { request, profile }) : errorHandler(e);
-            }
-            throw e;
-        }
-        return undefined;
-    };
-};
-exports.makeGetRequestResponder = makeGetRequestResponder;
-const apiJsonResponse = (statusCode, data, headers) => ({ statusCode, data, body: JSON.stringify(data), headers: { ...headers, 'content-type': 'application/json' } });
-exports.apiJsonResponse = apiJsonResponse;
-const apiTextResponse = (statusCode, data, headers) => ({ statusCode, data, body: data, headers: { ...headers, 'content-type': 'text/plain' } });
-exports.apiTextResponse = apiTextResponse;
-const apiHtmlResponse = (statusCode, data, headers) => ({ statusCode, data, body: data, headers: { ...headers, 'content-type': 'text/html' } });
-exports.apiHtmlResponse = apiHtmlResponse;
-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 = exports.METHOD || (exports.METHOD = {}));
-/* utils and middleware for loading request payload (must follow this pattern for `PayloadForRoute` to work) */
-// use this to support case insensitive header keys
-// note if there are multiple headers of the same value, this only returns the first value
-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;
-};
-exports.getHeader = getHeader;
-const getRequestBody = (request) => {
-    if ((0, exports.getHeader)(request.headers, 'content-type') !== 'application/json') {
-        throw new errors_1.InvalidRequestError('unknown content type: ' + (0, exports.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 errors_1.InvalidRequestError((0, assertions_1.assertErrorInstanceOf)(error, SyntaxError).message);
-    }
-};
-exports.getRequestBody = getRequestBody;
-// stub validator because writing validators is annoying
-const unsafePayloadValidator = () => (input) => {
-    return (0, guards_1.isPlainObject)(input) && Object.keys(input).length > 0;
-};
-exports.unsafePayloadValidator = unsafePayloadValidator;
-/*
- * the given validator is a guard, which provides the correct type this helper loads the body, runs the validator, throws if it isn't valid, or returns it as
- * the correct type if it is valid.
- *
- * this 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
- *
- * eg:
- *   export const exampleRoute = createRoute({name: 'exampleRoute', method: METHOD.POST, path: '/example/:id',
- *     requestServiceProvider: composeServiceMiddleware(
- *       requestServiceProvider, // previously compiled middleware can be re-composed if you have something to add
- *       requestPayloadProvider(validatePayload)
- *     )},
- *     async(params: {id: string}, services) => {
- *       const result = await services.myDocumentStore.putItem({
- *         ...services.payload,
- *         id: params.id,
- *       });
- *       return apiJsonResponse(201, result);
- *     }
- *   );
- * */
-const requestPayloadProvider = (validator) => () => (requestServices) => {
-    const payload = (0, exports.getRequestBody)(requestServices.request);
-    // for more precise error messages, throw your own InvalidRequestError from your validator function
-    if (!validator(payload)) {
-        throw new errors_1.InvalidRequestError();
-    }
-    return { ...requestServices, payload };
-};
-exports.requestPayloadProvider = requestPayloadProvider;