@snap/camera-kit 0.7.0

package/lib/handlers/mappingHandler.js

@@ -0,0 +1,65 @@
+import { __awaiter } from "tslib";
+import { onPageHidden } from "../common/pageVisibility";
+/**
+ * Map from one request type to another, potentially asynchronously.
+ *
+ * **NOTE:** If `maxMapConcurrency` is set to some finite number, and more requests are handled than are allowed to
+ * be concurrently mapped, the waiting requests will be placed into a unbounded buffer. If, for example, requests are
+ * handled with high frequency, `maxMapConcurrency` is low, and the `map` function returns a long-running Promise, this
+ * buffer could use a large amount of memory. Keep this in mind when using this handler.
+ *
+ * @param map Transform each request, may be sync or async.
+ * @param maxMapConcurrency If the `map` function is async, it will be invoked at most this number of times
+ * concurrently. Setting this to 1 could be useful if it's important for `map` to be called in serial.
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export const createMappingHandler = (map, maxMapConcurrency = Number.POSITIVE_INFINITY, flushOnPageHidden = true) => {
+    const buffer = [];
+    let mapConcurrency = 0;
+    const processRequest = (request) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            mapConcurrency++;
+            const mapped = request.map();
+            // We want to make sure that if the mapping operation is not async, we don't introduce asynchronicity here
+            // (which unfortunately happens even if you `await` a non-Promise value). This is important so that e.g.
+            // handlers which run when the page is terminated can send requests synchronously, since the browser may
+            // not pick up any async handlers registered to run on the following event loop.
+            if (mapped instanceof Promise)
+                request.next(yield mapped);
+            else if (mapped)
+                request.next(mapped);
+        }
+        catch (error) {
+            request.reject(error);
+        }
+        finally {
+            mapConcurrency--;
+        }
+        while (buffer.length > 0 && mapConcurrency < maxMapConcurrency) {
+            // Safety: we just checked for `buffer.length > 0`, so the shifted value will never be undefined.
+            processRequest(buffer.shift());
+        }
+    });
+    // This may indicate that the page is being unloaded, in which case we may want to flush any buffered requests
+    // regardless of our max concurrency – otherwise those requests will be lost when the page terminates.
+    if (flushOnPageHidden) {
+        onPageHidden(() => {
+            while (buffer.length > 0)
+                processRequest(buffer.shift());
+        });
+    }
+    return (next) => (request, metadata) => {
+        return new Promise((resolve, reject) => {
+            const mappableRequest = {
+                map: () => map(request),
+                next: (mappedRequest) => next(mappedRequest, metadata).then(resolve).catch(reject),
+                reject,
+            };
+            if (mapConcurrency < maxMapConcurrency)
+                processRequest(mappableRequest);
+            else
+                buffer.push(mappableRequest);
+        });
+    };
+};
+//# sourceMappingURL=mappingHandler.js.map

package/lib/handlers/mappingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappingHandler.js","sourceRoot":"","sources":["../../src/handlers/mappingHandler.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AASxD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAChC,GAAqD,EACrD,oBAA4B,MAAM,CAAC,iBAAiB,EACpD,iBAAiB,GAAG,IAAI,EACwB,EAAE;IAClD,MAAM,MAAM,GAAiC,EAAE,CAAC;IAChD,IAAI,cAAc,GAAG,CAAC,CAAC;IAEvB,MAAM,cAAc,GAAG,CAAO,OAAmC,EAAE,EAAE;QACjE,IAAI;YACA,cAAc,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YAC7B,0GAA0G;YAC1G,wGAAwG;YACxG,wGAAwG;YACxG,gFAAgF;YAChF,IAAI,MAAM,YAAY,OAAO;gBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,CAAC;iBACrD,IAAI,MAAM;gBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;SACzC;QAAC,OAAO,KAAK,EAAE;YACZ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SACzB;gBAAS;YACN,cAAc,EAAE,CAAC;SACpB;QACD,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,cAAc,GAAG,iBAAiB,EAAE;YAC5D,iGAAiG;YACjG,cAAc,CAAC,MAAM,CAAC,KAAK,EAAG,CAAC,CAAC;SACnC;IACL,CAAC,CAAA,CAAC;IAEF,8GAA8G;IAC9G,sGAAsG;IACtG,IAAI,iBAAiB,EAAE;QACnB,YAAY,CAAC,GAAG,EAAE;YACd,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,cAAc,CAAC,MAAM,CAAC,KAAK,EAAG,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;KACN;IAED,OAAO,CAAC,IAAmC,EAAE,EAAE,CAAC,CAAC,OAAY,EAAE,QAAe,EAAE,EAAE;QAC9E,OAAO,IAAI,OAAO,CAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,eAAe,GAA+B;gBAChD,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;gBACvB,IAAI,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;gBAClF,MAAM;aACT,CAAC;YACF,IAAI,cAAc,GAAG,iBAAiB;gBAAE,cAAc,CAAC,eAAe,CAAC,CAAC;;gBACnE,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACN,CAAC,CAAC","sourcesContent":["import { onPageHidden } from \"../common/pageVisibility\";\nimport { ChainableHandler, Handler, RequestMetadata } from \"./HandlerChainBuilder\";\n\ninterface MappableRequest<T> {\n    map: () => T | Promise<T>;\n    next: (request: T) => Promise<void>;\n    reject: (reason: unknown) => void;\n}\n\n/**\n * Map from one request type to another, potentially asynchronously.\n *\n * **NOTE:** If `maxMapConcurrency` is set to some finite number, and more requests are handled than are allowed to\n * be concurrently mapped, the waiting requests will be placed into a unbounded buffer. If, for example, requests are\n * handled with high frequency, `maxMapConcurrency` is low, and the `map` function returns a long-running Promise, this\n * buffer could use a large amount of memory. Keep this in mind when using this handler.\n *\n * @param map Transform each request, may be sync or async.\n * @param maxMapConcurrency If the `map` function is async, it will be invoked at most this number of times\n * concurrently. Setting this to 1 could be useful if it's important for `map` to be called in serial.\n * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}\n */\nexport const createMappingHandler = <Req, MappedReq, Res, Meta extends RequestMetadata>(\n    map: (request: Req) => MappedReq | Promise<MappedReq>,\n    maxMapConcurrency: number = Number.POSITIVE_INFINITY,\n    flushOnPageHidden = true\n): ChainableHandler<Req, Res, MappedReq, Res, Meta> => {\n    const buffer: MappableRequest<MappedReq>[] = [];\n    let mapConcurrency = 0;\n\n    const processRequest = async (request: MappableRequest<MappedReq>) => {\n        try {\n            mapConcurrency++;\n            const mapped = request.map();\n            // We want to make sure that if the mapping operation is not async, we don't introduce asynchronicity here\n            // (which unfortunately happens even if you `await` a non-Promise value). This is important so that e.g.\n            // handlers which run when the page is terminated can send requests synchronously, since the browser may\n            // not pick up any async handlers registered to run on the following event loop.\n            if (mapped instanceof Promise) request.next(await mapped);\n            else if (mapped) request.next(mapped);\n        } catch (error) {\n            request.reject(error);\n        } finally {\n            mapConcurrency--;\n        }\n        while (buffer.length > 0 && mapConcurrency < maxMapConcurrency) {\n            // Safety: we just checked for `buffer.length > 0`, so the shifted value will never be undefined.\n            processRequest(buffer.shift()!);\n        }\n    };\n\n    // This may indicate that the page is being unloaded, in which case we may want to flush any buffered requests\n    // regardless of our max concurrency – otherwise those requests will be lost when the page terminates.\n    if (flushOnPageHidden) {\n        onPageHidden(() => {\n            while (buffer.length > 0) processRequest(buffer.shift()!);\n        });\n    }\n\n    return (next: Handler<MappedReq, Res, Meta>) => (request: Req, metadata?: Meta) => {\n        return new Promise<Res>((resolve, reject) => {\n            const mappableRequest: MappableRequest<MappedReq> = {\n                map: () => map(request),\n                next: (mappedRequest) => next(mappedRequest, metadata).then(resolve).catch(reject),\n                reject,\n            };\n            if (mapConcurrency < maxMapConcurrency) processRequest(mappableRequest);\n            else buffer.push(mappableRequest);\n        });\n    };\n};\n"]}

package/lib/handlers/noCorsRetryingFetchHandler.d.ts

@@ -0,0 +1,48 @@
+import { ChainableHandler } from "./HandlerChainBuilder";
+/**
+ * Some requests may require a no-cors pre-flight (which are allowed to follow redirects) before they can be
+ * successful.
+ *
+ * An example is a federated identity authentication flow, like OpenID Connect or OAuth. In many such schemes,
+ * an unauthenticated request will not include CORs headers. Instead, a redirect to an Identity Provider will be
+ * returned. In order follow this redirect, the Fetch request must be made with "no-cors" mode.
+ *
+ * Once the "no-cors" request is made, redirects are followed resulting in authentication cookies being set on the
+ * original domain. Then, the original request can be retried and the server will authenticate the request and set
+ * proper CORs headers on the response.
+ *
+ * Here's an example request flow, in which the page already has cookies for IdentityProvider.com (if that wasn't
+ * the case, IdentityProvider.com would prompt the user for credentials and the rest of the flow would be the same):
+ *
+ * ```
+ * WebPage a.com        MyServer b.com    IdentityProvider c.com
+ *    |                         |                 |
+ * Original request,            |                 |
+ * unauthenticated:             |                 |
+ *    |------------------------>|                 |
+ *    |<--302: c.com, no CORs---|                 |
+ *    |                         |                 |
+ *    |                         |                 |
+ * No CORs headers in           |                 |
+ * response. Retry in           |                 |
+ * "no-cors" mode:              |                 |
+ *    |-----"no-cors" mode----->|                 |
+ *    |<--302: c.com, no CORs---|                 |
+ *    |                         |                 |
+ *    |                         |                 |
+ *    |------------------IdP cookies------------->|
+ *    |<----------302: b.com?token=foo------------|
+ *                              |                 |
+ *    |                         |                 |
+ *    |----b.com?token=foo----->|                 |
+ *    |<-302: b.com, set cookie-|                 |
+ *    |                         |                 |
+ *    |                         |                 |
+ * Retry original request,      |                 |
+ * now authenticated:           |                 |
+ *    |-----------cookie------->|                 |
+ *    |<-----------200----------|                 |
+ *                              |                 |
+ * ```
+ */
+export declare const createNoCorsRetryingFetchHandler: <Res>() => ChainableHandler<RequestInfo, Res, RequestInfo, Res, RequestInit | undefined>;

package/lib/handlers/noCorsRetryingFetchHandler.js

@@ -0,0 +1,94 @@
+import { __awaiter } from "tslib";
+import { getLogger } from "../logger/logger";
+const logger = getLogger("noCorsRetryingFetchHandler");
+const logRetry = (error) => {
+    logger.warn(`NoCorsRetrying handler got failed response:`, error, `Retrying request with {mode: "no-cors"}.`);
+};
+/**
+ * Some requests may require a no-cors pre-flight (which are allowed to follow redirects) before they can be
+ * successful.
+ *
+ * An example is a federated identity authentication flow, like OpenID Connect or OAuth. In many such schemes,
+ * an unauthenticated request will not include CORs headers. Instead, a redirect to an Identity Provider will be
+ * returned. In order follow this redirect, the Fetch request must be made with "no-cors" mode.
+ *
+ * Once the "no-cors" request is made, redirects are followed resulting in authentication cookies being set on the
+ * original domain. Then, the original request can be retried and the server will authenticate the request and set
+ * proper CORs headers on the response.
+ *
+ * Here's an example request flow, in which the page already has cookies for IdentityProvider.com (if that wasn't
+ * the case, IdentityProvider.com would prompt the user for credentials and the rest of the flow would be the same):
+ *
+ * ```
+ * WebPage a.com        MyServer b.com    IdentityProvider c.com
+ *    |                         |                 |
+ * Original request,            |                 |
+ * unauthenticated:             |                 |
+ *    |------------------------>|                 |
+ *    |<--302: c.com, no CORs---|                 |
+ *    |                         |                 |
+ *    |                         |                 |
+ * No CORs headers in           |                 |
+ * response. Retry in           |                 |
+ * "no-cors" mode:              |                 |
+ *    |-----"no-cors" mode----->|                 |
+ *    |<--302: c.com, no CORs---|                 |
+ *    |                         |                 |
+ *    |                         |                 |
+ *    |------------------IdP cookies------------->|
+ *    |<----------302: b.com?token=foo------------|
+ *                              |                 |
+ *    |                         |                 |
+ *    |----b.com?token=foo----->|                 |
+ *    |<-302: b.com, set cookie-|                 |
+ *    |                         |                 |
+ *    |                         |                 |
+ * Retry original request,      |                 |
+ * now authenticated:           |                 |
+ *    |-----------cookie------->|                 |
+ *    |<-----------200----------|                 |
+ *                              |                 |
+ * ```
+ */
+export const createNoCorsRetryingFetchHandler = () => {
+    // If concurrent requests are made to the same domain, we only want to perform one "no-cors" request. We assume
+    // requests to the same domain will set the same authentication cookies. To support this, we'll store any
+    // in-flight "no-cors" retries and re-use them for concurrent requests.
+    const noCorsRequests = new Map();
+    return (next) => (input, init = {}) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
+        // `host` includes domain:port, so works for local development. If the input is a relative path, we'll
+        // use `location.origin` to resolve into a fully qualified URL (although of course we don't actually
+        // anticipate any CORs issues in that case -- but this is cleaner than special-casing).
+        let requestKey = typeof input === "string" ? input : input.url;
+        try {
+            requestKey = new URL(requestKey, location.origin).host;
+        }
+        catch (_) {
+            /* no-op, use the full input URL as the requestKey */
+        }
+        try {
+            // By always attempting the request first, we avoid needing to maintain any state about the validity
+            // of the request (e.g. the expiration time for a credential). We just make the request, and if it
+            // fails, this tells us we've made an invalid request. This does result in one additional request, but
+            // it makes this much more flexible and avoids having to maintain state (which can be a source of bugs).
+            return yield next(input, init);
+        }
+        catch (error) {
+            // If the request fails because it was aborted, we assume this was done intentionally and we can stop.
+            if (error instanceof Error && error.name === "AbortError")
+                throw error;
+            // Otherwise we don't actually care what error occurred – we know this will be an error thrown by
+            // `fetch` itself (rather than some error encountered on the server, which wouldn't cause `next` to
+            // throw), and we'll just assume it's a CORs error. If it's not, we'll perform a "no-cors" retry anyway,
+            // which will presumably also fail, and that failure will be returned to the caller.
+            logRetry(error);
+            const noCorsRequest = (_a = noCorsRequests.get(requestKey)) !== null && _a !== void 0 ? _a : next(input, Object.assign(Object.assign({}, init), { mode: "no-cors" }));
+            noCorsRequests.set(requestKey, noCorsRequest);
+            yield noCorsRequest;
+            noCorsRequests.delete(requestKey);
+            return next(input, init);
+        }
+    });
+};
+//# sourceMappingURL=noCorsRetryingFetchHandler.js.map

package/lib/handlers/noCorsRetryingFetchHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noCorsRetryingFetchHandler.js","sourceRoot":"","sources":["../../src/handlers/noCorsRetryingFetchHandler.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,MAAM,MAAM,GAAG,SAAS,CAAC,4BAA4B,CAAC,CAAC;AAEvD,MAAM,QAAQ,GAAG,CAAC,KAAU,EAAE,EAAE;IAC5B,MAAM,CAAC,IAAI,CAAC,6CAA6C,EAAE,KAAK,EAAE,0CAA0C,CAAC,CAAC;AAClH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,GAM9C,EAAE;IACA,+GAA+G;IAC/G,yGAAyG;IACzG,uEAAuE;IACvE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEvD,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAO,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,EAAE;;QACxC,sGAAsG;QACtG,oGAAoG;QACpG,uFAAuF;QACvF,IAAI,UAAU,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;QAC/D,IAAI;YACA,UAAU,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;SAC1D;QAAC,OAAO,CAAC,EAAE;YACR,qDAAqD;SACxD;QAED,IAAI;YACA,oGAAoG;YACpG,kGAAkG;YAClG,sGAAsG;YACtG,wGAAwG;YACxG,OAAO,MAAM,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;SAClC;QAAC,OAAO,KAAK,EAAE;YACZ,sGAAsG;YACtG,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY;gBAAE,MAAM,KAAK,CAAC;YAEvE,iGAAiG;YACjG,mGAAmG;YACnG,wGAAwG;YACxG,oFAAoF;YACpF,QAAQ,CAAC,KAAK,CAAC,CAAC;YAChB,MAAM,aAAa,GAAG,MAAA,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,mCAAI,IAAI,CAAC,KAAK,kCAAO,IAAI,KAAE,IAAI,EAAE,SAAS,IAAG,CAAC;YAClG,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;YAC9C,MAAM,aAAa,CAAC;YACpB,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAClC,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;SAC5B;IACL,CAAC,CAAA,CAAC;AACN,CAAC,CAAC","sourcesContent":["import { getLogger } from \"../logger/logger\";\nimport { ChainableHandler } from \"./HandlerChainBuilder\";\n\nconst logger = getLogger(\"noCorsRetryingFetchHandler\");\n\nconst logRetry = (error: any) => {\n    logger.warn(`NoCorsRetrying handler got failed response:`, error, `Retrying request with {mode: \"no-cors\"}.`);\n};\n\n/**\n * Some requests may require a no-cors pre-flight (which are allowed to follow redirects) before they can be\n * successful.\n *\n * An example is a federated identity authentication flow, like OpenID Connect or OAuth. In many such schemes,\n * an unauthenticated request will not include CORs headers. Instead, a redirect to an Identity Provider will be\n * returned. In order follow this redirect, the Fetch request must be made with \"no-cors\" mode.\n *\n * Once the \"no-cors\" request is made, redirects are followed resulting in authentication cookies being set on the\n * original domain. Then, the original request can be retried and the server will authenticate the request and set\n * proper CORs headers on the response.\n *\n * Here's an example request flow, in which the page already has cookies for IdentityProvider.com (if that wasn't\n * the case, IdentityProvider.com would prompt the user for credentials and the rest of the flow would be the same):\n *\n * ```\n * WebPage a.com        MyServer b.com    IdentityProvider c.com\n *    |                         |                 |\n * Original request,            |                 |\n * unauthenticated:             |                 |\n *    |------------------------>|                 |\n *    |<--302: c.com, no CORs---|                 |\n *    |                         |                 |\n *    |                         |                 |\n * No CORs headers in           |                 |\n * response. Retry in           |                 |\n * \"no-cors\" mode:              |                 |\n *    |-----\"no-cors\" mode----->|                 |\n *    |<--302: c.com, no CORs---|                 |\n *    |                         |                 |\n *    |                         |                 |\n *    |------------------IdP cookies------------->|\n *    |<----------302: b.com?token=foo------------|\n *                              |                 |\n *    |                         |                 |\n *    |----b.com?token=foo----->|                 |\n *    |<-302: b.com, set cookie-|                 |\n *    |                         |                 |\n *    |                         |                 |\n * Retry original request,      |                 |\n * now authenticated:           |                 |\n *    |-----------cookie------->|                 |\n *    |<-----------200----------|                 |\n *                              |                 |\n * ```\n */\nexport const createNoCorsRetryingFetchHandler = <Res>(): ChainableHandler<\n    RequestInfo,\n    Res,\n    RequestInfo,\n    Res,\n    RequestInit | undefined\n> => {\n    // If concurrent requests are made to the same domain, we only want to perform one \"no-cors\" request. We assume\n    // requests to the same domain will set the same authentication cookies. To support this, we'll store any\n    // in-flight \"no-cors\" retries and re-use them for concurrent requests.\n    const noCorsRequests = new Map<string, Promise<Res>>();\n\n    return (next) => async (input, init = {}) => {\n        // `host` includes domain:port, so works for local development. If the input is a relative path, we'll\n        // use `location.origin` to resolve into a fully qualified URL (although of course we don't actually\n        // anticipate any CORs issues in that case -- but this is cleaner than special-casing).\n        let requestKey = typeof input === \"string\" ? input : input.url;\n        try {\n            requestKey = new URL(requestKey, location.origin).host;\n        } catch (_) {\n            /* no-op, use the full input URL as the requestKey */\n        }\n\n        try {\n            // By always attempting the request first, we avoid needing to maintain any state about the validity\n            // of the request (e.g. the expiration time for a credential). We just make the request, and if it\n            // fails, this tells us we've made an invalid request. This does result in one additional request, but\n            // it makes this much more flexible and avoids having to maintain state (which can be a source of bugs).\n            return await next(input, init);\n        } catch (error) {\n            // If the request fails because it was aborted, we assume this was done intentionally and we can stop.\n            if (error instanceof Error && error.name === \"AbortError\") throw error;\n\n            // Otherwise we don't actually care what error occurred – we know this will be an error thrown by\n            // `fetch` itself (rather than some error encountered on the server, which wouldn't cause `next` to\n            // throw), and we'll just assume it's a CORs error. If it's not, we'll perform a \"no-cors\" retry anyway,\n            // which will presumably also fail, and that failure will be returned to the caller.\n            logRetry(error);\n            const noCorsRequest = noCorsRequests.get(requestKey) ?? next(input, { ...init, mode: \"no-cors\" });\n            noCorsRequests.set(requestKey, noCorsRequest);\n            await noCorsRequest;\n            noCorsRequests.delete(requestKey);\n            return next(input, init);\n        }\n    };\n};\n"]}

