@openstax/ts-utils 1.34.0 → 1.34.1

package/packages/utils/src/routing/index.ts

@@ -1,424 +0,0 @@
-import * as pathToRegexp from 'path-to-regexp';
-import queryString from 'query-string';
-import { mapFind, memoize } from '../misc/helpers';
-import { Logger } from '../services/logger';
-import { createConsoleLogger } from '../services/logger/console';
-
-/* begin route structures */
-
-/* Generic type meanings:
- *  R: route. usually a placeholder for a specific route.
- *  Ru: route union. union of all actual routes defined by the application.
- *  Ri: route input. the router input, could be `Window.Location`, or `APIGatewayProxyEventV2` or something like that
- *  Ro: route output. the interface for what routes return. could be a react component, or the `ApiResponse` defined below
- *  RoF: route output final. the route output after response middleware runs. for instance in an api Ro will usually include `undefined` but 404 handling middleware will remove make RoF always `ApiResponse`
- *  P: route params. the uri parameters of the route
- *  Sa: app services. the app services (or service drivers) defined by the app entrypoint.
- *  Sr: request services. the request services built by this routes middleware chain.
- *  Ex: extension type. for arbitrary extra stuff only used in certain context, like METHOD in api routes.
- *  N: route name. union discriminator, and used as the api client method name when using the ApiGateway service.
- */
-
-/** HTTP query parameters */
-export 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 type RouteParams = {[key: string]: string};
-
-/** A type that is compatible with any `Route` type */
-export 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 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 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 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 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 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 type RouteMatchRecord<R> = R extends AnyRoute<R> ? {route: R; params: ParamsForRoute<R>} : never;
-
-
-type Flatten<T> = T extends any ? { [K in keyof T]: T[K] } : never;
-export type ExternalRoute<R> = R extends Route<infer N, infer P, infer Sa, infer Sr, infer Ri, infer Ro> & infer E
-  ? Route<N, P, Sa, Sr extends {payload: any} ? Flatten<Pick<Sr, 'payload'>> : Record<string, never>, Ri, Ro>
-    & Flatten<Omit<E, 'name' | 'path' | 'handler' | 'requestServiceProvider'>>
-  : never;
-
-/** this utility simplifies the route type to remove stuff that is only
- * relevant internal to the route, like the service types, keeping only
- * the payload type which is necessary for the apiGateway
- *
- * this helps avoid the "type too complicated" error that typescript throws
- * when there are a lot of routes with complex services
- **/
-export const routesList = <R>(routes: R[]) => routes as ExternalRoute<R>[];
-
-/**
- * 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 type PayloadForRoute<R> = RequestServicesForRoute<R> extends {payload: any}
-  ? RequestServicesForRoute<R>['payload']
-  : undefined;
-
-/* begin route creation helpers */
-
-// specifies `any` for output because i'm pretty sure it doesn't matter and it confuses the MakeRequestResponder type
-type RequestServiceProvider<Sa, Sr, Ri> = (app: Sa) => <R>(middleware: {request: Ri; logger: Logger}, match: RouteMatchRecord<R>) => Sr;
-type RouteHandler<P, Sr, Ro> = (params: P, request: Sr) => Ro;
-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}
-;
-
-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 const makeCreateRoute = <Sa, Ri, Ex = {}>(): CreateRoute<Sa, Ri, Ex> => <N extends string, Ro, Sr, P extends RouteParams | undefined = undefined>(...args: [CreateRouteConfig<Sa, Sr, Ri, N, Ex> & {handler: RouteHandler<P, Sr, Ro>}] | [CreateRouteConfig<Sa, Sr, Ri, N, Ex>, RouteHandler<P, Sr, Ro>]): Route<N, P, Sa, Sr, Ri, Ro> & Ex => {
-
-  return (args.length === 1
-    ? args[0]
-    : {...args[0], handler: args[1]}
-  ) as Route<N, P, Sa, Sr, Ri, Ro> & Ex;
-};
-
-/* 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 = <Ru extends {path: string}>() => <R>(
-  route: ExternalRoute<R> extends Ru ? R & {path: string} : R extends Ru ? R : never,
-  params: ParamsForRoute<R>,
-  query: QueryParams = {}
-) => {
-  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<any>();
-
-/* begin request responder */
-
-type RequestPathExtractor<Ri> = (request: Ri) => string;
-type RequestLogExtractor<Ri> = (request: Ri) => JsonCompatibleStruct;
-type RequestRouteMatcher<Ri, R> = (request: Ri, route: R) => boolean;
-type AppBinder = <Sa, F extends ((app: Sa, appBinder?: AppBinder) => any)>(app: Sa, middleware: F) => ReturnType<F>;
-
-const bindRoute = <Sa, R, Ri, Ro>(services: Sa, appBinder: AppBinder, pathExtractor: RequestPathExtractor<Ri>, matcher?: RequestRouteMatcher<Ri, AnySpecificRoute<R, Sa, Ri, Ro>>) => (route: AnySpecificRoute<R, Sa, Ri, Ro>) => {
-  const getParamsFromPath = pathToRegexp.match<ParamsForRouteOrEmpty<R>>(route.path, { decode: decodeURIComponent });
-  const boundServiceProvider = route.requestServiceProvider && appBinder(services, route.requestServiceProvider);
-
-  return (request: Ri, logger: Logger) => {
-    const path = pathExtractor(request);
-    const match = getParamsFromPath(path);
-
-    if ((!matcher || matcher(request, route)) && match) {
-      return {
-        name: route.name,
-        executor: () => route.handler(match.params, boundServiceProvider ? boundServiceProvider<R>({request, logger}, {route, params: match.params} as any) : undefined)
-      };
-    }
-  };
-};
-
-// this is a hack around weak type detection blocking use of the system without specifying a logger
-// https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-4.html#weak-type-detection
-type CompatibleServices<T1> = keyof T1 extends 'logger' ? T1 extends {logger: Logger} ? T1 : never : T1 & {logger?: Logger};
-
-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 const makeGetRequestResponder = <Sa, Ru, Ri, Ro>() => (
-  {routes, pathExtractor, routeMatcher, errorHandler, logExtractor}: {
-    routes: () => AnySpecificRoute<Ru, Sa, Ri, Ro>[];
-    pathExtractor: RequestPathExtractor<Ri>;
-    logExtractor?: RequestLogExtractor<Ri>;
-    routeMatcher?: RequestRouteMatcher<Ri, AnySpecificRoute<Ru, Sa, Ri, Ro>>;
-    errorHandler?: (e: Error, logger: Logger) => Ro;
-  }
-): RequestResponder<Sa, Ri, Ro> => <RoF>(
-  services: CompatibleServices<Sa>,
-  responseMiddleware?: (app: Sa) => (response: Ro | undefined, request: {request: Ri; logger: Logger}) => RoF
-) => {
-  const appBinderImpl: AppBinder = (app, middleware) => middleware(app, appBinder);
-  const appBinder = memoize(appBinderImpl);
-  const boundRoutes = routes().map(bindRoute<Sa, Ru, Ri, Ro>(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 = <T>(thing: T): thing is T & {
-    catch: <R extends T>(handler: (e: any) => R) => T | R;
-    then: <R extends T>(handler: (p: unknown) => R) => R;
-  } => thing instanceof Promise;
-
-  return (request: Ri): undefined | Ro | RoF => {
-    const logger = appLogger.createSubContext();
-
-    if (logExtractor) {
-      logger.setContext(logExtractor(request));
-    }
-
-    logger.log('begin request');
-
-    try {
-      const route = mapFind(boundRoutes, (route) => route(request, logger));
-
-      if (route) {
-        logger.log(`route matched ${route.name}`);
-
-        const result = boundResponseMiddleware ?
-          boundResponseMiddleware(route.executor(), {request, logger}) : route.executor();
-
-        if (isPromise(result) && errorHandler) {
-          const errorHandlerWithMiddleware = (e: Error) => boundResponseMiddleware ?
-            boundResponseMiddleware(errorHandler(e, logger), {request, logger}) : errorHandler(e, logger);
-
-          return result.catch(errorHandlerWithMiddleware);
-        } else {
-          return result;
-        }
-      } else if (boundResponseMiddleware) {
-        logger.log('no route matched, returning 404');
-        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;
-  };
-};
-
-/* begin mixin utils for API side */
-
-/** HTTP Headers */
-export type HttpHeaders = {[key: string]: string | undefined | string[]};
-
-/** A type that works in JSON */
-export type JsonCompatibleValue = string | number | null | undefined | boolean;
-
-/** A JSON array type */
-export type JsonCompatibleArray = Array<JsonCompatibleValue | JsonCompatibleStruct | JsonCompatibleStruct>;
-
-/** A JSON object type */
-export type JsonCompatibleStruct = {[key: string]: JsonCompatibleStruct | JsonCompatibleValue | JsonCompatibleArray};
-
-/** The type for an API response */
-export 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 const apiJsonResponse = <S extends number, T extends JsonCompatibleStruct>(statusCode: S, data: T, headers?: HttpHeaders): ApiResponse<S, T> => ({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 = <S extends number>(statusCode: S, data: string, headers?: HttpHeaders): ApiResponse<S, string> => ({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 = <S extends number>(statusCode: S, data: string, headers?: HttpHeaders): ApiResponse<S, string> => ({statusCode, data, body: data, headers: {...headers, 'content-type': 'text/html'}});
-
-/** HTTP method enum */
-export enum METHOD {
-  GET = 'GET',
-  HEAD = 'HEAD',
-  POST = 'POST',
-  PUT = 'PUT',
-  PATCH = 'PATCH',
-  DELETE = 'DELETE',
-  OPTIONS = 'OPTIONS',
-}
-
-export * from './helpers';

package/packages/utils/src/routing/validators/zod.spec.ts

@@ -1,16 +0,0 @@
-import * as z from 'zod';
-import { ValidationError } from '../../errors';
-import { zodPayloadValidator } from './zod';
-
-describe('zodPayloadValidator', () => {
-
-  it('passes', () => {
-    const schema = z.object({field: z.string()});
-    expect(zodPayloadValidator(schema)({field: 'value'})).toBe(true);
-  });
-  
-  it('fails', () => {
-    const schema = z.object({field: z.string()});
-    expect(() => zodPayloadValidator(schema)({field: 1})).toThrow(ValidationError);
-  });
-});

package/packages/utils/src/routing/validators/zod.ts

@@ -1,14 +0,0 @@
-/* spell-checker: ignore treeify */
-import { treeifyError } from 'zod';
-import type { z } from 'zod';
-import { ValidationError } from '../../errors';
-
-export const zodPayloadValidator = <T extends {}>(validator: z.ZodType<T, T>) => (input: {[key: string]: any}): input is T => {
-  const result = validator.safeParse(input);
-
-  if (result.success) {
-    return true;
-  }
-
-  throw new ValidationError(treeifyError(result.error));
-};

package/packages/utils/src/services/accountsGateway/README.md

@@ -1,3 +0,0 @@
-# accountsGateway
-
-Typing/formatting for interacting with OpenStax Accounts