@openstax/ts-utils 1.34.0 → 1.35.0

package/packages/utils/src/misc/hashValue.ts

@@ -1,18 +0,0 @@
-import { createHash } from 'crypto';
-
-export type HashValue = string | number | boolean | null | HashCompoundValue;
-export type HashCompoundValue = Array<HashValue> | {[key: string]: HashValue};
-
-/**
- * creates a string hash of lots of different kinds of things.
- *
- * @example hashValue({someKey: 'someValue'})
- */
-export const hashValue = (value: HashValue) => {
-  // hack for sorting keys https://stackoverflow.com/a/53593328/14809536
-  const allKeys = new Set<string>();
-  JSON.stringify(value, (k, v) => (allKeys.add(k), v));
-  const strValue = JSON.stringify(value, Array.from(allKeys).sort());
-
-  return createHash('sha1').update(strValue).digest('hex');
-};

package/packages/utils/src/misc/helpers.ts

@@ -1,259 +0,0 @@
-import type { Logger } from '../services/logger';
-
-/*
- * there was a reason i made these instead of using lodash/fp but i forget what it was. i think maybe
- * these do more validation that the second function gets a compatible object.
- */
-
-/**
- * Returns a function that gets the value of the given key from an object
- *
- * @param key
- * @example
- * const getAuthor = getKeyValue('author');
- * const author = getAuthor(book);
- */
-export const getKeyValue = <K extends string>(key: K) => <O extends {[_key in K]?: any}>(obj: O): O[K] => obj[key];
-
-/**
- * Returns a function that gets the value of the given key from an object, or the given default
- * value if the key is not present.
- *
- * @param key
- * @param defaultValue a default value matching the type of the value at the given key
- * @example
- * const getAuthorOrNope = getKeyValueOr('author', 'nope');
- * const authorOrNope = getAuthorOrNope(book);
- */
-export const getKeyValueOr = <K extends string, V, Od extends {[_key in K]?: any} = {[_key in K]?: any}>(key: K, defaultValue: V) => <O extends (Od extends undefined ? {[_key in K]?: any} : Od)>(obj: O): NonNullable<O[K]> | V => obj[key] || defaultValue;
-
-/**
- * Returns a function that sets the value of the given key on an object.
- *
- * @param key
- * @example
- * const putAuthor = putKeyValue('author');
- * const newBook = putAuthor(book, 'tom');
- */
-export const putKeyValue = <K extends string>(key: K) => <O extends {[_key in K]?: any}>(obj: O, value: O[K]): O => ({...obj, [key]: value});
-
-/**
- * Coerces a value into an array. If the value is already an array, it is returned as-is.
- * If the value is undefined, an empty array is returned.
- *
- * @param thing the value
- * @returns an array
- */
-export const coerceArray = <T>(thing: undefined | T | T[]): T[] => thing instanceof Array ? thing : thing !== undefined ? [thing] : [];
-
-type FlowFn<A, R> = (...args: [A]) => R;
-type AnyFlowFn = FlowFn<any, any>;
-type FlowFnResult<F, A> = F extends FlowFn<A, infer R> ? R : never;
-type FlowResult<C, A> = C extends [infer F1, ...infer Cr]
-  ? F1 extends AnyFlowFn
-    ? Cr extends never[]
-      ? FlowFnResult<F1, A>
-      : FlowResult<Cr, FlowFnResult<F1, A>>
-    : never
-  : never
-;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-type FlowChainArg<C> = C extends [infer F1, ...infer _]
-  ? F1 extends FlowFn<infer A, any>
-    ? A
-    : never
-  : never
-;
-
-/**
- * this is like lodash/flow but it uses a recursive type instead of hard-coding parameters
- */
-export const flow = <C extends AnyFlowFn[]>(...chain: C) => (param: FlowChainArg<C>): FlowResult<C, FlowChainArg<C>> => {
-  let result: any = param;
-
-  for (const fn of chain) {
-    result = fn(result);
-  }
-
-  return result;
-};
-
-export type RetryOptions = {
-  logger?: Logger;
-  wait?: number;
-  splay?: number;
-  retries?: number;
-  n?: number;
-};
-
-/**
- * Retries a function with a delay between retries.
- * @param fn The function to retry
- * @param [options] retry options
- * @param [options.wait=100] base wait of first retry (number), further retries are: t=n*wait,
- * default: 100
- * @param [options.splay=0.5] percentage to modify t by. 0.5 is 50%, which would make
- * t=n*wait+rand(wait*splay*-1, wait*splay), default: 0.5
- * @param [options.retries=2] number of times to retry. (2 retries means it'll try a max of 3 times),
- * default: 2
- * @param [options.n=0] the starting retry index. probably don't set this. unless you really want a very steep
- *  initial wait cliff with incremental increases, then maybe you'd set this. default: 0
- * @returns A promise that resolves with the result of the function, or rejects with the last error.
- */
-export const retryWithDelay = <R>(fn: (abort?: (e: Error) => never) => Promise<R>, options?: RetryOptions): Promise<R> => {
-  const {wait, splay, retries, n} = {wait: 100, splay: 0.5, retries: 2, n: 0, ...options};
-
-  if (n >= retries) {
-    return fn();
-  }
-
-  let aborted = false;
-
-  const timeout = (n+1)*wait+(Math.random() * 2 - 1) * splay * wait;
-  const retry = (e: Error) => new Promise<R>((resolve, reject) => {
-    if (aborted) {
-      reject(e);
-    }
-    else {
-      options?.logger?.log(`failed try ${n + 1} of ${retries}. ${e.message}`);
-      setTimeout(() => retryWithDelay(fn, {...options, n: n+1}).then(resolve, reject), timeout);
-    }
-  });
-  const abort = (e: Error): never => {
-    aborted = true;
-    throw e;
-  };
-
-  return fn(abort).catch(retry);
-};
-
-/**
- * a shameful helper to avoid needing to test code coverage of branches
- */
-export const fnIf = <T1, T2>(condition: boolean, trueValue: T1, falseValue: T2) => condition ? trueValue : falseValue;
-
-/**
- * maps the array and returns the first result that matches the predicate
- * avoids processing extra elements that would happen with .map().find() or .reduce
- *
- * eg the third element of the array is never processed:
- *   const result = mapFind([1,2,3], x => 'hello'.charAt(x), x => x === 'l');
- */
-export const mapFind = <I, R>(array: I[], mapper: (item: I) => R, predicate: (result: R) => boolean = (r: any) => !!r): R | undefined => {
-  for (const item of array) {
-    const mapped = mapper(item);
-
-    if (predicate(mapped)) {
-      return mapped;
-    }
-  }
-};
-
-/**
- * returns a function that will only ever call the given function once, returning the first result for every subsequent call
- *
- * does not cache rejected promises, to avoid cache poisoning on failed async requests
- *
- * eg:
- *   const heavyFunction = () => 'hello';
- *   const butOnlyOnce = once(() => 'hello');
- *
- *   heavyFunction() // returns `hello`;
- *   butOnlyOnce() // returns `hello`;
- */
-export const once = <F extends (...args: any[]) => any>(fn: F): F => {
-  const initialValue = {} as any as ReturnType<F>;
-  let result: ReturnType<F> = initialValue;
-  return ((...args: Parameters<F>) => {
-    if (result !== initialValue) {
-      return result;
-    }
-    result = fn(...args);
-    if (typeof result === 'object' && result as object instanceof Promise) {
-      // Clear the result when possible but do not return a Promise that resolves to the initialValue
-      (result as Promise<any>).catch(() => result = initialValue);
-    }
-    // If this is a rejected Promise, it should be returned before catch() actually overwrites it
-    return result;
-  }) as F;
-};
-
-/**
- * memoizes a function with any number of arguments
- *
- * does not cache rejected promises, to avoid cache poisoning on failed async requests
- */
-export const memoize = <F extends (...args: any[]) => any>(fn: F): F => {
-  interface CacheLayer {
-    weakLayers?: WeakMap<any, CacheLayer>;
-    strongLayers?: Map<any, CacheLayer>;
-    result?: ReturnType<F>;
-  }
-  const cache: CacheLayer = {};
-
-  const resolveCache = (cacheLayer: CacheLayer, [first, ...rest]: any[]): CacheLayer => {
-    if (!first) {
-      return cacheLayer;
-    }
-
-    const layers = first instanceof Object
-      ? (cacheLayer.weakLayers = (cacheLayer.weakLayers || (typeof WeakMap === 'undefined' ? undefined : new WeakMap())))
-      : (cacheLayer.strongLayers = (cacheLayer.strongLayers || new Map()))
-    ;
-
-    // argument is an object and WeakMap is not supported
-    if (!layers) {
-      return {};
-    }
-
-    const layer = layers.get(first) || {};
-
-    if (!layers.has(first)) {
-      layers.set(first, layer);
-    }
-
-    return resolveCache(layer, rest);
-  };
-
-  return ((...args: Parameters<F>) => {
-    const thisCache = resolveCache(cache, args);
-    if ('result' in thisCache) {
-      return thisCache.result;
-    }
-    thisCache.result = fn(...args);
-    if (typeof thisCache.result === 'object' && thisCache.result as object instanceof Promise) {
-      // Clear the result when possible but do not return a Promise that resolves to the initialValue
-      (thisCache.result as Promise<any>).catch(() => delete thisCache.result);
-    }
-    return thisCache.result;
-  }) as F;
-};
-
-/**
- * rounds number to given number of places
- *
- * eg:
- *  roundToPrecision(1234.123, 2); // returns 1200
- *  roundToPrecision(1234.123, -2); // returns 1234.12
- *  roundToPrecision(1234.125, -2); // returns 1234.13
- */
-export const roundToPrecision = (num: number, places: number) => {
-  const multiplier = Math.pow(10, -1 * places);
-  // https://stackoverflow.com/a/11832950/14809536
-  return Math.round((num + Number.EPSILON) * multiplier) / multiplier;
-};
-
-/**
- * a silly utility to help typescript realize an array is a tuple
- *
- * eg:
- *  const a = [5, 'string'] // type is `Array<string | number>`
- *  const t = tuple(5, 'string') type is `[5, 'string']`
- *
- * both have the same javascript value, but one is forced to be a tuple, which
- * is nice if its structure is important. examples are like the React.useState
- * pattern where there are two return values in a tuple, or if you're feeding
- * Object.fromEntries
- *
- */
-export const tuple = <A extends any[]>(...args: A) => args;

