@nextn/outbound-guard 0.1.1 → 0.1.2

package/dist/demo/loadgen.js

@@ -1,452 +0,0 @@
-// src/client.ts
-import { EventEmitter } from "events";
-
-// src/errors.ts
-var ResilientHttpError = class extends Error {
-  name;
-  constructor(message) {
-    super(message);
-    this.name = this.constructor.name;
-  }
-};
-var QueueFullError = class extends ResilientHttpError {
-  constructor(maxQueue) {
-    super(`Queue is full (maxQueue=${maxQueue}).`);
-    this.maxQueue = maxQueue;
-  }
-};
-var QueueTimeoutError = class extends ResilientHttpError {
-  constructor(enqueueTimeoutMs) {
-    super(`Queue wait exceeded (enqueueTimeoutMs=${enqueueTimeoutMs}).`);
-    this.enqueueTimeoutMs = enqueueTimeoutMs;
-  }
-};
-var RequestTimeoutError = class extends ResilientHttpError {
-  constructor(requestTimeoutMs) {
-    super(`Request timed out (requestTimeoutMs=${requestTimeoutMs}).`);
-    this.requestTimeoutMs = requestTimeoutMs;
-  }
-};
-
-// src/limiter.ts
-var ConcurrencyLimiter = class {
-  maxInFlight;
-  maxQueue;
-  enqueueTimeoutMs;
-  inFlight = 0;
-  queue = [];
-  constructor(opts) {
-    if (!Number.isFinite(opts.maxInFlight) || opts.maxInFlight <= 0) {
-      throw new Error(`maxInFlight must be > 0 (got ${opts.maxInFlight})`);
-    }
-    if (!Number.isFinite(opts.maxQueue) || opts.maxQueue < 0) {
-      throw new Error(`maxQueue must be >= 0 (got ${opts.maxQueue})`);
-    }
-    if (!Number.isFinite(opts.enqueueTimeoutMs) || opts.enqueueTimeoutMs <= 0) {
-      throw new Error(`enqueueTimeoutMs must be > 0 (got ${opts.enqueueTimeoutMs})`);
-    }
-    this.maxInFlight = opts.maxInFlight;
-    this.maxQueue = opts.maxQueue;
-    this.enqueueTimeoutMs = opts.enqueueTimeoutMs;
-  }
-  /**
-   * Acquire a permit. Resolves once you are allowed to proceed.
-   * MUST be followed by `release()` exactly once.
-   */
-  acquire() {
-    if (this.inFlight < this.maxInFlight) {
-      this.inFlight += 1;
-      return Promise.resolve();
-    }
-    if (this.maxQueue === 0 || this.queue.length >= this.maxQueue) {
-      return Promise.reject(new QueueFullError(this.maxQueue));
-    }
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        const idx = this.queue.findIndex((w) => w.resolve === resolve);
-        if (idx >= 0) {
-          const [w] = this.queue.splice(idx, 1);
-          clearTimeout(w.timer);
-        }
-        reject(new QueueTimeoutError(this.enqueueTimeoutMs));
-      }, this.enqueueTimeoutMs);
-      this.queue.push({ resolve, reject, timer });
-    });
-  }
-  /**
-   * Release a permit. Always call this in a `finally` block.
-   */
-  release() {
-    if (this.inFlight <= 0) {
-      throw new Error("release() called when inFlight is already 0");
-    }
-    const next = this.queue.shift();
-    if (next) {
-      clearTimeout(next.timer);
-      next.resolve();
-      return;
-    }
-    this.inFlight -= 1;
-  }
-  snapshot() {
-    return {
-      inFlight: this.inFlight,
-      queueDepth: this.queue.length,
-      maxInFlight: this.maxInFlight,
-      maxQueue: this.maxQueue
-    };
-  }
-};
-
-// src/http.ts
-import { request as undiciRequest } from "undici";
-function normalizeHeaders(headers) {
-  const out = {};
-  if (!headers) return out;
-  for (const [k, v] of Object.entries(headers)) {
-    if (Array.isArray(v)) out[k.toLowerCase()] = v.join(", ");
-    else if (typeof v === "string") out[k.toLowerCase()] = v;
-    else out[k.toLowerCase()] = String(v);
-  }
-  return out;
-}
-async function doHttpRequest(req, requestTimeoutMs) {
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), requestTimeoutMs);
-  try {
-    const res = await undiciRequest(req.url, {
-      method: req.method,
-      headers: req.headers,
-      body: req.body,
-      signal: ac.signal
-    });
-    const body = await res.body.arrayBuffer();
-    return {
-      status: res.statusCode,
-      headers: normalizeHeaders(res.headers),
-      body: new Uint8Array(body)
-    };
-  } catch (err) {
-    if (err?.name === "AbortError") {
-      throw new RequestTimeoutError(requestTimeoutMs);
-    }
-    throw err;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-// src/client.ts
-function normalizeUrlForKey(rawUrl) {
-  const u = new URL(rawUrl);
-  u.hostname = u.hostname.toLowerCase();
-  const isHttpDefault = u.protocol === "http:" && u.port === "80";
-  const isHttpsDefault = u.protocol === "https:" && u.port === "443";
-  if (isHttpDefault || isHttpsDefault) u.port = "";
-  return u.toString();
-}
-function defaultMicroCacheKeyFn(req) {
-  return `GET ${normalizeUrlForKey(req.url)}`;
-}
-function genRequestId() {
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-}
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-function clamp(n, lo, hi) {
-  return Math.max(lo, Math.min(hi, n));
-}
-var ResilientHttpClient = class extends EventEmitter {
-  constructor(opts) {
-    super();
-    this.opts = opts;
-    this.limiter = new ConcurrencyLimiter({
-      maxInFlight: opts.maxInFlight,
-      maxQueue: opts.maxQueue,
-      enqueueTimeoutMs: opts.enqueueTimeoutMs
-    });
-    this.requestTimeoutMs = opts.requestTimeoutMs;
-    const mc = opts.microCache;
-    if (mc?.enabled) {
-      const retry = mc.retry ? {
-        maxAttempts: mc.retry.maxAttempts ?? 3,
-        baseDelayMs: mc.retry.baseDelayMs ?? 50,
-        maxDelayMs: mc.retry.maxDelayMs ?? 200,
-        retryOnStatus: mc.retry.retryOnStatus ?? [429, 502, 503, 504]
-      } : void 0;
-      this.microCache = {
-        enabled: true,
-        ttlMs: mc.ttlMs ?? 1e3,
-        maxStaleMs: mc.maxStaleMs ?? 1e4,
-        maxEntries: mc.maxEntries ?? 500,
-        maxWaiters: mc.maxWaiters ?? 1e3,
-        followerTimeoutMs: mc.followerTimeoutMs ?? 5e3,
-        keyFn: mc.keyFn ?? defaultMicroCacheKeyFn,
-        retry
-      };
-      this.cache = /* @__PURE__ */ new Map();
-      this.inFlight = /* @__PURE__ */ new Map();
-    }
-  }
-  limiter;
-  requestTimeoutMs;
-  microCache;
-  cache;
-  inFlight;
-  microCacheReqCount = 0;
-  cleanupEveryNRequests = 100;
-  async request(req) {
-    if (this.microCache?.enabled && req.method === "GET" && req.body == null) {
-      return this.requestWithMicroCache(req);
-    }
-    return this.existingPipeline(req);
-  }
-  cloneResponse(res) {
-    return {
-      status: res.status,
-      headers: { ...res.headers },
-      body: new Uint8Array(res.body)
-    };
-  }
-  maybeCleanupExpired(cache, maxStaleMs) {
-    this.microCacheReqCount++;
-    if (this.microCacheReqCount % this.cleanupEveryNRequests !== 0) return;
-    const now = Date.now();
-    for (const [k, v] of cache.entries()) {
-      if (now - v.createdAt > maxStaleMs) cache.delete(k);
-    }
-  }
-  evictIfNeeded(cache, maxEntries) {
-    while (cache.size >= maxEntries) {
-      const oldestKey = cache.keys().next().value;
-      if (!oldestKey) break;
-      cache.delete(oldestKey);
-    }
-  }
-  isRetryableStatus(status, retryOnStatus) {
-    return retryOnStatus.includes(status);
-  }
-  computeBackoffMs(attemptIndex, baseDelayMs, maxDelayMs) {
-    const exp = baseDelayMs * Math.pow(2, attemptIndex - 1);
-    const capped = clamp(exp, baseDelayMs, maxDelayMs);
-    const jitter = 0.5 + Math.random();
-    return Math.round(capped * jitter);
-  }
-  async fetchWithLeaderRetry(req) {
-    const mc = this.microCache;
-    const retry = mc.retry;
-    if (!retry) return this.existingPipeline(req);
-    const { maxAttempts, baseDelayMs, maxDelayMs, retryOnStatus } = retry;
-    let last;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const res = await this.existingPipeline(req);
-      last = res;
-      if (this.isRetryableStatus(res.status, retryOnStatus) && attempt < maxAttempts) {
-        const delay = this.computeBackoffMs(attempt, baseDelayMs, maxDelayMs);
-        this.emit("microcache:retry", {
-          url: req.url,
-          attempt,
-          maxAttempts,
-          reason: `status ${res.status}`,
-          delayMs: delay
-        });
-        await sleep(delay);
-        continue;
-      }
-      return res;
-    }
-    return last;
-  }
-  /**
-   * Window behavior:
-   * - 0..ttlMs: return cache (fresh)
-   * - ttlMs..maxStaleMs: leader refreshes; others get old value until replaced (stale-while-revalidate)
-   * - >maxStaleMs: do not serve old; behave like no cache
-   *
-   * Follower controls (only when no cache is served):
-   * - maxWaiters: cap concurrent followers joining the leader
-   * - followerTimeoutMs: shared "join window" from first follower; after it expires, late followers fail fast until leader completes
-   */
-  async requestWithMicroCache(req) {
-    const mc = this.microCache;
-    const cache = this.cache;
-    const inFlight = this.inFlight;
-    this.maybeCleanupExpired(cache, mc.maxStaleMs);
-    const key = mc.keyFn(req);
-    const now = Date.now();
-    const hit0 = cache.get(key);
-    if (hit0 && now - hit0.createdAt > mc.maxStaleMs) {
-      cache.delete(key);
-    }
-    const hit = cache.get(key);
-    if (hit && now < hit.expiresAt) {
-      return this.cloneResponse(hit.value);
-    }
-    const group = inFlight.get(key);
-    if (group) {
-      const h = cache.get(key);
-      const staleAllowed = !!h && now - h.createdAt <= mc.maxStaleMs;
-      if (h && staleAllowed) {
-        return this.cloneResponse(h.value);
-      }
-      const age = now - group.windowStartMs;
-      if (age > mc.followerTimeoutMs) {
-        const err = new Error(`Follower window closed for key=${key}`);
-        err.name = "FollowerWindowClosedError";
-        throw err;
-      }
-      if (group.waiters >= mc.maxWaiters) {
-        const err = new Error(`Too many followers for key=${key}`);
-        err.name = "TooManyWaitersError";
-        throw err;
-      }
-      group.waiters += 1;
-      try {
-        const res = await group.promise;
-        return this.cloneResponse(res);
-      } finally {
-        group.waiters -= 1;
-      }
-    }
-    const prev = cache.get(key);
-    const prevStaleAllowed = !!prev && now - prev.createdAt <= mc.maxStaleMs;
-    const promise = (async () => {
-      const res = await this.fetchWithLeaderRetry(req);
-      if (res.status >= 200 && res.status < 300) {
-        this.evictIfNeeded(cache, mc.maxEntries);
-        const t = Date.now();
-        cache.set(key, {
-          value: this.cloneResponse(res),
-          createdAt: t,
-          expiresAt: t + mc.ttlMs
-        });
-      }
-      return res;
-    })();
-    const newGroup = {
-      promise,
-      windowStartMs: Date.now(),
-      waiters: 0
-    };
-    inFlight.set(key, newGroup);
-    try {
-      const res = await promise;
-      if (!(res.status >= 200 && res.status < 300) && prev && prevStaleAllowed) {
-        return this.cloneResponse(prev.value);
-      }
-      return this.cloneResponse(res);
-    } catch (err) {
-      if (prev && prevStaleAllowed) {
-        this.emit("microcache:refresh_failed", { key, url: req.url, error: err });
-        return this.cloneResponse(prev.value);
-      }
-      throw err;
-    } finally {
-      inFlight.delete(key);
-    }
-  }
-  async existingPipeline(req) {
-    const requestId = genRequestId();
-    try {
-      await this.limiter.acquire();
-    } catch (err) {
-      this.emit("request:rejected", { requestId, request: req, error: err });
-      throw err;
-    }
-    const start = Date.now();
-    this.emit("request:start", { requestId, request: req });
-    try {
-      const res = await doHttpRequest(req, this.requestTimeoutMs);
-      const durationMs = Date.now() - start;
-      this.emit("request:success", { requestId, request: req, status: res.status, durationMs });
-      return res;
-    } catch (err) {
-      const durationMs = Date.now() - start;
-      this.emit("request:failure", { requestId, request: req, error: err, durationMs });
-      throw err;
-    } finally {
-      this.limiter.release();
-    }
-  }
-  snapshot() {
-    const s = this.limiter.snapshot();
-    return { inFlight: s.inFlight, queueDepth: s.queueDepth };
-  }
-};
-
-// demo/loadgen.ts
-function sleep2(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-var client = new ResilientHttpClient({
-  maxInFlight: 5,
-  maxQueue: 20,
-  enqueueTimeoutMs: 100,
-  requestTimeoutMs: 4e3,
-  microCache: {
-    enabled: true,
-    ttlMs: 1e3,
-    maxStaleMs: 800,
-    maxEntries: 100,
-    // ⭐ important demo knobs
-    maxWaiters: 10,
-    followerTimeoutMs: 5e3,
-    retry: {
-      maxAttempts: 3,
-      baseDelayMs: 50,
-      maxDelayMs: 200,
-      retryOnStatus: [503]
-    }
-  }
-});
-client.on(
-  "microcache:retry",
-  (e) => console.log("[retry]", e.reason, `attempt ${e.attempt}`)
-);
-client.on(
-  "microcache:waiters_full",
-  () => console.log("[shed] follower queue full")
-);
-client.on(
-  "microcache:follower_window_closed",
-  () => console.log("[shed] follower window closed")
-);
-client.on(
-  "breaker:state",
-  (e) => console.log(`[breaker] ${e.key}: ${e.from} -> ${e.to}`)
-);
-async function burst(label, n) {
-  console.log(`
-=== burst: ${label} (${n} requests) ===`);
-  await Promise.allSettled(
-    Array.from({ length: n }, async (_, i) => {
-      try {
-        const res = await client.request({
-          method: "GET",
-          url: "http://localhost:3001/data"
-        });
-        console.log(
-          `[${label} #${i}]`,
-          res.status,
-          Buffer.from(res.body).toString()
-        );
-      } catch (err) {
-        console.log(`[${label} #${i}] ERROR`, err.name);
-      }
-    })
-  );
-}
-(async () => {
-  await burst("cold-start", 10);
-  await sleep2(500);
-  await burst("cached", 10);
-  await sleep2(1200);
-  await burst("refresh-with-stale", 10);
-  await sleep2(900);
-  await burst("failure", 20);
-  await sleep2(4e3);
-  await burst("recovered", 10);
-  console.log("\nDone.");
-})();
-//# sourceMappingURL=loadgen.js.map

package/dist/demo/loadgen.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/client.ts","../../src/errors.ts","../../src/limiter.ts","../../src/http.ts","../../demo/loadgen.ts"],"sourcesContent":["// src/client.ts\r\nimport { EventEmitter } from \"node:events\";\r\nimport { ConcurrencyLimiter } from \"./limiter.js\";\r\nimport { doHttpRequest } from \"./http.js\";\r\nimport type {\r\n  MicroCacheOptions,\r\n  ResilientHttpClientOptions,\r\n  ResilientRequest,\r\n  ResilientResponse,\r\n} from \"./types.js\";\r\n\r\nfunction normalizeUrlForKey(rawUrl: string): string {\r\n  const u = new URL(rawUrl);\r\n  u.hostname = u.hostname.toLowerCase();\r\n\r\n  const isHttpDefault = u.protocol === \"http:\" && u.port === \"80\";\r\n  const isHttpsDefault = u.protocol === \"https:\" && u.port === \"443\";\r\n  if (isHttpDefault || isHttpsDefault) u.port = \"\";\r\n\r\n  return u.toString();\r\n}\r\n\r\nfunction defaultMicroCacheKeyFn(req: ResilientRequest): string {\r\n  return `GET ${normalizeUrlForKey(req.url)}`;\r\n}\r\n\r\nfunction genRequestId(): string {\r\n  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;\r\n}\r\n\r\nfunction sleep(ms: number): Promise<void> {\r\n  return new Promise((r) => setTimeout(r, ms));\r\n}\r\n\r\nfunction clamp(n: number, lo: number, hi: number): number {\r\n  return Math.max(lo, Math.min(hi, n));\r\n}\r\n\r\ntype CacheEntry = {\r\n  createdAt: number;\r\n  expiresAt: number;\r\n  value: ResilientResponse;\r\n};\r\n\r\ntype InFlightGroup = {\r\n  promise: Promise<ResilientResponse>;\r\n  // follower join window\r\n  windowStartMs: number;\r\n  waiters: number; // followers currently joined (not counting leader)\r\n};\r\n\r\nexport class ResilientHttpClient extends EventEmitter {\r\n  private readonly limiter: ConcurrencyLimiter;\r\n  private readonly requestTimeoutMs: number;\r\n\r\n  private readonly microCache?: Required<\r\n    Pick<\r\n      MicroCacheOptions,\r\n      | \"enabled\"\r\n      | \"ttlMs\"\r\n      | \"maxStaleMs\"\r\n      | \"maxEntries\"\r\n      | \"maxWaiters\"\r\n      | \"followerTimeoutMs\"\r\n      | \"keyFn\"\r\n    >\r\n  > & {\r\n    retry?: {\r\n      maxAttempts: number;\r\n      baseDelayMs: number;\r\n      maxDelayMs: number;\r\n      retryOnStatus: number[];\r\n    };\r\n  };\r\n\r\n  private cache?: Map<string, CacheEntry>;\r\n  private inFlight?: Map<string, InFlightGroup>;\r\n\r\n  private microCacheReqCount = 0;\r\n  private readonly cleanupEveryNRequests = 100;\r\n\r\n  constructor(private readonly opts: ResilientHttpClientOptions) {\r\n    super();\r\n\r\n    this.limiter = new ConcurrencyLimiter({\r\n      maxInFlight: opts.maxInFlight,\r\n      maxQueue: opts.maxQueue,\r\n      enqueueTimeoutMs: opts.enqueueTimeoutMs,\r\n    });\r\n\r\n    this.requestTimeoutMs = opts.requestTimeoutMs;\r\n\r\n    const mc = opts.microCache;\r\n    if (mc?.enabled) {\r\n      const retry = mc.retry\r\n        ? {\r\n            maxAttempts: mc.retry.maxAttempts ?? 3,\r\n            baseDelayMs: mc.retry.baseDelayMs ?? 50,\r\n            maxDelayMs: mc.retry.maxDelayMs ?? 200,\r\n            retryOnStatus: mc.retry.retryOnStatus ?? [429, 502, 503, 504],\r\n          }\r\n        : undefined;\r\n\r\n      this.microCache = {\r\n        enabled: true,\r\n        ttlMs: mc.ttlMs ?? 1000,\r\n        maxStaleMs: mc.maxStaleMs ?? 10_000,\r\n        maxEntries: mc.maxEntries ?? 500,\r\n        maxWaiters: mc.maxWaiters ?? 1000,\r\n        followerTimeoutMs: mc.followerTimeoutMs ?? 5000,\r\n        keyFn: mc.keyFn ?? defaultMicroCacheKeyFn,\r\n        retry,\r\n      };\r\n\r\n      this.cache = new Map();\r\n      this.inFlight = new Map();\r\n    }\r\n  }\r\n\r\n  async request(req: ResilientRequest): Promise<ResilientResponse> {\r\n    if (this.microCache?.enabled && req.method === \"GET\" && req.body == null) {\r\n      return this.requestWithMicroCache(req);\r\n    }\r\n    return this.existingPipeline(req);\r\n  }\r\n\r\n  private cloneResponse(res: ResilientResponse): ResilientResponse {\r\n    return {\r\n      status: res.status,\r\n      headers: { ...res.headers },\r\n      body: new Uint8Array(res.body),\r\n    };\r\n  }\r\n\r\n  private maybeCleanupExpired(cache: Map<string, CacheEntry>, maxStaleMs: number): void {\r\n    this.microCacheReqCount++;\r\n    if (this.microCacheReqCount % this.cleanupEveryNRequests !== 0) return;\r\n\r\n    const now = Date.now();\r\n    for (const [k, v] of cache.entries()) {\r\n      if (now - v.createdAt > maxStaleMs) cache.delete(k);\r\n    }\r\n  }\r\n\r\n  private evictIfNeeded(cache: Map<string, CacheEntry>, maxEntries: number): void {\r\n    while (cache.size >= maxEntries) {\r\n      const oldestKey = cache.keys().next().value as string | undefined;\r\n      if (!oldestKey) break;\r\n      cache.delete(oldestKey);\r\n    }\r\n  }\r\n\r\n  private isRetryableStatus(status: number, retryOnStatus: number[]): boolean {\r\n    return retryOnStatus.includes(status);\r\n  }\r\n\r\n  private computeBackoffMs(attemptIndex: number, baseDelayMs: number, maxDelayMs: number): number {\r\n    const exp = baseDelayMs * Math.pow(2, attemptIndex - 1);\r\n    const capped = clamp(exp, baseDelayMs, maxDelayMs);\r\n    const jitter = 0.5 + Math.random();\r\n    return Math.round(capped * jitter);\r\n  }\r\n\r\n  private async fetchWithLeaderRetry(req: ResilientRequest): Promise<ResilientResponse> {\r\n    const mc = this.microCache!;\r\n    const retry = mc.retry;\r\n    if (!retry) return this.existingPipeline(req);\r\n\r\n    const { maxAttempts, baseDelayMs, maxDelayMs, retryOnStatus } = retry;\r\n\r\n    let last: ResilientResponse | undefined;\r\n\r\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\r\n      const res = await this.existingPipeline(req);\r\n      last = res;\r\n\r\n      if (this.isRetryableStatus(res.status, retryOnStatus) && attempt < maxAttempts) {\r\n        const delay = this.computeBackoffMs(attempt, baseDelayMs, maxDelayMs);\r\n        this.emit(\"microcache:retry\", {\r\n          url: req.url,\r\n          attempt,\r\n          maxAttempts,\r\n          reason: `status ${res.status}`,\r\n          delayMs: delay,\r\n        });\r\n        await sleep(delay);\r\n        continue;\r\n      }\r\n\r\n      return res;\r\n    }\r\n\r\n    // should never\r\n    return last!;\r\n  }\r\n\r\n  /**\r\n   * Window behavior:\r\n   * - 0..ttlMs: return cache (fresh)\r\n   * - ttlMs..maxStaleMs: leader refreshes; others get old value until replaced (stale-while-revalidate)\r\n   * - >maxStaleMs: do not serve old; behave like no cache\r\n   *\r\n   * Follower controls (only when no cache is served):\r\n   * - maxWaiters: cap concurrent followers joining the leader\r\n   * - followerTimeoutMs: shared \"join window\" from first follower; after it expires, late followers fail fast until leader completes\r\n   */\r\n  private async requestWithMicroCache(req: ResilientRequest): Promise<ResilientResponse> {\r\n    const mc = this.microCache!;\r\n    const cache = this.cache!;\r\n    const inFlight = this.inFlight!;\r\n\r\n    this.maybeCleanupExpired(cache, mc.maxStaleMs);\r\n\r\n    const key = mc.keyFn(req);\r\n    const now = Date.now();\r\n\r\n    // If cached entry exists but too old, delete it\r\n    const hit0 = cache.get(key);\r\n    if (hit0 && now - hit0.createdAt > mc.maxStaleMs) {\r\n      cache.delete(key);\r\n    }\r\n\r\n    const hit = cache.get(key);\r\n    if (hit && now < hit.expiresAt) {\r\n      return this.cloneResponse(hit.value);\r\n    }\r\n\r\n    // If refresh exists\r\n    const group = inFlight.get(key);\r\n    if (group) {\r\n      const h = cache.get(key);\r\n      const staleAllowed = !!h && now - h.createdAt <= mc.maxStaleMs;\r\n\r\n      // stale-while-revalidate: serve old immediately\r\n      if (h && staleAllowed) {\r\n        return this.cloneResponse(h.value);\r\n      }\r\n\r\n      // No cache allowed: followers must \"join\" or be rejected\r\n      const age = now - group.windowStartMs;\r\n      if (age > mc.followerTimeoutMs) {\r\n        const err = new Error(`Follower window closed for key=${key}`);\r\n        (err as any).name = \"FollowerWindowClosedError\";\r\n        throw err;\r\n      }\r\n\r\n      if (group.waiters >= mc.maxWaiters) {\r\n        const err = new Error(`Too many followers for key=${key}`);\r\n        (err as any).name = \"TooManyWaitersError\";\r\n        throw err;\r\n      }\r\n\r\n      group.waiters += 1;\r\n      try {\r\n        const res = await group.promise;\r\n        return this.cloneResponse(res);\r\n      } finally {\r\n        group.waiters -= 1;\r\n      }\r\n    }\r\n\r\n    // Become leader\r\n    const prev = cache.get(key);\r\n    const prevStaleAllowed = !!prev && now - prev.createdAt <= mc.maxStaleMs;\r\n\r\n    const promise = (async () => {\r\n      const res = await this.fetchWithLeaderRetry(req);\r\n\r\n      if (res.status >= 200 && res.status < 300) {\r\n        this.evictIfNeeded(cache, mc.maxEntries);\r\n        const t = Date.now();\r\n        cache.set(key, {\r\n          value: this.cloneResponse(res),\r\n          createdAt: t,\r\n          expiresAt: t + mc.ttlMs,\r\n        });\r\n      }\r\n\r\n      return res;\r\n    })();\r\n\r\n    const newGroup: InFlightGroup = {\r\n      promise,\r\n      windowStartMs: Date.now(),\r\n      waiters: 0,\r\n    };\r\n\r\n    inFlight.set(key, newGroup);\r\n\r\n    try {\r\n      const res = await promise;\r\n\r\n      // if not 2xx and we have stale allowed -> serve prev instead\r\n      if (!(res.status >= 200 && res.status < 300) && prev && prevStaleAllowed) {\r\n        return this.cloneResponse(prev.value);\r\n      }\r\n\r\n      return this.cloneResponse(res);\r\n    } catch (err) {\r\n      if (prev && prevStaleAllowed) {\r\n        this.emit(\"microcache:refresh_failed\", { key, url: req.url, error: err });\r\n        return this.cloneResponse(prev.value);\r\n      }\r\n      throw err;\r\n    } finally {\r\n      inFlight.delete(key);\r\n    }\r\n  }\r\n\r\n  private async existingPipeline(req: ResilientRequest): Promise<ResilientResponse> {\r\n    const requestId = genRequestId();\r\n\r\n    try {\r\n      await this.limiter.acquire();\r\n    } catch (err) {\r\n      this.emit(\"request:rejected\", { requestId, request: req, error: err });\r\n      throw err;\r\n    }\r\n\r\n    const start = Date.now();\r\n    this.emit(\"request:start\", { requestId, request: req });\r\n\r\n    try {\r\n      const res = await doHttpRequest(req, this.requestTimeoutMs);\r\n      const durationMs = Date.now() - start;\r\n      this.emit(\"request:success\", { requestId, request: req, status: res.status, durationMs });\r\n      return res;\r\n    } catch (err) {\r\n      const durationMs = Date.now() - start;\r\n      this.emit(\"request:failure\", { requestId, request: req, error: err, durationMs });\r\n      throw err;\r\n    } finally {\r\n      this.limiter.release();\r\n    }\r\n  }\r\n\r\n  snapshot(): { inFlight: number; queueDepth: number } {\r\n    const s = this.limiter.snapshot();\r\n    return { inFlight: s.inFlight, queueDepth: s.queueDepth };\r\n  }\r\n}\r\n","export abstract class ResilientHttpError extends Error {\r\n  public readonly name: string;\r\n  constructor(message: string) {\r\n    super(message);\r\n    this.name = this.constructor.name;\r\n  }\r\n}\r\n\r\nexport class QueueFullError extends ResilientHttpError {\r\n  constructor(public readonly maxQueue: number) {\r\n    super(`Queue is full (maxQueue=${maxQueue}).`);\r\n  }\r\n}\r\n\r\nexport class QueueTimeoutError extends ResilientHttpError {\r\n  constructor(public readonly enqueueTimeoutMs: number) {\r\n    super(`Queue wait exceeded (enqueueTimeoutMs=${enqueueTimeoutMs}).`);\r\n  }\r\n}\r\n\r\nexport class RequestTimeoutError extends ResilientHttpError {\r\n  constructor(public readonly requestTimeoutMs: number) {\r\n    super(`Request timed out (requestTimeoutMs=${requestTimeoutMs}).`);\r\n  }\r\n}\r\n\r\n\r\n\r\nexport class UpstreamError extends ResilientHttpError {\r\n  constructor(public readonly status: number) {\r\n    super(`Upstream returned error status=${status}.`);\r\n  }\r\n}\r\n","// src/limiter.ts\r\nimport { QueueFullError, QueueTimeoutError } from \"./errors.js\";\r\n\r\ntype ResolveFn = () => void;\r\ntype RejectFn = (err: unknown) => void;\r\n\r\ninterface Waiter {\r\n  resolve: ResolveFn;\r\n  reject: RejectFn;\r\n  timer: NodeJS.Timeout;\r\n}\r\n\r\n/**\r\n * A simple in-process concurrency limiter with a bounded FIFO queue.\r\n *\r\n * - At most maxInFlight \"permits\" can be held concurrently.\r\n * - If no permit is available, callers are queued up to maxQueue.\r\n * - If queue is full => reject immediately (QueueFullError).\r\n * - If a caller waits too long in the queue => reject (QueueTimeoutError).\r\n *\r\n * This is intentionally process-local: no persistence, no external coordination.\r\n */\r\nexport class ConcurrencyLimiter {\r\n  private readonly maxInFlight: number;\r\n  private readonly maxQueue: number;\r\n  private readonly enqueueTimeoutMs: number;\r\n\r\n  private inFlight = 0;\r\n  private queue: Waiter[] = [];\r\n\r\n  constructor(opts: { maxInFlight: number; maxQueue: number; enqueueTimeoutMs: number }) {\r\n    if (!Number.isFinite(opts.maxInFlight) || opts.maxInFlight <= 0) {\r\n      throw new Error(`maxInFlight must be > 0 (got ${opts.maxInFlight})`);\r\n    }\r\n    if (!Number.isFinite(opts.maxQueue) || opts.maxQueue < 0) {\r\n      throw new Error(`maxQueue must be >= 0 (got ${opts.maxQueue})`);\r\n    }\r\n    if (!Number.isFinite(opts.enqueueTimeoutMs) || opts.enqueueTimeoutMs <= 0) {\r\n      throw new Error(`enqueueTimeoutMs must be > 0 (got ${opts.enqueueTimeoutMs})`);\r\n    }\r\n\r\n    this.maxInFlight = opts.maxInFlight;\r\n    this.maxQueue = opts.maxQueue;\r\n    this.enqueueTimeoutMs = opts.enqueueTimeoutMs;\r\n  }\r\n\r\n  /**\r\n   * Acquire a permit. Resolves once you are allowed to proceed.\r\n   * MUST be followed by `release()` exactly once.\r\n   */\r\n  acquire(): Promise<void> {\r\n    // Fast path: permit available\r\n    if (this.inFlight < this.maxInFlight) {\r\n      this.inFlight += 1;\r\n      return Promise.resolve();\r\n    }\r\n\r\n    // Queue disabled or full\r\n    if (this.maxQueue === 0 || this.queue.length >= this.maxQueue) {\r\n      return Promise.reject(new QueueFullError(this.maxQueue));\r\n    }\r\n\r\n    // Enqueue and wait\r\n    return new Promise<void>((resolve, reject) => {\r\n      const timer = setTimeout(() => {\r\n        // On timeout, remove from queue if still present\r\n        const idx = this.queue.findIndex((w) => w.resolve === resolve);\r\n        if (idx >= 0) {\r\n          const [w] = this.queue.splice(idx, 1);\r\n          clearTimeout(w.timer);\r\n        }\r\n        reject(new QueueTimeoutError(this.enqueueTimeoutMs));\r\n      }, this.enqueueTimeoutMs);\r\n\r\n      this.queue.push({ resolve, reject, timer });\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Release a permit. Always call this in a `finally` block.\r\n   */\r\n  release(): void {\r\n    if (this.inFlight <= 0) {\r\n      // Defensive: indicates a bug in caller usage.\r\n      throw new Error(\"release() called when inFlight is already 0\");\r\n    }\r\n\r\n    // If someone is waiting, hand off permit directly without reducing inFlight.\r\n    const next = this.queue.shift();\r\n    if (next) {\r\n      clearTimeout(next.timer);\r\n      // Permit is transferred to the next waiter; inFlight stays the same.\r\n      next.resolve();\r\n      return;\r\n    }\r\n\r\n    // No waiters => reduce inFlight\r\n    this.inFlight -= 1;\r\n  }\r\n\r\n  snapshot(): { inFlight: number; queueDepth: number; maxInFlight: number; maxQueue: number } {\r\n    return {\r\n      inFlight: this.inFlight,\r\n      queueDepth: this.queue.length,\r\n      maxInFlight: this.maxInFlight,\r\n      maxQueue: this.maxQueue,\r\n    };\r\n  }\r\n}\r\n","// src/http.ts\r\nimport { request as undiciRequest } from \"undici\";\r\nimport { RequestTimeoutError } from \"./errors.js\";\r\nimport type { ResilientRequest, ResilientResponse } from \"./types.js\";\r\n\r\nfunction normalizeHeaders(headers: any): Record<string, string> {\r\n  const out: Record<string, string> = {};\r\n  if (!headers) return out;\r\n\r\n  // undici headers are an object-like structure (headers: Record<string, string | string[]>)\r\n  for (const [k, v] of Object.entries(headers)) {\r\n    if (Array.isArray(v)) out[k.toLowerCase()] = v.join(\", \");\r\n    else if (typeof v === \"string\") out[k.toLowerCase()] = v;\r\n    else out[k.toLowerCase()] = String(v);\r\n  }\r\n  return out;\r\n}\r\n\r\n/**\r\n * Execute a single HTTP request with a hard timeout using AbortController.\r\n * No retries. No breaker. Just raw outbound I/O with a timeout.\r\n */\r\nexport async function doHttpRequest(\r\n  req: ResilientRequest,\r\n  requestTimeoutMs: number\r\n): Promise<ResilientResponse> {\r\n  const ac = new AbortController();\r\n  const timer = setTimeout(() => ac.abort(), requestTimeoutMs);\r\n\r\n  try {\r\n    const res = await undiciRequest(req.url, {\r\n      method: req.method,\r\n      headers: req.headers,\r\n      body: req.body as any,\r\n      signal: ac.signal,\r\n    });\r\n\r\n    const body = await res.body.arrayBuffer();\r\n    return {\r\n      status: res.statusCode,\r\n      headers: normalizeHeaders(res.headers),\r\n      body: new Uint8Array(body),\r\n    };\r\n  } catch (err: any) {\r\n    // undici throws AbortError on abort\r\n    if (err?.name === \"AbortError\") {\r\n      throw new RequestTimeoutError(requestTimeoutMs);\r\n    }\r\n    throw err;\r\n  } finally {\r\n    clearTimeout(timer);\r\n  }\r\n}\r\n","// demo/loadgen.ts\r\nimport { ResilientHttpClient } from \"../src/client.js\";\r\n\r\nfunction sleep(ms: number) {\r\n  return new Promise((r) => setTimeout(r, ms));\r\n}\r\n\r\nconst client = new ResilientHttpClient({\r\n  maxInFlight: 5,\r\n  maxQueue: 20,\r\n  enqueueTimeoutMs: 100,\r\n  requestTimeoutMs: 4000,\r\n\r\n  microCache: {\r\n    enabled: true,\r\n    ttlMs: 1000,\r\n    maxStaleMs: 800,\r\n    maxEntries: 100,\r\n\r\n    // ⭐ important demo knobs\r\n    maxWaiters: 10,\r\n    followerTimeoutMs: 5000,\r\n\r\n    retry: {\r\n      maxAttempts: 3,\r\n      baseDelayMs: 50,\r\n      maxDelayMs: 200,\r\n      retryOnStatus: [503],\r\n    },\r\n  },\r\n});\r\n\r\n// Observe behavior\r\nclient.on(\"microcache:retry\", (e) =>\r\n  console.log(\"[retry]\", e.reason, `attempt ${e.attempt}`)\r\n);\r\nclient.on(\"microcache:waiters_full\", () =>\r\n  console.log(\"[shed] follower queue full\")\r\n);\r\nclient.on(\"microcache:follower_window_closed\", () =>\r\n  console.log(\"[shed] follower window closed\")\r\n);\r\nclient.on(\"breaker:state\", (e) =>\r\n  console.log(`[breaker] ${e.key}: ${e.from} -> ${e.to}`)\r\n);\r\n\r\nasync function burst(label: string, n: number) {\r\n  console.log(`\\n=== burst: ${label} (${n} requests) ===`);\r\n\r\n  await Promise.allSettled(\r\n    Array.from({ length: n }, async (_, i) => {\r\n      try {\r\n        const res = await client.request({\r\n          method: \"GET\",\r\n          url: \"http://localhost:3001/data\",\r\n        });\r\n\r\n        console.log(\r\n          `[${label} #${i}]`,\r\n          res.status,\r\n          Buffer.from(res.body).toString()\r\n        );\r\n      } catch (err: any) {\r\n        console.log(`[${label} #${i}] ERROR`, err.name);\r\n      }\r\n    })\r\n  );\r\n}\r\n\r\n(async () => {\r\n  // Cold start: singleflight + slow upstream\r\n  await burst(\"cold-start\", 10);\r\n\r\n  // Cached: zero upstream hits\r\n  await sleep(500);\r\n  await burst(\"cached\", 10);\r\n\r\n  // TTL expires → refresh with stale serve\r\n  await sleep(1200);\r\n  await burst(\"refresh-with-stale\", 10);\r\n\r\n  // Failure window → leader retries, followers protected\r\n  await sleep(900);\r\n  await burst(\"failure\", 20);\r\n\r\n  // Recovery\r\n  await sleep(4000);\r\n  await burst(\"recovered\", 10);\r\n\r\n  console.log(\"\\nDone.\");\r\n})();\r\n"],"mappings":"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","names":["sleep"]}

package/dist/demo/upstream.cjs

@@ -1,58 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  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
-));
-
-// demo/upstream.ts
-var import_node_http = __toESM(require("http"), 1);
-var hits = 0;
-var start = Date.now();
-function modeNow() {
-  const t = Date.now() - start;
-  if (t < 4e3) return "slow-ok";
-  if (t < 9e3) return "fail";
-  return "recover";
-}
-var server = import_node_http.default.createServer((_, res) => {
-  hits += 1;
-  const mode = modeNow();
-  console.log(`[upstream] hit #${hits} mode=${mode}`);
-  if (mode === "fail") {
-    setTimeout(() => {
-      res.statusCode = 503;
-      res.setHeader("content-type", "text/plain");
-      res.end("upstream failing");
-    }, 100);
-    return;
-  }
-  const delay = mode === "slow-ok" ? 1500 : 200;
-  setTimeout(() => {
-    res.statusCode = 200;
-    res.setHeader("content-type", "text/plain");
-    res.end(`ok-${mode}-#${hits}`);
-  }, delay);
-});
-server.listen(3001, () => {
-  console.log("\u{1F6A7} upstream listening on http://localhost:3001");
-  console.log("phases: 0-4s slow-ok | 4-9s fail(503) | 9s+ recover");
-});
-//# sourceMappingURL=upstream.cjs.map

