@http-client-toolkit/core 0.0.1 → 0.2.0

package/lib/index.d.ts

@@ -1,5 +1,158 @@
 import { z } from 'zod';
 
+interface CacheControlDirectives {
+    maxAge?: number;
+    sMaxAge?: number;
+    noCache: boolean;
+    noStore: boolean;
+    mustRevalidate: boolean;
+    proxyRevalidate: boolean;
+    public: boolean;
+    private: boolean;
+    immutable: boolean;
+    staleWhileRevalidate?: number;
+    staleIfError?: number;
+}
+/**
+ * Parse a Cache-Control header value into structured directives.
+ *
+ * Lenient: unrecognised directives are silently ignored, malformed
+ * numeric values result in undefined (treated as absent).
+ */
+declare function parseCacheControl(header: string | null | undefined): CacheControlDirectives;
+
+interface CacheEntryMetadata {
+    /** ETag response header, for If-None-Match conditional requests */
+    etag?: string;
+    /** Last-Modified response header, for If-Modified-Since conditional requests */
+    lastModified?: string;
+    /** Parsed Cache-Control directives */
+    cacheControl: CacheControlDirectives;
+    /**
+     * Date response header as epoch ms.
+     * Falls back to storedAt if the server didn't send Date.
+     */
+    responseDate: number;
+    /** Epoch ms when this entry was written to the cache */
+    storedAt: number;
+    /** Value of the Age response header at receipt time (seconds) */
+    ageHeader: number;
+    /** Raw Vary header value (e.g. "Accept, Accept-Encoding") */
+    varyHeaders?: string;
+    /** Captured request header values for Vary matching */
+    varyValues?: Record<string, string | undefined>;
+    /** HTTP status code of the original response */
+    statusCode: number;
+    /**
+     * Expires header as epoch ms. Used as freshness fallback
+     * when Cache-Control max-age is absent.
+     */
+    expires?: number;
+}
+interface CacheEntry<T = unknown> {
+    /** Discriminant field for the isCacheEntry type guard */
+    __cacheEntry: true;
+    /** The actual response value the caller requested */
+    value: T;
+    /** RFC 9111 metadata for freshness/revalidation decisions */
+    metadata: CacheEntryMetadata;
+}
+/**
+ * Type guard: distinguishes a CacheEntry envelope from a raw cached value.
+ *
+ * When respectCacheHeaders is enabled on a cache that previously stored raw
+ * values, those old entries will fail this check and be treated as cache misses.
+ */
+declare function isCacheEntry<T>(value: unknown): value is CacheEntry<T>;
+/**
+ * Parse an HTTP-date string (RFC 7231) into epoch ms.
+ * Returns undefined if the value is missing or unparseable.
+ *
+ * Handles:
+ * - IMF-fixdate: "Sun, 06 Nov 1994 08:49:37 GMT"
+ * - RFC 850: "Sunday, 06-Nov-94 08:49:37 GMT"
+ * - asctime: "Sun Nov  6 08:49:37 1994"
+ * - "0" (treated as already-expired per Expires spec)
+ */
+declare function parseHttpDate(value: string | null | undefined): number | undefined;
+/**
+ * Create a CacheEntry from a response value and the HTTP response headers.
+ *
+ * Call this after response body parsing + transformation + validation,
+ * right before storing in the cache.
+ */
+declare function createCacheEntry<T>(value: T, headers: Headers, statusCode: number): CacheEntry<T>;
+/**
+ * Refresh a cache entry after receiving a 304 Not Modified response.
+ *
+ * Updates metadata from the 304 response headers while keeping the
+ * existing cached value (body). Per RFC 9111 §4.3.4, the 304 response
+ * headers replace the stored headers.
+ */
+declare function refreshCacheEntry<T>(existing: CacheEntry<T>, newHeaders: Headers): CacheEntry<T>;
+
+type FreshnessStatus = 'fresh' | 'stale' | 'must-revalidate' | 'stale-while-revalidate' | 'stale-if-error' | 'no-cache';
+/**
+ * Calculate the freshness lifetime of a cache entry in seconds.
+ *
+ * Priority order for a private cache (RFC 9111 §4.2.2):
+ *   1. max-age (s-maxage is ignored — shared-cache-only)
+ *   2. Expires − Date
+ *   3. Heuristic: 10% of (Date − Last-Modified)
+ *   4. 0 (treat as immediately stale)
+ */
+declare function calculateFreshnessLifetime(metadata: CacheEntryMetadata): number;
+/**
+ * Calculate the current age of a cache entry in seconds.
+ *
+ * Per RFC 9111 §4.2.3:
+ *   apparent_age        = max(0, response_time − date_value)
+ *   corrected_age_value = age_value + response_delay
+ *   corrected_initial   = max(apparent_age, corrected_age_value)
+ *   resident_time       = now − response_time
+ *   current_age         = corrected_initial + resident_time
+ *
+ * We approximate response_delay as 0 since we don't track request_time.
+ * This is conservative (slightly underestimates age).
+ */
+declare function calculateCurrentAge(metadata: CacheEntryMetadata, now?: number): number;
+/**
+ * Determine the freshness status of a cache entry.
+ *
+ * Returns the most specific applicable status, used by HttpClient
+ * to decide whether to serve from cache, revalidate, or re-fetch.
+ */
+declare function getFreshnessStatus(metadata: CacheEntryMetadata, now?: number): FreshnessStatus;
+/**
+ * Calculate the TTL to pass to CacheStore.set().
+ *
+ * This must be long enough to cover the freshness lifetime PLUS any
+ * stale-serving windows (SWR, SIE), so the entry remains available
+ * in the store during those windows.
+ *
+ * Falls back to defaultTTL when no cache headers provide a lifetime.
+ */
+declare function calculateStoreTTL(metadata: CacheEntryMetadata, defaultTTL: number): number;
+
+/**
+ * Parse a Vary header value into normalised (lowercased) header names.
+ * Returns ['*'] for Vary: * (meaning the response varies on everything).
+ */
+declare function parseVaryHeader(varyHeader: string | null | undefined): Array<string>;
+/**
+ * Extract the values of Vary-listed headers from a request.
+ * Stored alongside the cache entry so we can compare on lookup.
+ */
+declare function captureVaryValues(varyFields: Array<string>, requestHeaders: Record<string, string | undefined>): Record<string, string | undefined>;
+/**
+ * Check whether a cached entry's Vary values match the current request.
+ *
+ * Returns false if:
+ *  - Vary includes '*' (never matches — always revalidate)
+ *  - Any Vary-listed header has a different value in the current request
+ */
+declare function varyMatches(cachedVaryValues: Record<string, string | undefined> | undefined, cachedVaryHeader: string | undefined, currentRequestHeaders: Record<string, string | undefined>): boolean;
+
 /**
  * Interface for caching API responses with TTL support
  */