package/packages/utils/src/misc/merge.ts

@@ -1,48 +0,0 @@
-import { isPlainObject } from '../guards';
-import type { UnionToIntersection } from '../types';
-
-/**
- * Takes two objects and returns an array of the keys that are common to both, with a type
- * limited to those keys.
- *
- * @param thing1 some object
- * @param thing2 another object
- * @returns an array of keys, type-limited to those keys
- */
-export const getCommonProperties = <T1 extends {}, T2 extends {}>(thing1: T1, thing2: T2) =>
-  Object.keys(thing1).filter((key) => Object.keys(thing2).includes(key)) as Array<keyof T1 & keyof T2>;
-
-/**
- * recursive merge properties of inputs. values are merged if they are
- * plain objects or arrays, otherwise if the same property exists in both
- * objects the value from the second argument will win.
- *
- * unlike lodash merge, this will not change object references for values that
- * exist only in one parameter.
- *
- * @example merge({thing: 'one'}, {thing: 'two', otherKey: 'one'}, {coolKey: 'coolValue'});
- */
-export const merge = <T extends Array<{}>>(...[thing1, ...tail]: T): UnionToIntersection<T[number]> => {
-
-  const mergedTail = tail.length > 0
-    ? merge(...tail)
-    : null;
-
-  if (!mergedTail) {
-    return thing1 as UnionToIntersection<T[number]>;
-  }
-
-  return {
-    ...thing1,
-    ...mergedTail,
-    ...getCommonProperties(thing1, mergedTail).reduce((result, property) => ({
-      ...result,
-      ...(isPlainObject(thing1[property]) && isPlainObject(mergedTail[property])
-        ? {[property]: merge(thing1[property], mergedTail[property])}
-        : (Array.isArray(thing1[property]) && Array.isArray(mergedTail[property]))
-          ? {[property]: [...thing1[property] as unknown as [], ...mergedTail[property] as unknown as []]}
-          : {}
-      ),
-    }), {}),
-  } as UnionToIntersection<T[number]>;
-};

