@openstax/ts-utils 1.1.31 → 1.1.33

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

@@ -0,0 +1,12 @@
+import type { HttpHeaders } from '.';
+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;
+};

package/dist/cjs/routing/helpers.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestPayloadProvider = exports.unsafePayloadValidator = exports.getRequestBody = exports.getHeader = void 0;
+const assertions_1 = require("../assertions");
+const errors_1 = require("../errors");
+const guards_1 = require("../guards");
+// 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;
+/* utils and middleware for loading request payload (must follow this pattern for `PayloadForRoute` to work) */
+// 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;

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

@@ -0,0 +1,182 @@
+"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 __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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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 helpers_1 = require("../misc/helpers");
+const profile_1 = require("../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);
+ *     }
+ *   });
+ */
+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, helpers_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, helpers_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 = {}));
+__exportStar(require("./helpers"), exports);

package/dist/cjs/services/authProvider/decryption.d.ts

@@ -1,4 +1,4 @@
-import { ConfigProviderForConfig } from '../../config';
+import type { ConfigProviderForConfig } from '../../config';
 import { CookieAuthProvider } from '.';
 declare type Config = {
     cookieName: string;

package/dist/cjs/services/authProvider/index.d.ts

@@ -1,6 +1,6 @@
-import { FetchConfig } from '../../fetch';
-import { Track } from '../../profile';
-import { HttpHeaders } from '../../routing';
+import type { FetchConfig } from '../../fetch';
+import type { Track } from '../../profile';
+import type { HttpHeaders } from '../../routing';
 export interface User {
     id: number;
     name: string;

package/dist/cjs/services/authProvider/index.js

@@ -5,8 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAuthTokenOrCookie = exports.stubAuthProvider = void 0;
 const cookie_1 = __importDefault(require("cookie"));
-const __1 = require("../..");
-const routing_1 = require("../../routing");
+const helpers_1 = require("../../misc/helpers");
+const helpers_2 = require("../../routing/helpers");
 const stubAuthProvider = (user) => ({
     getUser: () => Promise.resolve(user),
     getAuthorizedFetchConfig: () => Promise.resolve(user ? { headers: { Authorization: user.uuid } } : {})
@@ -14,10 +14,10 @@ const stubAuthProvider = (user) => ({
 exports.stubAuthProvider = stubAuthProvider;
 const getAuthTokenOrCookie = (request, cookieName) => {
     var _a;
-    const authHeader = (0, routing_1.getHeader)(request.headers, 'authorization');
+    const authHeader = (0, helpers_2.getHeader)(request.headers, 'authorization');
     const cookieValue = cookie_1.default.parse(((_a = request.cookies) === null || _a === void 0 ? void 0 : _a.join('; ')) || '')[cookieName];
     return authHeader && authHeader.length >= 8 && authHeader.startsWith('Bearer ')
-        ? (0, __1.tuple)(authHeader.slice(7), { Authorization: authHeader })
-        : (0, __1.tuple)(cookieValue, { cookie: cookie_1.default.serialize(cookieName, cookieValue) });
+        ? (0, helpers_1.tuple)(authHeader.slice(7), { Authorization: authHeader })
+        : (0, helpers_1.tuple)(cookieValue, { cookie: cookie_1.default.serialize(cookieName, cookieValue) });
 };
 exports.getAuthTokenOrCookie = getAuthTokenOrCookie;