@openstax/ts-utils 1.2.9 → 1.3.0

package/dist/esm/guards.d.ts

@@ -1,6 +1,30 @@
+/**
+ * checks if a thing is defined. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<string>`.
+ *
+ * `const result = (array as Array<string | undefined>).filter(isDefined);`
+ */
 export declare const isDefined: <X>(x: X) => x is Exclude<X, undefined>;
+/**
+ * checks if a thing is a number. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<number>`.
+ *
+ * `const result = (array as Array<number | undefined>).filter(isNumber);`
+ */
 export declare const isNumber: (x: any) => x is number;
+/**
+ * a guard for plain old javascript objects that are not based on some other prototype,
+ * for example making them safe to JSON stringify and stuff
+ */
 export declare const isPlainObject: (thing: any) => thing is {
     [key: string]: any;
 };
+/**
+ * if the first thing is defined it uses it, otherwise it returns the second thing. this isn't
+ * really a guard its just a way to provide a default value without creating a coverage branch.
+ *
+ * @example const valueWithDefault = ifDefined(thing, 'default value')
+ */
 export declare const ifDefined: <X, D>(x: X, d: D) => D | Exclude<X, undefined>;

package/dist/esm/guards.js

@@ -1,29 +1,28 @@
-/*
- * checks if a thing is defined. this is often easy to do with a simple if statement, but in certain
- * situations the guard is required and its nice to have one pre-defined.
+/**
+ * checks if a thing is defined. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<string>`.
  *
- * eg this filters the array but doesn't fix the array type:
- *   const result = (array as Array<string | undefined>).filter(thing => !!thing);
- *
- * eg this does the right thing:
- *   const result = (array as Array<string | undefined>).filter(isDefined);
- *
- * eg because writing this is annoying:
- *   const result = (array as Array<string | undefined>).filter(<X>(x: X): x is Exclude<X, undefined> => x !== undefined);
+ * `const result = (array as Array<string | undefined>).filter(isDefined);`
  */
 export const isDefined = (x) => x !== undefined;
+/**
+ * checks if a thing is a number. while often easy to do with a simple if statement, in certain
+ * situations the guard is required and its nice to have one pre-defined. E.g. in the following
+ * example, the result is `Array<number>`.
+ *
+ * `const result = (array as Array<number | undefined>).filter(isNumber);`
+ */
 export const isNumber = (x) => typeof x === 'number';
-/*
+/**
  * a guard for plain old javascript objects that are not based on some other prototype,
  * for example making them safe to JSON stringify and stuff
- * */
+ */
 export const isPlainObject = (thing) => thing instanceof Object && thing.__proto__.constructor.name === 'Object';
-/*
- * this isn't really a guard its just a way to provide a default value without creating a coverage branch.
- *
- * if the first thing is defined it uses it, otherwise it returns the second thing.
+/**
+ * if the first thing is defined it uses it, otherwise it returns the second thing. this isn't
+ * really a guard its just a way to provide a default value without creating a coverage branch.
  *
- * eg:
- *   const valueWithDefault = ifDefined(thing, 'default value')
+ * @example const valueWithDefault = ifDefined(thing, 'default value')
  */
 export const ifDefined = (x, d) => isDefined(x) ? x : d;

package/dist/esm/middleware/apiErrorHandler.d.ts

@@ -3,5 +3,13 @@ import type { Logger } from '../services/logger';
 declare type Handlers = {
     [key: string]: (e: Error, logger: Logger) => ApiResponse<number, any>;
 };
+/**
+ * Creates an error handler. Provides default handlers for `UnauthorizedError`,
+ * `SessionExpiredError`, `NotFoundError`, and `InvalidRequestError`. User-specified
+ * handlers can be added to these. If no handler is found, the error is logged and
+ * a 500 text response is returned.
+ *
+ * @param inputHandlers a map of errors to handler functions
+ */
 export declare const createErrorHandler: (inputHandlers?: Handlers | undefined) => (e: Error, logger: Logger) => Promise<ApiResponse<number, any>>;
 export {};

