@snap/camera-kit 0.7.0

package/lib/handlers/HandlerChainBuilder.js

@@ -0,0 +1,187 @@
+/**
+ * Creates a Handler chain – a series of functions composed such that each function may call a supplied `next` function
+ * which passes execution down the chain. When the final Handler in the chain returns, execution passes back up the
+ * chain eventually returning to the caller.
+ *
+ * Each Handler chain begins with a "raw" Handler – this is a function which takes some request and returns some
+ * response. A chain is then created by supplying a series of mapping functions – the ChainableHandler type – which will
+ * be called with the `next` Handler in the chain.
+ *
+ * Ex:
+ * ```ts
+ * const handler = (request: string, metadata?: RequestMetadata) => Promise.resolve(`Responded to ${request}`)
+ * const chainable = (next: Handler<string, string>) => (request: string, metadata?: RequestMetadata) => {
+ *   return next(`modified ${request}`, metadata)
+ * }
+ *
+ * const chain = new HandlerChainBuilder(handler)
+ *   .map(chainable)
+ *   .handler
+ *
+ * const response = await chain('hello')
+ * expect(response).toBe('Responded to modified hello; 0')
+ * ```
+ * You can largely ignore the `metadata` argument present in the above example. This is the mechanism by which an
+ * AbortSignal is passed to each Handler in the chain, but the only real requirement when implementing a Handler is
+ * to pass this argument along to the `next` function. In fact, many Handlers will want to be generic over the type
+ * of metadata:
+ * ```ts
+ * const chainable = <Meta>(next: Handler<string, string, Meta>) => (request: string, metadata: Meta) => {
+ *   return next(`modified ${request}`, metadata)
+ * }
+ * ```
+ * Actually, it's a very good idea for Handlers to be as generic as possible, since that will allow greater re-use. In
+ * the above example, we don't do anything with the response from `next`, so we can let that be generic, too:
+ * ```ts
+ * const chainable = <Res, Meta>(next: Handler<string, Res, Meta>) => (request: string, metadata: Meta) => {
+ *   return next(`modified ${request}`, metadata)
+ * }
+ * ```
+ * Now if some other Handler in the chain decides to return a different response type, our Handler won't require any
+ * changes to compile.
+ *
+ * ---
+ *
+ * Since execution passes from handler to handler in the chain, and then back, handlers have the opportunity to modify
+ * or observe both the request and response. This might be useful for implementing serialization/deserialization, but
+ * the simplest example that demonstrates this feature is measuring request latency:
+ * ```ts
+ * const latencyMeasuringHandler = <Req, Res, Meta>(next: Handler<Req, Res, Meta>) =>
+ *   async (req: Req, metadata: Meta) => {
+ *     const start = performance.now()
+ *     const response = await next(req, metadata)
+ *     const latency = performance.now() - start
+ *     console.log(`latency for request ${request} was ${latency}`)
+ *     return response
+ *   }
+ * ```
+ * Execution is first passed to our measuring handler, which marks the `start` timestamp. Then it passes execution on
+ * down the chain. After a response is received (by some handler down the chain), execution passes back up to our
+ * handler here, which records the amount of time spent inside `next`.
+ *
+ * ---
+ *
+ * Handlers may also abort requests. They can do this in two ways:
+ *   1. Create an `AbortController` and add its `AbortSignal` to the `metadata` object when calling `next`.
+ *   2. Resolve its returned Promise.
+ *
+ * The first approach is straightforward, but the second may benefit from an example – the simplest is a handler which
+ * will timeout a request:
+ * ```ts
+ * const timeoutHandler = <Req, Res, Meta>(next: Handler<Req, Res, Meta>) => (req: Req, metadata: Meta) => {
+ *   return Promise.race([
+ *     next(req, metadata),
+ *     sleep(1000),
+ *   ])
+ * }
+ * ```
+ * The Promise returned by this handler will resolve either when the `next` handler resolves or 1 second has elapsed,
+ * whichever happens first. If the timeout happens first, we want the `next` handler to recieve an abort signal so that
+ * it can terminate early (since its result is no longer needed).
+ *
+ * HandlerChainBuilder makes this happen by observing when each handler completes, and sending an abort signal to all
+ * the handlers "downstream" from the aborting handler.
+ */
+export class HandlerChainBuilder {
+    constructor(inner) {
+        // The TS compiler has the following behavior:
+        //
+        // class Infer<T extends SomeType | undefined> { constructor(f: (t?: T) => void) {} }
+        // const f = (t?: SomeType) => {}
+        // const i = new Infer(f)
+        //
+        // The type of `i` is inferred to be `Infer<SomeType>` instead of `Infer<SomeType | undefined>`, even though the
+        // type of `f`'s argument is `SomeType | undefined`. This seems to be a bug in type inference. Note that making
+        // the constructor argument required gives the expected behavior:
+        //
+        // class Infer<T extends SomeType | undefined> { constructor(f: (t: T) => void) {} }
+        // const f = (t?: SomeType) => {}
+        // const i = new Infer(f)
+        //
+        // Now `i` is inferred to be `Infer<SomeType | undefined>`.
+        //
+        // This has consequences if the inferred type T is used elsewhere in the class.
+        //
+        // In this case, we need to make sure that if the given `inner` function marks the metadata argument as
+        // optional, that HandlerChainBuilder correctly infers that the Meta type includes undefined. So we don't mark
+        // metadata as optional, and so we must cast to `Handler` (which does mark it as optional).
+        //
+        // Safety: We're adding `| undefined` to the metadata type, which may be unsafe – `undefined` may not be
+        // assignable to Meta. But when handling the argument of type Meta, we simply pass it through from handler to
+        // handler – we never call `inner` without passing the metadata argument we've received from some call to an
+        // outer handler. The typing visible to callers remains safe.
+        this.inner = inner;
+    }
+    get handler() {
+        return this.inner;
+    }
+    map(outer) {
+        // To create the next handler in the chain, we compose the "outer" handler with the "inner" handler.
+        //
+        // The outer handler observes its own completion and sends an abort signal to the inner handler when it has
+        // resolved. To prevent unexpected behavior, the inner handler also observes its own completion, setting a flag
+        // when it resolves so that – if it resolves before the outer handler – the outer handler can skip sending the
+        // abort signal (since the inner handler has already completed).
+        const outerHandler = (req, metadata) => {
+            var _a;
+            const abort = new AbortController();
+            const signal = abort.signal;
+            // It's important to not signal an abort to an inner handler which has already completed – it seems like
+            // this would be a non-issue (shouldn't aborting after completion be a no-op?), but specifically for the
+            // browser's implementation of `fetch`, aborting even after the `fetch` Promise resolves can cause an abort
+            // error if e.g. the Fetch Response's body has not yet been read.
+            //
+            // So, for safety, we will only abort inner handlers which are still executing.
+            let innerCompleted = false;
+            const maybeAbort = () => {
+                var _a;
+                // Safety: we never give `abort` to anyone else, so we know if the signal is aborted, this function
+                // has already run, so we can return early without fear of leaking. We also know if inner has completed,
+                // it has already performed cleanup.
+                if (signal.aborted || innerCompleted)
+                    return;
+                // If we've gotten here, the outer handler has either completed, or we heard an abort event while the
+                // inner handler is still executing – so we pass the abort signal down to the inner handler.
+                abort.abort();
+                (_a = metadata === null || metadata === void 0 ? void 0 : metadata.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener("abort", maybeAbort);
+            };
+            (_a = metadata === null || metadata === void 0 ? void 0 : metadata.signal) === null || _a === void 0 ? void 0 : _a.addEventListener("abort", maybeAbort);
+            const innerHandler = new Proxy(this.inner, {
+                apply: (target, thisArg, args) => {
+                    const [req, metadata] = args;
+                    // To help Handler authors out, we'll do some bookkeeping and cleanup for them – if they forget to
+                    // remove an abort event listener, we'll remove it for them when the Promise they return resolves.
+                    // Note: No need to proxy removeEventListener, since removing a non-existent listener just no-ops.
+                    const abortListeners = [];
+                    signal.addEventListener = new Proxy(signal.addEventListener, {
+                        apply: (target, thisArg, args) => {
+                            abortListeners.push(args[1]);
+                            return Reflect.apply(target, thisArg, args);
+                        },
+                    });
+                    const cleanupAndMarkComplete = () => {
+                        var _a;
+                        // The only reason we listen to upstream aborts is to pass them to the inner handler – since the
+                        // inner handler has completed, we no longer need the listener.
+                        (_a = metadata === null || metadata === void 0 ? void 0 : metadata.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener("abort", maybeAbort);
+                        abortListeners.forEach((listener) => signal.removeEventListener("abort", listener));
+                        innerCompleted = true;
+                    };
+                    const innerResponse = Reflect.apply(target, thisArg, [
+                        req,
+                        Object.assign(Object.assign({}, metadata), { signal }),
+                    ]);
+                    // Using `finally` is more idiomatic, but causes trouble in some environments (e.g. some testing
+                    // runtimes which detect uncaught rejected promises).
+                    innerResponse.catch(() => { }).then(cleanupAndMarkComplete);
+                    return innerResponse;
+                },
+            });
+            const outerResponse = outer(innerHandler)(req, metadata);
+            outerResponse.catch(() => { }).then(maybeAbort);
+            return outerResponse;
+        };
+        return new HandlerChainBuilder(outerHandler);
+    }
+}
+//# sourceMappingURL=HandlerChainBuilder.js.map

package/lib/handlers/HandlerChainBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandlerChainBuilder.js","sourceRoot":"","sources":["../../src/handlers/HandlerChainBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["export type RequestMetadata =\n    | {\n          signal?: AbortSignal | null | undefined;\n      }\n    | undefined;\nexport type Handler<Req, Res, Meta extends RequestMetadata> = (req: Req, metadata?: Meta) => Promise<Res>;\nexport type ChainableHandler<Req, Res, NextReq, NextRes, Meta extends RequestMetadata | undefined> = (\n    next: Handler<NextReq, NextRes, Meta>\n) => Handler<Req, Res, Meta>;\n\n/**\n * Creates a Handler chain – a series of functions composed such that each function may call a supplied `next` function\n * which passes execution down the chain. When the final Handler in the chain returns, execution passes back up the\n * chain eventually returning to the caller.\n *\n * Each Handler chain begins with a \"raw\" Handler – this is a function which takes some request and returns some\n * response. A chain is then created by supplying a series of mapping functions – the ChainableHandler type – which will\n * be called with the `next` Handler in the chain.\n *\n * Ex:\n * ```ts\n * const handler = (request: string, metadata?: RequestMetadata) => Promise.resolve(`Responded to ${request}`)\n * const chainable = (next: Handler<string, string>) => (request: string, metadata?: RequestMetadata) => {\n *   return next(`modified ${request}`, metadata)\n * }\n *\n * const chain = new HandlerChainBuilder(handler)\n *   .map(chainable)\n *   .handler\n *\n * const response = await chain('hello')\n * expect(response).toBe('Responded to modified hello; 0')\n * ```\n * You can largely ignore the `metadata` argument present in the above example. This is the mechanism by which an\n * AbortSignal is passed to each Handler in the chain, but the only real requirement when implementing a Handler is\n * to pass this argument along to the `next` function. In fact, many Handlers will want to be generic over the type\n * of metadata:\n * ```ts\n * const chainable = <Meta>(next: Handler<string, string, Meta>) => (request: string, metadata: Meta) => {\n *   return next(`modified ${request}`, metadata)\n * }\n * ```\n * Actually, it's a very good idea for Handlers to be as generic as possible, since that will allow greater re-use. In\n * the above example, we don't do anything with the response from `next`, so we can let that be generic, too:\n * ```ts\n * const chainable = <Res, Meta>(next: Handler<string, Res, Meta>) => (request: string, metadata: Meta) => {\n *   return next(`modified ${request}`, metadata)\n * }\n * ```\n * Now if some other Handler in the chain decides to return a different response type, our Handler won't require any\n * changes to compile.\n *\n * ---\n *\n * Since execution passes from handler to handler in the chain, and then back, handlers have the opportunity to modify\n * or observe both the request and response. This might be useful for implementing serialization/deserialization, but\n * the simplest example that demonstrates this feature is measuring request latency:\n * ```ts\n * const latencyMeasuringHandler = <Req, Res, Meta>(next: Handler<Req, Res, Meta>) =>\n *   async (req: Req, metadata: Meta) => {\n *     const start = performance.now()\n *     const response = await next(req, metadata)\n *     const latency = performance.now() - start\n *     console.log(`latency for request ${request} was ${latency}`)\n *     return response\n *   }\n * ```\n * Execution is first passed to our measuring handler, which marks the `start` timestamp. Then it passes execution on\n * down the chain. After a response is received (by some handler down the chain), execution passes back up to our\n * handler here, which records the amount of time spent inside `next`.\n *\n * ---\n *\n * Handlers may also abort requests. They can do this in two ways:\n *   1. Create an `AbortController` and add its `AbortSignal` to the `metadata` object when calling `next`.\n *   2. Resolve its returned Promise.\n *\n * The first approach is straightforward, but the second may benefit from an example – the simplest is a handler which\n * will timeout a request:\n * ```ts\n * const timeoutHandler = <Req, Res, Meta>(next: Handler<Req, Res, Meta>) => (req: Req, metadata: Meta) => {\n *   return Promise.race([\n *     next(req, metadata),\n *     sleep(1000),\n *   ])\n * }\n * ```\n * The Promise returned by this handler will resolve either when the `next` handler resolves or 1 second has elapsed,\n * whichever happens first. If the timeout happens first, we want the `next` handler to recieve an abort signal so that\n * it can terminate early (since its result is no longer needed).\n *\n * HandlerChainBuilder makes this happen by observing when each handler completes, and sending an abort signal to all\n * the handlers \"downstream\" from the aborting handler.\n */\nexport class HandlerChainBuilder<Req, Res, Meta extends RequestMetadata> {\n    private readonly inner: Handler<Req, Res, Meta>;\n\n    constructor(inner: (req: Req, metadata: Meta) => Promise<Res>) {\n        // The TS compiler has the following behavior:\n        //\n        // class Infer<T extends SomeType | undefined> { constructor(f: (t?: T) => void) {} }\n        // const f = (t?: SomeType) => {}\n        // const i = new Infer(f)\n        //\n        // The type of `i` is inferred to be `Infer<SomeType>` instead of `Infer<SomeType | undefined>`, even though the\n        // type of `f`'s argument is `SomeType | undefined`. This seems to be a bug in type inference. Note that making\n        // the constructor argument required gives the expected behavior:\n        //\n        // class Infer<T extends SomeType | undefined> { constructor(f: (t: T) => void) {} }\n        // const f = (t?: SomeType) => {}\n        // const i = new Infer(f)\n        //\n        // Now `i` is inferred to be `Infer<SomeType | undefined>`.\n        //\n        // This has consequences if the inferred type T is used elsewhere in the class.\n        //\n        // In this case, we need to make sure that if the given `inner` function marks the metadata argument as\n        // optional, that HandlerChainBuilder correctly infers that the Meta type includes undefined. So we don't mark\n        // metadata as optional, and so we must cast to `Handler` (which does mark it as optional).\n        //\n        // Safety: We're adding `| undefined` to the metadata type, which may be unsafe – `undefined` may not be\n        // assignable to Meta. But when handling the argument of type Meta, we simply pass it through from handler to\n        // handler – we never call `inner` without passing the metadata argument we've received from some call to an\n        // outer handler. The typing visible to callers remains safe.\n        this.inner = inner as Handler<Req, Res, Meta>;\n    }\n\n    get handler(): Handler<Req, Res, Meta> {\n        return this.inner;\n    }\n\n    map<PriorReq, PriorRes>(\n        outer: ChainableHandler<PriorReq, PriorRes, Req, Res, Meta>\n    ): HandlerChainBuilder<PriorReq, PriorRes, Meta> {\n        // To create the next handler in the chain, we compose the \"outer\" handler with the \"inner\" handler.\n        //\n        // The outer handler observes its own completion and sends an abort signal to the inner handler when it has\n        // resolved. To prevent unexpected behavior, the inner handler also observes its own completion, setting a flag\n        // when it resolves so that – if it resolves before the outer handler – the outer handler can skip sending the\n        // abort signal (since the inner handler has already completed).\n        const outerHandler = (req: PriorReq, metadata: Meta): Promise<PriorRes> => {\n            const abort = new AbortController();\n            const signal = abort.signal;\n\n            // It's important to not signal an abort to an inner handler which has already completed – it seems like\n            // this would be a non-issue (shouldn't aborting after completion be a no-op?), but specifically for the\n            // browser's implementation of `fetch`, aborting even after the `fetch` Promise resolves can cause an abort\n            // error if e.g. the Fetch Response's body has not yet been read.\n            //\n            // So, for safety, we will only abort inner handlers which are still executing.\n            let innerCompleted = false;\n\n            const maybeAbort = () => {\n                // Safety: we never give `abort` to anyone else, so we know if the signal is aborted, this function\n                // has already run, so we can return early without fear of leaking. We also know if inner has completed,\n                // it has already performed cleanup.\n                if (signal.aborted || innerCompleted) return;\n\n                // If we've gotten here, the outer handler has either completed, or we heard an abort event while the\n                // inner handler is still executing – so we pass the abort signal down to the inner handler.\n                abort.abort();\n                metadata?.signal?.removeEventListener(\"abort\", maybeAbort);\n            };\n\n            metadata?.signal?.addEventListener(\"abort\", maybeAbort);\n\n            const innerHandler = new Proxy(this.inner, {\n                apply: (target, thisArg, args) => {\n                    const [req, metadata] = args as Parameters<typeof target>;\n\n                    // To help Handler authors out, we'll do some bookkeeping and cleanup for them – if they forget to\n                    // remove an abort event listener, we'll remove it for them when the Promise they return resolves.\n                    // Note: No need to proxy removeEventListener, since removing a non-existent listener just no-ops.\n                    const abortListeners: EventListenerOrEventListenerObject[] = [];\n                    signal.addEventListener = new Proxy(signal.addEventListener, {\n                        apply: (target, thisArg, args) => {\n                            abortListeners.push(args[1]);\n                            return Reflect.apply(target, thisArg, args);\n                        },\n                    });\n\n                    const cleanupAndMarkComplete = () => {\n                        // The only reason we listen to upstream aborts is to pass them to the inner handler – since the\n                        // inner handler has completed, we no longer need the listener.\n                        metadata?.signal?.removeEventListener(\"abort\", maybeAbort);\n                        abortListeners.forEach((listener) => signal.removeEventListener(\"abort\", listener));\n                        innerCompleted = true;\n                    };\n\n                    const innerResponse: ReturnType<typeof target> = Reflect.apply(target, thisArg, [\n                        req,\n                        { ...metadata, signal },\n                    ]);\n\n                    // Using `finally` is more idiomatic, but causes trouble in some environments (e.g. some testing\n                    // runtimes which detect uncaught rejected promises).\n                    innerResponse.catch(() => {}).then(cleanupAndMarkComplete);\n                    return innerResponse;\n                },\n            });\n\n            const outerResponse = outer(innerHandler)(req, metadata);\n            outerResponse.catch(() => {}).then(maybeAbort);\n            return outerResponse;\n        };\n        return new HandlerChainBuilder(outerHandler as Handler<PriorReq, PriorRes, Meta>);\n    }\n}\n"]}

package/lib/handlers/arrayBufferParsingHandler.d.ts

@@ -0,0 +1,10 @@
+import { ChainableHandler, RequestMetadata } from "./HandlerChainBuilder";
+declare type ArrayBufferResponse = [ArrayBuffer, Response];
+declare type ChainableArrayBufferHandler<Req, Meta extends RequestMetadata> = ChainableHandler<Req, ArrayBufferResponse, Req, Response, Meta>;
+/**
+ * Parse a Fetch Response body into an ArrayBuffer.
+ *
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export declare const createArrayBufferParsingHandler: <Req, Meta extends RequestMetadata>() => ChainableArrayBufferHandler<Req, Meta>;
+export {};

package/lib/handlers/arrayBufferParsingHandler.js

@@ -0,0 +1,18 @@
+import { __awaiter } from "tslib";
+/**
+ * Parse a Fetch Response body into an ArrayBuffer.
+ *
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export const createArrayBufferParsingHandler = () => (next) => (req, metadata) => __awaiter(void 0, void 0, void 0, function* () {
+    const response = yield next(req, metadata);
+    let buffer;
+    try {
+        buffer = yield response.arrayBuffer();
+    }
+    catch (_) {
+        buffer = new ArrayBuffer(0);
+    }
+    return [buffer, response];
+});
+//# sourceMappingURL=arrayBufferParsingHandler.js.map

package/lib/handlers/arrayBufferParsingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayBufferParsingHandler.js","sourceRoot":"","sources":["../../src/handlers/arrayBufferParsingHandler.ts"],"names":[],"mappings":";AAWA;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAG7C,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAO,GAAG,EAAE,QAAQ,EAAE,EAAE;IACnC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC3C,IAAI,MAAmB,CAAC;IACxB,IAAI;QACA,MAAM,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;KACzC;IAAC,OAAO,CAAC,EAAE;QACR,MAAM,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;KAC/B;IACD,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC,CAAA,CAAC","sourcesContent":["import { ChainableHandler, RequestMetadata } from \"./HandlerChainBuilder\";\n\ntype ArrayBufferResponse = [ArrayBuffer, Response];\ntype ChainableArrayBufferHandler<Req, Meta extends RequestMetadata> = ChainableHandler<\n    Req,\n    ArrayBufferResponse,\n    Req,\n    Response,\n    Meta\n>;\n\n/**\n * Parse a Fetch Response body into an ArrayBuffer.\n *\n * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}\n */\nexport const createArrayBufferParsingHandler = <Req, Meta extends RequestMetadata>(): ChainableArrayBufferHandler<\n    Req,\n    Meta\n> => (next) => async (req, metadata) => {\n    const response = await next(req, metadata);\n    let buffer: ArrayBuffer;\n    try {\n        buffer = await response.arrayBuffer();\n    } catch (_) {\n        buffer = new ArrayBuffer(0);\n    }\n    return [buffer, response];\n};\n"]}

package/lib/handlers/batchingHandler.d.ts

@@ -0,0 +1,25 @@
+import { ChainableHandler, RequestMetadata } from "./HandlerChainBuilder";
+export interface BatchingHandlerOptions<Req, BatchReq> {
+    batchReduce: (batch: BatchReq | undefined, req: Req) => BatchReq | Promise<BatchReq>;
+    isBatchComplete: (batch: BatchReq) => boolean;
+    maxBatchAge?: number;
+    flushOnPageHidden?: boolean;
+}
+/**
+ * Accumulate requests into batches, which are then sent to the next handler in the chain. Batches are sent when either:
+ * - the given `isBatchComplete` function returns true, closing the current batch and sending it down the chain.
+ * - an optional `maxBatchAge` time has elapsed since the first request in the batch was received.
+ * - the page terminates.
+ *
+ * When handling a request, the Promise returned will resolve when that request has been successfully added to the
+ * current batch – **NOT** when that batch has been successfully processed by the rest of the handler chain.
+ *
+ * The `next` handler in the chain will receive the batch and should handle any errors arising from further processing
+ * on the batch (e.g. sending it to a server).
+ *
+ * **Note:** This handler does not support aborting handled requests via AbortSignal.
+ *
+ * @param options
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export declare const createBatchingHandler: <Req, BatchReq, BatchRes, Meta extends RequestMetadata>({ batchReduce, isBatchComplete, maxBatchAge, flushOnPageHidden, }: BatchingHandlerOptions<Req, BatchReq>) => ChainableHandler<Req, void, BatchReq, BatchRes, Meta>;

package/lib/handlers/batchingHandler.js

@@ -0,0 +1,79 @@
+import { __awaiter } from "tslib";
+import { isDuringVisibilityTransition, onPageHidden } from "../common/pageVisibility";
+import { createMappingHandler } from "./mappingHandler";
+/**
+ * Accumulate requests into batches, which are then sent to the next handler in the chain. Batches are sent when either:
+ * - the given `isBatchComplete` function returns true, closing the current batch and sending it down the chain.
+ * - an optional `maxBatchAge` time has elapsed since the first request in the batch was received.
+ * - the page terminates.
+ *
+ * When handling a request, the Promise returned will resolve when that request has been successfully added to the
+ * current batch – **NOT** when that batch has been successfully processed by the rest of the handler chain.
+ *
+ * The `next` handler in the chain will receive the batch and should handle any errors arising from further processing
+ * on the batch (e.g. sending it to a server).
+ *
+ * **Note:** This handler does not support aborting handled requests via AbortSignal.
+ *
+ * @param options
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export const createBatchingHandler = ({ batchReduce, isBatchComplete, maxBatchAge, flushOnPageHidden, }) => {
+    // Flush batches when the page is hidden by default.
+    const doFlushOnPageHidden = flushOnPageHidden !== null && flushOnPageHidden !== void 0 ? flushOnPageHidden : true;
+    // TODO: this should just be `number`, but we're picking up NodeJS types (@types/node) when building, so setTimeout
+    // gets a different return type than what it should have in the browser. We should build without NodeJS types, but
+    // that will require some fixes across the codebase.
+    let batchTimeout;
+    let currentBatch = undefined;
+    let clearOnHidden = () => { };
+    const reducingHandler = createMappingHandler((request) => __awaiter(void 0, void 0, void 0, function* () {
+        currentBatch = yield batchReduce(currentBatch, request);
+        return currentBatch;
+    }), 1);
+    const batchAndSend = (next, request, metadata) => {
+        const batch = request ? batchReduce(currentBatch, request) : currentBatch;
+        if (!batch)
+            return;
+        // `next` should handle its own errors – that is, the batchingHandler is meant to be placed in a handler chain
+        // prior to any error logging, retrying, etc. handlers.
+        const complete = batch instanceof Promise
+            ? batch.then((b) => next(b, metadata)).catch(() => { })
+            : next(batch, metadata).catch(() => { });
+        currentBatch = undefined;
+        clearTimeout(batchTimeout);
+        clearOnHidden();
+        return complete;
+    };
+    return (next) => (request, metadata) => __awaiter(void 0, void 0, void 0, function* () {
+        // 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 batching and synchronously call `next` so that
+        // the request is not lost.
+        if (isDuringVisibilityTransition("hidden") && doFlushOnPageHidden) {
+            yield batchAndSend(next, request, metadata);
+            return;
+        }
+        // If this is the first request in a batch, we need to set up some callbacks to flush the batch when certain
+        // events occur:
+        //
+        // - maxBatchAge time passes.
+        // - page visibility transitions to hidden (which could indicate the page is being unloaded).
+        //
+        if (currentBatch === undefined) {
+            const sendBatch = () => batchAndSend(next, undefined, metadata);
+            if (maxBatchAge !== undefined)
+                batchTimeout = setTimeout(sendBatch, maxBatchAge);
+            if (doFlushOnPageHidden)
+                clearOnHidden = onPageHidden(sendBatch);
+        }
+        const handle = reducingHandler(() => __awaiter(void 0, void 0, void 0, function* () {
+            if (!currentBatch)
+                return;
+            if (!isBatchComplete(currentBatch))
+                return;
+            yield batchAndSend(next, undefined, metadata);
+        }));
+        return handle(request, metadata);
+    });
+};
+//# sourceMappingURL=batchingHandler.js.map

package/lib/handlers/batchingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batchingHandler.js","sourceRoot":"","sources":["../../src/handlers/batchingHandler.ts"],"names":[],"mappings":"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","sourcesContent":["import { isDuringVisibilityTransition, onPageHidden } from \"../common/pageVisibility\";\nimport { ChainableHandler, Handler, RequestMetadata } from \"./HandlerChainBuilder\";\nimport { createMappingHandler } from \"./mappingHandler\";\n\nexport interface BatchingHandlerOptions<Req, BatchReq> {\n    batchReduce: (batch: BatchReq | undefined, req: Req) => BatchReq | Promise<BatchReq>;\n    isBatchComplete: (batch: BatchReq) => boolean;\n    maxBatchAge?: number;\n    flushOnPageHidden?: boolean;\n}\n\n/**\n * Accumulate requests into batches, which are then sent to the next handler in the chain. Batches are sent when either:\n * - the given `isBatchComplete` function returns true, closing the current batch and sending it down the chain.\n * - an optional `maxBatchAge` time has elapsed since the first request in the batch was received.\n * - the page terminates.\n *\n * When handling a request, the Promise returned will resolve when that request has been successfully added to the\n * current batch – **NOT** when that batch has been successfully processed by the rest of the handler chain.\n *\n * The `next` handler in the chain will receive the batch and should handle any errors arising from further processing\n * on the batch (e.g. sending it to a server).\n *\n * **Note:** This handler does not support aborting handled requests via AbortSignal.\n *\n * @param options\n * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}\n */\nexport const createBatchingHandler = <Req, BatchReq, BatchRes, Meta extends RequestMetadata>({\n    batchReduce,\n    isBatchComplete,\n    maxBatchAge,\n    flushOnPageHidden,\n}: BatchingHandlerOptions<Req, BatchReq>): ChainableHandler<Req, void, BatchReq, BatchRes, Meta> => {\n    // Flush batches when the page is hidden by default.\n    const doFlushOnPageHidden = flushOnPageHidden ?? true;\n    // TODO: this should just be `number`, but we're picking up NodeJS types (@types/node) when building, so setTimeout\n    // gets a different return type than what it should have in the browser. We should build without NodeJS types, but\n    // that will require some fixes across the codebase.\n    let batchTimeout: ReturnType<typeof setTimeout>;\n    let currentBatch: BatchReq | undefined = undefined;\n    let clearOnHidden = () => {};\n\n    const reducingHandler = createMappingHandler<Req, BatchReq, void, Meta>(async (request) => {\n        currentBatch = await batchReduce(currentBatch, request);\n        return currentBatch;\n    }, 1);\n\n    const batchAndSend = (next: Handler<BatchReq, BatchRes, Meta>, request?: Req, metadata?: Meta) => {\n        const batch = request ? batchReduce(currentBatch, request) : currentBatch;\n        if (!batch) return;\n\n        // `next` should handle its own errors – that is, the batchingHandler is meant to be placed in a handler chain\n        // prior to any error logging, retrying, etc. handlers.\n        const complete =\n            batch instanceof Promise\n                ? batch.then((b) => next(b, metadata)).catch(() => {})\n                : next(batch, metadata).catch(() => {});\n\n        currentBatch = undefined;\n        clearTimeout(batchTimeout);\n        clearOnHidden();\n\n        return complete;\n    };\n\n    return (next) => async (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 batching and synchronously call `next` so that\n        // the request is not lost.\n        if (isDuringVisibilityTransition(\"hidden\") && doFlushOnPageHidden) {\n            await batchAndSend(next, request, metadata);\n            return;\n        }\n\n        // If this is the first request in a batch, we need to set up some callbacks to flush the batch when certain\n        // events occur:\n        //\n        // - maxBatchAge time passes.\n        // - page visibility transitions to hidden (which could indicate the page is being unloaded).\n        //\n        if (currentBatch === undefined) {\n            const sendBatch = () => batchAndSend(next, undefined, metadata);\n            if (maxBatchAge !== undefined) batchTimeout = setTimeout(sendBatch, maxBatchAge);\n            if (doFlushOnPageHidden) clearOnHidden = onPageHidden(sendBatch);\n        }\n\n        const handle = reducingHandler(async () => {\n            if (!currentBatch) return;\n            if (!isBatchComplete(currentBatch)) return;\n            await batchAndSend(next, undefined, metadata);\n        });\n\n        return handle(request, metadata);\n    };\n};\n"]}

package/lib/handlers/cameraKitServiceFetchHandlerFactory.d.ts

@@ -0,0 +1,12 @@
+import { CameraKitConfiguration } from "../configuration";
+import { FetchHandler } from "./defaultFetchHandler";
+/**
+ * A Fetch implementation which adds headers required to make authenticated calls to the CameraKit backend service.
+ *
+ * @internal
+ */
+export declare const cameraKitServiceFetchHandlerFactory: {
+    (args_0: CameraKitConfiguration, args_1: FetchHandler<Response>): import("./HandlerChainBuilder").Handler<RequestInfo, Response, RequestInit | undefined>;
+    token: "cameraKitServiceFetchHandler";
+    dependencies: readonly ["configuration", "defaultFetchHandler"];
+};

package/lib/handlers/cameraKitServiceFetchHandlerFactory.js

@@ -0,0 +1,19 @@
+import { cameraKitUserAgent } from "../common/cameraKitUserAgent";
+import { configurationToken } from "../configuration";
+import { Injectable } from "../dependency-injection/Injectable";
+import { defaultFetchHandlerFactory } from "./defaultFetchHandler";
+import { HandlerChainBuilder } from "./HandlerChainBuilder";
+import { createHeadersModifyingFetchHandler } from "./headersModifyingFetchHandler";
+/**
+ * A Fetch implementation which adds headers required to make authenticated calls to the CameraKit backend service.
+ *
+ * @internal
+ */
+export const cameraKitServiceFetchHandlerFactory = Injectable("cameraKitServiceFetchHandler", [configurationToken, defaultFetchHandlerFactory.token], ({ apiToken }, defaultFetchHandler) => {
+    return new HandlerChainBuilder(defaultFetchHandler).map(createHeadersModifyingFetchHandler((headers) => {
+        headers.append("x-snap-client-user-agent", cameraKitUserAgent.userAgent);
+        headers.append("authorization", `Bearer ${apiToken}`);
+        return headers;
+    })).handler;
+});
+//# sourceMappingURL=cameraKitServiceFetchHandlerFactory.js.map

package/lib/handlers/cameraKitServiceFetchHandlerFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cameraKitServiceFetchHandlerFactory.js","sourceRoot":"","sources":["../../src/handlers/cameraKitServiceFetchHandlerFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAA0B,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAgB,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,kCAAkC,EAAE,MAAM,gCAAgC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,UAAU,CACzD,8BAA8B,EAC9B,CAAC,kBAAkB,EAAE,0BAA0B,CAAC,KAAK,CAAU,EAC/D,CAAC,EAAE,QAAQ,EAA0B,EAAE,mBAAiC,EAAE,EAAE;IACxE,OAAO,IAAI,mBAAmB,CAAC,mBAAmB,CAAC,CAAC,GAAG,CACnD,kCAAkC,CAAC,CAAC,OAAO,EAAE,EAAE;QAC3C,OAAO,CAAC,MAAM,CAAC,0BAA0B,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;QACzE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,UAAU,QAAQ,EAAE,CAAC,CAAC;QACtD,OAAO,OAAO,CAAC;IACnB,CAAC,CAAC,CACL,CAAC,OAAO,CAAC;AACd,CAAC,CACJ,CAAC","sourcesContent":["import { cameraKitUserAgent } from \"../common/cameraKitUserAgent\";\nimport { CameraKitConfiguration, configurationToken } from \"../configuration\";\nimport { Injectable } from \"../dependency-injection/Injectable\";\nimport { defaultFetchHandlerFactory, FetchHandler } from \"./defaultFetchHandler\";\nimport { HandlerChainBuilder } from \"./HandlerChainBuilder\";\nimport { createHeadersModifyingFetchHandler } from \"./headersModifyingFetchHandler\";\n\n/**\n * A Fetch implementation which adds headers required to make authenticated calls to the CameraKit backend service.\n *\n * @internal\n */\nexport const cameraKitServiceFetchHandlerFactory = Injectable(\n    \"cameraKitServiceFetchHandler\",\n    [configurationToken, defaultFetchHandlerFactory.token] as const,\n    ({ apiToken }: CameraKitConfiguration, defaultFetchHandler: FetchHandler) => {\n        return new HandlerChainBuilder(defaultFetchHandler).map(\n            createHeadersModifyingFetchHandler((headers) => {\n                headers.append(\"x-snap-client-user-agent\", cameraKitUserAgent.userAgent);\n                headers.append(\"authorization\", `Bearer ${apiToken}`);\n                return headers;\n            })\n        ).handler;\n    }\n);\n"]}