@@ -140,6 +293,12 @@ type AdaptiveConfig = z.infer<typeof AdaptiveConfigSchema>;
  * Interface for rate limiting API requests per resource
  */
 interface RateLimitStore {
+    /**
+     * Atomically acquire capacity for a request if the implementation supports it.
+     * When present and returning true, callers should treat the request as already
+     * recorded for rate-limit accounting.
+     */
+    acquire?(resource: string): Promise<boolean>;
     /**
      * Check if a request to a resource can proceed based on rate limits
      * @param resource The resource name (e.g., 'issues', 'characters')
@@ -177,6 +336,10 @@ interface RateLimitStore {
  * Enhanced interface for adaptive rate limiting stores with priority support
  */
 interface AdaptiveRateLimitStore extends RateLimitStore {
+    /**
+     * Atomically acquire capacity for a request if the implementation supports it.
+     */
+    acquire?(resource: string, priority?: RequestPriority): Promise<boolean>;
     /**
      * Check if a request to a resource can proceed based on rate limits
      * @param resource The resource name (e.g., 'issues', 'characters')
@@ -333,11 +496,31 @@ interface HttpClientOptions {
         reset?: Array<string>;
         combined?: Array<string>;
     };
+    /**
+     * When true, the client respects HTTP cache headers (Cache-Control, ETag,
+     * Last-Modified, Expires) per RFC 9111. When false (default), caching uses
+     * only the static defaultCacheTTL.
+     */
+    respectCacheHeaders?: boolean;
+    /**
+     * Override specific cache header behaviors. Only applies when
+     * respectCacheHeaders is true.
+     */
+    cacheHeaderOverrides?: {
+        /** Cache responses even when Cache-Control: no-store is set */
+        ignoreNoStore?: boolean;
+        /** Skip revalidation even when Cache-Control: no-cache is set */
+        ignoreNoCache?: boolean;
+        /** Minimum TTL in seconds — floor on header-derived freshness */
+        minimumTTL?: number;
+        /** Maximum TTL in seconds — cap on header-derived freshness */
+        maximumTTL?: number;
+    };
 }
 declare class HttpClient implements HttpClientContract {
-    private _http;
     private stores;
     private serverCooldowns;
+    private pendingRevalidations;
     private options;
     constructor(stores?: HttpClientStores, options?: HttpClientOptions);
     private normalizeRateLimitHeaders;
@@ -363,7 +546,16 @@ declare class HttpClient implements HttpClientContract {
     private applyServerRateLimitHints;
     private enforceServerCooldown;
     private enforceStoreRateLimit;
+    /**
+     * Wait for all pending background revalidations to complete.
+     * Primarily useful in tests to avoid dangling promises.
+     */
+    flushRevalidations(): Promise<void>;
+    private backgroundRevalidate;
+    private clampTTL;
+    private isServerErrorOrNetworkFailure;
     private generateClientError;
+    private parseResponseBody;
     get<Result>(url: string, options?: {
         signal?: AbortSignal;
         priority?: RequestPriority;
@@ -379,4 +571,4 @@ declare class HttpClientError extends Error {
     constructor(message: string, statusCode?: number);
 }
 
-export { type ActivityMetrics, AdaptiveCapacityCalculator, type AdaptiveConfig, AdaptiveConfigSchema, type AdaptiveRateLimitStore, type CacheStore, DEFAULT_RATE_LIMIT, type DedupeStore, type DynamicCapacityResult, HttpClient, type HttpClientContract, HttpClientError, type HttpClientOptions, type HttpClientStores, type RateLimitConfig, type RateLimitStore, type RequestPriority, hashRequest };
+export { type ActivityMetrics, AdaptiveCapacityCalculator, type AdaptiveConfig, AdaptiveConfigSchema, type AdaptiveRateLimitStore, type CacheControlDirectives, type CacheEntry, type CacheEntryMetadata, type CacheStore, DEFAULT_RATE_LIMIT, type DedupeStore, type DynamicCapacityResult, type FreshnessStatus, HttpClient, type HttpClientContract, HttpClientError, type HttpClientOptions, type HttpClientStores, type RateLimitConfig, type RateLimitStore, type RequestPriority, calculateCurrentAge, calculateFreshnessLifetime, calculateStoreTTL, captureVaryValues, createCacheEntry, getFreshnessStatus, hashRequest, isCacheEntry, parseCacheControl, parseHttpDate, parseVaryHeader, refreshCacheEntry, varyMatches };