nlcurl 0.7.0 → 0.9.0

package/README.md

@@ -1,31 +1,40 @@
 # NLcURL
 
-Pure TypeScript HTTP client with browser fingerprint impersonation.
-
-NLcURL provides session-based and one-shot HTTP APIs, browser profile impersonation, HTTP/2 support, cookie management, and a CLI. The project has zero runtime dependencies and uses only Node.js built-in modules.
-
-## Highlights
-
-- Zero runtime dependencies
-- Session API with connection pooling
-- HTTP/1.1 and HTTP/2 (ALPN negotiated) with RFC 9113 flow control
-- Browser profile impersonation (Chrome, Firefox, Safari, Edge, Tor)
-- Optional custom JA3 and Akamai H2 fingerprint values in request model
-- Cookie jar with RFC 6265 behavior, Public Suffix List enforcement, `SameSite=Lax` default, and `__Host-`/`__Secure-` prefix validation
-- `FormData` class for `multipart/form-data` uploads (RFC 7578)
-- mTLS and custom CA trust via `TLSOptions` (`cert`, `key`, `pfx`, `ca`, `passphrase`)
-- `ReadableStream<Uint8Array>` upload bodies (auto-drained before encoding)
-- Header validation per RFC 7230 (rejects CR/LF/NUL injection)
-- Streaming response support (`stream: true`) with automatic decompression
-- Automatic dual-stack connectivity via Happy Eyeballs (RFC 8305) — falls back to IPv4 instantly when IPv6 is unreachable, with optional `dnsFamily` pin
-- Automatic retry on H2 RST_STREAM protocol errors (codes 1, 2, 7, 8, 11, 13) with capped exponential backoff
-- CLI (`nlcurl`) for scripted and interactive use
-- WebSocket client with optional impersonated TLS handshake
-
-## Requirements
-
-- Node.js `>= 18.17.0`
-- npm (or compatible package manager)
+A pure TypeScript HTTP client with native TLS fingerprint impersonation. Zero runtime dependencies.
+
+NLcURL provides HTTP/1.1 and HTTP/2 request capabilities with a custom stealth TLS engine that reproduces browser-grade TLS and HTTP/2 fingerprints. It is designed for environments where accurate browser impersonation, advanced protocol control, and strict standards compliance are required.
+
+> **Note:** HTTP/3 (QUIC) is not supported. NLcURL supports HTTP/1.1 and HTTP/2 only.
+
+## Features
+
+- **TLS Fingerprint Impersonation** — Reproduce the exact TLS ClientHello of Chrome, Firefox, Safari, Edge, and Tor across 49 resolvable browser profiles, covering JA3, JA4, and Akamai HTTP/2 fingerprints.
+- **Custom Stealth TLS Engine** — A from-scratch TLS 1.2/1.3 implementation with GREASE injection (RFC 8701), configurable cipher suites, extension ordering, Encrypted Client Hello (ECH) support, HelloRetryRequest handling, KeyUpdate post-handshake rekeying, and session resumption via PSK.
+- **HTTP/1.1 & HTTP/2** — Full HTTP/1.1 with chunked transfer encoding, obs-fold header handling, and TE/CL conflict detection. HTTP/2 with HPACK compression, stream multiplexing, configurable flow control, MAX_CONCURRENT_STREAMS enforcement, PUSH_PROMISE rejection, and CONTINUATION size limits.
+- **Connection Pooling** — Per-origin connection reuse with idle eviction, configurable pool limits, and automatic HTTP/2 multiplexing.
+- **RFC 6265 Cookie Jar** — Persistent cookie storage with Public Suffix List validation, `__Host-`/`__Secure-` prefix enforcement, `SameSite` enforcement (Strict/Lax/None with Secure requirement per RFC 6265bis), CHIPS partitioned cookies, and Netscape file format import/export.
+- **HTTP Caching (RFC 9111)** — In-memory cache with multi-variant `Vary` support, `s-maxage`/`max-age` freshness, `ETag`/`Last-Modified` conditional revalidation, `Age` header, request-side `Cache-Control`, unsafe method invalidation, `stale-while-revalidate`, heuristic freshness, and five cache modes.
+- **HSTS (RFC 6797)** — Automatic `http://` to `https://` upgrading with `includeSubDomains` support and configurable preload lists.
+- **DNS-over-HTTPS (RFC 8484)** — Wire-format DoH with GET/POST methods, EDNS(0) with padding (RFC 6891/7830), bootstrap resolution, and integrated DNS caching.
+- **DNS-over-TLS (RFC 7858)** — Secure DNS resolution over TLS port 853 with persistent connection support and pre-configured public resolvers.
+- **HTTPS Resource Records (RFC 9460)** — SVCB/HTTPS DNS record resolution for ALPN hints, ECH config delivery, and address hints.
+- **Proxy Support** — HTTP CONNECT tunneling, HTTPS proxies, SOCKS4/4a, and SOCKS5 with optional username/password authentication. Environment variable resolution (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`).
+- **WebSocket (RFC 6455)** — Full WebSocket client with TLS fingerprinting, per-message deflate compression (RFC 7692), control frame validation (≤125 bytes), ping/pong, and binary/text framing.
+- **Server-Sent Events** — W3C EventSource-compliant SSE parser with streaming async generator interface, UTF-8 BOM stripping, and cross-chunk CRLF handling.
+- **Request/Response Interceptors** — Middleware pipeline for modifying requests before send and responses after receipt.
+- **Retry with Backoff** — Configurable automatic retry with linear or exponential backoff, jitter, `Retry-After` header respect, and custom retry predicates.
+- **Rate Limiting** — Token-bucket rate limiter with configurable request quotas and automatic queuing.
+- **Circuit Breaker** — Per-origin circuit breaker with configurable failure thresholds, half-open probing, and automatic recovery.
+- **Request Body Compression** — Outgoing body compression with gzip, deflate, and Brotli.
+- **Response Decompression** — Automatic decompression of gzip, deflate, Brotli, and zstd (Node.js 20.10+) with multi-layer encoding support.
+- **Happy Eyeballs v2 (RFC 8305)** — Dual-stack connection racing with 250ms stagger for optimal latency.
+- **Alt-Svc (RFC 7838)** — HTTP Alternative Services tracking with automatic protocol upgrade preference.
+- **FormData (RFC 7578)** — Multipart form-data encoding with file upload support.
+- **Authentication** — Built-in Basic, Bearer, Digest (RFC 7616), and AWS Signature V4 authentication, plus Digest proxy authentication.
+- **Progress Callbacks** — Upload and download progress events with byte counts and percentages.
+- **Structured Logging** — Console and JSON logger implementations with child logger support and configurable log levels.
+- **CLI Tool** — `nlcurl` command-line interface with curl-compatible flags for scripting and interactive use.
+- **Zero Dependencies** — Pure TypeScript with no runtime dependencies. Requires only Node.js ≥ 18.17.0.
 
 ## Installation
 
@@ -33,155 +42,155 @@ NLcURL provides session-based and one-shot HTTP APIs, browser profile impersonat
 npm install nlcurl
 ```
 
-For local development:
-
-```bash
-npm install
-npm run build
-```
+**Requirements:** Node.js ≥ 18.17.0
 
 ## Quick Start
 
-### One-shot request
+### One-Shot Requests
 
-```ts
-import { request } from "nlcurl";
+```typescript
+import { get, post } from "nlcurl";
 
-const response = await request({
-  url: "https://httpbin.org/get",
-  impersonate: "chrome136",
-});
+// Simple GET
+const response = await get("https://httpbin.org/get");
+console.log(response.status);      // 200
+console.log(response.json());      // parsed JSON body
 
-console.log(response.status);
-console.log(response.json());
+// POST with JSON body
+const res = await post("https://httpbin.org/post", { key: "value" });
+console.log(res.text());
 ```
 
-### Multipart form upload
-
-```ts
-import { post, FormData } from "nlcurl";
-
-const form = new FormData();
-form.append("username", "alice");
-form.append("avatar", { data: Buffer.from("..."), filename: "avatar.png", contentType: "image/png" });
-
-const res = await post("https://httpbin.org/post", form);
-console.log(res.json());
-```
+### Browser Impersonation
 
-### mTLS / custom CA
+```typescript
+import { get } from "nlcurl";
 
-```ts
-import { request } from "nlcurl";
-
-const res = await request({
-  url: "https://internal-api.example.com/data",
-  tls: {
-    cert: fs.readFileSync("client.pem"),
-    key: fs.readFileSync("client-key.pem"),
-    ca: fs.readFileSync("ca.pem"),
-  },
+const response = await get("https://example.com", {
+  impersonate: "chrome136",
 });
 ```
 
-### Session-based usage
+### Session with Connection Reuse
 
-```ts
+```typescript
 import { createSession } from "nlcurl";
 
 const session = createSession({
-  baseURL: "https://httpbin.org",
-  impersonate: "firefox138",
-  followRedirects: true,
+  baseURL: "https://api.example.com",
+  impersonate: "chrome136",
+  headers: { "authorization": "Bearer token" },
+  retry: { count: 3, backoff: "exponential" },
 });
 
-const res = await session.get("/headers");
-console.log(res.json());
+const users = await session.get("/users");
+const user = await session.post("/users", { name: "Alice" });
 
 session.close();
 ```
 
-### CLI usage
+### Stealth TLS
 
-```bash
-nlcurl --impersonate chrome136 https://tls.browserleaks.com/json
+```typescript
+import { get } from "nlcurl";
+
+// Uses the custom stealth TLS engine (bypasses Node.js TLS)
+const response = await get("https://example.com", {
+  stealth: true,
+  impersonate: "chrome136",
+});
 ```
 
-## CLI Reference
+### WebSocket
 
-```text
-nlcurl [OPTIONS] <URL>
+```typescript
+import { WebSocketClient } from "nlcurl";
+
+const ws = new WebSocketClient("wss://echo.websocket.events", {
+  impersonate: "chrome136",
+  compress: true,
+});
+
+ws.on("open", () => ws.sendText("Hello"));
+ws.on("message", (data) => console.log(data));
+ws.on("close", (code, reason) => console.log("Closed:", code));
 ```
 
-Key options:
-
-- `-X, --request <METHOD>` HTTP method
-- `-H, --header <Name: Value>` add request header
-- `-d, --data <DATA>` request body
-- `--data-raw <DATA>` raw request body
-- `-A, --user-agent <AGENT>` custom User-Agent
-- `-o, --output <FILE>` write response body to file
-- `-I, --head` send HEAD request
-- `-i, --include` include response headers
-- `-v, --verbose` verbose request/response output
-- `-s, --silent` suppress error output
-- `--compressed` request compressed response
-- `--impersonate <PROFILE>` browser profile
-- `--stealth` use stealth TLS engine
-- `--ja3 <FINGERPRINT>` custom JA3 fingerprint string
-- `--akamai <FINGERPRINT>` custom Akamai HTTP/2 fingerprint string
-- `--list-profiles` list available profiles
-- `-x, --proxy <URL>` proxy URL (request model supports it)
-- `-U, --proxy-user <USER:PASS>` proxy auth pair
-- `-k, --insecure` disable TLS verification
-- `-L, --location` follow redirects (default behavior)
-- `--no-location` disable redirect following
-- `--max-redirs <NUM>` max redirects (default `20`)
-- `-m, --max-time <SECONDS>` total timeout
-- `--http1.1` force HTTP/1.1
-- `--http2` force HTTP/2
-- `-b, --cookie <DATA>` send cookie header
-- `-c, --cookie-jar <FILE>` capture cookie jar target file
-- `-h, --help` show help
-- `-V, --version` show version
-
-For examples, see `docs/SETUP.md` and `docs/API.md`.
-
-## Supported Browser Families
-
-- Chrome (`chrome99` through `chrome136`, plus `chrome_latest` and `chrome` alias)
-- Firefox (`firefox133` through `firefox138`, plus `firefox_latest` and `firefox` alias)
-- Safari (`safari153` through `safari182`, plus `safari_latest` and `safari` alias)
-- Edge (`edge99`, `edge101`, `edge126`, `edge131`, `edge136`, `edge_latest`, `edge` alias)
-- Tor (`tor133`, `tor140`, `tor145`, `tor_latest`, `tor` alias)
-
-Run `nlcurl --list-profiles` to view the exact runtime list.
-
-## Development
+### CLI
 
 ```bash
-npm install
-npm run lint
-npm run test
-npm run test:integration
-npm run build
-```
+# Simple GET
+nlcurl https://httpbin.org/get
 
-Additional commands:
+# Impersonate Chrome with verbose output
+nlcurl -v --impersonate chrome136 https://example.com
 
-- `npm run clean` remove `dist`
-- `npm run test:all` run all tests
+# POST with data
+nlcurl -X POST -d '{"key":"value"}' -H "Content-Type: application/json" https://httpbin.org/post
 
-## Documentation Index
+# Through a proxy
+nlcurl -x socks5://127.0.0.1:1080 https://example.com
+```
 
-- `docs/API.md` — exported API reference
-- `docs/MODULES.md` — module-by-module usage guide
-- `docs/ARCHITECTURE.md` — system architecture and request flow
-- `docs/SETUP.md` — setup, build, and test instructions
-- `docs/CONFIGURATION.md` — request/session/CLI configuration
-- `docs/EXAMPLES.md` — comprehensive usage examples (API + CLI)
-- `docs/ONBOARDING.md` — contributor onboarding guide
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [API Reference](docs/API.md) | Complete API for all exported classes, functions, types, and interfaces |
+| [Configuration](docs/CONFIGURATION.md) | All configuration options for requests, sessions, TLS, DNS, caching, and proxies |
+| [Examples](docs/EXAMPLES.md) | Practical usage patterns covering common and advanced scenarios |
+| [Modules](docs/MODULES.md) | Architecture overview and detailed breakdown of every module |
+| [Onboarding](docs/ONBOARDING.md) | Getting started guide for new contributors and integrators |
+| [Setup](docs/SETUP.md) | Build, test, and development environment instructions |
+
+## Browser Profiles
+
+49 resolvable browser profile names across 5 browser families:
+
+| Browser | Profiles |
+|---------|----------|
+| Chrome | `chrome99` through `chrome136`, `chrome_latest`, `chrome` |
+| Firefox | `firefox133` through `firefox138`, `firefox_latest`, `firefox` |
+| Safari | `safari153` through `safari182`, `safari_latest`, `safari` |
+| Edge | `edge99` through `edge136`, `edge_latest`, `edge` |
+| Tor | `tor133` through `tor145`, `tor_latest`, `tor` |
+
+Each profile includes a complete TLS fingerprint (cipher suites, extensions, supported groups, signature algorithms), HTTP/2 settings fingerprint (SETTINGS frame, WINDOW_UPDATE, pseudo-header order, priority frames), and default HTTP headers with an accurate User-Agent string.
+
+## Standards Compliance
+
+NLcURL implements or references the following RFCs and standards:
+
+| Standard | Coverage |
+|----------|----------|
+| RFC 8446 | TLS 1.3 — full handshake, key schedule, AEAD record encryption |
+| RFC 5246 | TLS 1.2 — ECDHE key exchange, GCM/ChaCha20 cipher suites |
+| RFC 8701 | GREASE — randomized TLS extension values for anti-fingerprinting |
+| RFC 9113 | HTTP/2 — frames, HPACK, flow control, GOAWAY, stream multiplexing |
+| RFC 7541 | HPACK — header compression with Huffman encoding |
+| RFC 9112 | HTTP/1.1 — message syntax, chunked transfer encoding |
+| RFC 9111 | HTTP Caching — freshness, conditional requests, cache modes |
+| RFC 9110 | HTTP Semantics — methods, status codes, range requests |
+| RFC 6265 | HTTP Cookies — Set-Cookie parsing, domain/path scoping, prefixes |
+| RFC 6797 | HSTS — Strict-Transport-Security header processing |
+| RFC 8484 | DNS-over-HTTPS — wire-format queries, GET/POST methods |
+| RFC 7858 | DNS-over-TLS — encrypted DNS over port 853 |
+| RFC 9460 | SVCB/HTTPS DNS Records — service binding, ALPN, ECH delivery |
+| RFC 8305 | Happy Eyeballs v2 — dual-stack connection racing |
+| RFC 6455 | WebSocket — upgrade handshake, framing, close protocol |
+| RFC 7692 | WebSocket Compression — permessage-deflate negotiation |
+| RFC 7838 | HTTP Alt-Svc — alternative service advertisement |
+| RFC 7578 | Multipart Form Data — multipart/form-data encoding |
+| RFC 7616 | HTTP Digest Authentication — MD5/SHA-256, qop=auth |
+| RFC 1928 | SOCKS5 — proxy protocol with auth negotiation |
+| RFC 5869 | HKDF — key derivation for TLS key schedule |
+| RFC 9180 | HPKE — Hybrid Public Key Encryption for ECH |
+| RFC 7413 | TCP Fast Open — platform-aware TFO support |
+| RFC 8297 | 103 Early Hints — Link header parsing |
+| RFC 6891 | EDNS(0) — Extension Mechanisms for DNS OPT records |
+| RFC 7830 | DNS Padding — query size obfuscation for privacy |
+| RFC 6265bis | Cookie SameSite — Strict/Lax/None enforcement, Secure requirement |
 
 ## License
 
-MIT. See `LICENSE`.
+MIT

package/dist/cache/groups.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Represents a named group of cache keys for batch invalidation.
+ */
+export interface CacheGroup {
+    name: string;
+    keys: Set<string>;
+    lastInvalidated: number;
+}
+/**
+ * Parses a comma-separated Cache-Groups header into an array of group names.
+ *
+ * @param {string} header - The raw Cache-Groups header value.
+ * @returns {string[]} Parsed group names.
+ */
+export declare function parseCacheGroups(header: string): string[];
+/**
+ * Manages cache key groupings for targeted invalidation of related cache entries.
+ *
+ * @class
+ */
+export declare class CacheGroupStore {
+    private readonly groups;
+    /**
+     * Associates a cache key with one or more named groups.
+     *
+     * @param {string} cacheKey - The cache key to associate.
+     * @param {string[]} groupNames - The groups to add the key to.
+     */
+    addToGroups(cacheKey: string, groupNames: string[]): void;
+    /**
+     * Removes a cache key from all groups.
+     *
+     * @param {string} cacheKey - The cache key to remove.
+     */
+    removeFromAll(cacheKey: string): void;
+    /**
+     * Returns the set of cache keys belonging to a specific group.
+     *
+     * @param {string} groupName - The group name.
+     * @returns {Set<string>} The cache keys in the group.
+     */
+    getGroupKeys(groupName: string): Set<string>;
+    /**
+     * Invalidates a single group, clearing its keys and recording the timestamp.
+     *
+     * @param {string} groupName - The group name to invalidate.
+     * @returns {string[]} The cache keys that were in the invalidated group.
+     */
+    invalidate(groupName: string): string[];
+    /**
+     * Invalidates all groups, clearing their keys and recording the timestamp.
+     *
+     * @returns {string[]} All unique cache keys that were invalidated.
+     */
+    invalidateAll(): string[];
+    /**
+     * Checks whether a cache key has been invalidated since a given timestamp.
+     *
+     * @param {string} cacheKey - The cache key to check.
+     * @param {number} storedAt - The timestamp when the entry was stored.
+     * @returns {boolean} `true` if the key was invalidated after `storedAt`.
+     */
+    isInvalidatedSince(cacheKey: string, storedAt: number): boolean;
+    /**
+     * Returns the number of tracked groups.
+     *
+     * @returns {number} The group count.
+     */
+    get size(): number;
+    /**
+     * Removes all groups and their key associations.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=groups.d.ts.map

package/dist/cache/groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../src/cache/groups.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAMzD;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IAExD;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI;IAWzD;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMrC;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAI5C;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAUvC;;;;OAIG;IACH,aAAa,IAAI,MAAM,EAAE;IAYzB;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAS/D;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/cache/groups.js

@@ -0,0 +1,118 @@
+/**
+ * Parses a comma-separated Cache-Groups header into an array of group names.
+ *
+ * @param {string} header - The raw Cache-Groups header value.
+ * @returns {string[]} Parsed group names.
+ */
+export function parseCacheGroups(header) {
+    if (!header)
+        return [];
+    return header
+        .split(",")
+        .map((s) => s.trim().replace(/"/g, ""))
+        .filter(Boolean);
+}
+/**
+ * Manages cache key groupings for targeted invalidation of related cache entries.
+ *
+ * @class
+ */
+export class CacheGroupStore {
+    groups = new Map();
+    /**
+     * Associates a cache key with one or more named groups.
+     *
+     * @param {string} cacheKey - The cache key to associate.
+     * @param {string[]} groupNames - The groups to add the key to.
+     */
+    addToGroups(cacheKey, groupNames) {
+        for (const name of groupNames) {
+            let group = this.groups.get(name);
+            if (!group) {
+                group = { name, keys: new Set(), lastInvalidated: 0 };
+                this.groups.set(name, group);
+            }
+            group.keys.add(cacheKey);
+        }
+    }
+    /**
+     * Removes a cache key from all groups.
+     *
+     * @param {string} cacheKey - The cache key to remove.
+     */
+    removeFromAll(cacheKey) {
+        for (const group of this.groups.values()) {
+            group.keys.delete(cacheKey);
+        }
+    }
+    /**
+     * Returns the set of cache keys belonging to a specific group.
+     *
+     * @param {string} groupName - The group name.
+     * @returns {Set<string>} The cache keys in the group.
+     */
+    getGroupKeys(groupName) {
+        return this.groups.get(groupName)?.keys ?? new Set();
+    }
+    /**
+     * Invalidates a single group, clearing its keys and recording the timestamp.
+     *
+     * @param {string} groupName - The group name to invalidate.
+     * @returns {string[]} The cache keys that were in the invalidated group.
+     */
+    invalidate(groupName) {
+        const group = this.groups.get(groupName);
+        if (!group)
+            return [];
+        const keys = [...group.keys];
+        group.keys.clear();
+        group.lastInvalidated = Date.now();
+        return keys;
+    }
+    /**
+     * Invalidates all groups, clearing their keys and recording the timestamp.
+     *
+     * @returns {string[]} All unique cache keys that were invalidated.
+     */
+    invalidateAll() {
+        const allKeys = new Set();
+        for (const group of this.groups.values()) {
+            for (const key of group.keys) {
+                allKeys.add(key);
+            }
+            group.keys.clear();
+            group.lastInvalidated = Date.now();
+        }
+        return [...allKeys];
+    }
+    /**
+     * Checks whether a cache key has been invalidated since a given timestamp.
+     *
+     * @param {string} cacheKey - The cache key to check.
+     * @param {number} storedAt - The timestamp when the entry was stored.
+     * @returns {boolean} `true` if the key was invalidated after `storedAt`.
+     */
+    isInvalidatedSince(cacheKey, storedAt) {
+        for (const group of this.groups.values()) {
+            if (group.keys.has(cacheKey) && group.lastInvalidated > storedAt) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Returns the number of tracked groups.
+     *
+     * @returns {number} The group count.
+     */
+    get size() {
+        return this.groups.size;
+    }
+    /**
+     * Removes all groups and their key associations.
+     */
+    clear() {
+        this.groups.clear();
+    }
+}
+//# sourceMappingURL=groups.js.map

package/dist/cache/groups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../src/cache/groups.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM;SACV,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;SACtC,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAe;IACT,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IAExD;;;;;OAKG;IACH,WAAW,CAAC,QAAgB,EAAE,UAAoB;QAChD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;gBACtD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC/B,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,QAAgB;QAC5B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,IAAI,GAAG,EAAE,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,SAAiB;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QAEtB,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,aAAa;QACX,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAClC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC7B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACnB,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,CAAC;QACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAgB,EAAE,QAAgB;QACnD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,eAAe,GAAG,QAAQ,EAAE,CAAC;gBACjE,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/cache/no-vary-search.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Parsed No-Vary-Search header directive (proposal spec).
+ */
+export interface NoVarySearchDirective {
+    params: boolean | string[];
+    except: string[];
+    keyOrder: boolean;
+}
+/**
+ * Parses a No-Vary-Search header value into a structured directive.
+ *
+ * @param {string} header - The raw No-Vary-Search header value.
+ * @returns {NoVarySearchDirective|null} The parsed directive, or `null` if the header is empty.
+ */
+export declare function parseNoVarySearch(header: string): NoVarySearchDirective | null;
+/**
+ * Determines whether two URLs match according to a No-Vary-Search directive.
+ *
+ * @param {string} cachedUrl - The URL of the cached response.
+ * @param {string} requestUrl - The URL of the incoming request.
+ * @param {NoVarySearchDirective} directive - The No-Vary-Search directive to apply.
+ * @returns {boolean} `true` if the URLs are considered equivalent under the directive.
+ */
+export declare function urlsMatchWithNoVarySearch(cachedUrl: string, requestUrl: string, directive: NoVarySearchDirective): boolean;
+/**
+ * Normalizes a URL for cache key generation by applying No-Vary-Search filtering.
+ *
+ * @param {string} url - The URL to normalize.
+ * @param {NoVarySearchDirective} directive - The No-Vary-Search directive to apply.
+ * @returns {string} The normalized URL string.
+ */
+export declare function normalizeUrlForCache(url: string, directive: NoVarySearchDirective): string;
+//# sourceMappingURL=no-vary-search.d.ts.map

package/dist/cache/no-vary-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-vary-search.d.ts","sourceRoot":"","sources":["../../src/cache/no-vary-search.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CA4B9E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,GAAG,OAAO,CAwB1H;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,GAAG,MAAM,CAiB1F"}