package/lib/handlers/debugHandler.d.ts

@@ -0,0 +1,8 @@
+import { ChainableHandler } from "./HandlerChainBuilder";
+/**
+ * Addes cookies to auth requests to custom LensCore binaries
+ * when there are debugging overrides.
+ *
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export declare const createDebugHandler: <Res>() => ChainableHandler<RequestInfo, Res, RequestInfo, Res, RequestInit | undefined>;

package/lib/handlers/debugHandler.js

@@ -0,0 +1,27 @@
+import { isString } from "../common/typeguards";
+import { getConfigurationOverrides } from "../configurationOverrides";
+/**
+ * Addes cookies to auth requests to custom LensCore binaries
+ * when there are debugging overrides.
+ *
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export const createDebugHandler = () => {
+    var _a;
+    const noCustomWasmEndpoint = !((_a = getConfigurationOverrides()) === null || _a === void 0 ? void 0 : _a.wasmEndpointOverride);
+    if (noCustomWasmEndpoint) {
+        return (next) => next;
+    }
+    return (next) => (input, init) => {
+        var _a;
+        const url = isString(input) ? input : (_a = input === null || input === void 0 ? void 0 : input.url) !== null && _a !== void 0 ? _a : "";
+        // if requests are made to internal LensCore binaries site
+        // we have to include cookies for auth purposes
+        // as per https://wiki.sc-corp.net/x/KsnRCg
+        if (url.startsWith("https://lens-core-wasm.sc-corp.net/")) {
+            return next(input, Object.assign(Object.assign({}, init), { credentials: "include" }));
+        }
+        return next(input, init);
+    };
+};
+//# sourceMappingURL=debugHandler.js.map

package/lib/handlers/debugHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugHandler.js","sourceRoot":"","sources":["../../src/handlers/debugHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAGtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAMhC,EAAE;;IACA,MAAM,oBAAoB,GAAG,CAAC,CAAA,MAAA,yBAAyB,EAAE,0CAAE,oBAAoB,CAAA,CAAC;IAEhF,IAAI,oBAAoB,EAAE;QACtB,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;KACzB;IACD,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;;QAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,GAAG,mCAAI,EAAE,CAAC;QACvD,0DAA0D;QAC1D,+CAA+C;QAC/C,2CAA2C;QAC3C,IAAI,GAAG,CAAC,UAAU,CAAC,qCAAqC,CAAC,EAAE;YACvD,OAAO,IAAI,CAAC,KAAK,kCACV,IAAI,KACP,WAAW,EAAE,SAAS,IACxB,CAAC;SACN;QACD,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC;AACN,CAAC,CAAC","sourcesContent":["import { isString } from \"../common/typeguards\";\nimport { getConfigurationOverrides } from \"../configurationOverrides\";\nimport { ChainableHandler, HandlerChainBuilder } from \"./HandlerChainBuilder\";\n\n/**\n * Addes cookies to auth requests to custom LensCore binaries\n * when there are debugging overrides.\n *\n * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}\n */\nexport const createDebugHandler = <Res>(): ChainableHandler<\n    RequestInfo,\n    Res,\n    RequestInfo,\n    Res,\n    RequestInit | undefined\n> => {\n    const noCustomWasmEndpoint = !getConfigurationOverrides()?.wasmEndpointOverride;\n\n    if (noCustomWasmEndpoint) {\n        return (next) => next;\n    }\n    return (next) => (input, init) => {\n        const url = isString(input) ? input : input?.url ?? \"\";\n        // if requests are made to internal LensCore binaries site\n        // we have to include cookies for auth purposes\n        // as per https://wiki.sc-corp.net/x/KsnRCg\n        if (url.startsWith(\"https://lens-core-wasm.sc-corp.net/\")) {\n            return next(input, {\n                ...init,\n                credentials: \"include\",\n            });\n        }\n        return next(input, init);\n    };\n};\n"]}

