@openstax/ts-utils 1.1.26 → 1.1.28

package/dist/esm/index.js

@@ -0,0 +1,210 @@
+import { createHash } from 'crypto';
+import deepEqual from 'deep-equal';
+import { isPlainObject } from './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');
+ * */
+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 });
+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;
+};
+/*
+ * 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;
+        }
+    }
+};
+/*
+ * creates a string hash of lots of different kinds of things.
+ *
+ * eg:
+ *   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');
+};
+/*
+ * 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 const once = (fn) => {
+    const initialValue = {};
+    let result = initialValue;
+    return ((...args) => result === initialValue ? (result = fn(...args)) : result);
+};
+/*
+ * 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 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, []);
+};
+/*
+ * memoizes a function with any number of arguments
+ */
+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);
+        return thisCache.result = (thisCache.result || fn(...args));
+    });
+};
+/*
+ * 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;
+};
+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.
+ *
+ * eg:
+ *   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]] }
+                    : {}),
+        }), {}),
+    };
+};
+/*
+ * 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/middleware.d.ts

@@ -0,0 +1,9 @@
+import { TupleExtends } from './types';
+export declare 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 declare type MiddlewareTransformProvider<Sa, M, A extends any[], R> = (app: Sa) => (middleware: M, ...args: A) => Omit<M, keyof R> & R;
+export declare type MiddlewareInput<S> = S extends MiddlewareProvider<any, infer M, any, any> ? M : never;
+export declare 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 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;
+export declare const makeComposeMiddleware: <Sa, M>() => <C extends any[]>(...chain: C) => MiddlewareProvider<Sa, M, ServiceMiddlewareProviderChainArgs<C>, ServiceMiddlewareProviderChainResult<C, M>>;

package/dist/esm/middleware.js

@@ -0,0 +1,34 @@
+/*
+ * 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.
+ *
+ * eg:
+ *   export const composeServiceMiddleware = makeComposeMiddleware<AppServices, {request: ApiRouteRequest}>();
+ *   export const composeResponseMiddleware = makeComposeMiddleware<AppServices, Promise<ApiRouteResponse> | undefined>();
+ *
+ * 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
+ *
+ * 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/pagination.d.ts

@@ -0,0 +1,63 @@
+import { QueryParams, RouteMatchRecord } from './routing';
+export declare type PaginationHandler<Pa, Q extends QueryParams> = <R>(queryParams: Q, match: RouteMatchRecord<R>) => Pa & {
+    getUnusedQueryParams: () => Q;
+};
+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;
+        };
+    };
+};
+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;
+        };
+    };
+};
+export interface PageNumberPaginationResultInput<T> {
+    items: T[];
+    pageSize: number;
+    currentPage: number;
+    totalItems: number;
+    totalPages: number;
+}

package/dist/esm/pagination.js

@@ -0,0 +1,77 @@
+import { notNaN } from './assertions';
+import { InvalidRequestError } from './errors';
+import { renderAnyRouteUrl } from './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));
+ */
+export 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 };
+};
+export const loadMorePagination = (queryParams, { route, params }) => {
+    const { pageToken, ...otherParams } = queryParams;
+    return {
+        getUnusedQueryParams: () => otherParams,
+        getPageTokenString: () => pageToken,
+        getPageTokenNumber: () => pageToken && typeof pageToken === 'string'
+            ? notNaN(parseInt(pageToken, 10), () => { throw new InvalidRequestError(); })
+            : undefined,
+        getPaginationResponse: ({ items, ...meta }) => {
+            return {
+                items,
+                meta,
+                links: {
+                    nextPage: meta.nextPageToken
+                        ? renderAnyRouteUrl(route, params, { ...queryParams, pageToken: meta.nextPageToken.toString() })
+                        : undefined,
+                }
+            };
+        },
+    };
+};
+export const pageNumberPagination = (queryParams, { route, params }) => {
+    const { page, ...otherParams } = queryParams;
+    const numberPage = page && typeof page === 'string'
+        ? notNaN(parseInt(page, 10), () => { throw new InvalidRequestError(); })
+        : undefined;
+    return {
+        getUnusedQueryParams: () => otherParams,
+        getPaginationParams: () => ({ page: numberPage }),
+        getPaginationResponse: ({ items, ...meta }) => {
+            return {
+                items,
+                meta,
+                links: {
+                    firstPage: renderAnyRouteUrl(route, params, { ...queryParams, page: '1' }),
+                    lastPage: renderAnyRouteUrl(route, params, { ...queryParams, page: meta.totalPages.toString() }),
+                    nextPage: meta.currentPage < meta.totalPages
+                        ? renderAnyRouteUrl(route, params, { ...queryParams, page: (meta.currentPage + 1).toString() })
+                        : undefined,
+                    prevPage: meta.currentPage > 1
+                        ? renderAnyRouteUrl(route, params, { ...queryParams, page: (meta.currentPage - 1).toString() })
+                        : undefined
+                }
+            };
+        },
+    };
+};