package/dist/demo/upstream.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../demo/upstream.ts"],"sourcesContent":["// demo/upstream.ts\r\nimport http from \"node:http\";\r\n\r\nlet hits = 0;\r\nconst start = Date.now();\r\n\r\n/**\r\n * Deterministic phases (time-based):\r\n * 0s..4s    : slow OK (shows singleflight + microcache)\r\n * 4s..9s    : fail (503) (shows leader-only retry + breaker + shedding)\r\n * 9s..      : recover OK (shows recovery + fresh cache)\r\n */\r\nfunction modeNow(): \"slow-ok\" | \"fail\" | \"recover\" {\r\n  const t = Date.now() - start;\r\n  if (t < 4000) return \"slow-ok\";\r\n  if (t < 9000) return \"fail\";\r\n  return \"recover\";\r\n}\r\n\r\nconst server = http.createServer((_, res) => {\r\n  hits += 1;\r\n  const mode = modeNow();\r\n\r\n  console.log(`[upstream] hit #${hits} mode=${mode}`);\r\n\r\n  if (mode === \"fail\") {\r\n    // Return 503 quickly (retryable)\r\n    setTimeout(() => {\r\n      res.statusCode = 503;\r\n      res.setHeader(\"content-type\", \"text/plain\");\r\n      res.end(\"upstream failing\");\r\n    }, 100);\r\n    return;\r\n  }\r\n\r\n  const delay = mode === \"slow-ok\" ? 1500 : 200;\r\n\r\n  setTimeout(() => {\r\n    res.statusCode = 200;\r\n    res.setHeader(\"content-type\", \"text/plain\");\r\n    res.end(`ok-${mode}-#${hits}`);\r\n  }, delay);\r\n});\r\n\r\nserver.listen(3001, () => {\r\n  console.log(\"🚧 upstream listening on http://localhost:3001\");\r\n  console.log(\"phases: 0-4s slow-ok | 4-9s fail(503) | 9s+ recover\");\r\n});\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AACA,uBAAiB;AAEjB,IAAI,OAAO;AACX,IAAM,QAAQ,KAAK,IAAI;AAQvB,SAAS,UAA0C;AACjD,QAAM,IAAI,KAAK,IAAI,IAAI;AACvB,MAAI,IAAI,IAAM,QAAO;AACrB,MAAI,IAAI,IAAM,QAAO;AACrB,SAAO;AACT;AAEA,IAAM,SAAS,iBAAAA,QAAK,aAAa,CAAC,GAAG,QAAQ;AAC3C,UAAQ;AACR,QAAM,OAAO,QAAQ;AAErB,UAAQ,IAAI,mBAAmB,IAAI,SAAS,IAAI,EAAE;AAElD,MAAI,SAAS,QAAQ;AAEnB,eAAW,MAAM;AACf,UAAI,aAAa;AACjB,UAAI,UAAU,gBAAgB,YAAY;AAC1C,UAAI,IAAI,kBAAkB;AAAA,IAC5B,GAAG,GAAG;AACN;AAAA,EACF;AAEA,QAAM,QAAQ,SAAS,YAAY,OAAO;AAE1C,aAAW,MAAM;AACf,QAAI,aAAa;AACjB,QAAI,UAAU,gBAAgB,YAAY;AAC1C,QAAI,IAAI,MAAM,IAAI,KAAK,IAAI,EAAE;AAAA,EAC/B,GAAG,KAAK;AACV,CAAC;AAED,OAAO,OAAO,MAAM,MAAM;AACxB,UAAQ,IAAI,uDAAgD;AAC5D,UAAQ,IAAI,qDAAqD;AACnE,CAAC;","names":["http"]}