package/lib/handlers/defaultFetchHandler.d.ts

@@ -0,0 +1,15 @@
+export declare type FetchHandler<R = Response> = (input: RequestInfo, init?: RequestInit) => Promise<R>;
+/**
+ * The default Fetch implementation, used to make a simple HTTP requests without any custom headers. This can be passed
+ * to `HandlerChainBuilder` to form the basis for other Fetch implementations (e.g. with custom headers, which extract
+ * the Response body, etc.)
+ *
+ * Has support for retries, client-side timeout, and navigating federated auth flows that may not support CORs requests.
+ *
+ * @internal
+ */
+export declare const defaultFetchHandlerFactory: {
+    (): import("./HandlerChainBuilder").Handler<RequestInfo, Response, RequestInit | undefined>;
+    token: "defaultFetchHandler";
+    dependencies: [];
+};

package/lib/handlers/defaultFetchHandler.js

@@ -0,0 +1,29 @@
+import { Injectable } from "../dependency-injection/Injectable";
+import { createDebugHandler } from "./debugHandler";
+import { HandlerChainBuilder } from "./HandlerChainBuilder";
+import { createNoCorsRetryingFetchHandler } from "./noCorsRetryingFetchHandler";
+import { createRetryingHandler } from "./retryingHandler";
+import { createTimeoutHandler } from "./timeoutHandler";
+/**
+ * The default Fetch implementation, used to make a simple HTTP requests without any custom headers. This can be passed
+ * to `HandlerChainBuilder` to form the basis for other Fetch implementations (e.g. with custom headers, which extract
+ * the Response body, etc.)
+ *
+ * Has support for retries, client-side timeout, and navigating federated auth flows that may not support CORs requests.
+ *
+ * @internal
+ */
+export const defaultFetchHandlerFactory = Injectable("defaultFetchHandler", () => {
+    return (
+    // Safety: We're re-typing fetch's second argument from `init?: RequestInit | undefined` to
+    // `init: RequestInit | void` – this is semantically equivalent, but the void makes for nicer ergonomics
+    // elsewhere (e.g. so that callers can omit the second argument instead of being forced to pass undefined).
+    new HandlerChainBuilder(fetch)
+        .map(createDebugHandler())
+        .map(createNoCorsRetryingFetchHandler())
+        .map(createRetryingHandler())
+        // TODO: completely arbitrary timeout -- this should be configurable by consumers, and we should think
+        // about a sane default timeout UX... it's probably less than 10 seconds.
+        .map(createTimeoutHandler({ timeout: 10 * 1000 })).handler);
+});
+//# sourceMappingURL=defaultFetchHandler.js.map

