@openstax/ts-utils 1.1.30 → 1.1.32

package/dist/cjs/index.d.ts

@@ -1,29 +1,4 @@
-import { UnionToIntersection } from './types';
-export declare const getKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O) => O[K];
-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]>;
-export declare const putKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O, value: O[K]) => O;
-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;
-export declare const flow: <C extends AnyFlowFn[]>(...chain: C) => (param: FlowChainArg<C>) => FlowResult<C, FlowChainArg<C>>;
-export declare const fnIf: <T1, T2>(condition: boolean, trueValue: T1, falseValue: T2) => T1 | T2;
-export declare const mapFind: <I, R>(array: I[], mapper: (item: I) => R, predicate?: (result: R) => boolean) => R | undefined;
-declare type HashValue = string | number | boolean | null | HashCompoundValue;
-declare type HashCompoundValue = Array<HashValue> | {
-    [key: string]: HashValue;
-};
-export declare const hashValue: (value: HashValue) => string;
-export declare const once: <F extends (...args: any[]) => any>(fn: F) => F;
-export declare const partitionSequence: <T, P>(getPartition: (thing: T, previous?: P | undefined) => {
-    matches?: boolean | undefined;
-    value: P;
-}, sequence: T[]) => [P, T[]][];
-export declare const memoize: <F extends (...args: any[]) => any>(fn: F) => F;
-export declare const roundToPrecision: (num: number, places: number) => number;
-export declare const getCommonProperties: <T1 extends {}, T2 extends {}>(thing1: T1, thing2: T2) => (keyof T1 & keyof T2)[];
-export declare const merge: <T extends {}[]>(...[thing1, ...tail]: T) => UnionToIntersection<T[number]>;
-export declare const tuple: <A extends any[]>(...args: A) => A;
-export {};
+export * from './misc/partitionSequence';
+export * from './misc/helpers';
+export * from './misc/merge';
+export * from './misc/hashValue';

package/dist/cjs/index.js

