@pureq/pureq 1.0.0

package/dist/src/middleware/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../../src/middleware/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAe,aAAa,EAAE,MAAM,eAAe,CAAC;AAI5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,aAAa,CAAC,KAAK,MAAM,CAAC;CAChE;AAkBD;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,UAAU,CAgC9D"}

package/dist/src/middleware/dedupe.js

@@ -0,0 +1,46 @@
+import { stableKeyValues, stableQuery } from "../utils/stableKey";
+// stableKeyValues and stableQuery are imported from ../utils/stableKey
+function defaultKeyBuilder(req, includeHeaders, includeBody) {
+    const headersPart = includeHeaders ? stableKeyValues(req.headers) : "";
+    const bodyPart = includeBody ? JSON.stringify(req.body ?? null) : "";
+    return [
+        req.method,
+        req.url,
+        stableKeyValues(req.params),
+        stableQuery(req.query),
+        headersPart,
+        bodyPart,
+    ].join("|");
+}
+/**
+ * Deduplicates in-flight requests with the same request signature.
+ * Useful for UI bursts and concurrent cache stampede prevention.
+ */
+export function dedupe(options = {}) {
+    const methods = new Set(options.methods ?? ["GET", "HEAD"]);
+    const inflight = new Map();
+    return async (req, next) => {
+        if (!methods.has(req.method)) {
+            return next(req);
+        }
+        const key = options.keyBuilder?.(req) ??
+            defaultKeyBuilder(req, options.includeHeaders ?? false, options.includeBody ?? false);
+        const existing = inflight.get(key);
+        if (existing) {
+            const sharedResponse = await existing;
+            return sharedResponse.clone();
+        }
+        const pending = (async () => {
+            try {
+                return await next(req);
+            }
+            finally {
+                inflight.delete(key);
+            }
+        })();
+        inflight.set(key, pending);
+        const response = await pending;
+        return response.clone();
+    };
+}
+//# sourceMappingURL=dedupe.js.map

package/dist/src/middleware/dedupe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../../src/middleware/dedupe.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AASlE,uEAAuE;AAEvE,SAAS,iBAAiB,CAAC,GAA4B,EAAE,cAAuB,EAAE,WAAoB;IACpG,MAAM,WAAW,GAAG,cAAc,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAErE,OAAO;QACL,GAAG,CAAC,MAAM;QACV,GAAG,CAAC,GAAG;QACP,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;QAC3B,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;QACtB,WAAW;QACX,QAAQ;KACT,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,UAAyB,EAAE;IAChD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;IAE1D,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;QAED,MAAM,GAAG,GACP,OAAO,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC;YACzB,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK,EAAE,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC,CAAC;QAExF,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC;YACtC,OAAO,cAAc,CAAC,KAAK,EAAE,CAAC;QAChC,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;oBAAS,CAAC;gBACT,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QAEL,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAE3B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC;QAC/B,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/middleware/defaultTimeout.d.ts

@@ -0,0 +1,6 @@
+import type { Middleware } from "../types/http";
+/**
+ * Applies a default timeout when a request does not explicitly specify one.
+ */
+export declare function defaultTimeout(timeoutMs: number): Middleware;
+//# sourceMappingURL=defaultTimeout.d.ts.map

package/dist/src/middleware/defaultTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultTimeout.d.ts","sourceRoot":"","sources":["../../../src/middleware/defaultTimeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAoB5D"}

package/dist/src/middleware/defaultTimeout.js

@@ -0,0 +1,23 @@
+import { markPolicyMiddleware } from "../policy/guardrails";
+/**
+ * Applies a default timeout when a request does not explicitly specify one.
+ */
+export function defaultTimeout(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("pureq: defaultTimeout requires a positive timeoutMs");
+    }
+    const middleware = async (req, next) => {
+        if (req.timeout !== undefined) {
+            return next(req);
+        }
+        return next({
+            ...req,
+            timeout: timeoutMs,
+        });
+    };
+    return markPolicyMiddleware(middleware, {
+        name: "defaultTimeout",
+        kind: "timeout",
+    });
+}
+//# sourceMappingURL=defaultTimeout.js.map

