@openstax/ts-utils 1.34.0 → 1.34.1

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

@@ -0,0 +1,47 @@
+import { TupleZip } from '../types';
+export type MiddlewareProvider<Sa, M, A extends any[], R> = (app: Sa, appBinder?: ((app: Sa, provider: MiddlewareProvider<Sa, M, A, R>) => (middleware: M, ...args: A) => R)) => (middleware: M, ...args: A) => R;
+export type MiddlewareTransformProvider<Sa, M, A extends any[], R> = (app: Sa) => (middleware: M, ...args: A) => Omit<M, keyof R> & R;
+export type MiddlewareInput<S> = S extends MiddlewareProvider<any, infer M, any, any> ? M : never;
+export type ServiceMiddlewareProviderResult<M, S> = [M] extends [never] ? never : [M] extends [MiddlewareInput<S>] ? S extends MiddlewareTransformProvider<any, M, any, infer R> ? (Omit<R, keyof M> & M) extends R ? Omit<R, keyof M> & M : R extends M ? R : Omit<M, keyof R> & R : S extends MiddlewareProvider<any, M, any, infer R> ? R : never : never;
+export type ServiceMiddlewareProviderArgs<S> = S extends MiddlewareProvider<any, any, infer A, any> ? A : never;
+export 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 type ServiceMiddlewareProviderChainArgs<C> = C extends [infer S1, ...infer S] ? S extends never[] ? ServiceMiddlewareProviderArgs<S1> : TupleZip<ServiceMiddlewareProviderChainArgs<S>, ServiceMiddlewareProviderArgs<S1>> : 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/index.js

@@ -0,0 +1,44 @@
+/**
+ * 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 const makeComposeMiddleware = () => (...chain) => (app, appBinder) => {
+    const boundChain = chain.map(provider => appBinder ? appBinder(app, provider) : provider(app));
+    return (middleware, ...args) => {
+        return boundChain.reduce((result, provider) => provider(result, ...args), middleware);
+    };
+};

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

@@ -0,0 +1,20 @@
+import { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { ConfigProviderForConfig } from '../config';
+import { ApiResponse } from '../routing';
+type Config = {
+    corsAllowedHostRegex: string;
+};
+/**
+ * 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

@@ -0,0 +1,40 @@
+import { resolveConfigValue } from '../config/resolveConfigValue';
+import { once } from '../misc/helpers';
+import { apiTextResponse } from '../routing';
+/**
+ * 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 getAllowedHostRegex = once(() => resolveConfigValue(config.corsAllowedHostRegex));
+    const cors = async () => {
+        const allowedHost = await getAllowedHostRegex();
+        if (request.headers.origin && request.headers.origin !== 'null' && new URL(request.headers.origin).hostname.match(new RegExp(allowedHost))) {
+            return {
+                'Access-Control-Allow-Origin': request.headers.origin,
+                'Access-Control-Allow-Credentials': 'true',
+                'Access-Control-Allow-Headers': 'content-type, x-request-id',
+                'Access-Control-Allow-Methods': 'POST, GET, PUT, PATCH, DELETE, OPTIONS',
+            };
+        }
+    };
+    if (responsePromise) {
+        return responsePromise.then(async (response) => {
+            response.headers = {
+                ...await cors(),
+                ...response.headers
+            };
+            return response;
+        });
+    }
+    if (request.requestContext.http.method === 'OPTIONS') {
+        return cors().then(headers => apiTextResponse(200, '', headers));
+    }
+    return responsePromise;
+};

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

@@ -0,0 +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

@@ -0,0 +1,10 @@
+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');
+    }
+    return response;
+};

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

@@ -0,0 +1,10 @@
+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 declare const hashValue: (value: HashValue) => string;

package/dist/esm/misc/hashValue.js

@@ -0,0 +1,13 @@
+import { createHash } from 'crypto';
+/**
+ * creates a string hash of lots of different kinds of things.
+ *
+ * @example hashValue({someKey: 'someValue'})
+ */
+export const hashValue = (value) => {
+    // hack for sorting keys https://stackoverflow.com/a/53593328/14809536
+    const allKeys = new Set();
+    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/dist/esm/misc/helpers.d.ts

@@ -0,0 +1,124 @@
+import type { Logger } from '../services/logger';
+/**
+ * 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 in K]?: any; }>(key: K, defaultValue: V) => <O extends (Od extends undefined ? { [_key in K]?: any; } : Od)>(obj: O) => NonNullable<O[K]> | V;
+/**
+ * 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: undefined | T | T[]) => T[];
+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;
+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>>;
+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 declare const retryWithDelay: <R>(fn: (abort?: (e: Error) => never) => Promise<R>, options?: RetryOptions) => 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
+ *
+ * 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 declare const once: <F extends (...args: any[]) => any>(fn: F) => F;
+/**
+ * memoizes a function with any number of arguments
+ *
+ * does not cache rejected promises, to avoid cache poisoning on failed async requests
+ */
+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

@@ -0,0 +1,199 @@
+/*
+ * 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 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) => {
+    let result = param;
+    for (const fn of chain) {
+        result = fn(result);
+    }
+    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) {
+        return fn();
+    }
+    let aborted = false;
+    const timeout = (n + 1) * wait + (Math.random() * 2 - 1) * splay * wait;
+    const retry = (e) => new Promise((resolve, reject) => {
+        var _a;
+        if (aborted) {
+            reject(e);
+        }
+        else {
+            (_a = options === null || options === void 0 ? void 0 : options.logger) === null || _a === void 0 ? void 0 : _a.log(`failed try ${n + 1} of ${retries}. ${e.message}`);
+            setTimeout(() => retryWithDelay(fn, { ...options, n: n + 1 }).then(resolve, reject), timeout);
+        }
+    });
+    const abort = (e) => {
+        aborted = true;
+        throw e;
+    };
+    return fn(abort).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
+ *
+ * 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 = (array, mapper, predicate = (r) => !!r) => {
+    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 = (fn) => {
+    const initialValue = {};
+    let result = initialValue;
+    return ((...args) => {
+        if (result !== initialValue) {
+            return result;
+        }
+        result = fn(...args);
+        if (typeof result === 'object' && result instanceof Promise) {
+            // Clear the result when possible but do not return a Promise that resolves to the initialValue
+            result.catch(() => result = initialValue);
+        }
+        // If this is a rejected Promise, it should be returned before catch() actually overwrites it
+        return result;
+    });
+};
+/**
+ * memoizes a function with any number of arguments
+ *
+ * does not cache rejected promises, to avoid cache poisoning on failed async requests
+ */
+export const memoize = (fn) => {
+    const cache = {};
+    const resolveCache = (cacheLayer, [first, ...rest]) => {
+        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) => {
+        const thisCache = resolveCache(cache, args);
+        if ('result' in thisCache) {
+            return thisCache.result;
+        }
+        thisCache.result = fn(...args);
+        if (typeof thisCache.result === 'object' && thisCache.result instanceof Promise) {
+            // Clear the result when possible but do not return a Promise that resolves to the initialValue
+            thisCache.result.catch(() => delete thisCache.result);
+        }
+        return thisCache.result;
+    });
+};
+/**
+ * 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, places) => {
+    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 = (...args) => args;

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

@@ -0,0 +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) => 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 declare const merge: <T extends Array<{}>>(...[thing1, ...tail]: T) => UnionToIntersection<T[number]>;

package/dist/esm/misc/merge.js

@@ -0,0 +1,40 @@
+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.
+ *
+ * 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 = (...[thing1, ...tail]) => {
+    const mergedTail = tail.length > 0
+        ? merge(...tail)
+        : null;
+    if (!mergedTail) {
+        return thing1;
+    }
+    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], ...mergedTail[property]] }
+                    : {}),
+        }), {}),
+    };
+};

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

@@ -0,0 +1,35 @@
+/**
+ * partitions a sequence based on a partition function returning {value: any; matches?: boolean}
+ *  - if the function returns `matches` explicitly then adjacent matching elements will
+ *    be grouped and the predicate value in the result will be from the last item in the group
+ *  - if the function returns only a value then matching will be evaluated based on the deep
+ *    equality of the value with its neighbors
+ *
+ * this is different from lodash/partition and lodash/groupBy because:
+ *  - it preserves the order of the items, items will only be grouped if they are already adjacent
+ *  - there can be any number of groups
+ *  - it tells you the partition value
+ *  - the partition value can be reduced, if you care (so you can like, partition on sequential values)
+ *
+ *  simple predicate:
+ *    returns: [[0, [1,2]], [1, [3,4,5]]]
+ *    partitionSequence((n: number) => ({value: Math.floor(n / 3)}), [1,2,3,4,5])
+ *
+ *  mutating partition:
+ *    returns: [
+ *      [{min: 1,max: 3}, [1,2,3]],
+ *      [{min: 5,max: 6}, [5,6]],
+ *      [{min: 8,max: 8}, [8]],
+ *    ]
+ *    partitionSequence(
+ *      (n: number, p?: {min: number; max: number}) =>
+ *        p && p.max + 1 === n
+ *          ? {value: {...p, max: n}, matches: true}
+ *          : {value: {min: n, max: n}, matches: false}
+ *      , [1,2,3,5,6,8]
+ *    )
+ */
+export declare const partitionSequence: <T, P>(getPartition: (thing: T, previous?: P) => {
+    matches?: boolean;
+    value: P;
+}, sequence: T[]) => [P, T[]][];