package/packages/utils/src/pagination/index.spec.ts

@@ -1,150 +0,0 @@
-import { getKeyValue, putKeyValue } from '..';
-import { InvalidRequestError } from '../errors';
-import { createPaginationMiddleware, loadMorePagination, pageNumberPagination } from '../pagination';
-import { makeCreateRoute, QueryParams } from '../routing';
-
-interface RouteRequest {
-  method: string;
-  path: string;
-  query: {[key: string]: string | undefined};
-}
-interface AppServices {
-}
-
-const createRoute = makeCreateRoute<AppServices, RouteRequest>();
-const route = createRoute({name: 'testRoute', path: '/foobar', handler: (_: {}) => ({body: 'body'})});
-
-describe('createPaginationMiddleware', () => {
-  it('removes unused query from request', () => {
-    const middleware = createPaginationMiddleware<RouteRequest>()({
-      getQueryParams: getKeyValue('query'),
-      setUnusedQueryParams: putKeyValue('query'),
-      paginator: jest.fn(() => ({getUnusedQueryParams: () => ({unused: 'query'})}))
-    });
-
-    const services = middleware()({request: {method: 'GET', path: '/foo', query: {some: 'query'}}}, {route, params: {}});
-
-    expect(services.request.query).toEqual({unused: 'query'});
-  });
-});
-
-describe('loadMorePaginationMiddleware', () => {
-  it('gives page token as string', () => {
-    const pagination = loadMorePagination<typeof route, QueryParams>({pageToken: 'foobar'}, {route, params: {}});
-    expect(pagination.getPageTokenString()).toBe('foobar');
-  });
-
-  it('gives page token as number', () => {
-    const pagination = loadMorePagination<typeof route, QueryParams>({pageToken: '7'}, {route, params: {}});
-    expect(pagination.getPageTokenNumber()).toBe(7);
-  });
-
-  it('gives page token as number (default)', () => {
-    const pagination = loadMorePagination<typeof route, QueryParams>({}, {route, params: {}});
-    expect(pagination.getPageTokenNumber()).toBeUndefined();
-  });
-
-  it('throws on invalid number', () => {
-    const pagination = loadMorePagination<typeof route, QueryParams>({pageToken: 'foobar'}, {route, params: {}});
-    expect(() => pagination.getPageTokenNumber()).toThrow();
-  });
-
-  it('builds a response', () => {
-    const pagination = loadMorePagination<typeof route, QueryParams>({pageToken: 'foobar'}, {route, params: {}});
-    expect(pagination.getPaginationResponse({items: [1,2,3], nextPageToken: undefined})).toEqual({
-      items: [1,2,3],
-      meta: {},
-      links: {},
-    });
-  });
-
-  it('builds a response with next page token', () => {
-    const pagination = loadMorePagination<typeof route, QueryParams>({pageToken: 'foobar'}, {route, params: {}});
-    expect(pagination.getPaginationResponse({items: [1,2,3], nextPageToken: 'next token'})).toEqual({
-      items: [1,2,3],
-      meta: {nextPageToken: 'next token'},
-      links: {nextPage: '/foobar?pageToken=next%20token'},
-    });
-  });
-
-  it('gets remaining query params', () => {
-    const pagination = loadMorePagination<typeof route, QueryParams>({pageToken: '7', otherParam: 'other'}, {route, params: {}});
-    expect(pagination.getUnusedQueryParams()).toEqual({otherParam: 'other'});
-  });
-});
-
-describe('pageNumberPaginationMiddleware', () => {
-  it('gives pagination params', () => {
-    const pagination = pageNumberPagination<typeof route, QueryParams>({page: '2'}, {route, params: {}});
-    expect(pagination.getPaginationParams()).toEqual({page: 2});
-  });
-
-  it('gives pagination params (default)', () => {
-    const pagination = pageNumberPagination<typeof route, QueryParams>({}, {route, params: {}});
-    expect(pagination.getPaginationParams()).toEqual({page: undefined});
-  });
-
-  it('throws on invalid number', () => {
-    expect(() => pageNumberPagination<typeof route, QueryParams>({page: 'asdf'}, {route, params: {}})).toThrow(InvalidRequestError);
-  });
-
-  it('build pagination response', () => {
-    const pagination = pageNumberPagination<typeof route, QueryParams>({page: '2'}, {route, params: {}});
-    expect(pagination.getPaginationResponse({items: [1,2,3], pageSize: 5, currentPage: 2, totalItems: 15, totalPages: 3})).toEqual({
-      items: [1,2,3],
-      meta: {
-        pageSize: 5,
-        currentPage: 2,
-        totalItems: 15,
-        totalPages: 3,
-      },
-      links: {
-        firstPage: '/foobar?page=1',
-        lastPage: '/foobar?page=3',
-        nextPage: '/foobar?page=3',
-        prevPage: '/foobar?page=1',
-      }
-    });
-  });
-
-  it('omits previous when there isn\'t one', () => {
-    const pagination = pageNumberPagination<typeof route, QueryParams>({page: '1'}, {route, params: {}});
-    expect(pagination.getPaginationResponse({items: [1,2,3], pageSize: 5, currentPage: 1, totalItems: 15, totalPages: 3})).toEqual({
-      items: [1,2,3],
-      meta: {
-        pageSize: 5,
-        currentPage: 1,
-        totalItems: 15,
-        totalPages: 3,
-      },
-      links: {
-        firstPage: '/foobar?page=1',
-        lastPage: '/foobar?page=3',
-        nextPage: '/foobar?page=2',
-      }
-    });
-  });
-
-  it('omits next when there isn\'t one', () => {
-    const pagination = pageNumberPagination<typeof route, QueryParams>({page: '3'}, {route, params: {}});
-    expect(pagination.getPaginationResponse({items: [1,2,3], pageSize: 5, currentPage: 3, totalItems: 15, totalPages: 3})).toEqual({
-      items: [1,2,3],
-      meta: {
-        pageSize: 5,
-        currentPage: 3,
-        totalItems: 15,
-        totalPages: 3,
-      },
-      links: {
-        firstPage: '/foobar?page=1',
-        lastPage: '/foobar?page=3',
-        prevPage: '/foobar?page=2',
-      }
-    });
-  });
-
-  it('gets remaining query params', () => {
-    const pagination = pageNumberPagination<typeof route, QueryParams>({page: '3', otherParam: 'other'}, {route, params: {}});
-    expect(pagination.getUnusedQueryParams()).toEqual({otherParam: 'other'});
-  });
-});

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

