cloudstructs 0.6.17 → 0.6.18

package/assets/slack-textract/detect.lambda/index.js

@@ -21,6 +21,10 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
@@ -287,6 +291,7 @@ var require_p_timeout = __commonJS({
         reject(timeoutError);
       }, milliseconds);
       pFinally(
+        // eslint-disable-next-line promise/prefer-await-to-then
         promise.then(resolve, reject),
         () => {
           clearTimeout(timer);
@@ -484,6 +489,9 @@ var require_dist = __commonJS({
         this._intervalCount = this._carryoverConcurrencyCount ? this._pendingCount : 0;
         this._processQueue();
       }
+      /**
+      Executes all queued functions until it reaches the limit.
+      */
       _processQueue() {
         while (this._tryToStartAnother()) {
         }
@@ -498,6 +506,9 @@ var require_dist = __commonJS({
         this._concurrency = newConcurrency;
         this._processQueue();
       }
+      /**
+      Adds a sync or async task to the queue. Always returns a promise.
+      */
       async add(fn, options = {}) {
         return new Promise((resolve, reject) => {
           const run = async () => {
@@ -521,9 +532,17 @@ var require_dist = __commonJS({
           this.emit("add");
         });
       }
+      /**
+          Same as `.add()`, but accepts an array of sync or async functions.
+      
+          @returns A promise that resolves when all functions are resolved.
+          */
       async addAll(functions, options) {
         return Promise.all(functions.map(async (function_) => this.add(function_, options)));
       }
+      /**
+      Start (or resume) executing enqueued tasks within concurrency limit. No need to call this if queue is not paused (via `options.autoStart = false` or by `.pause()` method.)
+      */
       start() {
         if (!this._isPaused) {
           return this;
@@ -532,12 +551,23 @@ var require_dist = __commonJS({
         this._processQueue();
         return this;
       }
+      /**
+      Put queue execution on hold.
+      */
       pause() {
         this._isPaused = true;
       }
+      /**
+      Clear the queue.
+      */
       clear() {
         this._queue = new this._queueClass();
       }
+      /**
+          Can be called multiple times. Useful if you for example add additional items at a later time.
+      
+          @returns A promise that settles when the queue becomes empty.
+          */
       async onEmpty() {
         if (this._queue.size === 0) {
           return;
@@ -550,6 +580,11 @@ var require_dist = __commonJS({
           };
         });
       }
+      /**
+          The difference with `.onEmpty` is that `.onIdle` guarantees that all work from the queue has finished. `.onEmpty` merely signals that the queue is empty, but it could mean that some promises haven't completed yet.
+      
+          @returns A promise that settles when the queue becomes empty, and all promises have completed; `queue.size === 0 && queue.pending === 0`.
+          */
       async onIdle() {
         if (this._pendingCount === 0 && this._queue.size === 0) {
           return;
@@ -562,21 +597,38 @@ var require_dist = __commonJS({
           };
         });
       }
+      /**
+      Size of the queue.
+      */
       get size() {
         return this._queue.size;
       }
+      /**
+          Size of the queue, filtered by the given options.
+      
+          For example, this can be used to find the number of items remaining in the queue with a specific priority level.
+          */
       sizeBy(options) {
         return this._queue.filter(options).length;
       }
+      /**
+      Number of pending promises.
+      */
       get pending() {
         return this._pendingCount;
       }
+      /**
+      Whether the queue is currently paused.
+      */
       get isPaused() {
         return this._isPaused;
       }
       get timeout() {
         return this._timeout;
       }
+      /**
+      Set the timeout for future operations.
+      */
       set timeout(milliseconds) {
         this._timeout = milliseconds;
       }
@@ -820,9 +872,13 @@ var require_p_retry = __commonJS({
     var retry = require_retry2();
     var networkErrorMsgs = [
       "Failed to fetch",
+      // Chrome
       "NetworkError when attempting to fetch resource.",
+      // Firefox
       "The Internet connection appears to be offline.",
+      // Safari
       "Network request failed"
+      // `cross-fetch`
     ];
     var AbortError = class extends Error {
       constructor(message) {
@@ -1171,14 +1227,18 @@ var require_enhanceError = __commonJS({
       error.isAxiosError = true;
       error.toJSON = function toJSON() {
         return {
+          // Standard
           message: this.message,
           name: this.name,
+          // Microsoft
           description: this.description,
           number: this.number,
+          // Mozilla
           fileName: this.fileName,
           lineNumber: this.lineNumber,
           columnNumber: this.columnNumber,
           stack: this.stack,
+          // Axios
           config: this.config,
           code: this.code
         };
@@ -1227,44 +1287,50 @@ var require_cookies = __commonJS({
   "node_modules/axios/lib/helpers/cookies.js"(exports, module2) {
     "use strict";
     var utils = require_utils();
-    module2.exports = utils.isStandardBrowserEnv() ? function standardBrowserEnv() {
-      return {
-        write: function write(name, value, expires, path, domain, secure) {
-          var cookie = [];
-          cookie.push(name + "=" + encodeURIComponent(value));
-          if (utils.isNumber(expires)) {
-            cookie.push("expires=" + new Date(expires).toGMTString());
-          }
-          if (utils.isString(path)) {
-            cookie.push("path=" + path);
-          }
-          if (utils.isString(domain)) {
-            cookie.push("domain=" + domain);
+    module2.exports = utils.isStandardBrowserEnv() ? (
+      // Standard browser envs support document.cookie
+      function standardBrowserEnv() {
+        return {
+          write: function write(name, value, expires, path, domain, secure) {
+            var cookie = [];
+            cookie.push(name + "=" + encodeURIComponent(value));
+            if (utils.isNumber(expires)) {
+              cookie.push("expires=" + new Date(expires).toGMTString());
+            }
+            if (utils.isString(path)) {
+              cookie.push("path=" + path);
+            }
+            if (utils.isString(domain)) {
+              cookie.push("domain=" + domain);
+            }
+            if (secure === true) {
+              cookie.push("secure");
+            }
+            document.cookie = cookie.join("; ");
+          },
+          read: function read(name) {
+            var match = document.cookie.match(new RegExp("(^|;\\s*)(" + name + ")=([^;]*)"));
+            return match ? decodeURIComponent(match[3]) : null;
+          },
+          remove: function remove(name) {
+            this.write(name, "", Date.now() - 864e5);
           }
-          if (secure === true) {
-            cookie.push("secure");
+        };
+      }()
+    ) : (
+      // Non standard browser env (web workers, react-native) lack needed support.
+      function nonStandardBrowserEnv() {
+        return {
+          write: function write() {
+          },
+          read: function read() {
+            return null;
+          },
+          remove: function remove() {
           }
-          document.cookie = cookie.join("; ");
-        },
-        read: function read(name) {
-          var match = document.cookie.match(new RegExp("(^|;\\s*)(" + name + ")=([^;]*)"));
-          return match ? decodeURIComponent(match[3]) : null;
-        },
-        remove: function remove(name) {
-          this.write(name, "", Date.now() - 864e5);
-        }
-      };
-    }() : function nonStandardBrowserEnv() {
-      return {
-        write: function write() {
-        },
-        read: function read() {
-          return null;
-        },
-        remove: function remove() {
-        }
-      };
-    }();
+        };
+      }()
+    );
   }
 });
 
@@ -1360,38 +1426,45 @@ var require_isURLSameOrigin = __commonJS({
   "node_modules/axios/lib/helpers/isURLSameOrigin.js"(exports, module2) {
     "use strict";
     var utils = require_utils();
-    module2.exports = utils.isStandardBrowserEnv() ? function standardBrowserEnv() {
-      var msie = /(msie|trident)/i.test(navigator.userAgent);
-      var urlParsingNode = document.createElement("a");
-      var originURL;
-      function resolveURL(url) {
-        var href = url;
-        if (msie) {
+    module2.exports = utils.isStandardBrowserEnv() ? (
+      // Standard browser envs have full support of the APIs needed to test
+      // whether the request URL is of the same origin as current location.
+      function standardBrowserEnv() {
+        var msie = /(msie|trident)/i.test(navigator.userAgent);
+        var urlParsingNode = document.createElement("a");
+        var originURL;
+        function resolveURL(url) {
+          var href = url;
+          if (msie) {
+            urlParsingNode.setAttribute("href", href);
+            href = urlParsingNode.href;
+          }
           urlParsingNode.setAttribute("href", href);
-          href = urlParsingNode.href;
+          return {
+            href: urlParsingNode.href,
+            protocol: urlParsingNode.protocol ? urlParsingNode.protocol.replace(/:$/, "") : "",
+            host: urlParsingNode.host,
+            search: urlParsingNode.search ? urlParsingNode.search.replace(/^\?/, "") : "",
+            hash: urlParsingNode.hash ? urlParsingNode.hash.replace(/^#/, "") : "",
+            hostname: urlParsingNode.hostname,
+            port: urlParsingNode.port,
+            pathname: urlParsingNode.pathname.charAt(0) === "/" ? urlParsingNode.pathname : "/" + urlParsingNode.pathname
+          };
         }
-        urlParsingNode.setAttribute("href", href);
-        return {
-          href: urlParsingNode.href,
-          protocol: urlParsingNode.protocol ? urlParsingNode.protocol.replace(/:$/, "") : "",
-          host: urlParsingNode.host,
-          search: urlParsingNode.search ? urlParsingNode.search.replace(/^\?/, "") : "",
-          hash: urlParsingNode.hash ? urlParsingNode.hash.replace(/^#/, "") : "",
-          hostname: urlParsingNode.hostname,
-          port: urlParsingNode.port,
-          pathname: urlParsingNode.pathname.charAt(0) === "/" ? urlParsingNode.pathname : "/" + urlParsingNode.pathname
+        originURL = resolveURL(window.location.href);
+        return function isURLSameOrigin(requestURL) {
+          var parsed = utils.isString(requestURL) ? resolveURL(requestURL) : requestURL;
+          return parsed.protocol === originURL.protocol && parsed.host === originURL.host;
         };
-      }
-      originURL = resolveURL(window.location.href);
-      return function isURLSameOrigin(requestURL) {
-        var parsed = utils.isString(requestURL) ? resolveURL(requestURL) : requestURL;
-        return parsed.protocol === originURL.protocol && parsed.host === originURL.host;
-      };
-    }() : function nonStandardBrowserEnv() {
-      return function isURLSameOrigin() {
-        return true;
-      };
-    }();
+      }()
+    ) : (
+      // Non standard browser envs (web workers, react-native) lack needed support.
+      function nonStandardBrowserEnv() {
+        return function isURLSameOrigin() {
+          return true;
+        };
+      }()
+    );
   }
 });
 
@@ -1905,7 +1978,11 @@ var require_browser = __commonJS({
       if (typeof navigator !== "undefined" && navigator.userAgent && navigator.userAgent.toLowerCase().match(/(edge|trident)\/(\d+)/)) {
         return false;
       }
-      return typeof document !== "undefined" && document.documentElement && document.documentElement.style && document.documentElement.style.WebkitAppearance || typeof window !== "undefined" && window.console && (window.console.firebug || window.console.exception && window.console.table) || typeof navigator !== "undefined" && navigator.userAgent && navigator.userAgent.toLowerCase().match(/firefox\/(\d+)/) && parseInt(RegExp.$1, 10) >= 31 || typeof navigator !== "undefined" && navigator.userAgent && navigator.userAgent.toLowerCase().match(/applewebkit\/(\d+)/);
+      return typeof document !== "undefined" && document.documentElement && document.documentElement.style && document.documentElement.style.WebkitAppearance || // Is firebug? http://stackoverflow.com/a/398120/376773
+      typeof window !== "undefined" && window.console && (window.console.firebug || window.console.exception && window.console.table) || // Is firefox >= v31?
+      // https://developer.mozilla.org/en-US/docs/Tools/Web_Console#Styling_messages
+      typeof navigator !== "undefined" && navigator.userAgent && navigator.userAgent.toLowerCase().match(/firefox\/(\d+)/) && parseInt(RegExp.$1, 10) >= 31 || // Double check webkit in userAgent just in case we are in a worker
+      typeof navigator !== "undefined" && navigator.userAgent && navigator.userAgent.toLowerCase().match(/applewebkit\/(\d+)/);
     }
     function formatArgs(args) {
       args[0] = (this.useColors ? "%c" : "") + this.namespace + (this.useColors ? " %c" : " ") + args[0] + (this.useColors ? "%c " : " ") + "+" + module2.exports.humanize(this.diff);
@@ -2504,7 +2581,11 @@ var require_follow_redirects = __commonJS({
       for (var event of events) {
         request.on(event, eventHandlers[event]);
       }
-      this._currentUrl = /^\//.test(this._options.path) ? url.format(this._options) : this._options.path;
+      this._currentUrl = /^\//.test(this._options.path) ? url.format(this._options) : (
+        // When making a request to a proxy, […]
+        // a client MUST send the target URI in absolute-form […].
+        this._options.path
+      );
       if (this._isRedirect) {
         var i = 0;
         var self = this;
@@ -2552,11 +2633,16 @@ var require_follow_redirects = __commonJS({
       var beforeRedirect = this._options.beforeRedirect;
       if (beforeRedirect) {
         requestHeaders = Object.assign({
+          // The Host header was set by nativeProtocol.request
           Host: response.req.getHeader("host")
         }, this._options.headers);
       }
       var method = this._options.method;
-      if ((statusCode === 301 || statusCode === 302) && this._options.method === "POST" || statusCode === 303 && !/^(?:GET|HEAD)$/.test(this._options.method)) {
+      if ((statusCode === 301 || statusCode === 302) && this._options.method === "POST" || // RFC7231§6.4.4: The 303 (See Other) status code indicates that
+      // the server is redirecting the user agent to a different resource […]
+      // A user agent can perform a retrieval request targeting that URI
+      // (a GET or HEAD request if using HTTP) […]
+      statusCode === 303 && !/^(?:GET|HEAD)$/.test(this._options.method)) {
         this._options.method = "GET";
         this._requestBodyBuffers = [];
         removeMatchingHeaders(/^content-/i, this._options.headers);
@@ -2665,7 +2751,10 @@ var require_follow_redirects = __commonJS({
     function urlToOptions(urlObject) {
       var options = {
         protocol: urlObject.protocol,
-        hostname: urlObject.hostname.startsWith("[") ? urlObject.hostname.slice(1, -1) : urlObject.hostname,
+        hostname: urlObject.hostname.startsWith("[") ? (
+          /* istanbul ignore next */
+          urlObject.hostname.slice(1, -1)
+        ) : urlObject.hostname,
         hash: urlObject.hash,
         search: urlObject.search,
         pathname: urlObject.pathname,
@@ -3160,6 +3249,10 @@ var require_defaults = __commonJS({
         }
         return data;
       }],
+      /**
+       * A timeout in milliseconds to abort a request. If set to 0 (default) a
+       * timeout is not created.
+       */
       timeout: 0,
       xsrfCookieName: "XSRF-TOKEN",
       xsrfHeaderName: "X-XSRF-TOKEN",
@@ -12870,7 +12963,9 @@ var require_form_data = __commonJS({
       var contentType = this._getContentType(value, options);
       var contents = "";
       var headers = {
+        // add custom disposition as third element or keep it two elements if not
         "Content-Disposition": ["form-data", 'name="' + field + '"'].concat(contentDisposition || []),
+        // if no content type. allow it to be empty array
         "Content-Type": [].concat(contentType || [])
       };
       if (typeof options.header == "object") {
@@ -13285,6 +13380,12 @@ var require_methods = __commonJS({
       return self.apiCall.bind(self, method);
     }
     var Methods = class extends eventemitter3_1.EventEmitter {
+      // TODO: As of writing, `WebClient` already extends EventEmitter...
+      // and I want WebClient to extend this class...
+      // and multiple inheritance in JS is cursed...
+      // so I'm just making this class extend EventEmitter.
+      //
+      // It shouldn't be here, indeed. Nothing here uses it, indeed. But it must be here for the sake of sanity.
       constructor() {
         super();
         this.admin = {
@@ -13877,32 +13978,53 @@ var require_dist3 = __commonJS({
       getLevel() {
         return this.level;
       }
+      /**
+       * Sets the instance's log level so that only messages which are equal or more severe are output to the console.
+       */
       setLevel(level) {
         this.level = level;
       }
+      /**
+       * Set the instance's name, which will appear on each log line before the message.
+       */
       setName(name) {
         this.name = name;
       }
+      /**
+       * Log a debug message
+       */
       debug(...msg) {
         if (ConsoleLogger.isMoreOrEqualSevere(LogLevel.DEBUG, this.level)) {
           console.debug(ConsoleLogger.labels.get(LogLevel.DEBUG), this.name, ...msg);
         }
       }
+      /**
+       * Log an info message
+       */
       info(...msg) {
         if (ConsoleLogger.isMoreOrEqualSevere(LogLevel.INFO, this.level)) {
           console.info(ConsoleLogger.labels.get(LogLevel.INFO), this.name, ...msg);
         }
       }
+      /**
+       * Log a warning message
+       */
       warn(...msg) {
         if (ConsoleLogger.isMoreOrEqualSevere(LogLevel.WARN, this.level)) {
           console.warn(ConsoleLogger.labels.get(LogLevel.WARN), this.name, ...msg);
         }
       }
+      /**
+       * Log an error message
+       */
       error(...msg) {
         if (ConsoleLogger.isMoreOrEqualSevere(LogLevel.ERROR, this.level)) {
           console.error(ConsoleLogger.labels.get(LogLevel.ERROR), this.name, ...msg);
         }
       }
+      /**
+       * Helper to compare two log levels and determine if a is equal or more severe than b
+       */
       static isMoreOrEqualSevere(a, b) {
         return ConsoleLogger.severity[a] >= ConsoleLogger.severity[b];
       }
@@ -14111,6 +14233,9 @@ var require_WebClient = __commonJS({
     var retry_policies_1 = __importDefault(require_retry_policies());
     var helpers_1 = require_helpers();
     var WebClient2 = class extends methods_1.Methods {
+      /**
+       * @param token - An API token to authenticate/authorize with Slack (usually start with `xoxp`, `xoxb`)
+       */
       constructor(token, { slackApiUrl = "https://slack.com/api/", logger = void 0, logLevel = logger_1.LogLevel.INFO, maxRequestConcurrency = 3, retryConfig = retry_policies_1.default.tenRetriesInAboutThirtyMinutes, agent = void 0, tls = void 0, rejectRateLimitedCalls = false, headers = {}, teamId = void 0 } = {}) {
         super();
         this.token = token;
@@ -14138,11 +14263,21 @@ var require_WebClient = __commonJS({
           transformRequest: [this.serializeApiCallOptions.bind(this)],
           validateStatus: () => true,
           maxRedirects: 0,
+          // disabling axios' automatic proxy support:
+          // axios would read from envvars to configure a proxy automatically, but it doesn't support TLS destinations.
+          // for compatibility with https://api.slack.com, and for a larger set of possible proxies (SOCKS or other
+          // protocols), users of this package should use the `agent` option to configure a proxy.
           proxy: false
         });
         delete this.axios.defaults.headers.post["Content-Type"];
         this.logger.debug("initialized");
       }
+      /**
+       * Generic method for calling a Web API method
+       *
+       * @param method - the Web API method to call {@link https://api.slack.com/methods}
+       * @param options - options
+       */
       async apiCall(method, options) {
         this.logger.debug(`apiCall('${method}') start`);
         warnDeprecations(method, this.logger);
@@ -14245,6 +14380,9 @@ var require_WebClient = __commonJS({
           return accumulator;
         })();
       }
+      /**
+       * Low-level function to make a single API request. handles queuing, retries, and http-level errors
+       */
       async makeRequest(url, body, headers = {}) {
         const task = () => this.requestQueue.add(async () => {
           this.logger.debug("will perform http request");
@@ -14283,6 +14421,15 @@ var require_WebClient = __commonJS({
         });
         return p_retry_1.default(task, this.retryConfig);
       }
+      /**
+       * Transforms options (a simple key-value object) into an acceptable value for a body. This can be either
+       * a string, used when posting with a content-type of url-encoded. Or, it can be a readable stream, used
+       * when the options contain a binary (a stream or a buffer) and the upload should be done with content-type
+       * multipart/form-data.
+       *
+       * @param options - arguments for the Web API method
+       * @param headers - a mutable object representing the HTTP headers for the outgoing request
+       */
       serializeApiCallOptions(options, headers) {
         let containsBinaryData = false;
         const flattened = Object.entries(options).map(([key, value]) => {
@@ -14332,6 +14479,11 @@ var require_WebClient = __commonJS({
           return accumulator;
         }, initialValue));
       }
+      /**
+       * Processes an HTTP response into a WebAPICallResult by performing JSON parsing on the body and merging relevent
+       * HTTP headers into the object.
+       * @param response - an http response
+       */
       buildResult(response) {
         const data = response.data;
         if (data.response_metadata === void 0) {
@@ -14744,10 +14896,12 @@ var require_dist5 = __commonJS({
       }
     };
     exports.assert = {
+      // Unknowns.
       undefined: (value) => assertType(is.undefined(value), "undefined", value),
       string: (value) => assertType(is.string(value), "string", value),
       number: (value) => assertType(is.number(value), "number", value),
       bigint: (value) => assertType(is.bigint(value), "bigint", value),
+      // eslint-disable-next-line @typescript-eslint/ban-types
       function_: (value) => assertType(is.function_(value), "Function", value),
       null_: (value) => assertType(is.null_(value), "null", value),
       class_: (value) => assertType(is.class_(value), "Class", value),
@@ -14773,7 +14927,9 @@ var require_dist5 = __commonJS({
       promise: (value) => assertType(is.promise(value), "Promise", value),
       generatorFunction: (value) => assertType(is.generatorFunction(value), "GeneratorFunction", value),
       asyncGeneratorFunction: (value) => assertType(is.asyncGeneratorFunction(value), "AsyncGeneratorFunction", value),
+      // eslint-disable-next-line @typescript-eslint/ban-types
       asyncFunction: (value) => assertType(is.asyncFunction(value), "AsyncFunction", value),
+      // eslint-disable-next-line @typescript-eslint/ban-types
       boundFunction: (value) => assertType(is.boundFunction(value), "Function", value),
       regExp: (value) => assertType(is.regExp(value), "RegExp", value),
       date: (value) => assertType(is.date(value), "Date", value),
@@ -14827,10 +14983,13 @@ var require_dist5 = __commonJS({
       propertyKey: (value) => assertType(is.propertyKey(value), "PropertyKey", value),
       formData: (value) => assertType(is.formData(value), "FormData", value),
       urlSearchParams: (value) => assertType(is.urlSearchParams(value), "URLSearchParams", value),
+      // Numbers.
       evenInteger: (value) => assertType(is.evenInteger(value), "even integer", value),
       oddInteger: (value) => assertType(is.oddInteger(value), "odd integer", value),
+      // Two arguments.
       directInstanceOf: (instance, class_) => assertType(is.directInstanceOf(instance, class_), "T", instance),
       inRange: (value, range) => assertType(is.inRange(value, range), "in range", value),
+      // Variadic functions.
       any: (predicate, ...values) => {
         return assertType(is.any(predicate, ...values), "predicate returns truthy for any value", values, { multipleValues: true });
       },
@@ -16024,6 +16183,7 @@ var require_http_cache_semantics = __commonJS({
     ]);
     var hopByHopHeaders = {
       date: true,
+      // included, because we add Age update Date
       connection: true,
       "keep-alive": true,
       "proxy-authenticate": true,
@@ -16034,6 +16194,7 @@ var require_http_cache_semantics = __commonJS({
       upgrade: true
     };
     var excludedFromRevalidationUpdate = {
+      // Since the old body is reused, it doesn't make sense to change properties of the body
       "content-length": true,
       "content-encoding": true,
       "transfer-encoding": true,
@@ -16120,7 +16281,19 @@ var require_http_cache_semantics = __commonJS({
         return Date.now();
       }
       storable() {
-        return !!(!this._reqcc["no-store"] && ("GET" === this._method || "HEAD" === this._method || "POST" === this._method && this._hasExplicitExpiration()) && understoodStatuses.has(this._status) && !this._rescc["no-store"] && (!this._isShared || !this._rescc.private) && (!this._isShared || this._noAuthorization || this._allowsStoringAuthenticated()) && (this._resHeaders.expires || this._rescc["max-age"] || this._isShared && this._rescc["s-maxage"] || this._rescc.public || statusCodeCacheableByDefault.has(this._status)));
+        return !!(!this._reqcc["no-store"] && // A cache MUST NOT store a response to any request, unless:
+        // The request method is understood by the cache and defined as being cacheable, and
+        ("GET" === this._method || "HEAD" === this._method || "POST" === this._method && this._hasExplicitExpiration()) && // the response status code is understood by the cache, and
+        understoodStatuses.has(this._status) && // the "no-store" cache directive does not appear in request or response header fields, and
+        !this._rescc["no-store"] && // the "private" response directive does not appear in the response, if the cache is shared, and
+        (!this._isShared || !this._rescc.private) && // the Authorization header field does not appear in the request, if the cache is shared,
+        (!this._isShared || this._noAuthorization || this._allowsStoringAuthenticated()) && // the response either:
+        // contains an Expires header field, or
+        (this._resHeaders.expires || // contains a max-age response directive, or
+        // contains a s-maxage response directive and the cache is shared, or
+        // contains a public response directive.
+        this._rescc["max-age"] || this._isShared && this._rescc["s-maxage"] || this._rescc.public || // has a status code that is defined as cacheable by default
+        statusCodeCacheableByDefault.has(this._status)));
       }
       _hasExplicitExpiration() {
         return this._isShared && this._rescc["s-maxage"] || this._rescc["max-age"] || this._resHeaders.expires;
@@ -16151,7 +16324,9 @@ var require_http_cache_semantics = __commonJS({
         return this._requestMatches(req, false);
       }
       _requestMatches(req, allowHeadMethod) {
-        return (!this._url || this._url === req.url) && this._host === req.headers.host && (!req.method || this._method === req.method || allowHeadMethod && "HEAD" === req.method) && this._varyMatches(req);
+        return (!this._url || this._url === req.url) && this._host === req.headers.host && // the request method associated with the stored response allows it to be used for the presented request, and
+        (!req.method || this._method === req.method || allowHeadMethod && "HEAD" === req.method) && // selecting header fields nominated by the stored response (if any) match those presented, and
+        this._varyMatches(req);
       }
       _allowsStoringAuthenticated() {
         return this._rescc["must-revalidate"] || this._rescc.public || this._rescc["s-maxage"];
@@ -16205,6 +16380,10 @@ var require_http_cache_semantics = __commonJS({
         headers.date = new Date(this.now()).toUTCString();
         return headers;
       }
+      /**
+       * Value of the Date response header or current time if Date was invalid
+       * @return timestamp
+       */
       date() {
         const serverDate = Date.parse(this._resHeaders.date);
         if (isFinite(serverDate)) {
@@ -16212,6 +16391,12 @@ var require_http_cache_semantics = __commonJS({
         }
         return this._responseTime;
       }
+      /**
+       * Value of the Age header, in seconds, updated for the current time.
+       * May be fractional.
+       *
+       * @return Number
+       */
       age() {
         let age = this._ageValue();
         const residentTime = (this.now() - this._responseTime) / 1e3;
@@ -16220,6 +16405,13 @@ var require_http_cache_semantics = __commonJS({
       _ageValue() {
         return toNumberOrZero(this._resHeaders.age);
       }
+      /**
+       * Value of applicable max-age (or heuristic equivalent) in seconds. This counts since response's `Date`.
+       *
+       * For an up-to-date value, see `timeToLive()`.
+       *
+       * @return Number
+       */
       maxAge() {
         if (!this.storable() || this._rescc["no-cache"]) {
           return 0;
@@ -16316,6 +16508,13 @@ var require_http_cache_semantics = __commonJS({
           reqcc: this._reqcc
         };
       }
+      /**
+       * Headers for sending to the origin server to revalidate stale response.
+       * Allows server to return 304 to allow reuse of the previous response.
+       *
+       * Hop by hop headers are always stripped.
+       * Revalidation headers may be added or removed, depending on request.
+       */
       revalidationHeaders(incomingReq) {
         this._assertRequestHasHeaders(incomingReq);
         const headers = this._copyWithoutHopByHopHeaders(incomingReq.headers);
@@ -16346,6 +16545,15 @@ var require_http_cache_semantics = __commonJS({
         }
         return headers;
       }
+      /**
+       * Creates new CachePolicy with information combined from the previews response,
+       * and the new revalidation response.
+       *
+       * Returns {policy, modified} where modified is a boolean indicating
+       * whether the response body has been modified, and old cached body can't be used.
+       *
+       * @return {Object} {policy: CachePolicy, modified: Boolean}
+       */
       revalidatedPolicy(request, response) {
         this._assertRequestHasHeaders(request);
         if (this._useStaleIfError() && isErrorResponse(response)) {
@@ -16375,6 +16583,9 @@ var require_http_cache_semantics = __commonJS({
         if (!matches) {
           return {
             policy: new this.constructor(request, response),
+            // Client receiving 304 without body, even if it's invalid/mismatched has no option
+            // but to reuse a cached body. We don't have a good way to tell clients to do
+            // error recovery in such case.
             modified: response.status != 304,
             matches: false
           };
@@ -17206,6 +17417,7 @@ var require_agent = __commonJS({
     var kOriginSet = Symbol("cachedOriginSet");
     var kGracefullyClosing = Symbol("gracefullyClosing");
     var nameKeys = [
+      // `http2.connect()` options
       "maxDeflateDynamicTableSize",
       "maxSessionMemory",
       "maxHeaderListPairs",
@@ -17213,10 +17425,12 @@ var require_agent = __commonJS({
       "maxReservedRemoteStreams",
       "maxSendHeaderBlockLength",
       "paddingStrategy",
+      // `tls.connect()` options
       "localAddress",
       "path",
       "rejectUnauthorized",
       "minDHSize",
+      // `tls.createSecureContext()` options
       "ca",
       "cert",
       "clientCertEngine",
@@ -17252,7 +17466,12 @@ var require_agent = __commonJS({
     };
     var closeCoveredSessions = (where, session) => {
       for (const coveredSession of where) {
-        if (coveredSession[kOriginSet].length < session[kOriginSet].length && coveredSession[kOriginSet].every((origin) => session[kOriginSet].includes(origin)) && coveredSession[kCurrentStreamsCount] + session[kCurrentStreamsCount] <= session.remoteSettings.maxConcurrentStreams) {
+        if (
+          // The set is a proper subset when its length is less than the other set.
+          coveredSession[kOriginSet].length < session[kOriginSet].length && // And the other set includes all elements of the subset.
+          coveredSession[kOriginSet].every((origin) => session[kOriginSet].includes(origin)) && // Makes sure that the session can handle all requests from the covered session.
+          coveredSession[kCurrentStreamsCount] + session[kCurrentStreamsCount] <= session.remoteSettings.maxConcurrentStreams
+        ) {
           gracefullyClose(coveredSession);
         }
       }
@@ -17357,7 +17576,9 @@ var require_agent = __commonJS({
               }
               if (session[kOriginSet].includes(normalizedOrigin)) {
                 const sessionCurrentStreamsCount = session[kCurrentStreamsCount];
-                if (sessionCurrentStreamsCount >= sessionMaxConcurrentStreams || session[kGracefullyClosing] || session.destroyed) {
+                if (sessionCurrentStreamsCount >= sessionMaxConcurrentStreams || session[kGracefullyClosing] || // Unfortunately the `close` event isn't called immediately,
+                // so `session.destroyed` is `true`, but `session.closed` is `false`.
+                session.destroyed) {
                   continue;
                 }
                 if (!optimalSession) {
@@ -18915,6 +19136,7 @@ var require_core = __commonJS({
       "beforeRedirect",
       "beforeError",
       "beforeRetry",
+      // Promise-Only
       "afterResponse"
     ];
     function validateSearchParameters(searchParameters) {
@@ -18963,6 +19185,7 @@ var require_core = __commonJS({
             writable: true,
             configurable: true,
             enumerable: false,
+            // @ts-expect-error TS doesn't see the check above
             value: source[name]
           };
         }
@@ -18986,11 +19209,15 @@ var require_core = __commonJS({
             value: self[kResponse]
           });
           Object.defineProperty(this, "options", {
+            // This fails because of TS 3.7.2 useDefineForClassFields
+            // Ref: https://github.com/microsoft/TypeScript/issues/34972
             enumerable: false,
             value: self.options
           });
         } else {
           Object.defineProperty(this, "options", {
+            // This fails because of TS 3.7.2 useDefineForClassFields
+            // Ref: https://github.com/microsoft/TypeScript/issues/34972
             enumerable: false,
             value: self
           });
@@ -19076,7 +19303,10 @@ var require_core = __commonJS({
     var Request = class extends stream_1.Duplex {
       constructor(url, options = {}, defaults) {
         super({
+          // This must be false, to enable throwing after destroy
+          // It is used for retry logic in Promise API
           autoDestroy: false,
+          // It needs to be zero because we're just proxying the data to another stream
           highWaterMark: 0
         });
         this[kDownloadedSize] = 0;
@@ -19974,6 +20204,7 @@ var require_core = __commonJS({
           }
         }
       }
+      // Node.js 12 has incorrect types, so the encoding must be a string
       _write(chunk, encoding, callback) {
         const write = () => {
           this._writeRequest(chunk, encoding, callback);
@@ -20048,10 +20279,16 @@ var require_core = __commonJS({
       get _isAboutToError() {
         return this[kStopReading];
       }
+      /**
+      The remote IP address.
+      */
       get ip() {
         var _a;
         return (_a = this.socket) === null || _a === void 0 ? void 0 : _a.remoteAddress;
       }
+      /**
+      Indicates whether the request has been aborted or not.
+      */
       get aborted() {
         var _a, _b, _c;
         return ((_b = (_a = this[kRequest]) === null || _a === void 0 ? void 0 : _a.destroyed) !== null && _b !== void 0 ? _b : this.destroyed) && !((_c = this[kOriginalResponse]) === null || _c === void 0 ? void 0 : _c.complete);
@@ -20060,6 +20297,9 @@ var require_core = __commonJS({
         var _a, _b;
         return (_b = (_a = this[kRequest]) === null || _a === void 0 ? void 0 : _a.socket) !== null && _b !== void 0 ? _b : void 0;
       }
+      /**
+      Progress event for downloading (receiving a response).
+      */
       get downloadProgress() {
         let percent;
         if (this[kResponseSize]) {
@@ -20075,6 +20315,9 @@ var require_core = __commonJS({
           total: this[kResponseSize]
         };
       }
+      /**
+      Progress event for uploading (sending a request).
+      */
       get uploadProgress() {
         let percent;
         if (this[kBodySize]) {
@@ -20090,10 +20333,40 @@ var require_core = __commonJS({
           total: this[kBodySize]
         };
       }
+      /**
+          The object contains the following properties:
+      
+          - `start` - Time when the request started.
+          - `socket` - Time when a socket was assigned to the request.
+          - `lookup` - Time when the DNS lookup finished.
+          - `connect` - Time when the socket successfully connected.
+          - `secureConnect` - Time when the socket securely connected.
+          - `upload` - Time when the request finished uploading.
+          - `response` - Time when the request fired `response` event.
+          - `end` - Time when the response fired `end` event.
+          - `error` - Time when the request fired `error` event.
+          - `abort` - Time when the request fired `abort` event.
+          - `phases`
+              - `wait` - `timings.socket - timings.start`
+              - `dns` - `timings.lookup - timings.socket`
+              - `tcp` - `timings.connect - timings.lookup`
+              - `tls` - `timings.secureConnect - timings.connect`
+              - `request` - `timings.upload - (timings.secureConnect || timings.connect)`
+              - `firstByte` - `timings.response - timings.upload`
+              - `download` - `timings.end - timings.response`
+              - `total` - `(timings.end || timings.error || timings.abort) - timings.start`
+      
+          If something has not been measured yet, it will be `undefined`.
+      
+          __Note__: The time is a `number` representing the milliseconds elapsed since the UNIX epoch.
+          */
       get timings() {
         var _a;
         return (_a = this[kRequest]) === null || _a === void 0 ? void 0 : _a.timings;
       }
+      /**
+      Whether the response was retrieved from the cache.
+      */
       get isFromCache() {
         return this[kIsFromCache];
       }
@@ -20740,6 +21013,7 @@ var require_source5 = __commonJS({
         methodRewriting: true,
         ignoreInvalidCookies: false,
         context: {},
+        // TODO: Set this to `true` when Got 12 gets released
         http2: false,
         allowGetBody: false,
         https: void 0,