package/lib/handlers/persistingHandler.d.ts

@@ -0,0 +1,14 @@
+import { Persistence } from "../persistence/Persistence";
+import { ChainableHandler, RequestMetadata } from "./HandlerChainBuilder";
+/**
+ * This handler persists in-flight requests locally, so that if there is an unexpected termination of the process (e.g.
+ * the browser tab crashes or is closed) those requests can be recovered and retried on the next page load.
+ *
+ * Keep in mind, using this handler means some *successful* requests may be repeated (e.g. if the request made it to a
+ * server, which responded, but the response didn't reach the browser before the tab closed). Any handler chain making
+ * use of this handler should only handle idempotent requests.
+ *
+ * @param persistence Requests will be temporarily stored here while they are in-flight.
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export declare const createPersistingHandler: <Req, Res, Meta extends RequestMetadata>(persistence: Persistence<[Req, Meta | undefined]>) => ChainableHandler<Req, Res, Req, Res, Meta>;

package/lib/handlers/persistingHandler.js

@@ -0,0 +1,71 @@
+import { __awaiter } from "tslib";
+import { getLogger } from "../logger/logger";
+const logger = getLogger("persistingHandler");
+/**
+ * This handler persists in-flight requests locally, so that if there is an unexpected termination of the process (e.g.
+ * the browser tab crashes or is closed) those requests can be recovered and retried on the next page load.
+ *
+ * Keep in mind, using this handler means some *successful* requests may be repeated (e.g. if the request made it to a
+ * server, which responded, but the response didn't reach the browser before the tab closed). Any handler chain making
+ * use of this handler should only handle idempotent requests.
+ *
+ * @param persistence Requests will be temporarily stored here while they are in-flight.
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export const createPersistingHandler = (persistence) => {
+    let needsRecovery = true;
+    const maybePerformRecovery = (next) => __awaiter(void 0, void 0, void 0, function* () {
+        if (!needsRecovery)
+            return;
+        needsRecovery = false;
+        try {
+            const requests = yield persistence.removeAll();
+            if (requests.length === 0)
+                return;
+            // If a recovered request fails, we'll report the error and prevent it from disrupting other requests. We
+            // won't re-persist to avoid a poison-pill request that remains in storage forever.
+            requests.forEach(([request, metadata]) => performRequest(next)(request, metadata).catch((error) => {
+                logger.error(error);
+            }));
+            // If we fail to retrieve, we have no option but to report the error and proceed. Since we can't tell here
+            // if there were any requests to recover, we cannot say if an error here will actually result in data loss.
+        }
+        catch (error) {
+            // TODO: we will also want to report persistence size (either here or elsewhere) to detect scenarious that
+            // could result in unbounded DB growth.
+            logger.error(error);
+        }
+    });
+    const performRequest = (next) => (req, metadata) => __awaiter(void 0, void 0, void 0, function* () {
+        // If there are requests to be recovered (e.g. a prior session crashed while requests were in-flight), they will
+        // be passed to the next handler in the chain. This will happen at most once per page load.
+        maybePerformRecovery(next);
+        // Whether the persistence succeeds or fails, we always want to make the request – so we don't need to wait for
+        // the request to be stored before passing it to the `next` handler. This is why we're not awaiting the store
+        // call here. We'll also swallow any errors, simply returning `null` for the key – persistence and recovery are
+        // always best-effort, and failure should not disrupt other application behavior.
+        const keyPromise = persistence.store([req, metadata]).catch((error) => {
+            logger.error(error);
+            return null;
+        });
+        try {
+            return yield next(req, metadata);
+        }
+        finally {
+            // We don't care if the request was successful or not, either way once it is completed we will remove
+            // the request from the persistent store.
+            keyPromise
+                .then((key) => {
+                if (key !== null)
+                    return persistence.remove(key);
+                return;
+            })
+                // If removal fails, we will recover and re-send the request – failure could occur if the OS cannot
+                // complete the DB transaction (e.g. power loss), or potentially in other exceptional scenarios.
+                // Therefore it's important that requests handled by this handler be idempotent.
+                .catch((error) => logger.error(error));
+        }
+    });
+    return performRequest;
+};
+//# sourceMappingURL=persistingHandler.js.map

package/lib/handlers/persistingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistingHandler.js","sourceRoot":"","sources":["../../src/handlers/persistingHandler.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAI7C,MAAM,MAAM,GAAG,SAAS,CAAC,mBAAmB,CAAC,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACnC,WAAiD,EACP,EAAE;IAC5C,IAAI,aAAa,GAAG,IAAI,CAAC;IACzB,MAAM,oBAAoB,GAAG,CAAO,IAA6B,EAAE,EAAE;QACjE,IAAI,CAAC,aAAa;YAAE,OAAO;QAC3B,aAAa,GAAG,KAAK,CAAC;QACtB,IAAI;YACA,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,CAAC;YAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAClC,yGAAyG;YACzG,mFAAmF;YACnF,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,CACrC,cAAc,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACpD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC,CAAC,CACL,CAAC;YAEF,0GAA0G;YAC1G,2GAA2G;SAC9G;QAAC,OAAO,KAAK,EAAE;YACZ,0GAA0G;YAC1G,uCAAuC;YACvC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;SACvB;IACL,CAAC,CAAA,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,IAA6B,EAAE,EAAE,CAAC,CAAO,GAAQ,EAAE,QAAe,EAAE,EAAE;QAC1F,gHAAgH;QAChH,2FAA2F;QAC3F,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAE3B,+GAA+G;QAC/G,6GAA6G;QAC7G,+GAA+G;QAC/G,iFAAiF;QACjF,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAClE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,IAAI;YACA,OAAO,MAAM,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;SACpC;gBAAS;YACN,qGAAqG;YACrG,yCAAyC;YACzC,UAAU;iBACL,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;gBACV,IAAI,GAAG,KAAK,IAAI;oBAAE,OAAO,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjD,OAAO;YACX,CAAC,CAAC;gBACF,mGAAmG;gBACnG,gGAAgG;gBAChG,gFAAgF;iBAC/E,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;SAC9C;IACL,CAAC,CAAA,CAAC;IACF,OAAO,cAAc,CAAC;AAC1B,CAAC,CAAC","sourcesContent":["import { getLogger } from \"../logger/logger\";\nimport { Persistence } from \"../persistence/Persistence\";\nimport { ChainableHandler, Handler, RequestMetadata } from \"./HandlerChainBuilder\";\n\nconst logger = getLogger(\"persistingHandler\");\n\n/**\n * This handler persists in-flight requests locally, so that if there is an unexpected termination of the process (e.g.\n * the browser tab crashes or is closed) those requests can be recovered and retried on the next page load.\n *\n * Keep in mind, using this handler means some *successful* requests may be repeated (e.g. if the request made it to a\n * server, which responded, but the response didn't reach the browser before the tab closed). Any handler chain making\n * use of this handler should only handle idempotent requests.\n *\n * @param persistence Requests will be temporarily stored here while they are in-flight.\n * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}\n */\nexport const createPersistingHandler = <Req, Res, Meta extends RequestMetadata>(\n    persistence: Persistence<[Req, Meta | undefined]>\n): ChainableHandler<Req, Res, Req, Res, Meta> => {\n    let needsRecovery = true;\n    const maybePerformRecovery = async (next: Handler<Req, Res, Meta>) => {\n        if (!needsRecovery) return;\n        needsRecovery = false;\n        try {\n            const requests = await persistence.removeAll();\n            if (requests.length === 0) return;\n            // If a recovered request fails, we'll report the error and prevent it from disrupting other requests. We\n            // won't re-persist to avoid a poison-pill request that remains in storage forever.\n            requests.forEach(([request, metadata]) =>\n                performRequest(next)(request, metadata).catch((error) => {\n                    logger.error(error);\n                })\n            );\n\n            // If we fail to retrieve, we have no option but to report the error and proceed. Since we can't tell here\n            // if there were any requests to recover, we cannot say if an error here will actually result in data loss.\n        } catch (error) {\n            // TODO: we will also want to report persistence size (either here or elsewhere) to detect scenarious that\n            // could result in unbounded DB growth.\n            logger.error(error);\n        }\n    };\n\n    const performRequest = (next: Handler<Req, Res, Meta>) => async (req: Req, metadata?: Meta) => {\n        // If there are requests to be recovered (e.g. a prior session crashed while requests were in-flight), they will\n        // be passed to the next handler in the chain. This will happen at most once per page load.\n        maybePerformRecovery(next);\n\n        // Whether the persistence succeeds or fails, we always want to make the request – so we don't need to wait for\n        // the request to be stored before passing it to the `next` handler. This is why we're not awaiting the store\n        // call here. We'll also swallow any errors, simply returning `null` for the key – persistence and recovery are\n        // always best-effort, and failure should not disrupt other application behavior.\n        const keyPromise = persistence.store([req, metadata]).catch((error) => {\n            logger.error(error);\n            return null;\n        });\n        try {\n            return await next(req, metadata);\n        } finally {\n            // We don't care if the request was successful or not, either way once it is completed we will remove\n            // the request from the persistent store.\n            keyPromise\n                .then((key) => {\n                    if (key !== null) return persistence.remove(key);\n                    return;\n                })\n                // If removal fails, we will recover and re-send the request – failure could occur if the OS cannot\n                // complete the DB transaction (e.g. power loss), or potentially in other exceptional scenarios.\n                // Therefore it's important that requests handled by this handler be idempotent.\n                .catch((error) => logger.error(error));\n        }\n    };\n    return performRequest;\n};\n"]}

package/lib/handlers/rateLimitingHandler.d.ts

@@ -0,0 +1,20 @@
+import { ChainableHandler, RequestMetadata } from "./HandlerChainBuilder";
+/**
+ * Limit the rate at which requests are passed to the next handler in the chain.
+ *
+ * During any page transitions to "hidden" – possibly indicating the page is about to terminate – requests will not be
+ * rate limited, to ensure that they are not lost.
+ *
+ * TODO: If there are requests in the queue waiting to be sent when the page transitions to "hidden," these will not
+ * be immediately sent. This means there still is an edge case in which a request may be lost on page termination. This
+ * can be fixed with changes to `createMappingHandler`.
+ *
+ * **NOTE:** Under the hood, requests that come in faster than the set `duration` are placed in an unbounded buffer.
+ * If many requests are made quickly and `duration` is long, this could result in high memory usage. Keep this in mind
+ * when using this handler.
+ *
+ * @param duration In milliseconds. Requests will be passed to the next handler in the chain no faster than this. That
+ * is, if `duration` is `1000`, the next handler will be called at most once per second.
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export declare const createRateLimitingHandler: <Req, Res, Meta extends RequestMetadata>(duration: number, flushOnPageHidden?: boolean) => ChainableHandler<Req, Res, Req, Res, Meta>;

package/lib/handlers/rateLimitingHandler.js

@@ -0,0 +1,43 @@
+import { __awaiter } from "tslib";
+import { isDuringVisibilityTransition } from "../common/pageVisibility";
+import { createMappingHandler } from "./mappingHandler";
+const delay = (duration) => new Promise((resolve) => setTimeout(resolve, duration));
+/**
+ * Limit the rate at which requests are passed to the next handler in the chain.
+ *
+ * During any page transitions to "hidden" – possibly indicating the page is about to terminate – requests will not be
+ * rate limited, to ensure that they are not lost.
+ *
+ * TODO: If there are requests in the queue waiting to be sent when the page transitions to "hidden," these will not
+ * be immediately sent. This means there still is an edge case in which a request may be lost on page termination. This
+ * can be fixed with changes to `createMappingHandler`.
+ *
+ * **NOTE:** Under the hood, requests that come in faster than the set `duration` are placed in an unbounded buffer.
+ * If many requests are made quickly and `duration` is long, this could result in high memory usage. Keep this in mind
+ * when using this handler.
+ *
+ * @param duration In milliseconds. Requests will be passed to the next handler in the chain no faster than this. That
+ * is, if `duration` is `1000`, the next handler will be called at most once per second.
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export const createRateLimitingHandler = (duration, flushOnPageHidden = true) => {
+    let mostRecentSendTime = undefined;
+    const mappingHandler = createMappingHandler((request) => __awaiter(void 0, void 0, void 0, function* () {
+        if (mostRecentSendTime !== undefined) {
+            const millisUntilNextSend = duration - (Date.now() - mostRecentSendTime);
+            if (millisUntilNextSend > 0)
+                yield delay(millisUntilNextSend);
+        }
+        mostRecentSendTime = Date.now();
+        return request;
+    }), 1, flushOnPageHidden);
+    return (next) => (request, metadata) => {
+        // Requests may be made while the page is transitioning to hidden – for example, the page is being unloaded and
+        // we're reporting final metrics. In this case, we need to skip rate limiting and synchronously call `next`
+        // so that the request is not lost.
+        if (isDuringVisibilityTransition("hidden") && flushOnPageHidden)
+            return next(request, metadata);
+        return mappingHandler(next)(request, metadata);
+    };
+};
+//# sourceMappingURL=rateLimitingHandler.js.map

package/lib/handlers/rateLimitingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimitingHandler.js","sourceRoot":"","sources":["../../src/handlers/rateLimitingHandler.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACrC,QAAgB,EAChB,iBAAiB,GAAG,IAAI,EACkB,EAAE;IAC5C,IAAI,kBAAkB,GAAuB,SAAS,CAAC;IAEvD,MAAM,cAAc,GAAG,oBAAoB,CACvC,CAAO,OAAO,EAAE,EAAE;QACd,IAAI,kBAAkB,KAAK,SAAS,EAAE;YAClC,MAAM,mBAAmB,GAAG,QAAQ,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,kBAAkB,CAAC,CAAC;YACzE,IAAI,mBAAmB,GAAG,CAAC;gBAAE,MAAM,KAAK,CAAC,mBAAmB,CAAC,CAAC;SACjE;QACD,kBAAkB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACnB,CAAC,CAAA,EACD,CAAC,EACD,iBAAiB,CACpB,CAAC;IAEF,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;QACnC,+GAA+G;QAC/G,2GAA2G;QAC3G,mCAAmC;QACnC,IAAI,4BAA4B,CAAC,QAAQ,CAAC,IAAI,iBAAiB;YAAE,OAAO,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAChG,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC,CAAC;AACN,CAAC,CAAC","sourcesContent":["import { isDuringVisibilityTransition } from \"../common/pageVisibility\";\nimport { ChainableHandler, RequestMetadata } from \"./HandlerChainBuilder\";\nimport { createMappingHandler } from \"./mappingHandler\";\n\nconst delay = (duration: number) => new Promise<void>((resolve) => setTimeout(resolve, duration));\n\n/**\n * Limit the rate at which requests are passed to the next handler in the chain.\n *\n * During any page transitions to \"hidden\" – possibly indicating the page is about to terminate – requests will not be\n * rate limited, to ensure that they are not lost.\n *\n * TODO: If there are requests in the queue waiting to be sent when the page transitions to \"hidden,\" these will not\n * be immediately sent. This means there still is an edge case in which a request may be lost on page termination. This\n * can be fixed with changes to `createMappingHandler`.\n *\n * **NOTE:** Under the hood, requests that come in faster than the set `duration` are placed in an unbounded buffer.\n * If many requests are made quickly and `duration` is long, this could result in high memory usage. Keep this in mind\n * when using this handler.\n *\n * @param duration In milliseconds. Requests will be passed to the next handler in the chain no faster than this. That\n * is, if `duration` is `1000`, the next handler will be called at most once per second.\n * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}\n */\nexport const createRateLimitingHandler = <Req, Res, Meta extends RequestMetadata>(\n    duration: number,\n    flushOnPageHidden = true\n): ChainableHandler<Req, Res, Req, Res, Meta> => {\n    let mostRecentSendTime: number | undefined = undefined;\n\n    const mappingHandler = createMappingHandler<Req, Req, Res, Meta>(\n        async (request) => {\n            if (mostRecentSendTime !== undefined) {\n                const millisUntilNextSend = duration - (Date.now() - mostRecentSendTime);\n                if (millisUntilNextSend > 0) await delay(millisUntilNextSend);\n            }\n            mostRecentSendTime = Date.now();\n            return request;\n        },\n        1,\n        flushOnPageHidden\n    );\n\n    return (next) => (request, metadata) => {\n        // Requests may be made while the page is transitioning to hidden – for example, the page is being unloaded and\n        // we're reporting final metrics. In this case, we need to skip rate limiting and synchronously call `next`\n        // so that the request is not lost.\n        if (isDuringVisibilityTransition(\"hidden\") && flushOnPageHidden) return next(request, metadata);\n        return mappingHandler(next)(request, metadata);\n    };\n};\n"]}

package/lib/handlers/requestStateEmittingHandler.d.ts

@@ -0,0 +1,29 @@
+import { TypedCustomEvent } from "../events/TypedCustomEvent";
+import { TypedEventTarget } from "../events/TypedEventTarget";
+import { ChainableHandler, RequestMetadata } from "./HandlerChainBuilder";
+interface Started {
+    requestId: number;
+    timeMs: number;
+    dimensions: Dimensions;
+}
+interface Completed {
+    requestId: number;
+    timeMs: number;
+    dimensions: Dimensions;
+    status: number;
+    sizeByte: number;
+}
+interface Errored {
+    requestId: number;
+    timeMs: number;
+    dimensions: Dimensions;
+    error: Error;
+}
+export declare type Dimensions = Record<string, string | undefined>;
+export declare type RequestStateEvents = TypedCustomEvent<"started", Started> | TypedCustomEvent<"completed", Completed> | TypedCustomEvent<"errored", Errored>;
+export declare const requestStateEventTarget: TypedEventTarget<RequestStateEvents>;
+export declare const dispatchRequestStarted: (data: Omit<Started, "requestId" | "timeMs">) => Started;
+export declare const dispatchRequestCompleted: (data: Omit<Completed, "timeMs">) => Completed;
+export declare const dispatchRequestErrored: (data: Omit<Errored, "timeMs">) => Errored;
+export declare const createRequestStateEmittingHandler: <D extends Dimensions = Dimensions>() => ChainableHandler<[RequestInfo, D], Response, RequestInfo, Response, RequestMetadata>;
+export {};

package/lib/handlers/requestStateEmittingHandler.js

@@ -0,0 +1,43 @@
+import { __awaiter } from "tslib";
+import { ensureError } from "../common/errorHelpers";
+import { getTimeMs } from "../common/time";
+import { TypedCustomEvent } from "../events/TypedCustomEvent";
+import { TypedEventTarget } from "../events/TypedEventTarget";
+let requestId = 0;
+const safeParseInt = (str) => {
+    if (str == null)
+        return 0;
+    const maybeInt = parseInt(str);
+    return isNaN(maybeInt) ? 0 : maybeInt;
+};
+export const requestStateEventTarget = new TypedEventTarget();
+export const dispatchRequestStarted = (data) => {
+    const started = Object.assign(Object.assign({}, data), { requestId: requestId++, timeMs: getTimeMs() });
+    requestStateEventTarget.dispatchEvent(new TypedCustomEvent("started", started));
+    return started;
+};
+export const dispatchRequestCompleted = (data) => {
+    const completed = Object.assign(Object.assign({}, data), { timeMs: getTimeMs() });
+    requestStateEventTarget.dispatchEvent(new TypedCustomEvent("completed", completed));
+    return completed;
+};
+export const dispatchRequestErrored = (data) => {
+    const errored = Object.assign(Object.assign({}, data), { timeMs: getTimeMs() });
+    requestStateEventTarget.dispatchEvent(new TypedCustomEvent("errored", errored));
+    return errored;
+};
+export const createRequestStateEmittingHandler = () => (next) => ([request, dimensions], metadata) => __awaiter(void 0, void 0, void 0, function* () {
+    const { requestId } = dispatchRequestStarted({ dimensions });
+    try {
+        const response = yield next(request, metadata);
+        const status = response.status;
+        const sizeByte = safeParseInt(response.headers.get("content-length"));
+        dispatchRequestCompleted({ requestId, dimensions, status, sizeByte });
+        return response;
+    }
+    catch (error) {
+        dispatchRequestErrored({ requestId, dimensions, error: ensureError(error) });
+        throw error;
+    }
+});
+//# sourceMappingURL=requestStateEmittingHandler.js.map

package/lib/handlers/requestStateEmittingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestStateEmittingHandler.js","sourceRoot":"","sources":["../../src/handlers/requestStateEmittingHandler.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAG9D,IAAI,SAAS,GAAG,CAAC,CAAC;AAClB,MAAM,YAAY,GAAG,CAAC,GAAkB,EAAE,EAAE;IACxC,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IAC1B,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC1C,CAAC,CAAC;AA8BF,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,gBAAgB,EAAsB,CAAC;AAElF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,IAA2C,EAAW,EAAE;IAC3F,MAAM,OAAO,mCAAiB,IAAI,KAAE,SAAS,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,GAAE,CAAC;IAClF,uBAAuB,CAAC,aAAa,CAAC,IAAI,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,IAA+B,EAAa,EAAE;IACnF,MAAM,SAAS,mCAAmB,IAAI,KAAE,MAAM,EAAE,SAAS,EAAE,GAAE,CAAC;IAC9D,uBAAuB,CAAC,aAAa,CAAC,IAAI,gBAAgB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;IACpF,OAAO,SAAS,CAAC;AACrB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,IAA6B,EAAW,EAAE;IAC7E,MAAM,OAAO,mCAAiB,IAAI,KAAE,MAAM,EAAE,SAAS,EAAE,GAAE,CAAC;IAC1D,uBAAuB,CAAC,aAAa,CAAC,IAAI,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAM/C,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAO,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE;IACrD,MAAM,EAAE,SAAS,EAAE,GAAG,sBAAsB,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;IAC7D,IAAI;QACA,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC/B,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACtE,wBAAwB,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACtE,OAAO,QAAQ,CAAC;KACnB;IAAC,OAAO,KAAK,EAAE;QACZ,sBAAsB,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7E,MAAM,KAAK,CAAC;KACf;AACL,CAAC,CAAA,CAAC","sourcesContent":["import { ensureError } from \"../common/errorHelpers\";\nimport { getTimeMs } from \"../common/time\";\nimport { TypedCustomEvent } from \"../events/TypedCustomEvent\";\nimport { TypedEventTarget } from \"../events/TypedEventTarget\";\nimport { ChainableHandler, RequestMetadata } from \"./HandlerChainBuilder\";\n\nlet requestId = 0;\nconst safeParseInt = (str: string | null) => {\n    if (str == null) return 0;\n    const maybeInt = parseInt(str);\n    return isNaN(maybeInt) ? 0 : maybeInt;\n};\n\ninterface Started {\n    requestId: number;\n    timeMs: number;\n    dimensions: Dimensions;\n}\n\ninterface Completed {\n    requestId: number;\n    timeMs: number;\n    dimensions: Dimensions;\n    status: number;\n    sizeByte: number;\n}\n\ninterface Errored {\n    requestId: number;\n    timeMs: number;\n    dimensions: Dimensions;\n    error: Error;\n}\n\nexport type Dimensions = Record<string, string | undefined>;\n\nexport type RequestStateEvents =\n    | TypedCustomEvent<\"started\", Started>\n    | TypedCustomEvent<\"completed\", Completed>\n    | TypedCustomEvent<\"errored\", Errored>;\n\nexport const requestStateEventTarget = new TypedEventTarget<RequestStateEvents>();\n\nexport const dispatchRequestStarted = (data: Omit<Started, \"requestId\" | \"timeMs\">): Started => {\n    const started: Started = { ...data, requestId: requestId++, timeMs: getTimeMs() };\n    requestStateEventTarget.dispatchEvent(new TypedCustomEvent(\"started\", started));\n    return started;\n};\n\nexport const dispatchRequestCompleted = (data: Omit<Completed, \"timeMs\">): Completed => {\n    const completed: Completed = { ...data, timeMs: getTimeMs() };\n    requestStateEventTarget.dispatchEvent(new TypedCustomEvent(\"completed\", completed));\n    return completed;\n};\n\nexport const dispatchRequestErrored = (data: Omit<Errored, \"timeMs\">): Errored => {\n    const errored: Errored = { ...data, timeMs: getTimeMs() };\n    requestStateEventTarget.dispatchEvent(new TypedCustomEvent(\"errored\", errored));\n    return errored;\n};\n\nexport const createRequestStateEmittingHandler = <D extends Dimensions = Dimensions>(): ChainableHandler<\n    [RequestInfo, D],\n    Response,\n    RequestInfo,\n    Response,\n    RequestMetadata\n> => (next) => async ([request, dimensions], metadata) => {\n    const { requestId } = dispatchRequestStarted({ dimensions });\n    try {\n        const response = await next(request, metadata);\n        const status = response.status;\n        const sizeByte = safeParseInt(response.headers.get(\"content-length\"));\n        dispatchRequestCompleted({ requestId, dimensions, status, sizeByte });\n        return response;\n    } catch (error) {\n        dispatchRequestErrored({ requestId, dimensions, error: ensureError(error) });\n        throw error;\n    }\n};\n"]}

package/lib/handlers/responseCachingHandler.d.ts

@@ -0,0 +1,27 @@
+import { Persistence, ValidKey } from "../persistence/Persistence";
+import { ChainableHandler, RequestMetadata } from "./HandlerChainBuilder";
+export declare type CachingStrategy<T> = (key: ValidKey, cache: Persistence<T>, network: () => Promise<T>) => Promise<T>;
+/**
+ * Create a CachingStrategy that first makes a request to the network, falling back to cache if the network request
+ * fails. If the network request fails and a prior response has not been cached, an error is returned to the caller.
+ */
+export declare const staleIfErrorStrategy: <T>() => CachingStrategy<T>;
+/**
+ * Create a CachingStrategy that first does a cache lookup – if the response is found in cache, it is returned and the
+ * entry is updated with a request to the network in the background. If no cached response is found, the network request
+ * is made, the result cached and returned to the caller.
+ */
+export declare const staleWhileRevalidateStrategy: <T>() => CachingStrategy<T>;
+/**
+ * Create a Handler capable of caching responses using various caching strategies.
+ *
+ * More than one caching strategy can be provided, and they will be composed into a single strategy. For example, an
+ * expiringStrategy could be composed with a staleIfErrorStrategy so that responses
+ *
+ * @param cache A Persistence instance capable of storing responses.
+ * @param resolveKey This function is called once for each request, and must return a valid persistence key
+ * corresponding uniquely to that request.
+ * @param strategy A CachingStrategy used to determine when to retrieve from cache vs. request from the network.
+ * @returns
+ */
+export declare const createResponseCachingHandler: <Req, Res, Meta extends RequestMetadata>(cache: Persistence<Res>, resolveKey: (request: Req, metadata?: Meta | undefined) => ValidKey, strategy: CachingStrategy<Res>) => ChainableHandler<Req, Res, Req, Res, Meta>;

package/lib/handlers/responseCachingHandler.js

@@ -0,0 +1,94 @@
+import { __awaiter } from "tslib";
+import { ensureError } from "../common/errorHelpers";
+import { cacheKeyNotFoundError } from "../namedErrors";
+import { getLogger } from "../logger/logger";
+const logger = getLogger("responseCachingHandler");
+const notFound = (key) => cacheKeyNotFoundError(`Response for key ${key} not found in cache.`);
+const strategyFailed = (key, cause) => new Error(`Network request and cache lookup for ${key} both failed.`, { cause });
+/**
+ * Create a CachingStrategy that first makes a request to the network, falling back to cache if the network request
+ * fails. If the network request fails and a prior response has not been cached, an error is returned to the caller.
+ */
+export const staleIfErrorStrategy = () => (key, cache, network) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const response = yield network();
+        cache.store(key, response).catch((error) => {
+            logger.warn(`staleIfErrorStrategy failed to store key ${key}.`, error);
+        });
+        return response;
+    }
+    catch (networkError) {
+        try {
+            const cachedResponse = yield cache.retrieve(key);
+            if (!cachedResponse)
+                throw notFound(key);
+            logger.debug(`staleIfErrorStrategy successfully fell back to cache for key ${key} after network error.`, networkError);
+            return cachedResponse;
+        }
+        catch (cacheError) {
+            const error = ensureError(cacheError);
+            error.cause = networkError;
+            throw strategyFailed(key, error);
+        }
+    }
+});
+/**
+ * Create a CachingStrategy that first does a cache lookup – if the response is found in cache, it is returned and the
+ * entry is updated with a request to the network in the background. If no cached response is found, the network request
+ * is made, the result cached and returned to the caller.
+ */
+export const staleWhileRevalidateStrategy = () => (key, cache, network) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const cachedResponse = yield cache.retrieve(key);
+        if (!cachedResponse)
+            throw notFound(key);
+        network()
+            .then((response) => cache.store(key, response))
+            .catch((error) => {
+            logger.warn(`staleWhileRevalidateStrategy failed to retrieve and store key ${key}.`, error);
+        });
+        return cachedResponse;
+    }
+    catch (cacheError) {
+        try {
+            const response = yield network();
+            cache.store(key, response).catch((error) => {
+                logger.warn(`staleWhileRevalidateStrategy failed to store key ${key}.`, error);
+            });
+            logger.debug(`staleWhileRevalidateStrategy successfully fell back to network for key ${key} after cache error.`, cacheError);
+            return response;
+        }
+        catch (networkError) {
+            const error = ensureError(networkError);
+            error.cause = cacheError;
+            throw strategyFailed(key, error);
+        }
+    }
+});
+/**
+ * Create a Handler capable of caching responses using various caching strategies.
+ *
+ * More than one caching strategy can be provided, and they will be composed into a single strategy. For example, an
+ * expiringStrategy could be composed with a staleIfErrorStrategy so that responses
+ *
+ * @param cache A Persistence instance capable of storing responses.
+ * @param resolveKey This function is called once for each request, and must return a valid persistence key
+ * corresponding uniquely to that request.
+ * @param strategy A CachingStrategy used to determine when to retrieve from cache vs. request from the network.
+ * @returns
+ */
+export const createResponseCachingHandler = (cache, resolveKey, strategy) => {
+    return (next) => (request, metadata) => __awaiter(void 0, void 0, void 0, function* () {
+        const network = () => next(request, metadata);
+        let key;
+        try {
+            key = resolveKey(request, metadata);
+        }
+        catch (error) {
+            logger.warn("Cache lookup failed because the cache key could not be resolved.", error);
+            return network();
+        }
+        return strategy(key, cache, network);
+    });
+};
+//# sourceMappingURL=responseCachingHandler.js.map