package/lib/handlers/defaultFetchHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultFetchHandler.js","sourceRoot":"","sources":["../../src/handlers/defaultFetchHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAIxD;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC,qBAAqB,EAAE,GAAG,EAAE;IAC7E,OAAO;IACH,2FAA2F;IAC3F,wGAAwG;IACxG,2GAA2G;IAC3G,IAAI,mBAAmB,CAAiD,KAAK,CAAC;SACzE,GAAG,CAAC,kBAAkB,EAAE,CAAC;SACzB,GAAG,CAAC,gCAAgC,EAAE,CAAC;SACvC,GAAG,CAAC,qBAAqB,EAAE,CAAC;QAE7B,sGAAsG;QACtG,yEAAyE;SACxE,GAAG,CAAC,oBAAoB,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CACjE,CAAC;AACN,CAAC,CAAC,CAAC","sourcesContent":["import { Injectable } from \"../dependency-injection/Injectable\";\nimport { createDebugHandler } from \"./debugHandler\";\nimport { HandlerChainBuilder } from \"./HandlerChainBuilder\";\nimport { createNoCorsRetryingFetchHandler } from \"./noCorsRetryingFetchHandler\";\nimport { createRetryingHandler } from \"./retryingHandler\";\nimport { createTimeoutHandler } from \"./timeoutHandler\";\n\nexport type FetchHandler<R = Response> = (input: RequestInfo, init?: RequestInit) => Promise<R>;\n\n/**\n * The default Fetch implementation, used to make a simple HTTP requests without any custom headers. This can be passed\n * to `HandlerChainBuilder` to form the basis for other Fetch implementations (e.g. with custom headers, which extract\n * the Response body, etc.)\n *\n * Has support for retries, client-side timeout, and navigating federated auth flows that may not support CORs requests.\n *\n * @internal\n */\n\nexport const defaultFetchHandlerFactory = Injectable(\"defaultFetchHandler\", () => {\n    return (\n        // Safety: We're re-typing fetch's second argument from `init?: RequestInit | undefined` to\n        // `init: RequestInit | void` – this is semantically equivalent, but the void makes for nicer ergonomics\n        // elsewhere (e.g. so that callers can omit the second argument instead of being forced to pass undefined).\n        new HandlerChainBuilder<RequestInfo, Response, RequestInit | undefined>(fetch)\n            .map(createDebugHandler())\n            .map(createNoCorsRetryingFetchHandler())\n            .map(createRetryingHandler())\n\n            // TODO: completely arbitrary timeout -- this should be configurable by consumers, and we should think\n            // about a sane default timeout UX... it's probably less than 10 seconds.\n            .map(createTimeoutHandler({ timeout: 10 * 1000 })).handler\n    );\n});\n"]}

