@openstax/ts-utils 1.34.0 → 1.34.1

package/dist/cjs/misc/helpers.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tuple = exports.roundToPrecision = exports.memoize = exports.once = exports.mapFind = exports.fnIf = exports.retryWithDelay = 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.
+ */
+/**
+ * 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);
+ */
+const getKeyValue = (key) => (obj) => obj[key];
+exports.getKeyValue = getKeyValue;
+/**
+ * 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);
+ */
+const getKeyValueOr = (key, defaultValue) => (obj) => obj[key] || defaultValue;
+exports.getKeyValueOr = getKeyValueOr;
+/**
+ * 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');
+ */
+const putKeyValue = (key) => (obj, value) => ({ ...obj, [key]: value });
+exports.putKeyValue = putKeyValue;
+/**
+ * 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
+ */
+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;
+/**
+ * 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.
+ */
+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(() => (0, exports.retryWithDelay)(fn, { ...options, n: n + 1 }).then(resolve, reject), timeout);
+        }
+    });
+    const abort = (e) => {
+        aborted = true;
+        throw e;
+    };
+    return fn(abort).catch(retry);
+};
+exports.retryWithDelay = retryWithDelay;
+/**
+ * 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
+ *
+ * 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`;
+ */
+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;
+    });
+};
+exports.once = once;
+/**
+ * memoizes a function with any number of arguments
+ *
+ * does not cache rejected promises, to avoid cache poisoning on failed async requests
+ */
+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;
+    });
+};
+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,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/cjs/misc/merge.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.merge = exports.getCommonProperties = void 0;
+const guards_1 = require("../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
+ */
+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.
+ *
+ * @example 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,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/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/pagination/index.d.ts

@@ -0,0 +1,91 @@
+import { QueryParams, 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 declare 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>) => M & {
+    pagination: Pa & {
+        getUnusedQueryParams: () => Q;
+    };
+};
+export declare const loadMorePagination: <R, Q extends QueryParams>(queryParams: Q, { route, params }: RouteMatchRecord<R>) => {
+    getUnusedQueryParams: () => Omit<Q, "pageToken">;
+    getPageTokenString: () => string | string[] | null | undefined;
+    getPageTokenNumber: () => number | undefined;
+    getPaginationResponse: <T>({ items, ...meta }: LoadMorePaginationResultInput<T>) => {
+        items: T[];
+        meta: {
+            nextPageToken: string | number | undefined;
+        };
+        links: {
+            nextPage: string | 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 declare const pageNumberPagination: <R, Q extends QueryParams>(queryParams: Q, { route, params }: RouteMatchRecord<R>) => {
+    getUnusedQueryParams: () => Omit<Q, "page">;
+    getPaginationParams: () => {
+        page: number | undefined;
+    };
+    getPaginationResponse: <T>({ items, ...meta }: PageNumberPaginationResultInput<T>) => {
+        items: T[];
+        meta: {
+            pageSize: number;
+            currentPage: number;
+            totalItems: number;
+            totalPages: number;
+        };
+        links: {
+            firstPage: string;
+            lastPage: string;
+            nextPage: string | undefined;
+            prevPage: string | 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;
+}

package/dist/cjs/pagination/index.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageNumberPagination = exports.loadMorePagination = exports.createPaginationMiddleware = void 0;
+const assertions_1 = require("../assertions");
+const errors_1 = require("../errors");
+const routing_1 = require("../routing");
+/**
+ * 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));
+ */
+const createPaginationMiddleware = () => ({ getQueryParams, setUnusedQueryParams, paginator }) => () => (middleware, match) => {
+    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 };
+};
+exports.createPaginationMiddleware = createPaginationMiddleware;
+const loadMorePagination = (queryParams, { route, params }) => {
+    const { pageToken, ...otherParams } = queryParams;
+    return {
+        getUnusedQueryParams: () => otherParams,
+        getPageTokenString: () => pageToken,
+        getPageTokenNumber: () => pageToken && typeof pageToken === 'string'
+            ? (0, assertions_1.notNaN)(parseInt(pageToken, 10), () => { throw new errors_1.InvalidRequestError(); })
+            : undefined,
+        getPaginationResponse: ({ items, ...meta }) => {
+            return {
+                items,
+                meta,
+                links: {
+                    nextPage: meta.nextPageToken
+                        ? (0, routing_1.renderAnyRouteUrl)(route, params, { ...queryParams, pageToken: meta.nextPageToken.toString() })
+                        : undefined,
+                }
+            };
+        },
+    };
+};
+exports.loadMorePagination = loadMorePagination;
+const pageNumberPagination = (queryParams, { route, params }) => {
+    const { page, ...otherParams } = queryParams;
+    const numberPage = page && typeof page === 'string'
+        ? (0, assertions_1.notNaN)(parseInt(page, 10), () => { throw new errors_1.InvalidRequestError(); })
+        : undefined;
+    return {
+        getUnusedQueryParams: () => otherParams,
+        getPaginationParams: () => ({ page: numberPage }),
+        getPaginationResponse: ({ items, ...meta }) => {
+            return {
+                items,
+                meta,
+                links: {
+                    firstPage: (0, routing_1.renderAnyRouteUrl)(route, params, { ...queryParams, page: '1' }),
+                    lastPage: (0, routing_1.renderAnyRouteUrl)(route, params, { ...queryParams, page: meta.totalPages.toString() }),
+                    nextPage: meta.currentPage < meta.totalPages
+                        ? (0, routing_1.renderAnyRouteUrl)(route, params, { ...queryParams, page: (meta.currentPage + 1).toString() })
+                        : undefined,
+                    prevPage: meta.currentPage > 1
+                        ? (0, routing_1.renderAnyRouteUrl)(route, params, { ...queryParams, page: (meta.currentPage - 1).toString() })
+                        : undefined
+                }
+            };
+        },
+    };
+};
+exports.pageNumberPagination = pageNumberPagination;

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

@@ -0,0 +1,57 @@
+import type { HttpHeaders } from '.';
+/**
+ * Get the value of a header, case insensitive; note if there are multiple headers of the same
+ * value, this only returns the first value
+ *
+ * @param headers
+ * @param name the name of the header, case ignored
+ */
+export declare const getHeader: (headers: HttpHeaders, name: string) => string | undefined;
+/**
+ * Gets the body of a request
+ * @param request
+ * @throws InvalidRequestError if the content type is not application/json or not parsable
+ */
+export declare const getRequestBody: (request: {
+    headers: HttpHeaders;
+    body?: string | undefined;
+}) => any;
+/**
+ * stub validator because writing validators is annoying
+ */
+export declare const unsafePayloadValidator: <T>() => (input: any) => input is T;
+/**
+ * Middleware that validates the request payload and adds it to the middleware (with key `payload`)
+ * so it can be accessed downstream.
+ *
+ * This middleware 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
+ *
+ * @param validator a guard function that takes the request payload and returns true if it is valid,
+ * narrowing the type of the payload to the correct type
+ * @throws InvalidRequestError if the payload is not valid
+ *
+ * @example
+ * export const exampleRoute = createRoute({
+ *   name: 'exampleRoute', method: METHOD.POST, path: '/example/:id',
+ *   requestServiceProvider: composeServiceMiddleware(
+ *     // here we are adding to previously composed middleware
+ *     requestServiceProvider,
+ *     requestPayloadProvider(validatePayload)
+ *   )},
+ *   async(params: {id: string}, services) => {
+ *     const result = await services.myDocumentStore.putItem({
+ *       ...services.payload,
+ *       id: params.id,
+ *     });
+ *     return apiJsonResponse(201, result);
+ *   }
+ * );
+ */
+export declare const requestPayloadProvider: <T>(validator: (input: any) => input is T) => () => <M extends {
+    request: Parameters<typeof getRequestBody>[0];
+}>(requestServices: M) => M & {
+    payload: T;
+};