@http-client-toolkit/core 0.1.0 → 0.2.0

package/lib/index.cjs

@@ -3,6 +3,25 @@
 var zod = require('zod');
 var crypto = require('crypto');
 
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -24,6 +43,231 @@ var __async = (__this, __arguments, generator) => {
   });
 };
 
+// src/cache/cache-control-parser.ts
+var EMPTY_DIRECTIVES = {
+  noCache: false,
+  noStore: false,
+  mustRevalidate: false,
+  proxyRevalidate: false,
+  public: false,
+  private: false,
+  immutable: false
+};
+function parseSeconds(raw) {
+  if (raw === void 0) return void 0;
+  const n = Number.parseInt(raw.trim(), 10);
+  return Number.isFinite(n) && n >= 0 ? n : void 0;
+}
+function parseCacheControl(header) {
+  if (!header) return __spreadValues({}, EMPTY_DIRECTIVES);
+  const result = __spreadValues({}, EMPTY_DIRECTIVES);
+  for (const part of header.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const eqIdx = trimmed.indexOf("=");
+    const key = (eqIdx === -1 ? trimmed : trimmed.slice(0, eqIdx)).trim().toLowerCase();
+    const value = eqIdx === -1 ? void 0 : trimmed.slice(eqIdx + 1).trim();
+    switch (key) {
+      case "max-age":
+        result.maxAge = parseSeconds(value);
+        break;
+      case "s-maxage":
+        result.sMaxAge = parseSeconds(value);
+        break;
+      case "no-cache":
+        result.noCache = true;
+        break;
+      case "no-store":
+        result.noStore = true;
+        break;
+      case "must-revalidate":
+        result.mustRevalidate = true;
+        break;
+      case "proxy-revalidate":
+        result.proxyRevalidate = true;
+        break;
+      case "public":
+        result.public = true;
+        break;
+      case "private":
+        result.private = true;
+        break;
+      case "immutable":
+        result.immutable = true;
+        break;
+      case "stale-while-revalidate":
+        result.staleWhileRevalidate = parseSeconds(value);
+        break;
+      case "stale-if-error":
+        result.staleIfError = parseSeconds(value);
+        break;
+    }
+  }
+  return result;
+}
+
+// src/cache/cache-entry.ts
+function isCacheEntry(value) {
+  return typeof value === "object" && value !== null && value.__cacheEntry === true && "value" in value && "metadata" in value;
+}
+function parseHttpDate(value) {
+  if (value === null || value === void 0) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  if (trimmed === "0") return 0;
+  const ms = Date.parse(trimmed);
+  return Number.isFinite(ms) ? ms : void 0;
+}
+function createCacheEntry(value, headers, statusCode) {
+  var _a, _b, _c, _d;
+  const now = Date.now();
+  const dateMs = (_a = parseHttpDate(headers.get("date"))) != null ? _a : now;
+  const ageRaw = headers.get("age");
+  const ageHeader = ageRaw !== null ? Number.parseInt(ageRaw.trim(), 10) || 0 : 0;
+  return {
+    __cacheEntry: true,
+    value,
+    metadata: {
+      etag: (_b = headers.get("etag")) != null ? _b : void 0,
+      lastModified: (_c = headers.get("last-modified")) != null ? _c : void 0,
+      cacheControl: parseCacheControl(headers.get("cache-control")),
+      responseDate: dateMs,
+      storedAt: now,
+      ageHeader,
+      varyHeaders: (_d = headers.get("vary")) != null ? _d : void 0,
+      statusCode,
+      expires: parseHttpDate(headers.get("expires"))
+    }
+  };
+}
+function refreshCacheEntry(existing, newHeaders) {
+  var _a;
+  const now = Date.now();
+  const dateMs = (_a = parseHttpDate(newHeaders.get("date"))) != null ? _a : now;
+  const ageRaw = newHeaders.get("age");
+  const ageHeader = ageRaw !== null ? Number.parseInt(ageRaw.trim(), 10) || 0 : 0;
+  const newCacheControl = newHeaders.get("cache-control");
+  const newEtag = newHeaders.get("etag");
+  const newLastModified = newHeaders.get("last-modified");
+  const newExpires = newHeaders.get("expires");
+  const newVary = newHeaders.get("vary");
+  return {
+    __cacheEntry: true,
+    value: existing.value,
+    metadata: __spreadProps(__spreadValues({}, existing.metadata), {
+      cacheControl: newCacheControl ? parseCacheControl(newCacheControl) : existing.metadata.cacheControl,
+      etag: newEtag != null ? newEtag : existing.metadata.etag,
+      lastModified: newLastModified != null ? newLastModified : existing.metadata.lastModified,
+      responseDate: dateMs,
+      storedAt: now,
+      ageHeader,
+      expires: newExpires !== null ? parseHttpDate(newExpires) : existing.metadata.expires,
+      varyHeaders: newVary != null ? newVary : existing.metadata.varyHeaders
+      // statusCode stays the same (the original 200, not 304)
+    })
+  };
+}
+
+// src/cache/freshness.ts
+function calculateFreshnessLifetime(metadata) {
+  const { cacheControl } = metadata;
+  if (cacheControl.maxAge !== void 0) {
+    return cacheControl.maxAge;
+  }
+  if (metadata.expires !== void 0) {
+    if (metadata.expires === 0) return 0;
+    const delta = (metadata.expires - metadata.responseDate) / 1e3;
+    return Math.max(0, delta);
+  }
+  if (metadata.lastModified) {
+    const lastModMs = Date.parse(metadata.lastModified);
+    if (Number.isFinite(lastModMs)) {
+      const age = (metadata.responseDate - lastModMs) / 1e3;
+      if (age > 0) {
+        return Math.floor(age * 0.1);
+      }
+    }
+  }
+  return 0;
+}
+function calculateCurrentAge(metadata, now) {
+  const currentTime = now != null ? now : Date.now();
+  const responseTime = metadata.storedAt;
+  const apparentAge = Math.max(
+    0,
+    (responseTime - metadata.responseDate) / 1e3
+  );
+  const correctedAgeValue = metadata.ageHeader;
+  const correctedInitialAge = Math.max(apparentAge, correctedAgeValue);
+  const residentTime = (currentTime - responseTime) / 1e3;
+  return correctedInitialAge + residentTime;
+}
+function getFreshnessStatus(metadata, now) {
+  const { cacheControl } = metadata;
+  if (cacheControl.noCache) {
+    return "no-cache";
+  }
+  const freshnessLifetime = calculateFreshnessLifetime(metadata);
+  const currentAge = calculateCurrentAge(metadata, now);
+  if (freshnessLifetime > currentAge) {
+    return "fresh";
+  }
+  const staleness = currentAge - freshnessLifetime;
+  if (cacheControl.mustRevalidate) {
+    return "must-revalidate";
+  }
+  if (cacheControl.staleWhileRevalidate !== void 0 && staleness <= cacheControl.staleWhileRevalidate) {
+    return "stale-while-revalidate";
+  }
+  if (cacheControl.staleIfError !== void 0 && staleness <= cacheControl.staleIfError) {
+    return "stale-if-error";
+  }
+  return "stale";
+}
+function calculateStoreTTL(metadata, defaultTTL) {
+  var _a, _b;
+  const freshness = calculateFreshnessLifetime(metadata);
+  if (freshness === 0 && metadata.cacheControl.maxAge === void 0) {
+    return defaultTTL;
+  }
+  const swrWindow = (_a = metadata.cacheControl.staleWhileRevalidate) != null ? _a : 0;
+  const sieWindow = (_b = metadata.cacheControl.staleIfError) != null ? _b : 0;
+  const staleWindow = Math.max(swrWindow, sieWindow);
+  return freshness + staleWindow;
+}
+
+// src/cache/vary.ts
+function parseVaryHeader(varyHeader) {
+  if (!varyHeader) return [];
+  const trimmed = varyHeader.trim();
+  if (trimmed === "*") return ["*"];
+  return trimmed.split(",").map((f) => f.trim().toLowerCase()).filter(Boolean);
+}
+function captureVaryValues(varyFields, requestHeaders) {
+  var _a;
+  const values = {};
+  for (const field of varyFields) {
+    const lower = field.toLowerCase();
+    values[lower] = (_a = requestHeaders[lower]) != null ? _a : requestHeaders[field];
+  }
+  return values;
+}
+function varyMatches(cachedVaryValues, cachedVaryHeader, currentRequestHeaders) {
+  var _a;
+  if (!cachedVaryHeader) return true;
+  const fields = parseVaryHeader(cachedVaryHeader);
+  if (fields.length === 0) return true;
+  if (fields[0] === "*") return false;
+  if (!cachedVaryValues) return false;
+  for (const field of fields) {
+    const lower = field.toLowerCase();
+    const cachedVal = cachedVaryValues[lower];
+    const currentVal = (_a = currentRequestHeaders[lower]) != null ? _a : currentRequestHeaders[field];
+    if (cachedVal !== currentVal) return false;
+  }
+  return true;
+}
+
 // src/errors/http-client-error.ts
 var HttpClientError = class extends Error {
   constructor(message, statusCode) {
@@ -258,15 +502,18 @@ function wait(ms, signal) {
 var HttpClient = class {
   constructor(stores = {}, options = {}) {
     this.serverCooldowns = /* @__PURE__ */ new Map();
-    var _a, _b, _c;
+    this.pendingRevalidations = [];
+    var _a, _b, _c, _d;
     this.stores = stores;
     this.options = {
       defaultCacheTTL: (_a = options.defaultCacheTTL) != null ? _a : 3600,
       throwOnRateLimit: (_b = options.throwOnRateLimit) != null ? _b : true,
       maxWaitTime: (_c = options.maxWaitTime) != null ? _c : 6e4,
+      respectCacheHeaders: (_d = options.respectCacheHeaders) != null ? _d : false,
       responseTransformer: options.responseTransformer,
       errorHandler: options.errorHandler,
       responseHandler: options.responseHandler,
+      cacheHeaderOverrides: options.cacheHeaderOverrides,
       rateLimitHeaders: this.normalizeRateLimitHeaders(
         options.rateLimitHeaders
       )
@@ -522,6 +769,81 @@ var HttpClient = class {
       return hasAtomicAcquire;
     });
   }
+  /**
+   * Wait for all pending background revalidations to complete.
+   * Primarily useful in tests to avoid dangling promises.
+   */
+  flushRevalidations() {
+    return __async(this, null, function* () {
+      yield Promise.allSettled(this.pendingRevalidations);
+      this.pendingRevalidations = [];
+    });
+  }
+  backgroundRevalidate(url, hash, entry) {
+    return __async(this, null, function* () {
+      var _a, _b;
+      const headers = new Headers();
+      if (entry.metadata.etag) {
+        headers.set("If-None-Match", entry.metadata.etag);
+      }
+      if (entry.metadata.lastModified) {
+        headers.set("If-Modified-Since", entry.metadata.lastModified);
+      }
+      try {
+        const response = yield fetch(url, { headers });
+        this.applyServerRateLimitHints(url, response.headers, response.status);
+        if (response.status === 304) {
+          const refreshed = refreshCacheEntry(entry, response.headers);
+          const ttl = this.clampTTL(
+            calculateStoreTTL(refreshed.metadata, this.options.defaultCacheTTL)
+          );
+          yield (_a = this.stores.cache) == null ? void 0 : _a.set(hash, refreshed, ttl);
+          return;
+        }
+        if (response.ok) {
+          const parsedBody = yield this.parseResponseBody(response);
+          let data = parsedBody.data;
+          if (this.options.responseTransformer && data) {
+            data = this.options.responseTransformer(data);
+          }
+          if (this.options.responseHandler) {
+            data = this.options.responseHandler(data);
+          }
+          const newEntry = createCacheEntry(
+            data,
+            response.headers,
+            response.status
+          );
+          const ttl = this.clampTTL(
+            calculateStoreTTL(newEntry.metadata, this.options.defaultCacheTTL)
+          );
+          yield (_b = this.stores.cache) == null ? void 0 : _b.set(hash, newEntry, ttl);
+        }
+      } catch (e) {
+      }
+    });
+  }
+  clampTTL(ttl) {
+    const overrides = this.options.cacheHeaderOverrides;
+    if (!overrides) return ttl;
+    let clamped = ttl;
+    if (overrides.minimumTTL !== void 0) {
+      clamped = Math.max(clamped, overrides.minimumTTL);
+    }
+    if (overrides.maximumTTL !== void 0) {
+      clamped = Math.min(clamped, overrides.maximumTTL);
+    }
+    return clamped;
+  }
+  isServerErrorOrNetworkFailure(error) {
+    var _a;
+    if (typeof error === "object" && error !== null && "response" in error) {
+      const status = (_a = error.response) == null ? void 0 : _a.status;
+      if (typeof status === "number" && status >= 500) return true;
+    }
+    if (error instanceof TypeError) return true;
+    return false;
+  }
   generateClientError(err) {
     var _a, _b;
     if (this.options.errorHandler) {
@@ -567,16 +889,58 @@ var HttpClient = class {
   }
   get(_0) {
     return __async(this, arguments, function* (url, options = {}) {
+      var _a, _b;
       const { signal, priority = "background" } = options;
       const { endpoint, params } = this.parseUrlForHashing(url);
       const hash = hashRequest(endpoint, params);
       const resource = this.inferResource(url);
+      let staleEntry;
+      let staleCandidate;
       try {
         yield this.enforceServerCooldown(url, signal);
         if (this.stores.cache) {
           const cachedResult = yield this.stores.cache.get(hash);
           if (cachedResult !== void 0) {
-            return cachedResult;
+            if (this.options.respectCacheHeaders && isCacheEntry(cachedResult)) {
+              const entry = cachedResult;
+              const status = getFreshnessStatus(entry.metadata);
+              switch (status) {
+                case "fresh":
+                  return entry.value;
+                case "no-cache":
+                  if ((_a = this.options.cacheHeaderOverrides) == null ? void 0 : _a.ignoreNoCache) {
+                    return entry.value;
+                  }
+                  staleEntry = entry;
+                  break;
+                case "must-revalidate":
+                  staleEntry = entry;
+                  break;
+                case "stale-while-revalidate": {
+                  const revalidation = this.backgroundRevalidate(
+                    url,
+                    hash,
+                    entry
+                  );
+                  this.pendingRevalidations.push(revalidation);
+                  revalidation.finally(() => {
+                    this.pendingRevalidations = this.pendingRevalidations.filter(
+                      (p) => p !== revalidation
+                    );
+                  });
+                  return entry.value;
+                }
+                case "stale-if-error":
+                  staleCandidate = entry;
+                  staleEntry = entry;
+                  break;
+                case "stale":
+                  staleEntry = entry;
+                  break;
+              }
+            } else if (!this.options.respectCacheHeaders) {
+              return cachedResult;
+            }
           }
         }
         if (this.stores.dedupe) {
@@ -604,8 +968,38 @@ var HttpClient = class {
             signal
           );
         }
-        const response = yield fetch(url, { signal });
+        const fetchInit = { signal };
+        if (this.options.respectCacheHeaders && staleEntry) {
+          const conditionalHeaders = new Headers();
+          if (staleEntry.metadata.etag) {
+            conditionalHeaders.set("If-None-Match", staleEntry.metadata.etag);
+          }
+          if (staleEntry.metadata.lastModified) {
+            conditionalHeaders.set(
+              "If-Modified-Since",
+              staleEntry.metadata.lastModified
+            );
+          }
+          if ([...conditionalHeaders].length > 0) {
+            fetchInit.headers = conditionalHeaders;
+          }
+        }
+        const response = yield fetch(url, fetchInit);
         this.applyServerRateLimitHints(url, response.headers, response.status);
+        if (this.options.respectCacheHeaders && response.status === 304 && staleEntry) {
+          const refreshed = refreshCacheEntry(staleEntry, response.headers);
+          const ttl = this.clampTTL(
+            calculateStoreTTL(refreshed.metadata, this.options.defaultCacheTTL)
+          );
+          if (this.stores.cache) {
+            yield this.stores.cache.set(hash, refreshed, ttl);
+          }
+          const result2 = refreshed.value;
+          if (this.stores.dedupe) {
+            yield this.stores.dedupe.complete(hash, result2);
+          }
+          return result2;
+        }
         const parsedBody = yield this.parseResponseBody(response);
         if (!response.ok) {
           const error = {
@@ -631,13 +1025,40 @@ var HttpClient = class {
           yield rateLimit.record(resource, priority);
         }
         if (this.stores.cache) {
-          yield this.stores.cache.set(hash, result, this.options.defaultCacheTTL);
+          if (this.options.respectCacheHeaders) {
+            const cc = parseCacheControl(response.headers.get("cache-control"));
+            const shouldStore = !cc.noStore || ((_b = this.options.cacheHeaderOverrides) == null ? void 0 : _b.ignoreNoStore);
+            if (shouldStore) {
+              const entry = createCacheEntry(
+                result,
+                response.headers,
+                response.status
+              );
+              const ttl = this.clampTTL(
+                calculateStoreTTL(entry.metadata, this.options.defaultCacheTTL)
+              );
+              yield this.stores.cache.set(hash, entry, ttl);
+            }
+          } else {
+            yield this.stores.cache.set(
+              hash,
+              result,
+              this.options.defaultCacheTTL
+            );
+          }
         }
         if (this.stores.dedupe) {
           yield this.stores.dedupe.complete(hash, result);
         }
         return result;
       } catch (error) {
+        if (this.options.respectCacheHeaders && staleCandidate && this.isServerErrorOrNetworkFailure(error)) {
+          const result = staleCandidate.value;
+          if (this.stores.dedupe) {
+            yield this.stores.dedupe.complete(hash, result);
+          }
+          return result;
+        }
         if (this.stores.dedupe) {
           yield this.stores.dedupe.fail(hash, error);
         }
@@ -658,6 +1079,18 @@ exports.AdaptiveConfigSchema = AdaptiveConfigSchema;
 exports.DEFAULT_RATE_LIMIT = DEFAULT_RATE_LIMIT;
 exports.HttpClient = HttpClient;
 exports.HttpClientError = HttpClientError;
+exports.calculateCurrentAge = calculateCurrentAge;
+exports.calculateFreshnessLifetime = calculateFreshnessLifetime;
+exports.calculateStoreTTL = calculateStoreTTL;
+exports.captureVaryValues = captureVaryValues;
+exports.createCacheEntry = createCacheEntry;
+exports.getFreshnessStatus = getFreshnessStatus;
 exports.hashRequest = hashRequest;
+exports.isCacheEntry = isCacheEntry;
+exports.parseCacheControl = parseCacheControl;
+exports.parseHttpDate = parseHttpDate;
+exports.parseVaryHeader = parseVaryHeader;
+exports.refreshCacheEntry = refreshCacheEntry;
+exports.varyMatches = varyMatches;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map