package/lib/handlers/headersModifyingFetchHandler.d.ts

@@ -0,0 +1,8 @@
+import { ChainableHandler } from "./HandlerChainBuilder";
+/**
+ * Modify a Fetch Request's headers.
+ *
+ * @param modifyHeaders
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export declare const createHeadersModifyingFetchHandler: <Res>(modifyHeaders: (headers: Headers) => Headers) => ChainableHandler<RequestInfo, Res, RequestInfo, Res, RequestInit | undefined>;

package/lib/handlers/headersModifyingFetchHandler.js

@@ -0,0 +1,13 @@
+/**
+ * Modify a Fetch Request's headers.
+ *
+ * @param modifyHeaders
+ * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}
+ */
+export const createHeadersModifyingFetchHandler = (modifyHeaders) => (next) => (input, init) => {
+    const headers = init && init.headers ? new Headers(init.headers) : typeof input === "string" ? new Headers() : input.headers;
+    const modifiedHeaders = modifyHeaders(headers);
+    // When `init` contains headers, `fetch` uses these *instead* of any headers found in the `input` Request.
+    return next(input, Object.assign(Object.assign({}, init), { headers: modifiedHeaders }));
+};
+//# sourceMappingURL=headersModifyingFetchHandler.js.map

package/lib/handlers/headersModifyingFetchHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headersModifyingFetchHandler.js","sourceRoot":"","sources":["../../src/handlers/headersModifyingFetchHandler.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAC9C,aAA4C,EACiC,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;IAC1G,MAAM,OAAO,GACT,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IAEjH,MAAM,eAAe,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAE/C,0GAA0G;IAC1G,OAAO,IAAI,CAAC,KAAK,kCAAO,IAAI,KAAE,OAAO,EAAE,eAAe,IAAG,CAAC;AAC9D,CAAC,CAAC","sourcesContent":["import { ChainableHandler } from \"./HandlerChainBuilder\";\n\n/**\n * Modify a Fetch Request's headers.\n *\n * @param modifyHeaders\n * @returns {@link ChainableHandler}, suitable for use in {@link HandlerChainBuilder.map}\n */\nexport const createHeadersModifyingFetchHandler = <Res>(\n    modifyHeaders: (headers: Headers) => Headers\n): ChainableHandler<RequestInfo, Res, RequestInfo, Res, RequestInit | undefined> => (next) => (input, init) => {\n    const headers =\n        init && init.headers ? new Headers(init.headers) : typeof input === \"string\" ? new Headers() : input.headers;\n\n    const modifiedHeaders = modifyHeaders(headers);\n\n    // When `init` contains headers, `fetch` uses these *instead* of any headers found in the `input` Request.\n    return next(input, { ...init, headers: modifiedHeaders });\n};\n"]}

package/lib/handlers/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./defaultFetchHandler";
+export * from "./cameraKitServiceFetchHandlerFactory";

package/lib/handlers/index.js

@@ -0,0 +1,3 @@
+export * from "./defaultFetchHandler";
+export * from "./cameraKitServiceFetchHandlerFactory";
+//# sourceMappingURL=index.js.map

package/lib/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,uCAAuC,CAAC","sourcesContent":["export * from \"./defaultFetchHandler\";\nexport * from \"./cameraKitServiceFetchHandlerFactory\";\n"]}

package/lib/handlers/mappingHandler.d.ts

@@ -0,0 +1,15 @@
+import { ChainableHandler, RequestMetadata } from "./HandlerChainBuilder";
+/**
+ * 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 declare const createMappingHandler: <Req, MappedReq, Res, Meta extends RequestMetadata>(map: (request: Req) => MappedReq | Promise<MappedReq>, maxMapConcurrency?: number, flushOnPageHidden?: boolean) => ChainableHandler<Req, Res, MappedReq, Res, Meta>;