package/dist/src/middleware/defaultTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultTimeout.js","sourceRoot":"","sources":["../../../src/middleware/defaultTimeout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,UAAU,GAAe,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACjD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;QAED,OAAO,IAAI,CAAC;YACV,GAAG,GAAG;YACN,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO,oBAAoB,CAAC,UAAU,EAAE;QACtC,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,SAAS;KAChB,CAAC,CAAC;AACL,CAAC"}

package/dist/src/middleware/diagnostics.d.ts

@@ -0,0 +1,28 @@
+import type { Middleware, RequestConfig } from "../types/http";
+import type { TransportEvent } from "../types/events";
+export type DiagnosticEvent = TransportEvent & {
+    readonly method: RequestConfig["method"];
+    readonly durationMs: number;
+};
+export interface DiagnosticsSnapshot {
+    readonly total: number;
+    readonly success: number;
+    readonly failed: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly recentEvents: readonly DiagnosticEvent[];
+}
+export interface DiagnosticsController {
+    readonly middleware: Middleware;
+    readonly snapshot: () => DiagnosticsSnapshot;
+    readonly reset: () => void;
+}
+export interface DiagnosticsOptions {
+    readonly maxEvents?: number;
+    readonly onEvent?: (event: DiagnosticEvent) => void;
+}
+/**
+ * Middleware diagnostics collector for runtime policy visibility.
+ */
+export declare function createMiddlewareDiagnostics(options?: DiagnosticsOptions): DiagnosticsController;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/src/middleware/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/middleware/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE/D,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAExE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG;IAC7C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,mBAAmB,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CACrD;AA6BD;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,kBAAuB,GAAG,qBAAqB,CA2GnG"}

package/dist/src/middleware/diagnostics.js