package/dist/esm/profile.d.ts

@@ -0,0 +1,59 @@
+import { GenericFetch } from './fetch';
+import { ApiResponse, HttpHeaders } from './routing';
+export interface Call {
+    start: number;
+    end?: number;
+    children: Array<Profile | ProfileData>;
+}
+export declare type ProfileFunction = <Fn extends (...args: any[]) => any>(trackName: string, fn: (p: Track) => Fn) => Fn;
+export interface Track {
+    track: ProfileFunction;
+    trackFetch: <F extends GenericFetch>(fetch: F) => F;
+    setTracing: (tracing: boolean | Promise<boolean>) => void;
+    getTracing: () => Promise<undefined | boolean>;
+    data: () => Call;
+    report: () => CallReport;
+    adopt: (child: Profile) => void;
+}
+export interface ProfileData {
+    name: string;
+    calls: Call[];
+}
+export interface Profile extends ProfileData {
+    report: () => ProfileReport;
+    start: () => Track & {
+        end: () => void;
+    };
+}
+interface CallReport {
+    time: number | string;
+    children: ProfileReport[];
+    coverage: 'unknown' | {
+        accountedTime: number;
+        unaccountedTime: number;
+        accountedPercent: number;
+    };
+}
+interface ProfileReport {
+    name: string;
+    time: 'unknown' | {
+        total: number;
+        min: number;
+        max: number;
+        avg: number;
+    };
+    calls: CallReport[];
+}
+export declare const createProfile: (name: string, options?: {
+    trace?: boolean | Promise<boolean>;
+}) => Profile;
+export declare const makeProfileApiResponseMiddleware: <Ri extends {
+    headers: HttpHeaders;
+}>(showReport: (request: Ri) => string | boolean) => () => (responsePromise: Promise<ApiResponse<number, any>> | undefined, { request, profile }: {
+    request: Ri;
+    profile: Track;
+}) => Promise<ApiResponse<number, any>> | undefined;
+export declare const makeHtmlReport: (report: CallReport) => string;
+export declare const makeHtmlProfileReport: (report: ProfileReport) => string;
+export declare const makeHtmlCallReport: (report: CallReport, index: number) => string;
+export {};

package/dist/esm/profile.js