@@ -1,231 +1,20 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.tuple = exports.merge = exports.getCommonProperties = exports.roundToPrecision = exports.memoize = exports.partitionSequence = exports.once = exports.hashValue = exports.mapFind = exports.fnIf = exports.flow = exports.coerceArray = exports.putKeyValue = exports.getKeyValueOr = exports.getKeyValue = void 0;
-const crypto_1 = require("crypto");
-const deep_equal_1 = __importDefault(require("deep-equal"));
-const guards_1 = require("./guards");
-/*
- * 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.
- *
- * const getAuthor = getKeyValue('author');
- * const author = getAuthor(book);
- *
- * const getAuthorOrNope = getKeyValueOr('author', 'nope');
- * const authorOrNope = getAuthorOrNope(book);
- *
- * const putAuthor = putKeyValue('author');
- * const newBook = putAuthor(book, 'tom');
- * */
-const getKeyValue = (key) => (obj) => obj[key];
-exports.getKeyValue = getKeyValue;
-const getKeyValueOr = (key, defaultValue) => (obj) => obj[key] || defaultValue;
-exports.getKeyValueOr = getKeyValueOr;
-const putKeyValue = (key) => (obj, value) => ({ ...obj, [key]: value });
-exports.putKeyValue = putKeyValue;
-const coerceArray = (thing) => thing instanceof Array ? thing : thing !== undefined ? [thing] : [];
-exports.coerceArray = coerceArray;
-/*
- * this is like lodash/flow but it uses a recursive type instead of hard-coding parameters
- */
-const flow = (...chain) => (param) => {
-    let result = param;
-    for (const fn of chain) {
-        result = fn(result);
-    }
-    return result;
-};
-exports.flow = flow;
-/*
- * a shameful helper to avoid needing to test code coverage of branches
- */
-const fnIf = (condition, trueValue, falseValue) => condition ? trueValue : falseValue;
-exports.fnIf = fnIf;
-/*
- * 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');
- */
-const mapFind = (array, mapper, predicate = (r) => !!r) => {
-    for (const item of array) {
-        const mapped = mapper(item);
-        if (predicate(mapped)) {
-            return mapped;
-        }
-    }
-};
-exports.mapFind = mapFind;
-/*
- * creates a string hash of lots of different kinds of things.
- *
- * eg:
- *   hashValue({someKey: 'someValue'})
- * */
-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 (0, crypto_1.createHash)('sha1').update(strValue).digest('hex');
-};
-exports.hashValue = hashValue;
-/*
- * 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`;
- */
-const once = (fn) => {
-    const initialValue = {};
-    let result = initialValue;
-    return ((...args) => result === initialValue ? (result = fn(...args)) : result);
-};
-exports.once = once;
-/*
- * 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]
- *    )
- */
-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 && (0, deep_equal_1.default)(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, []);
-};
-exports.partitionSequence = partitionSequence;
-/*
- * memoizes a function with any number of arguments
- */
-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);
-        return thisCache.result = (thisCache.result || fn(...args));
-    });
-};
-exports.memoize = memoize;
-/*
- * 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
- */
-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;
-};
-exports.roundToPrecision = roundToPrecision;
-const getCommonProperties = (thing1, thing2) => Object.keys(thing1).filter((key) => Object.keys(thing2).includes(key));
-exports.getCommonProperties = getCommonProperties;
-/*
- * 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.
- *
- * eg:
- *   merge({thing: 'one'}, {thing: 'two', otherKey: 'one'}, {coolKey: 'coolValue'});
- */
-const merge = (...[thing1, ...tail]) => {
-    const mergedTail = tail.length > 0
-        ? (0, exports.merge)(...tail)
-        : null;
-    if (!mergedTail) {
-        return thing1;
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
     }
-    return {
-        ...thing1,
-        ...mergedTail,
-        ...(0, exports.getCommonProperties)(thing1, mergedTail).reduce((result, property) => ({
-            ...result,
-            ...((0, guards_1.isPlainObject)(thing1[property]) && (0, guards_1.isPlainObject)(mergedTail[property])
-                ? { [property]: (0, exports.merge)(thing1[property], mergedTail[property]) }
-                : (Array.isArray(thing1[property]) && Array.isArray(mergedTail[property]))
-                    ? { [property]: [...thing1[property], ...mergedTail[property]] }
-                    : {}),
-        }), {}),
-    };
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
-exports.merge = merge;
-/*
- * 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
- *
- */
-const tuple = (...args) => args;
-exports.tuple = tuple;
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./misc/partitionSequence"), exports);
+__exportStar(require("./misc/helpers"), exports);
+__exportStar(require("./misc/merge"), exports);
+__exportStar(require("./misc/hashValue"), exports);

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

@@ -0,0 +1,6 @@
+declare type HashValue = string | number | boolean | null | HashCompoundValue;
+declare type HashCompoundValue = Array<HashValue> | {
+    [key: string]: HashValue;
+};
+export declare const hashValue: (value: HashValue) => string;
+export {};

package/dist/cjs/misc/hashValue.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashValue = void 0;
+const crypto_1 = require("crypto");
+/*
+ * creates a string hash of lots of different kinds of things.
+ *
+ * eg:
+ *   hashValue({someKey: 'someValue'})
+ * */
+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 (0, crypto_1.createHash)('sha1').update(strValue).digest('hex');
+};
+exports.hashValue = hashValue;

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

@@ -0,0 +1,17 @@
+export declare const getKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O) => O[K];
+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]>;
+export declare const putKeyValue: <K extends string>(key: K) => <O extends { [key in K]?: any; }>(obj: O, value: O[K]) => O;
+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;
+export declare const flow: <C extends AnyFlowFn[]>(...chain: C) => (param: FlowChainArg<C>) => FlowResult<C, FlowChainArg<C>>;
+export declare const fnIf: <T1, T2>(condition: boolean, trueValue: T1, falseValue: T2) => T1 | T2;
+export declare const mapFind: <I, R>(array: I[], mapper: (item: I) => R, predicate?: (result: R) => boolean) => R | undefined;
+export declare const once: <F extends (...args: any[]) => any>(fn: F) => F;
+export declare const memoize: <F extends (...args: any[]) => any>(fn: F) => F;
+export declare const roundToPrecision: (num: number, places: number) => number;
+export declare const tuple: <A extends any[]>(...args: A) => A;
+export {};