package/dist/demo/upstream.d.cts

@@ -1,2 +0,0 @@
-
-export {  }

package/dist/demo/upstream.d.ts

@@ -1,2 +0,0 @@
-
-export {  }

package/dist/demo/upstream.js

@@ -1,34 +0,0 @@
-// demo/upstream.ts
-import http from "http";
-var hits = 0;
-var start = Date.now();
-function modeNow() {
-  const t = Date.now() - start;
-  if (t < 4e3) return "slow-ok";
-  if (t < 9e3) return "fail";
-  return "recover";
-}
-var server = http.createServer((_, res) => {
-  hits += 1;
-  const mode = modeNow();
-  console.log(`[upstream] hit #${hits} mode=${mode}`);
-  if (mode === "fail") {
-    setTimeout(() => {
-      res.statusCode = 503;
-      res.setHeader("content-type", "text/plain");
-      res.end("upstream failing");
-    }, 100);
-    return;
-  }
-  const delay = mode === "slow-ok" ? 1500 : 200;
-  setTimeout(() => {
-    res.statusCode = 200;
-    res.setHeader("content-type", "text/plain");
-    res.end(`ok-${mode}-#${hits}`);
-  }, delay);
-});
-server.listen(3001, () => {
-  console.log("\u{1F6A7} upstream listening on http://localhost:3001");
-  console.log("phases: 0-4s slow-ok | 4-9s fail(503) | 9s+ recover");
-});
-//# sourceMappingURL=upstream.js.map