package/dist/esm/middleware/apiErrorHandler.js

@@ -7,6 +7,14 @@ const defaultHandlers = {
     NotFoundError: (e) => apiTextResponse(404, `404 ${e.message}`),
     InvalidRequestError: (e) => apiTextResponse(400, `400 ${e.message}`),
 };
+/**
+ * Creates an error handler. Provides default handlers for `UnauthorizedError`,
+ * `SessionExpiredError`, `NotFoundError`, and `InvalidRequestError`. User-specified
+ * handlers can be added to these. If no handler is found, the error is logged and
+ * a 500 text response is returned.
+ *
+ * @param inputHandlers a map of errors to handler functions
+ */
 export const createErrorHandler = (inputHandlers) => {
     const handlers = { ...defaultHandlers, ...inputHandlers };
     return async (e, logger) => {

package/dist/esm/middleware/apiSlowResponseMiddleware.d.ts

@@ -5,6 +5,18 @@ declare type Config = {
     logResponseSlowerThan: string;
     timeoutResponseAfter: string;
 };
+/**
+ * Creates response middleware that logs slow responses and times out responses that take too long. lambda functions have a timeout setting, but when a lambda times out there is no way to log anything helpful before it exists. this middleware allows the logger context to show up for timeout requests. just make sure that the `timeoutResponseAfter` is set to something slightly shorter than the lambda timeout so that it has time to run.
+ *
+ * @param config
+ * @param config.logResponseSlowerThan the config that specifies the threshold for a slow response
+ * @param config.timeoutResponseAfter the config that specifies the timeout for a response
+ * @example
+ * createSlowResponseMiddleware({
+ *   logResponseSlowerThan: envConfig('LOG_SLOW_RESPONSE', 'runtime', '1000'),
+ *   timeoutResponseAfter: envConfig('RESPONSE_TIMEOUT', 'runtime', '28000'),
+ * });
+ */
 export declare const createSlowResponseMiddleware: (config: ConfigProviderForConfig<Config>) => () => (response: Promise<ApiResponse<number, any>> | undefined, { logger }: {
     logger: Logger;
 }) => Promise<ApiResponse<number, string>> | undefined;

package/dist/esm/middleware/apiSlowResponseMiddleware.js

@@ -2,6 +2,18 @@ import { resolveConfigValue } from '../config/resolveConfigValue';
 import { once } from '../misc/helpers';
 import { apiTextResponse } from '../routing';
 import { Level } from '../services/logger';
+/**
+ * Creates response middleware that logs slow responses and times out responses that take too long. lambda functions have a timeout setting, but when a lambda times out there is no way to log anything helpful before it exists. this middleware allows the logger context to show up for timeout requests. just make sure that the `timeoutResponseAfter` is set to something slightly shorter than the lambda timeout so that it has time to run.
+ *
+ * @param config
+ * @param config.logResponseSlowerThan the config that specifies the threshold for a slow response
+ * @param config.timeoutResponseAfter the config that specifies the timeout for a response
+ * @example
+ * createSlowResponseMiddleware({
+ *   logResponseSlowerThan: envConfig('LOG_SLOW_RESPONSE', 'runtime', '1000'),
+ *   timeoutResponseAfter: envConfig('RESPONSE_TIMEOUT', 'runtime', '28000'),
+ * });
+ */
 export const createSlowResponseMiddleware = (config) => {
     const getSlowThreshold = once(() => resolveConfigValue(config.logResponseSlowerThan).then(result => parseInt(result, 10)));
     const getTimeoutAfter = once(() => resolveConfigValue(config.timeoutResponseAfter).then(result => parseInt(result, 10)));

package/dist/esm/middleware/lambdaCorsResponseMiddleware.d.ts

@@ -4,7 +4,17 @@ import { ApiResponse } from '../routing';
 declare type Config = {
     corsAllowedHostRegex: string;
 };
-export declare const createLambdaCorsResponseMiddleware: (config: ConfigProviderForConfig<Config>) => (responsePromise: Promise<ApiResponse<number, any>> | undefined, { request }: {
+/**
+ * Creates response middleware that adds CORS headers to responses from approved hosts.
+ *
+ * @param config the config object
+ * @param config.corsAllowedHostRegex the config that specifies the regex for allowed hosts
+ * @example
+ * createLambdaCorsResponseMiddleware({
+ *   corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'
+ * }),
+ */
+export declare const createLambdaCorsResponseMiddleware: (config: ConfigProviderForConfig<Config>) => () => (responsePromise: Promise<ApiResponse<number, any>> | undefined, { request }: {
     request: APIGatewayProxyEventV2;
 }) => Promise<ApiResponse<number, any>> | undefined;
 export {};

package/dist/esm/middleware/lambdaCorsResponseMiddleware.js

@@ -1,6 +1,16 @@
 import { resolveConfigValue } from '../config/resolveConfigValue';
 import { apiTextResponse } from '../routing';
-export const createLambdaCorsResponseMiddleware = (config) => (responsePromise, { request }) => {
+/**
+ * Creates response middleware that adds CORS headers to responses from approved hosts.
+ *
+ * @param config the config object
+ * @param config.corsAllowedHostRegex the config that specifies the regex for allowed hosts
+ * @example
+ * createLambdaCorsResponseMiddleware({
+ *   corsAllowedHostRegex: '(openstax.org|herokuapp.com)$'
+ * }),
+ */
+export const createLambdaCorsResponseMiddleware = (config) => () => (responsePromise, { request }) => {
     const cors = async () => {
         const allowedHost = await resolveConfigValue(config.corsAllowedHostRegex);
         if (request.headers.origin && request.headers.origin !== 'null' && new URL(request.headers.origin).hostname.match(new RegExp(allowedHost))) {

package/dist/esm/middleware/throwNotFoundMiddleware.d.ts

@@ -1 +1,4 @@
+/**
+ * Creates response middleware that throws a `NotFoundError` if the response is undefined.
+ */
 export declare const createThrowNotFoundMiddleware: <Ro>() => () => (response: Promise<Ro> | undefined) => Promise<Ro>;

package/dist/esm/middleware/throwNotFoundMiddleware.js

@@ -1,4 +1,7 @@
 import { NotFoundError } from '../errors';
+/**
+ * Creates response middleware that throws a `NotFoundError` if the response is undefined.
+ */
 export const createThrowNotFoundMiddleware = () => () => (response) => {
     if (!response) {
         throw new NotFoundError('not found');

package/dist/esm/middleware.d.ts

@@ -6,4 +6,42 @@ export declare type ServiceMiddlewareProviderResult<M, S> = [M] extends [never]
 export declare type ServiceMiddlewareProviderArgs<S> = S extends MiddlewareProvider<any, any, infer A, any> ? A : never;
 export declare type ServiceMiddlewareProviderChainResult<C, M> = C extends [infer S1, ...infer S] ? S extends never[] ? ServiceMiddlewareProviderResult<M, S1> : ServiceMiddlewareProviderChainResult<S, ServiceMiddlewareProviderResult<M, S1>> : C extends unknown ? M : never;
 export declare type ServiceMiddlewareProviderChainArgs<C> = C extends [infer S1, ...infer S] ? S extends never[] ? ServiceMiddlewareProviderArgs<S1> : TupleExtends<ServiceMiddlewareProviderChainArgs<S>, ServiceMiddlewareProviderArgs<S1>> extends 'yes' ? ServiceMiddlewareProviderChainArgs<S> : TupleExtends<ServiceMiddlewareProviderArgs<S1>, ServiceMiddlewareProviderChainArgs<S>> extends 'yes' ? ServiceMiddlewareProviderArgs<S1> : never : C extends unknown ? [] : never;
+/**
+ * Creates a middleware composer for given AppServices and input value types. The composer accepts a list of middleware
+ * that it assembles into a chain. The function returned by the composer takes a value of the given input value type,
+ * passes that value through the chain, and returns the result of the last element in the chain. The ending value will
+ * depend on the composed middleware.
+ *
+ * Examples:
+ *
+ * ```
+ * export const composeServiceMiddleware =
+ *   makeComposeMiddleware<AppServices, {request: ApiRouteRequest}>();
+ * export const composeResponseMiddleware =
+ *   makeComposeMiddleware<AppServices, Promise<ApiRouteResponse> | undefined>();
+ *
+ * // `requestServiceProvider` is a function that expects
+ * //`{request: ApiRouteRequest}` (specified in the call to
+ * //`makeComposeMiddleware`); for requestServiceProviders as part of routes in
+ * // particular, the request responder calls this when it resolves the routes.
+ *
+ * const requestServiceProvider = composeServiceMiddleware(
+ *   cookieAuthMiddleware, // expects `request` (from input), adds `authProvider`
+ *   myDocumentStoreMiddleware, // expects authProvider, adds the document store
+ *   myDocumentSearchMiddleware, // expects document store, adds search provider
+ * ); // if you try to specify them in the wrong order it'll yell at you
+ * ```
+ *
+ * WARNING: depending on how you use it, typescript _sometimes_ explodes on these recursive types. if you have problems in your build
+ * with memory, you will have to specify the expected result type when calling the middleware reducer. this is a little annoying,
+ * but it will still correctly error if the type you specify is wrong, so you've still got the type safety.
+ *
+ * ```
+ * // this might work, or it might make your compiler run out of memory
+ * eg: const myThing = makeComposeMiddleware()(...);
+ *
+ * // this helps typescript figure out what is going on
+ * eg: const myThing: myType = makeComposeMiddleware()(...);
+ * ```
+ */
 export declare const makeComposeMiddleware: <Sa, M>() => <C extends any[]>(...chain: C) => MiddlewareProvider<Sa, M, ServiceMiddlewareProviderChainArgs<C>, ServiceMiddlewareProviderChainResult<C, M>>;

package/dist/esm/middleware.js

@@ -1,31 +1,41 @@
-/*
- * this function creates a middleware composer for the given AppServices and starting value. the ending
- * value will depend on the composed values. after composing the values, the composer returns a function that
- * expects the given input value and returns the result of the last element of the middleware chain.
+/**
+ * Creates a middleware composer for given AppServices and input value types. The composer accepts a list of middleware
+ * that it assembles into a chain. The function returned by the composer takes a value of the given input value type,
+ * passes that value through the chain, and returns the result of the last element in the chain. The ending value will
+ * depend on the composed middleware.
  *
- * eg:
- *   export const composeServiceMiddleware = makeComposeMiddleware<AppServices, {request: ApiRouteRequest}>();
- *   export const composeResponseMiddleware = makeComposeMiddleware<AppServices, Promise<ApiRouteResponse> | undefined>();
+ * Examples:
  *
- * eg:
- *   // `requestServiceProvider` is a function that expects `{request: ApiRouteResponse}` (specified in the call to `makeComposeMiddleware`)
- *   // for requestServiceProviders as part of routes in particular, the request responder calls this when it resolves the routes.
- *   const requestServiceProvider = composeServiceMiddleware(
- *     cookieAuthMiddleware, // this one just depends on `request`, which is in the input, and returns that plus the authProvider
- *     myDocumentStoreMiddleware, // this one expects the authProvider, and adds the document store
- *     myDocumentSearchMiddleware, // this one expects the document store, and adds the search provider
- *   ); // if you try to specify them in the wrong order it'll yell at you
+ * ```
+ * export const composeServiceMiddleware =
+ *   makeComposeMiddleware<AppServices, {request: ApiRouteRequest}>();
+ * export const composeResponseMiddleware =
+ *   makeComposeMiddleware<AppServices, Promise<ApiRouteResponse> | undefined>();
+ *
+ * // `requestServiceProvider` is a function that expects
+ * //`{request: ApiRouteRequest}` (specified in the call to
+ * //`makeComposeMiddleware`); for requestServiceProviders as part of routes in
+ * // particular, the request responder calls this when it resolves the routes.
+ *
+ * const requestServiceProvider = composeServiceMiddleware(
+ *   cookieAuthMiddleware, // expects `request` (from input), adds `authProvider`
+ *   myDocumentStoreMiddleware, // expects authProvider, adds the document store
+ *   myDocumentSearchMiddleware, // expects document store, adds search provider
+ * ); // if you try to specify them in the wrong order it'll yell at you
+ * ```
  *
  * WARNING: depending on how you use it, typescript _sometimes_ explodes on these recursive types. if you have problems in your build
  * with memory, you will have to specify the expected result type when calling the middleware reducer. this is a little annoying,
  * but it will still correctly error if the type you specify is wrong, so you've still got the type safety.
  *
+ * ```
  * // this might work, or it might make your compiler run out of memory
  * eg: const myThing = makeComposeMiddleware()(...);
  *
  * // this helps typescript figure out what is going on
  * eg: const myThing: myType = makeComposeMiddleware()(...);
- * */
+ * ```
+ */
 export const makeComposeMiddleware = () => (...chain) => (app, appBinder) => {
     const boundChain = chain.map(provider => appBinder ? appBinder(app, provider) : provider(app));
     return (middleware, ...args) => {

package/dist/esm/misc/hashValue.d.ts

@@ -2,5 +2,10 @@ declare type HashValue = string | number | boolean | null | HashCompoundValue;
 declare type HashCompoundValue = Array<HashValue> | {
     [key: string]: HashValue;
 };
+/**
+ * creates a string hash of lots of different kinds of things.
+ *
+ * @example hashValue({someKey: 'someValue'})
+ */
 export declare const hashValue: (value: HashValue) => string;
 export {};

package/dist/esm/misc/hashValue.js

@@ -1,10 +1,9 @@
 import { createHash } from 'crypto';
-/*
+/**
  * creates a string hash of lots of different kinds of things.
  *
- * eg:
- *   hashValue({someKey: 'someValue'})
- * */
+ * @example hashValue({someKey: 'someValue'})
+ */
 export const hashValue = (value) => {
     // hack for sorting keys https://stackoverflow.com/a/53593328/14809536
     const allKeys = new Set();

package/dist/esm/misc/helpers.d.ts

@@ -1,12 +1,48 @@
+/**
+ * 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 declare const getKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O) => O[K];
+/**
+ * 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 declare const getKeyValueOr: <K extends string, V, Od extends { [key in K]?: any; } = { [key_1 in K]?: any; }>(key: K, defaultValue: V) => <O extends Od extends undefined ? { [key_2 in K]?: any; } : Od>(obj: O) => V | NonNullable<O[K]>;
+/**
+ * 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 declare const putKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O, value: O[K]) => O;
+/**
+ * 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 declare const coerceArray: <T>(thing: T | T[] | undefined) => T[];
 declare type FlowFn<A, R> = (...args: [A]) => R;
 declare type AnyFlowFn = FlowFn<any, any>;
 declare type FlowFnResult<F, A> = F extends FlowFn<A, infer R> ? R : never;
 declare 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;
 declare 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 declare const flow: <C extends AnyFlowFn[]>(...chain: C) => (param: FlowChainArg<C>) => FlowResult<C, FlowChainArg<C>>;
 declare type RetryOptions = {
     wait?: number;
@@ -14,11 +50,69 @@ declare type RetryOptions = {
     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 declare const retryWithDelay: <R>(fn: () => Promise<R>, options?: RetryOptions | undefined) => Promise<R>;
+/**
+ * a shameful helper to avoid needing to test code coverage of branches
+ */
 export declare const fnIf: <T1, T2>(condition: boolean, trueValue: T1, falseValue: T2) => T1 | T2;
+/**
+ * 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 declare const mapFind: <I, R>(array: I[], mapper: (item: I) => R, predicate?: (result: R) => boolean) => R | undefined;
+/**
+ * returns a function that will only ever call the given function once, returning the first result for every subsequent call
+ *
+ * eg:
+ *   const heavyFunction = () => 'hello';
+ *   const butOnlyOnce = once(() => 'hello');
+ *
+ *   heavyFunction() // returns `hello`;
+ *   butOnlyOnce() // returns `hello`;
+ */
 export declare const once: <F extends (...args: any[]) => any>(fn: F) => F;
+/**
+ * memoizes a function with any number of arguments
+ */
 export declare const memoize: <F extends (...args: any[]) => any>(fn: F) => 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 declare const roundToPrecision: (num: number, places: number) => number;
+/**
+ * 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 declare const tuple: <A extends any[]>(...args: A) => A;
 export {};

package/dist/esm/misc/helpers.js

@@ -1,21 +1,45 @@
 /*
  * 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 = (key) => (obj) => 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 = (key, defaultValue) => (obj) => 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 getKeyValue = (key) => (obj) => obj[key];
-export const getKeyValueOr = (key, defaultValue) => (obj) => obj[key] || defaultValue;
+ */
 export const putKeyValue = (key) => (obj, value) => ({ ...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 = (thing) => thing instanceof Array ? thing : thing !== undefined ? [thing] : [];
-/*
+/**
  * this is like lodash/flow but it uses a recursive type instead of hard-coding parameters
  */
 export const flow = (...chain) => (param) => {
@@ -25,6 +49,20 @@ export const flow = (...chain) => (param) => {
     }
     return result;
 };
+/**
+ * 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 = (fn, options) => {
     const { wait, splay, retries, n } = { wait: 100, splay: 0.5, retries: 2, n: 0, ...options };
     if (n >= retries) {
@@ -36,11 +74,11 @@ export const retryWithDelay = (fn, options) => {
     });
     return fn().catch(retry);
 };
-/*
+/**
  * a shameful helper to avoid needing to test code coverage of branches
  */
 export const fnIf = (condition, trueValue, falseValue) => 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
  *
@@ -55,7 +93,7 @@ export const mapFind = (array, mapper, predicate = (r) => !!r) => {
         }
     }
 };
-/*
+/**
  * returns a function that will only ever call the given function once, returning the first result for every subsequent call
  *
  * eg:
@@ -70,7 +108,7 @@ export const once = (fn) => {
     let result = initialValue;
     return ((...args) => result === initialValue ? (result = fn(...args)) : result);
 };
-/*
+/**
  * memoizes a function with any number of arguments
  */
 export const memoize = (fn) => {
@@ -97,7 +135,7 @@ export const memoize = (fn) => {
         return thisCache.result = (thisCache.result || fn(...args));
     });
 };
-/*
+/**
  * rounds number to given number of places
  *
  * eg:
@@ -110,7 +148,7 @@ export const roundToPrecision = (num, 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:

package/dist/esm/misc/merge.d.ts

@@ -1,3 +1,21 @@
 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 declare const getCommonProperties: <T1 extends {}, T2 extends {}>(thing1: T1, thing2: T2) => (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 declare const merge: <T extends {}[]>(...[thing1, ...tail]: T) => UnionToIntersection<T[number]>;

package/dist/esm/misc/merge.js

@@ -1,6 +1,14 @@
 import { isPlainObject } from '../guards';
+/**
+ * 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 = (thing1, thing2) => Object.keys(thing1).filter((key) => Object.keys(thing2).includes(key));
-/*
+/**
  * 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.
@@ -8,8 +16,7 @@ export const getCommonProperties = (thing1, thing2) => Object.keys(thing1).filte
  * unlike lodash merge, this will not change object references for values that
  * exist only in one parameter.
  *
- * eg:
- *   merge({thing: 'one'}, {thing: 'two', otherKey: 'one'}, {coolKey: 'coolValue'});
+ * @example merge({thing: 'one'}, {thing: 'two', otherKey: 'one'}, {coolKey: 'coolValue'});
  */
 export const merge = (...[thing1, ...tail]) => {
     const mergedTail = tail.length > 0