package/dist/cjs/misc/helpers.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tuple = exports.roundToPrecision = exports.memoize = exports.once = exports.mapFind = exports.fnIf = exports.flow = exports.coerceArray = exports.putKeyValue = exports.getKeyValueOr = exports.getKeyValue = void 0;
+/*
+ * 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.
+ *
+ * const getAuthor = getKeyValue('author');
+ * const author = getAuthor(book);
+ *
+ * const getAuthorOrNope = getKeyValueOr('author', 'nope');
+ * const authorOrNope = getAuthorOrNope(book);
+ *
+ * const putAuthor = putKeyValue('author');
+ * const newBook = putAuthor(book, 'tom');
+ * */
+const getKeyValue = (key) => (obj) => obj[key];
+exports.getKeyValue = getKeyValue;
+const getKeyValueOr = (key, defaultValue) => (obj) => obj[key] || defaultValue;
+exports.getKeyValueOr = getKeyValueOr;
+const putKeyValue = (key) => (obj, value) => ({ ...obj, [key]: value });
+exports.putKeyValue = putKeyValue;
+const coerceArray = (thing) => thing instanceof Array ? thing : thing !== undefined ? [thing] : [];
+exports.coerceArray = coerceArray;
+/*
+ * this is like lodash/flow but it uses a recursive type instead of hard-coding parameters
+ */
+const flow = (...chain) => (param) => {
+    let result = param;
+    for (const fn of chain) {
+        result = fn(result);
+    }
+    return result;
+};
+exports.flow = flow;
+/*
+ * a shameful helper to avoid needing to test code coverage of branches
+ */
+const fnIf = (condition, trueValue, falseValue) => condition ? trueValue : falseValue;
+exports.fnIf = fnIf;
+/*
+ * 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');
+ */
+const mapFind = (array, mapper, predicate = (r) => !!r) => {
+    for (const item of array) {
+        const mapped = mapper(item);
+        if (predicate(mapped)) {
+            return mapped;
+        }
+    }
+};
+exports.mapFind = mapFind;
+/*
+ * 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`;
+ */
+const once = (fn) => {
+    const initialValue = {};
+    let result = initialValue;
+    return ((...args) => result === initialValue ? (result = fn(...args)) : result);
+};
+exports.once = once;
+/*
+ * memoizes a function with any number of arguments
+ */
+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);
+        return thisCache.result = (thisCache.result || fn(...args));
+    });
+};
+exports.memoize = memoize;
+/*
+ * 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
+ */
+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;
+};
+exports.roundToPrecision = roundToPrecision;
+/*
+ * 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
+ *
+ */
+const tuple = (...args) => args;
+exports.tuple = tuple;

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

@@ -0,0 +1,3 @@
+import type { UnionToIntersection } from '../types';
+export declare const getCommonProperties: <T1 extends {}, T2 extends {}>(thing1: T1, thing2: T2) => (keyof T1 & keyof T2)[];
+export declare const merge: <T extends {}[]>(...[thing1, ...tail]: T) => UnionToIntersection<T[number]>;

package/dist/cjs/misc/merge.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.merge = exports.getCommonProperties = void 0;
+const guards_1 = require("../guards");
+const getCommonProperties = (thing1, thing2) => Object.keys(thing1).filter((key) => Object.keys(thing2).includes(key));
+exports.getCommonProperties = getCommonProperties;
+/*
+ * 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.
+ *
+ * eg:
+ *   merge({thing: 'one'}, {thing: 'two', otherKey: 'one'}, {coolKey: 'coolValue'});
+ */
+const merge = (...[thing1, ...tail]) => {
+    const mergedTail = tail.length > 0
+        ? (0, exports.merge)(...tail)
+        : null;
+    if (!mergedTail) {
+        return thing1;
+    }
+    return {
+        ...thing1,
+        ...mergedTail,
+        ...(0, exports.getCommonProperties)(thing1, mergedTail).reduce((result, property) => ({
+            ...result,
+            ...((0, guards_1.isPlainObject)(thing1[property]) && (0, guards_1.isPlainObject)(mergedTail[property])
+                ? { [property]: (0, exports.merge)(thing1[property], mergedTail[property]) }
+                : (Array.isArray(thing1[property]) && Array.isArray(mergedTail[property]))
+                    ? { [property]: [...thing1[property], ...mergedTail[property]] }
+                    : {}),
+        }), {}),
+    };
+};
+exports.merge = merge;

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