package/{packages/utils/src/misc/partitionSequence.ts → dist/esm/misc/partitionSequence.js}

@@ -1,5 +1,4 @@
 import deepEqual from 'deep-equal';
-
 /**
  * partitions a sequence based on a partition function returning {value: any; matches?: boolean}
  *  - if the function returns `matches` explicitly then adjacent matching elements will
@@ -31,26 +30,19 @@ import deepEqual from 'deep-equal';
  *      , [1,2,3,5,6,8]
  *    )
  */
-export const partitionSequence = <T, P>(
-  getPartition: (thing: T, previous?: P) => {matches?: boolean; value: P},
-  sequence: T[]
-) => {
-  const appendItem = (result: [P, T[]][], item: T): [P, T[]][] => {
-    const current = result[result.length - 1];
-    const itemPartition = getPartition(item, current?.[0]);
-
-    if (current && (
-      (itemPartition.matches === undefined && deepEqual(current[0], itemPartition.value))
-      || itemPartition.matches
-    )) {
-      current[0] = itemPartition.value;
-      current[1].push(item);
-    } else {
-      result.push([itemPartition.value, [item]]);
-    }
-
-    return result;
-  };
-
-  return sequence.reduce(appendItem, [] as [P, T[]][]);
+export const partitionSequence = (getPartition, sequence) => {
+    const appendItem = (result, item) => {
+        const current = result[result.length - 1];
+        const itemPartition = getPartition(item, current === null || current === void 0 ? void 0 : current[0]);
+        if (current && ((itemPartition.matches === undefined && deepEqual(current[0], itemPartition.value))
+            || itemPartition.matches)) {
+            current[0] = itemPartition.value;
+            current[1].push(item);
+        }
+        else {
+            result.push([itemPartition.value, [item]]);
+        }
+        return result;
+    };
+    return sequence.reduce(appendItem, []);
 };