package/dist/demo/upstream.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../demo/upstream.ts"],"sourcesContent":["// demo/upstream.ts\r\nimport http from \"node:http\";\r\n\r\nlet hits = 0;\r\nconst start = Date.now();\r\n\r\n/**\r\n * Deterministic phases (time-based):\r\n * 0s..4s    : slow OK (shows singleflight + microcache)\r\n * 4s..9s    : fail (503) (shows leader-only retry + breaker + shedding)\r\n * 9s..      : recover OK (shows recovery + fresh cache)\r\n */\r\nfunction modeNow(): \"slow-ok\" | \"fail\" | \"recover\" {\r\n  const t = Date.now() - start;\r\n  if (t < 4000) return \"slow-ok\";\r\n  if (t < 9000) return \"fail\";\r\n  return \"recover\";\r\n}\r\n\r\nconst server = http.createServer((_, res) => {\r\n  hits += 1;\r\n  const mode = modeNow();\r\n\r\n  console.log(`[upstream] hit #${hits} mode=${mode}`);\r\n\r\n  if (mode === \"fail\") {\r\n    // Return 503 quickly (retryable)\r\n    setTimeout(() => {\r\n      res.statusCode = 503;\r\n      res.setHeader(\"content-type\", \"text/plain\");\r\n      res.end(\"upstream failing\");\r\n    }, 100);\r\n    return;\r\n  }\r\n\r\n  const delay = mode === \"slow-ok\" ? 1500 : 200;\r\n\r\n  setTimeout(() => {\r\n    res.statusCode = 200;\r\n    res.setHeader(\"content-type\", \"text/plain\");\r\n    res.end(`ok-${mode}-#${hits}`);\r\n  }, delay);\r\n});\r\n\r\nserver.listen(3001, () => {\r\n  console.log(\"🚧 upstream listening on http://localhost:3001\");\r\n  console.log(\"phases: 0-4s slow-ok | 4-9s fail(503) | 9s+ recover\");\r\n});\r\n"],"mappings":";AACA,OAAO,UAAU;AAEjB,IAAI,OAAO;AACX,IAAM,QAAQ,KAAK,IAAI;AAQvB,SAAS,UAA0C;AACjD,QAAM,IAAI,KAAK,IAAI,IAAI;AACvB,MAAI,IAAI,IAAM,QAAO;AACrB,MAAI,IAAI,IAAM,QAAO;AACrB,SAAO;AACT;AAEA,IAAM,SAAS,KAAK,aAAa,CAAC,GAAG,QAAQ;AAC3C,UAAQ;AACR,QAAM,OAAO,QAAQ;AAErB,UAAQ,IAAI,mBAAmB,IAAI,SAAS,IAAI,EAAE;AAElD,MAAI,SAAS,QAAQ;AAEnB,eAAW,MAAM;AACf,UAAI,aAAa;AACjB,UAAI,UAAU,gBAAgB,YAAY;AAC1C,UAAI,IAAI,kBAAkB;AAAA,IAC5B,GAAG,GAAG;AACN;AAAA,EACF;AAEA,QAAM,QAAQ,SAAS,YAAY,OAAO;AAE1C,aAAW,MAAM;AACf,QAAI,aAAa;AACjB,QAAI,UAAU,gBAAgB,YAAY;AAC1C,QAAI,IAAI,MAAM,IAAI,KAAK,IAAI,EAAE;AAAA,EAC/B,GAAG,KAAK;AACV,CAAC;AAED,OAAO,OAAO,MAAM,MAAM;AACxB,UAAQ,IAAI,uDAAgD;AAC5D,UAAQ,IAAI,qDAAqD;AACnE,CAAC;","names":[]}