@@ -1,117 +0,0 @@
-import { notNaN } from '../assertions';
-import { InvalidRequestError } from '../errors';
-import { QueryParams, renderAnyRouteUrl, RouteMatchRecord } from '../routing';
-
-export type PaginationHandler<Pa, Q extends QueryParams> = <R>(queryParams: Q, match: RouteMatchRecord<R>) => Pa & {
-  getUnusedQueryParams: () => Q;
-};
-
-/**
- * helper to create middleware with the given paginator. aside from taking care of annoying to write pagination logic, these helpers also make
- * sure that all item list responses have the same formatting.
- *
- * eg:
- *   const getQueryParams = getKeyValueOr('queryStringParameters', {} as QueryParams);
- *   const setUnusedQueryParams = putKeyValue('queryStringParameters');
- *
- *   export const loadMorePaginationMiddleware = createPaginationMiddleware<ApiRouteRequest>()({getQueryParams, setUnusedQueryParams, paginator: loadMorePagination});
- *   export const pageNumberPaginationMiddleware = createPaginationMiddleware<ApiRouteRequest>()({getQueryParams, setUnusedQueryParams, paginator: pageNumberPagination});
- *
- * eg the pagination middleware then provides your necessary inputs (getPageToken... in this case) and formats the response:
- *  const result = await services.myDocumentStore.getVersions(key, services.pagination.getPageTokenNumber());
- *
- *  if (!result) {
- *    throw new NotFoundError('requested item not found');
- *  }
- *
- *  return apiJsonResponse(200, services.pagination.getPaginationResponse(result));
- */
-export const createPaginationMiddleware = <Ri, Q extends QueryParams = {[key: string]: string | undefined}, R = any>() =>
-  <Pa>({getQueryParams, setUnusedQueryParams, paginator}: {
-    getQueryParams: (request: Ri) => Q;
-    setUnusedQueryParams: (request: Ri, query: Q) => Ri;
-    paginator: PaginationHandler<Pa, Q>;
-  }) => <M extends {request: Ri}>() => (middleware: M, match: RouteMatchRecord<R>) => {
-    const queryParams = getQueryParams(middleware.request);
-    const pagination = paginator(queryParams, match);
-
-    // remove pagination params from downstream logic
-    middleware.request = setUnusedQueryParams(middleware.request, pagination.getUnusedQueryParams());
-
-    return {...middleware, pagination};
-  };
-
-  export const loadMorePagination = <R, Q extends QueryParams>(queryParams: Q, {route, params}: RouteMatchRecord<R>) => {
-    const {pageToken, ...otherParams} = queryParams;
-
-    return {
-      getUnusedQueryParams: () => otherParams,
-      getPageTokenString: () => pageToken,
-      getPageTokenNumber: () => pageToken && typeof pageToken === 'string'
-        ? notNaN(parseInt(pageToken, 10), () => { throw new InvalidRequestError(); })
-        : undefined
-      ,
-      getPaginationResponse: <T>({items, ...meta}: LoadMorePaginationResultInput<T>) => {
-        return {
-          items,
-          meta,
-          links: {
-            nextPage: meta.nextPageToken
-              ? renderAnyRouteUrl(route, params, {...queryParams, pageToken: meta.nextPageToken.toString()})
-              : undefined,
-          }
-        };
-      },
-    };
-  };
-
-/**
- * if you're writing a data loader, this is what you need to return to be compatible with the loadMore style paginator.
- * this is how the response formatter knows the token for the next page to put in the response metadata.
- * */
-export interface LoadMorePaginationResultInput<T> {
-  items: T[];
-  nextPageToken: string | number | undefined;
-}
-
-export const pageNumberPagination = <R, Q extends QueryParams>(queryParams: Q, {route, params}: RouteMatchRecord<R>) => {
-  const {page, ...otherParams} = queryParams;
-
-  const numberPage = page && typeof page === 'string'
-    ? notNaN(parseInt(page, 10), () => { throw new InvalidRequestError(); })
-    : undefined;
-
-  return  {
-    getUnusedQueryParams: () => otherParams,
-    getPaginationParams: () => ({page: numberPage}),
-    getPaginationResponse: <T>({items, ...meta}: PageNumberPaginationResultInput<T>) => {
-
-      return {
-        items,
-        meta,
-        links: {
-          firstPage: renderAnyRouteUrl(route, params, {...queryParams, page: '1'}),
-          lastPage: renderAnyRouteUrl(route, params, {...queryParams, page: meta.totalPages.toString()}),
-          nextPage: meta.currentPage < meta.totalPages
-            ? renderAnyRouteUrl(route, params, {...queryParams, page: (meta.currentPage + 1).toString()})
-            : undefined,
-          prevPage: meta.currentPage > 1
-            ? renderAnyRouteUrl(route, params, {...queryParams, page: (meta.currentPage - 1).toString()})
-            : undefined
-        }
-      };
-    },
-  };
-};
-
-/**
- * if you're writing a data loader, this is what you need to return to be compatible with the pageNumber style paginator.
- * this is how the response formatter knows the information to put in the response metadata.
- * */
-export interface PageNumberPaginationResultInput<T> {
-  items: T[];
-  pageSize: number;
-  currentPage: number;
-  totalItems: number;
-  totalPages: number;
-}