@@ -0,0 +1,191 @@
+import { isNumber } from './guards';
+import { apiHtmlResponse, apiJsonResponse, getHeader } from './routing';
+import { merge, roundToPrecision } from '.';
+const callReport = (call) => {
+    const time = call.start && call.end
+        ? call.end - call.start
+        : 'unknown';
+    const children = call.children
+        .filter(profile => profile.calls.length > 0)
+        .map(profileReport);
+    const accountedTime = children.reduce((result, profile) => typeof profile.time === 'string' ? result : result + profile.time.total, 0);
+    const coverage = typeof time === 'number' && children.length > 0 ? {
+        accountedTime,
+        unaccountedTime: time - accountedTime,
+        accountedPercent: roundToPrecision(accountedTime / time, -2),
+    } : 'unknown';
+    return { time, children, coverage };
+};
+const profileReport = (profile) => {
+    const calls = profile.calls.map(callReport);
+    const times = calls
+        .map(call => call.time)
+        .filter(isNumber);
+    const time = times.length > 0 ? {
+        total: times.reduce((result, item) => result + item, 0),
+        min: Math.min(...times),
+        max: Math.max(...times),
+        avg: Math.round(times.reduce((result, item) => result + item, 0) / times.length),
+    } : 'unknown';
+    return {
+        name: profile.name, calls, time
+    };
+};
+export const createProfile = (name, options = {}) => {
+    const profile = {
+        name,
+        calls: [],
+        report: () => profileReport(profile),
+        start: () => {
+            const call = { start: Date.now(), children: [] };
+            profile.calls.push(call);
+            return {
+                end: () => { call.end = Date.now(); },
+                report: () => callReport({ end: Date.now(), ...call }),
+                data: () => ({ end: Date.now(), ...call }),
+                adopt: (childProfile) => { call.children.push(childProfile); },
+                setTracing: (tracing) => { options.trace = tracing; },
+                getTracing: async () => options.trace,
+                trackFetch: (fetch) => {
+                    const trackProfile = createProfile('fetch', options);
+                    call.children.push(trackProfile);
+                    return (async (url, config) => {
+                        const { end, ...track } = trackProfile.start();
+                        const fetchConfig = await options.trace
+                            ? merge(config || {}, {
+                                headers: { 'x-application-profile': 'trace' }
+                            })
+                            : config;
+                        return fetch(url, fetchConfig).then(response => {
+                            const fetchProfileJson = response.headers.get('x-application-profile');
+                            const fetchProfile = fetchProfileJson ? JSON.parse(fetchProfileJson) : undefined;
+                            end();
+                            if (fetchProfile) {
+                                const subrequestProfile = createProfile(url, options);
+                                subrequestProfile.calls.push(fetchProfile);
+                                track.adopt(subrequestProfile);
+                            }
+                            return response;
+                        });
+                    });
+                },
+                track: (trackName, fn) => {
+                    const trackProfile = createProfile(trackName, options);
+                    call.children.push(trackProfile);
+                    return ((...args) => {
+                        const { end, ...track } = trackProfile.start();
+                        const result = fn(track)(...args);
+                        if (result instanceof Promise) {
+                            return result.finally(() => { end(); });
+                        }
+                        else {
+                            end();
+                            return result;
+                        }
+                    });
+                }
+            };
+        },
+    };
+    return profile;
+};
+export const makeProfileApiResponseMiddleware = (showReport) => () => (responsePromise, { request, profile }) => {
+    if (responsePromise) {
+        return responsePromise.then(async (response) => {
+            const reportFormat = showReport(request);
+            const enabled = await profile.getTracing();
+            // profiling is disabled, return original response
+            if (!enabled) {
+                return response;
+            }
+            // there is no report format, return original response but
+            // add sub-request trace response if necessary
+            if (reportFormat === false) {
+                if (getHeader(request.headers, 'x-application-profile')) {
+                    return {
+                        ...response,
+                        headers: {
+                            ...response.headers,
+                            'x-application-profile': JSON.stringify(profile.data())
+                        }
+                    };
+                }
+                return response;
+                // override response with html report
+            }
+            else if (reportFormat === 'html') {
+                return apiHtmlResponse(200, makeHtmlReport(profile.report()));
+            }
+            // override response with json report
+            return apiJsonResponse(200, profile.report());
+        });
+    }
+    return responsePromise;
+};
+export const makeHtmlReport = (report) => `
+<head>
+  <style>
+    table {
+      border-collapse: collapse;
+    }
+    table td,th {
+      border: 1px solid #ccc;
+      padding: 10px;
+    }
+    summary {
+      padding: 10px 0;
+    }
+  </style>
+</head>
+<body>
+  ${makeHtmlCallReport(report, 0)}
+</body>
+`;
+export const makeHtmlProfileReport = (report) => `
+<details>
+  <summary>Profile: ${report.name}</summary>
+  <table>
+    <thead>
+      <tr>
+        <th>call #</th>
+        <th>children</th>
+        <th>time</th>
+        <th>time coverage (accounted/unaccounted/percent)</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${report.calls.map((call, i) => `<tr>
+        <td>${i + 1}</td>
+        <td>${call.children.length}</td>
+        <td>${call.time}</td>
+        <td>${typeof call.coverage === 'string' ? call.coverage : `${call.coverage.accountedTime}/${call.coverage.unaccountedTime}/${call.coverage.accountedPercent}`}</td>
+      </tr>`)}
+    </tbody>
+  </table>
+  <div style="padding-left: 20px; border-left: 1px solid #ccc;">
+    ${report.calls.map(makeHtmlCallReport).join('')}
+  </div>
+</details>
+`;
+export const makeHtmlCallReport = (report, index) => `
+<h4>call # ${index + 1} children<h4>
+<table>
+  <thead>
+    <tr>
+      <th>name</th>
+      <th>calls</th>
+      <th>time (total (min/max/avg))</th>
+    </tr>
+  </thead>
+  <tbody>
+    ${report.children.map(profile => `<tr>
+      <td>${profile.name}</td>
+      <td>${profile.calls.length}</td>
+      <td>${typeof profile.time === 'string' ? profile.time : `${profile.time.total} (${profile.time.min}/${profile.time.max}/${profile.time.avg})`}</td>
+    </tr>`).join('')}
+  </tbody>
+</table>
+<div style="margin-left: 20px">
+  ${report.children.map(makeHtmlProfileReport).join('')}
+</div>
+`;