@@ -0,0 +1,4 @@
+export declare const partitionSequence: <T, P>(getPartition: (thing: T, previous?: P | undefined) => {
+    matches?: boolean | undefined;
+    value: P;
+}, sequence: T[]) => [P, T[]][];

package/dist/cjs/misc/partitionSequence.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.partitionSequence = void 0;
+const deep_equal_1 = __importDefault(require("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
+ *    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]
+ *    )
+ */
+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 && (0, deep_equal_1.default)(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, []);
+};
+exports.partitionSequence = partitionSequence;

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

@@ -0,0 +1,12 @@
+import type { HttpHeaders } from '.';
+export declare const getHeader: (headers: HttpHeaders, name: string) => string | undefined;
+export declare const getRequestBody: (request: {
+    headers: HttpHeaders;
+    body?: string | undefined;
+}) => any;
+export declare const unsafePayloadValidator: <T>() => (input: any) => input is T;
+export declare const requestPayloadProvider: <T>(validator: (input: any) => input is T) => () => <M extends {
+    request: Parameters<typeof getRequestBody>[0];
+}>(requestServices: M) => M & {
+    payload: T;
+};

package/dist/cjs/routing/helpers.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestPayloadProvider = exports.unsafePayloadValidator = exports.getRequestBody = exports.getHeader = void 0;
+const assertions_1 = require("../assertions");
+const errors_1 = require("../errors");
+const guards_1 = require("../guards");
+// use this to support case insensitive header keys
+// note if there are multiple headers of the same value, this only returns the first value
+const getHeader = (headers, name) => {
+    const key = Object.keys(headers).find(header => header.toLowerCase() === name.toLowerCase());
+    const value = key ? headers[key] : undefined;
+    return value instanceof Array
+        ? value[0]
+        : value;
+};
+exports.getHeader = getHeader;
+const getRequestBody = (request) => {
+    if ((0, exports.getHeader)(request.headers, 'content-type') !== 'application/json') {
+        throw new errors_1.InvalidRequestError('unknown content type: ' + (0, exports.getHeader)(request.headers, 'content-type'));
+    }
+    if (!request.body) {
+        return {};
+    }
+    try {
+        return JSON.parse(request.body);
+    }
+    catch (error) {
+        // Since the body is provided by the user, invalid JSON in the body is an invalid request
+        // We return the message which tells them why the JSON is invalid, but no backtrace
+        throw new errors_1.InvalidRequestError((0, assertions_1.assertErrorInstanceOf)(error, SyntaxError).message);
+    }
+};
+exports.getRequestBody = getRequestBody;
+/* utils and middleware for loading request payload (must follow this pattern for `PayloadForRoute` to work) */
+// stub validator because writing validators is annoying
+const unsafePayloadValidator = () => (input) => {
+    return (0, guards_1.isPlainObject)(input) && Object.keys(input).length > 0;
+};
+exports.unsafePayloadValidator = unsafePayloadValidator;
+/*
+ * the given validator is a guard, which provides the correct type this helper loads the body, runs the validator, throws if it isn't valid, or returns it as
+ * the correct type if it is valid.
+ *
+ * this accomplishes a few things:
+ *   - establishes type of payload for route body logic
+ *   - validates the payload for route logic
+ *   - establishes type of payload for client logic calling this route
+ *
+ * eg:
+ *   export const exampleRoute = createRoute({name: 'exampleRoute', method: METHOD.POST, path: '/example/:id',
+ *     requestServiceProvider: composeServiceMiddleware(
+ *       requestServiceProvider, // previously compiled middleware can be re-composed if you have something to add
+ *       requestPayloadProvider(validatePayload)
+ *     )},
+ *     async(params: {id: string}, services) => {
+ *       const result = await services.myDocumentStore.putItem({
+ *         ...services.payload,
+ *         id: params.id,
+ *       });
+ *       return apiJsonResponse(201, result);
+ *     }
+ *   );
+ * */
+const requestPayloadProvider = (validator) => () => (requestServices) => {
+    const payload = (0, exports.getRequestBody)(requestServices.request);
+    // for more precise error messages, throw your own InvalidRequestError from your validator function
+    if (!validator(payload)) {
+        throw new errors_1.InvalidRequestError();
+    }
+    return { ...requestServices, payload };
+};
+exports.requestPayloadProvider = requestPayloadProvider;