@@ -0,0 +1,131 @@
+import { toPureqError } from "../types/result";
+function getMetaValue(req, key) {
+    if (typeof req !== "object" || req === null || !("_meta" in req)) {
+        return undefined;
+    }
+    const meta = req._meta;
+    if (!meta) {
+        return undefined;
+    }
+    return meta[key];
+}
+function getPolicyTrace(req) {
+    const value = getMetaValue(req, "policyTrace");
+    return Array.isArray(value) ? value : undefined;
+}
+function percentile(values, p) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[idx] ?? 0;
+}
+/**
+ * Middleware diagnostics collector for runtime policy visibility.
+ */
+export function createMiddlewareDiagnostics(options = {}) {
+    const maxEvents = options.maxEvents ?? 200;
+    const durations = [];
+    const events = [];
+    let total = 0;
+    let success = 0;
+    let failed = 0;
+    const middleware = async (req, next) => {
+        const startedAt = Date.now();
+        const requestIdMeta = getMetaValue(req, "requestId");
+        const retryCountMeta = getMetaValue(req, "retryCount");
+        const requestId = typeof requestIdMeta === "string" ? requestIdMeta : undefined;
+        const retryCount = typeof retryCountMeta === "number" ? retryCountMeta : undefined;
+        try {
+            const response = await next(req);
+            const durationMs = Date.now() - startedAt;
+            const policyTrace = getPolicyTrace(req);
+            total += 1;
+            success += 1;
+            durations.push(durationMs);
+            // Cap durations array to prevent unbounded memory growth
+            if (durations.length > maxEvents) {
+                durations.splice(0, durations.length - maxEvents);
+            }
+            events.push({
+                phase: "success",
+                at: Date.now(),
+                ...(requestId !== undefined ? { requestId } : {}),
+                method: req.method,
+                url: req.url,
+                startedAt,
+                status: response.status,
+                durationMs,
+                ...(retryCount !== undefined ? { retryCount } : {}),
+                ...(policyTrace !== undefined ? { policyTrace } : {}),
+            });
+            const latest = events[events.length - 1];
+            if (latest) {
+                options.onEvent?.(latest);
+            }
+            if (events.length > maxEvents) {
+                events.splice(0, events.length - maxEvents);
+            }
+            return response;
+        }
+        catch (error) {
+            const durationMs = Date.now() - startedAt;
+            const normalized = toPureqError(error, {
+                method: req.method,
+                url: req.url,
+            });
+            total += 1;
+            failed += 1;
+            durations.push(durationMs);
+            // Cap durations array to prevent unbounded memory growth
+            if (durations.length > maxEvents) {
+                durations.splice(0, durations.length - maxEvents);
+            }
+            const policyTrace = getPolicyTrace(req);
+            events.push({
+                phase: "error",
+                at: Date.now(),
+                ...(requestId !== undefined ? { requestId } : {}),
+                method: req.method,
+                url: req.url,
+                startedAt,
+                durationMs,
+                errorKind: normalized.kind,
+                ...(retryCount !== undefined ? { retryCount } : {}),
+                ...(policyTrace !== undefined ? { policyTrace } : {}),
+            });
+            const latest = events[events.length - 1];
+            if (latest) {
+                options.onEvent?.(latest);
+            }
+            if (events.length > maxEvents) {
+                events.splice(0, events.length - maxEvents);
+            }
+            throw error;
+        }
+    };
+    const snapshot = () => {
+        return {
+            total,
+            success,
+            failed,
+            p50: percentile(durations, 50),
+            p95: percentile(durations, 95),
+            recentEvents: [...events],
+        };
+    };
+    const reset = () => {
+        total = 0;
+        success = 0;
+        failed = 0;
+        durations.length = 0;
+        events.length = 0;
+    };
+    return {
+        middleware,
+        snapshot,
+        reset,
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/src/middleware/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/middleware/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/src/middleware/diagnosticsExporters.d.ts

@@ -0,0 +1,27 @@
+import type { DiagnosticEvent } from "./diagnostics";
+export interface DiagnosticsExporter {
+    readonly export: (event: DiagnosticEvent) => void;
+}
+export interface OpenTelemetryLikeMeter {
+    readonly createCounter: (name: string, options?: {
+        description?: string;
+    }) => {
+        add: (value: number, attributes?: Record<string, string | number | boolean>) => void;
+    };
+    readonly createHistogram: (name: string, options?: {
+        description?: string;
+        unit?: string;
+    }) => {
+        record: (value: number, attributes?: Record<string, string | number | boolean>) => void;
+    };
+}
+/**
+ * Console-based diagnostics exporter for development/debugging.
+ *
+ * WARNING: This exporter logs full URLs which may contain sensitive query
+ * parameters. Use `redactUrlQueryParams()` to sanitize event URLs before
+ * passing them to production logging exporters.
+ */
+export declare function createConsoleDiagnosticsExporter(logger?: Pick<Console, "log">): DiagnosticsExporter;
+export declare function createOpenTelemetryDiagnosticsExporter(meter: OpenTelemetryLikeMeter): DiagnosticsExporter;
+//# sourceMappingURL=diagnosticsExporters.d.ts.map

package/dist/src/middleware/diagnosticsExporters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnosticsExporters.d.ts","sourceRoot":"","sources":["../../../src/middleware/diagnosticsExporters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,aAAa,EAAE,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAC/B;QAAE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,CAAA;KAAE,CAAC;IAC9F,QAAQ,CAAC,eAAe,EAAE,CACxB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9C;QAAE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,CAAA;KAAE,CAAC;CAClG;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,GAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAW,GACrC,mBAAmB,CAQrB;AAED,wBAAgB,sCAAsC,CACpD,KAAK,EAAE,sBAAsB,GAC5B,mBAAmB,CAgCrB"}

package/dist/src/middleware/diagnosticsExporters.js

@@ -0,0 +1,45 @@
+/**
+ * Console-based diagnostics exporter for development/debugging.
+ *
+ * WARNING: This exporter logs full URLs which may contain sensitive query
+ * parameters. Use `redactUrlQueryParams()` to sanitize event URLs before
+ * passing them to production logging exporters.
+ */
+export function createConsoleDiagnosticsExporter(logger = console) {
+    return {
+        export(event) {
+            logger.log(`[pureq] phase=${event.phase} ${event.method} ${event.url} duration=${event.durationMs}ms status=${event.status ?? "n/a"} errorKind=${event.errorKind ?? "none"} policyTrace=${event.policyTrace?.length ?? 0}`);
+        },
+    };
+}
+export function createOpenTelemetryDiagnosticsExporter(meter) {
+    const counter = meter.createCounter("pureq.requests.total", {
+        description: "Total pureq requests observed by diagnostics",
+    });
+    const histogram = meter.createHistogram("pureq.request.duration", {
+        description: "pureq request duration",
+        unit: "ms",
+    });
+    return {
+        export(event) {
+            const attributes = {
+                phase: event.phase,
+                method: event.method,
+                url: event.url,
+                success: event.phase === "success",
+            };
+            if (event.status !== undefined) {
+                attributes.status = event.status;
+            }
+            if (event.errorKind !== undefined) {
+                attributes.errorKind = event.errorKind;
+            }
+            if (event.policyTrace !== undefined) {
+                attributes.policyTraceCount = event.policyTrace.length;
+            }
+            counter.add(1, attributes);
+            histogram.record(event.durationMs, attributes);
+        },
+    };
+}
+//# sourceMappingURL=diagnosticsExporters.js.map

package/dist/src/middleware/diagnosticsExporters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnosticsExporters.js","sourceRoot":"","sources":["../../../src/middleware/diagnosticsExporters.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAC9C,SAA+B,OAAO;IAEtC,OAAO;QACL,MAAM,CAAC,KAAK;YACV,MAAM,CAAC,GAAG,CACR,iBAAiB,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,aAAa,KAAK,CAAC,UAAU,aAAa,KAAK,CAAC,MAAM,IAAI,KAAK,cAAc,KAAK,CAAC,SAAS,IAAI,MAAM,gBAAgB,KAAK,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,EAAE,CAChN,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sCAAsC,CACpD,KAA6B;IAE7B,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAAC,sBAAsB,EAAE;QAC1D,WAAW,EAAE,8CAA8C;KAC5D,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,KAAK,CAAC,eAAe,CAAC,wBAAwB,EAAE;QAChE,WAAW,EAAE,wBAAwB;QACrC,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IAEH,OAAO;QACL,MAAM,CAAC,KAAK;YACV,MAAM,UAAU,GAA8C;gBAC5D,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,OAAO,EAAE,KAAK,CAAC,KAAK,KAAK,SAAS;aACnC,CAAC;YAEF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC/B,UAAU,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACnC,CAAC;YACD,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBAClC,UAAU,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;YACzC,CAAC;YACD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;gBACpC,UAAU,CAAC,gBAAgB,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC;YACzD,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;YAC3B,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QACjD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/middleware/hedge.d.ts

@@ -0,0 +1,17 @@
+import type { Middleware, RequestConfig } from "../types/http";
+export interface HedgeOptions {
+    readonly hedgeAfterMs: number;
+    readonly methods?: readonly RequestConfig["method"][];
+    readonly keyBuilder?: (req: Readonly<RequestConfig>) => string;
+    readonly maxParallel?: number;
+}
+/**
+ * Sends a duplicate request after a short delay and returns the first successful response.
+ *
+ * NOTE: The current implementation always launches exactly 2 requests
+ * (1 primary + 1 hedge). The maxParallel option controls whether hedging
+ * is enabled (>= 2) or disabled (< 2). Values above 2 are accepted but
+ * behave identically to 2.
+ */
+export declare function hedge(options: HedgeOptions): Middleware;
+//# sourceMappingURL=hedge.d.ts.map

package/dist/src/middleware/hedge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hedge.d.ts","sourceRoot":"","sources":["../../../src/middleware/hedge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAI/D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,aAAa,CAAC,KAAK,MAAM,CAAC;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA4BD;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,UAAU,CAsGvD"}

package/dist/src/middleware/hedge.js

@@ -0,0 +1,125 @@
+import { appendPolicyTrace, deepCopyMeta } from "../utils/policyTrace";
+/**
+ * Creates a forked AbortSignal that mirrors the parent signal
+ * but can be independently aborted when the race is decided.
+ */
+function forkSignal(signal) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+    if (signal) {
+        if (signal.aborted) {
+            onAbort();
+        }
+        else {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            if (signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}
+/**
+ * Sends a duplicate request after a short delay and returns the first successful response.
+ *
+ * NOTE: The current implementation always launches exactly 2 requests
+ * (1 primary + 1 hedge). The maxParallel option controls whether hedging
+ * is enabled (>= 2) or disabled (< 2). Values above 2 are accepted but
+ * behave identically to 2.
+ */
+export function hedge(options) {
+    if (!Number.isFinite(options.hedgeAfterMs) || options.hedgeAfterMs < 0) {
+        throw new Error("pureq: hedge requires a non-negative hedgeAfterMs");
+    }
+    const methods = new Set(options.methods ?? ["GET"]);
+    const keyBuilder = options.keyBuilder ?? ((req) => `${req.method}:${req.url}`);
+    const maxParallel = Math.max(1, options.maxParallel ?? 2);
+    return async (req, next) => {
+        if (!methods.has(req.method) || maxParallel < 2) {
+            return next(req);
+        }
+        const key = keyBuilder(req);
+        const startedAt = Date.now();
+        // Each fork gets its own deep-copied _meta to prevent
+        // cross-fork trace pollution (race condition prevention).
+        const primaryFork = forkSignal(req.signal);
+        const primaryReq = {
+            ...req,
+            signal: primaryFork.signal,
+            _meta: deepCopyMeta(req),
+        };
+        const primaryPromise = next(primaryReq);
+        // Track how many promises are actually in flight for the rejection threshold.
+        let totalPromises = 1;
+        let hedgeResolve;
+        let hedgeReject;
+        const hedgePromise = new Promise((resolve, reject) => {
+            hedgeResolve = resolve;
+            hedgeReject = reject;
+        });
+        let hedgeFork;
+        const timer = setTimeout(() => {
+            hedgeFork = forkSignal(req.signal);
+            const hedgedReq = {
+                ...req,
+                signal: hedgeFork.signal,
+                _meta: deepCopyMeta(req),
+            };
+            appendPolicyTrace(hedgedReq, {
+                policy: "hedge",
+                decision: "launch",
+                at: Date.now(),
+                reason: "hedge timer elapsed",
+                key,
+            });
+            totalPromises = 2;
+            next(hedgedReq).then(hedgeResolve, hedgeReject);
+        }, options.hedgeAfterMs);
+        const finish = async (winner) => {
+            clearTimeout(timer);
+            primaryFork.cleanup();
+            hedgeFork?.cleanup();
+            appendPolicyTrace(req, {
+                policy: "hedge",
+                decision: "success",
+                at: Date.now(),
+                reason: "first response won the race",
+                key,
+                ageMs: Date.now() - startedAt,
+            });
+            return winner;
+        };
+        try {
+            return await new Promise((resolve, reject) => {
+                const errors = [];
+                let rejectedCount = 0;
+                const onFulfill = (response) => {
+                    finish(response).then(resolve, reject);
+                };
+                const onReject = (error) => {
+                    errors.push(error);
+                    rejectedCount += 1;
+                    // Use actual number of in-flight promises instead of a hardcoded value
+                    if (rejectedCount >= totalPromises) {
+                        const aggregate = new Error("pureq: hedged requests failed");
+                        aggregate.causes = errors;
+                        reject(aggregate);
+                    }
+                };
+                primaryPromise.then(onFulfill, onReject);
+                hedgePromise.then(onFulfill, onReject);
+            });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            primaryFork.cleanup();
+            hedgeFork?.cleanup();
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=hedge.js.map

package/dist/src/middleware/hedge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hedge.js","sourceRoot":"","sources":["../../../src/middleware/hedge.ts"],"names":[],"mappings":"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"}

package/dist/src/middleware/httpCache.d.ts

@@ -0,0 +1,14 @@
+import type { Middleware, RequestConfig } from "../types/http";
+export interface HttpCacheOptions {
+    readonly ttlMs: number;
+    readonly staleIfErrorMs?: number;
+    readonly methods?: readonly RequestConfig["method"][];
+    readonly keyBuilder?: (req: Readonly<RequestConfig>) => string;
+    /** Maximum number of cached entries. Oldest entries are evicted first (LRU). */
+    readonly maxEntries?: number;
+}
+/**
+ * Basic HTTP cache with ETag revalidation and stale-if-error fallback.
+ */
+export declare function httpCache(options: HttpCacheOptions): Middleware;
+//# sourceMappingURL=httpCache.d.ts.map

package/dist/src/middleware/httpCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpCache.d.ts","sourceRoot":"","sources":["../../../src/middleware/httpCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAM/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,aAAa,CAAC,KAAK,MAAM,CAAC;IAC/D,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAiBD;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CA8H/D"}

package/dist/src/middleware/httpCache.js

@@ -0,0 +1,126 @@
+import { resolveStalePolicy } from "./stalePolicy";
+import { stableKeyValues, stableQuery } from "../utils/stableKey";
+import { appendPolicyTrace } from "../utils/policyTrace";
+// stableKeyValues and stableQuery are imported from ../utils/stableKey
+function defaultKeyBuilder(req) {
+    return [req.method, req.url, stableKeyValues(req.params), stableQuery(req.query)].join("|");
+}
+// appendPolicyTrace is imported from ../utils/policyTrace
+/**
+ * Basic HTTP cache with ETag revalidation and stale-if-error fallback.
+ */
+export function httpCache(options) {
+    if (!Number.isFinite(options.ttlMs) || options.ttlMs <= 0) {
+        throw new Error("pureq: httpCache requires a positive ttlMs");
+    }
+    const methods = new Set(options.methods ?? ["GET"]);
+    const cache = new Map();
+    const staleIfErrorMs = options.staleIfErrorMs ?? 0;
+    const keyBuilder = options.keyBuilder ?? defaultKeyBuilder;
+    const maxEntries = options.maxEntries ?? Infinity;
+    return async (req, next) => {
+        if (!methods.has(req.method)) {
+            return next(req);
+        }
+        const key = keyBuilder(req);
+        const cached = cache.get(key);
+        const now = Date.now();
+        if (cached) {
+            const policy = resolveStalePolicy({
+                storedAt: cached.storedAt,
+                now,
+                ttlMs: options.ttlMs,
+                staleIfErrorMs,
+            });
+            if (policy.isFresh) {
+                appendPolicyTrace(req, {
+                    policy: "cache",
+                    decision: "hit",
+                    at: now,
+                    reason: "fresh cache entry",
+                    key,
+                    ageMs: policy.ageMs,
+                    ttlMs: options.ttlMs,
+                });
+                return cached.response.clone();
+            }
+        }
+        const headers = { ...(req.headers ?? {}) };
+        if (cached?.etag && !headers["If-None-Match"]) {
+            headers["If-None-Match"] = cached.etag;
+        }
+        if (cached?.lastModified && !headers["If-Modified-Since"]) {
+            headers["If-Modified-Since"] = cached.lastModified;
+        }
+        try {
+            const response = await next({
+                ...req,
+                headers,
+            });
+            if (cached && response.status === 304) {
+                appendPolicyTrace(req, {
+                    policy: "cache",
+                    decision: "revalidate",
+                    at: Date.now(),
+                    reason: "etag matched",
+                    key,
+                });
+                cache.set(key, {
+                    ...cached,
+                    storedAt: Date.now(),
+                });
+                return cached.response.clone();
+            }
+            if (response.ok) {
+                const etag = response.headers.get("etag") ?? undefined;
+                const lastModified = response.headers.get("last-modified") ?? undefined;
+                // Evict oldest entry if cache exceeds maxEntries (LRU)
+                if (cache.size >= maxEntries && !cache.has(key)) {
+                    const oldestKey = cache.keys().next().value;
+                    if (oldestKey !== undefined) {
+                        cache.delete(oldestKey);
+                    }
+                }
+                cache.set(key, {
+                    response: response.clone(),
+                    storedAt: Date.now(),
+                    ...(etag !== undefined ? { etag } : {}),
+                    ...(lastModified !== undefined ? { lastModified } : {}),
+                });
+                appendPolicyTrace(req, {
+                    policy: "cache",
+                    decision: "store",
+                    at: Date.now(),
+                    reason: "cached successful response",
+                    key,
+                    ttlMs: options.ttlMs,
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            if (cached) {
+                const policy = resolveStalePolicy({
+                    storedAt: cached.storedAt,
+                    now: Date.now(),
+                    ttlMs: options.ttlMs,
+                    staleIfErrorMs,
+                });
+                if (policy.canServeStaleOnError) {
+                    appendPolicyTrace(req, {
+                        policy: "cache",
+                        decision: "stale-if-error",
+                        at: Date.now(),
+                        reason: "upstream request failed",
+                        key,
+                        ageMs: policy.ageMs,
+                        ttlMs: options.ttlMs,
+                    });
+                    return cached.response.clone();
+                }
+            }
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=httpCache.js.map