@openstax/ts-utils 1.1.30 → 1.1.32

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

@@ -0,0 +1,96 @@
+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 * from './helpers';

package/dist/esm/routing/index.js

@@ -0,0 +1,144 @@
+import * as pathToRegexp from 'path-to-regexp';
+import queryString from 'query-string';
+import { mapFind, memoize } from '../misc/helpers';
+import { createProfile } from '../profile';
+/*
+ * 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);
+ *     }
+ *   });
+ */
+export const makeCreateRoute = () => (...args) => {
+    return (args.length === 1
+        ? args[0]
+        : { ...args[0], handler: args[1] });
+};
+/* begin reverse routing utils */
+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;
+};
+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, 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)
+ *     );
+ */
+export const makeGetRequestResponder = () => ({ routes, pathExtractor, routeMatcher, errorHandler }) => (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;
+    // *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 } = createProfile(new Date().toISOString()).start();
+        try {
+            const executor = 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;
+    };
+};
+export const apiJsonResponse = (statusCode, data, headers) => ({ statusCode, data, body: JSON.stringify(data), headers: { ...headers, 'content-type': 'application/json' } });
+export const apiTextResponse = (statusCode, data, headers) => ({ statusCode, data, body: data, headers: { ...headers, 'content-type': 'text/plain' } });
+export const apiHtmlResponse = (statusCode, data, headers) => ({ statusCode, data, body: data, headers: { ...headers, 'content-type': 'text/html' } });
+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/services/authProvider/decryption.js

@@ -1,7 +1,7 @@
 import { compactDecrypt, compactVerify, importSPKI } from 'jose';
-import { once } from '../..';
 import { resolveConfigValue } from '../../config/resolveConfigValue';
 import { ifDefined } from '../../guards';
+import { once } from '../../misc/helpers';
 import { getAuthTokenOrCookie } from '.';
 export const decryptionAuthProvider = (initializer) => (configProvider) => {
     const config = configProvider[ifDefined(initializer.configSpace, 'decryption')];