@isdk/proxy 0.1.1

package/README.cn.md

@@ -0,0 +1,138 @@
+# @isdk/proxy
+
+这是一个专为 Node.js 开发者设计的高性能、开发者友好的缓存引擎，旨在解决数据密集型应用中 HTTP 响应缓存管理的复杂性。
+
+## 为什么选择 @isdk/proxy？
+
+在**高并发 API 代理**、**网页爬虫**或**微服务**等场景下，缓存管理通常需要在“速度”和“容量”之间进行妥协。`@isdk/proxy` 通过其独特的**混合多级架构**，完美解决了这一痛点：
+
+- **解决“内存 vs. 容量”的矛盾**：它将小而热的响应存储在内存 (L1) 中以实现纳秒级访问，同时将大文件响应体转储到持久化磁盘 (L2)。更重要的是，它实现了 **“元数据驻留”**——无论响应体多大，其判定逻辑（Headers、Status、Policy）始终保留在内存中，确保瞬时完成缓存有效性评估。
+- **防止缓存雪崩/击穿 (Cache Stampede)**：当一个热点缓存失效时，它通过内置的“请求合并”机制，确保同一时间只有一个网络请求被发出，有效保护上游服务器不被瞬间激增的并发请求压垮。
+- **完全解耦，环境中立**：基于 Web 标准的 `Request`/`Response` 对象构建。这意味着你的缓存逻辑不再被某个具体的 HTTP 库（如 MSW, Axios, Fetch 或 Crawlee）所绑定，一套逻辑，到处运行。
+
+## 核心特性
+
+- **🚀 混合多级缓存**: L1 (LRU 内存) 提供极速响应，L2 (内容寻址磁盘 `cacache`) 提供持久化存储。
+- **🌊 原生流式分发**: 内部完全基于 Stream 管道化构建，在代理大文件时天然防 OOM 内存溢出。
+- **🧠 智能元数据驻留**: 无论文件多大，元数据 (Headers, Status, Policy) 始终驻留在内存中，确保纳秒级的缓存策略判定。
+- **🔄 过期后异步更新 (SWR)**: 立即返回过期数据，同时在后台静默更新缓存，实现“零等待”响应。
+- **🛡️ 请求合并防击穿 (Request Coalescing)**: 当大量并发请求同一资源时，通过全局 Map 合并排队，确保只有一个源站网络请求被发出，彻底防止缓存击穿。
+- **🚑 强离线容灾**: 当后端服务宕机时，自动强制返回旧缓存 (`staleIfError`)；甚至可以无视 `no-store` 指令强制缓存一切内容 (`forceCache`)。
+- **🕵️ 透明的缓存状态**: 自动在返回结果中注入 `x-proxy-cache` 响应头 (`HIT`, `STALE`, `MISS`, `STALE_IF_ERROR`)，极大方便调试与监控。
+- **🌐 环境中立**: 完美适配所有支持 Web 标准 `Request`/`Response` API 的环境。
+
+## 安装
+
+```bash
+pnpm add @isdk/proxy
+```
+
+## 快速开始：核心协调函数
+
+使用 `@isdk/proxy` 的主要方式是通过 `fetchWithCache` 函数，它可以包装任何 HTTP 请求逻辑。
+
+```typescript
+import { SmartCache, createCachedFetch } from '@isdk/proxy';
+
+// 1. 初始化混合缓存实例
+const cache = new SmartCache({
+  storagePath: './.cache',
+  maxMemorySize: 1024 * 1024 // 内存阈值 1MB
+});
+
+// 2. 创建一个预配置的缓存 Fetcher (内部会自动防缓存击穿)
+const myFetch = createCachedFetch({
+  cache,
+  config: {
+    staleIfError: true,
+    forceCache: false // 设置为 true 可无视 no-store 强制缓存一切，适用于离线应用
+  },
+  backgroundUpdate: true // 开启 SWR (过期后后台静默更新)
+});
+
+// 3. 在应用的任何地方愉快地使用它！
+const request = new Request('https://api.example.com/data');
+const response = await myFetch(request, (req) => fetch(req)); // 传入任何返回 Promise<Response> 的获取函数
+
+console.log(response.headers.get('x-proxy-cache')); // 输出: "MISS", "HIT", "STALE" 或 "STALE_IF_ERROR"
+const data = await response.json();
+```
+
+## 适配器 (Adapters)
+
+`@isdk/proxy` 旨在成为环境无关的纯净核心。虽然核心库保持纯粹，但你可以轻松集成或找到针对特定环境的适配器：
+
+- **MSW 适配器**: 参见 `@isdk/proxy-msw` (独立包)，将此缓存引擎作为 MSW 拦截器使用。
+- **Axios 适配器**: 可以通过将 Axios 配置转换为 Web 标准 `Request` 轻松实现。
+- **Crawlee 适配器**: 能够集成到爬虫生命周期中，减少重复抓取。
+
+## 架构设计详解
+
+### 1. 混合存储策略 (Hybrid Storage)
+
+- **L1 (内存层)**: 基于 `@cacheable/memory`。对于小文件（小于 `maxMemorySize`），同时存储元数据和响应体。
+- **L2 (磁盘层)**: 基于 `cacache`（内容寻址存储）。负责持久化和大数据存储。
+- **性能优化**: 对于大文件，响应体只保存在磁盘，但其 **元数据（Metadata）** 仍会驻留在内存中。这意味着即使磁盘文件很大，系统依然可以瞬间判断其是否过期。
+
+### 2. 请求合并 (Request Collapsing)
+
+当多个并发请求同时遇到缓存缺失或过期时，`@isdk/proxy` 会利用 `In-Flight` 状态 Map 追踪正在进行的 Promise，确保只有**一个**真实的网络请求被发出。其他请求会根据配置选择等待新数据或立即返回现有的过期数据。
+
+### 3. SWR 与 后台更新
+
+当缓存过期但在 SWR 窗口内时：
+
+1. `fetchWithCache` 立即构造并返回旧的 `Response`。
+2. 启动异步网络请求。
+3. 网络请求完成后，自动更新 L1 和 L2 缓存。
+
+## API 参考
+
+### `createCachedFetch(options)` (强烈推荐)
+
+面向终端用户的高阶工厂函数。它会自动在内部闭包中维护并发追踪器，为你生成一个开箱即用、绝不会发生缓存击穿的 Fetch 实例。
+
+- **`options.cache`**: `SmartCache` 实例。
+- **`options.config`**: 全局缓存配置对象 (`SiteCacheConfig`):
+  - `staleIfError` (boolean): 网络请求失败时，是否强制返回本地过期的旧缓存以保障可用性。
+  - `forceCache` (boolean): 是否无视源站的 `Cache-Control: no-store` 指令强制执行缓存入盘。适用于极端弱网或离线优先的应用场景。
+- **`options.backgroundUpdate`**: 设置为 `true` 以开启 SWR (Stale-While-Revalidate) 行为。
+- **`options.activeCacheWrites`**: 可选参数。一个 `Map<string, Promise<void>>`，用于在多个 `createCachedFetch` 实例之间共享并发追踪状态，实现应用级别的缓存击穿防护。
+- **返回值**: 一个可随处调用的 `(request: Request, fetcher: (req: Request) => Promise<Response>) => Promise<Response>` 包装函数。
+
+### `createFetchWithCache(activeCacheWrites?)`
+
+单一职责的高阶函数。专门用于封装和隔离 `activeCacheWrites` 并发追踪器。
+它会返回一个绑定了闭包内 Map 的 `fetchWithCache` 变体函数。如果你正在构建中间件，但又不想使用顶层的 `createCachedFetch` 工厂，可以用它来免除手动维护追踪器的烦恼。
+
+- **`activeCacheWrites`**: 可选参数。外部传入的 `Map<string, Promise<void>>` 作为并发追踪器。如果不提供，将自动创建一个新的内部 Map。在多个实例间共享同一个 Map 可以实现应用范围内的请求合并。
+- **返回值**: `(request: Request, fetcher: (req: Request) => Promise<Response>, options: Omit<FetchWithCacheOptions, 'activeCacheWrites'>) => Promise<Response>`
+
+### `fetchWithCache(request, fetcher, options)`
+
+底层的核心缓存协调函数。如果你在开发更上层的插件或有特殊的生命周期控制需求，可以直接调用它。
+
+- **`request`**: Web 标准的 `Request` 对象。
+- **`fetcher`**: 发起真实网络请求的回调函数 `(req: Request) => Promise<Response>`。
+- **`options.activeCacheWrites`**: 必须由**外部传入**的一个 `Map<string, Promise<void>>`，用于在多个并发的 `fetchWithCache` 调用间共享锁状态，以实现请求合并。如果你不想自己维护它，请使用 `createCachedFetch` 或 `createFetchWithCache`。
+
+### `SmartCache`
+
+管理多级混合存储的核心引擎。
+
+- `new SmartCache(options)`
+- **`options.maxMemorySize`**: 响应体进入内存 (L1) 的大小阈值（字节），超过此大小的文件将直接进入磁盘流传输（默认 `1048576` 即 1MB）。
+- **`options.storagePath`**: 磁盘 L2 缓存（cacache）的物理存储路径（默认为操作系统的临时目录）。
+
+### 缓存状态标头 (Cache Status Headers)
+
+由 `@isdk/proxy` 处理并返回的所有 `Response`，其 Headers 中都会注入 `x-proxy-cache` 字段以便观测生命周期，可能的值有：
+
+- `HIT`: 完美命中，数据完全来自于 L1 内存或 L2 磁盘缓存。
+- `MISS`: 缓存未命中（或主动绕过缓存），数据真实来自于源站请求。
+- `STALE`: 命中过期缓存（已通过 SWR 机制在后台发起了静默网络更新）。
+- `STALE_IF_ERROR`: 源站请求失败（网络断开或报错），系统作为兜底强制返回了过期的旧缓存。
+
+## 许可证
+
+MIT

package/README.md

@@ -0,0 +1,129 @@
+# @isdk/proxy
+
+A high-performance, developer-friendly caching engine for Node.js, specifically designed to solve the complexity of managing HTTP response caches in data-intensive applications.
+
+## Why @isdk/proxy?
+
+In high-concurrency environments—like **API Proxies**, **Web Scrapers**, or **Microservices**—managing caches is often a trade-off between speed and memory.
+
+`@isdk/proxy` provides a **Hybrid Multi-tier Architecture** that gives you the best of both worlds:
+
+- **It solves the Memory vs. Capacity problem**: Keeps small, hot responses in memory (L1) for nanosecond access, while offloading large bodies to persistent disk (L2) without losing the ability to instantly evaluate cache policies.
+- **It prevents Cache Stampede**: When a hot entry expires, it ensures only ONE network request is made, preventing your upstream from being crushed by concurrent misses.
+- **It is Framework-Agnostic**: Built on Web standard `Request`/`Response` objects, it decouples your caching logic from your HTTP client (MSW, Axios, Fetch, Crawlee, etc.).
+
+## Key Features
+
+- **🚀 Hybrid Multi-tier Cache**: Extreme speed with L1 (LRU Memory) and persistence with L2 (Content Addressable Disk via `cacache`).
+- **🌊 Streaming Native**: Fully stream-based internal pipeline natively prevents Out-Of-Memory (OOM) issues when proxying large files.
+- **🧠 Intelligent Meta-Residency**: Metadata (Headers, Status, Policy) stays in memory regardless of body size, ensuring nanosecond cache policy evaluations.
+- **🔄 Stale-While-Revalidate (SWR)**: Serve stale content instantly while updating the cache silently in the background.
+- **🛡️ Request Coalescing (Anti-Stampede)**: Prevent cache stampede by coalescing identical concurrent requests using a shared tracker, ensuring only one network request is made.
+- **🚑 Offline Resilience**: Automatically serve stale content if the upstream is down (`staleIfError`), or forcefully cache everything ignoring `Cache-Control: no-store` (`forceCache`).
+- **🕵️ Transparent Cache Status**: Injects standard `x-proxy-cache` headers (`HIT`, `STALE`, `MISS`, `STALE_IF_ERROR`) into responses for easy observability.
+- **🌐 Framework Agnostic**: Works everywhere by using standard Web `Request`/`Response` APIs.
+
+## Installation
+
+```bash
+pnpm add @isdk/proxy
+```
+
+## Quick Start: The Core Orchestrator
+
+The primary way to use `@isdk/proxy` is via the `fetchWithCache` function, which can wrap any HTTP request logic.
+
+```typescript
+import { SmartCache, createCachedFetch } from '@isdk/proxy';
+
+// 1. Initialize the hybrid cache
+const cache = new SmartCache({
+  storagePath: './.cache',
+  maxMemorySize: 1024 * 1024 // 1MB threshold
+});
+
+// 2. Create a pre-configured cached fetcher (automatically tracks concurrent requests)
+const myFetch = createCachedFetch({
+  cache,
+  config: {
+    staleIfError: true,
+    forceCache: false // Set to true to cache everything (ignore no-store) for offline-first apps
+  },
+  backgroundUpdate: true // Enable SWR
+});
+
+// 3. Use it anywhere in your app!
+const request = new Request('https://api.example.com/data');
+const response = await myFetch(request, (req) => fetch(req));
+
+console.log(response.headers.get('x-proxy-cache')); // "MISS", "HIT", "STALE", or "STALE_IF_ERROR"
+const data = await response.json();
+```
+
+## Adapters
+
+`@isdk/proxy` is designed to be framework-agnostic. While the core library is pure, you can find (or build) adapters for specific environments:
+
+- **MSW Adapter**: See `@isdk/proxy-msw` (separate package) to use this caching engine as an MSW interceptor.
+- **Axios Adapter**: Easily implemented by converting Axios config to Web `Request`.
+
+## Architecture
+
+### Hybrid Storage Strategy
+
+- **L1 (Memory)**: Powered by `@cacheable/memory`. Stores both Meta and Body for small files (< `maxMemorySize`).
+- **L2 (Disk)**: Powered by `cacache`. Stores all data for persistence.
+- **Optimization**: For large files, only the Metadata is kept in memory. The body is streamed or read from disk only when requested, saving significant memory.
+
+### Request Collapsing
+
+When multiple concurrent requests hit a missing or expired cache entry, `@isdk/proxy` ensures that only **one** request goes to the network. Subsequent requests will wait for the same promise or serve the background-updated data.
+
+## API Reference
+
+### `createCachedFetch(options)` (Recommended)
+
+A higher-order factory function designed for end-users. It creates a pre-configured `fetch` equivalent that automatically tracks concurrent requests internally to prevent cache stampedes.
+
+- **`options.cache`**: An instance of `SmartCache`.
+- **`options.config`**: A `SiteCacheConfig` object containing:
+  - `staleIfError` (boolean): Serve stale cache if the network fails.
+  - `forceCache` (boolean): Force cache everything, ignoring `Cache-Control: no-store`. Ideal for offline-first resilience.
+- **`options.backgroundUpdate`**: Set to `true` to enable SWR behavior.
+- **`options.activeCacheWrites`**: Optional. A `Map<string, Promise<void>>` that can be shared across multiple `createCachedFetch` instances to enable application-level cache stampede prevention.
+- **Returns**: A reusable `(request: Request, fetcher: (req: Request) => Promise<Response>) => Promise<Response>` function.
+
+### `createFetchWithCache(activeCacheWrites?)`
+
+A single-responsibility higher-order function that encapsulates the `activeCacheWrites` concurrency tracker. It returns a variant of `fetchWithCache` that shares an internal Map to coalesce identical concurrent requests. Use this if you are building an intermediate wrapper but don't want to rely on the top-level `createCachedFetch` factory.
+
+- **`activeCacheWrites`**: Optional. An external `Map<string, Promise<void>>` to be used as the concurrency tracker. If not provided, a new internal Map will be created. Sharing the same Map across multiple instances enables application-wide request coalescing.
+- **Returns**: `(request: Request, fetcher: (req: Request) => Promise<Response>, options: Omit<FetchWithCacheOptions, 'activeCacheWrites'>) => Promise<Response>`
+
+### `fetchWithCache(request, fetcher, options)`
+
+The core caching orchestrator. Use this directly if you need low-level control or are building a library on top of it.
+
+- **`request`**: Web Standard `Request`.
+- **`fetcher`**: The raw fetching callback `(req: Request) => Promise<Response>`.
+- **`options.activeCacheWrites`**: A `Map<string, Promise<void>>` that YOU must provide and maintain to coalesce concurrent requests. (If you don't want to manage this, use `createCachedFetch` or `createFetchWithCache` instead).
+
+### `SmartCache`
+
+The hybrid multi-tier storage engine.
+
+- `new SmartCache(options)`
+- **`options.maxMemorySize`**: Threshold (in bytes) for offloading bodies to disk (default `1048576`, i.e., 1MB).
+- **`options.storagePath`**: Disk storage path for the `cacache` engine (defaults to a system temp folder).
+
+### Cache Status Headers
+
+Every response processed by `@isdk/proxy` will include an `x-proxy-cache` header indicating its lifecycle:
+- `HIT`: Served entirely from L1 or L2 cache.
+- `MISS`: Bypassed cache and fetched from the origin server.
+- `STALE`: Served from stale cache while a background update was initiated (SWR).
+- `STALE_IF_ERROR`: Origin fetch failed; served from stale cache as a fallback.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,213 @@
+import { KeyvCacheableMemoryOptions } from '@cacheable/memory';
+
+/**
+ * 缓存键过滤配置
+ *
+ * 用于定义在生成缓存指纹时，哪些字段应该被包含或排除。
+ */
+interface KeyFilterConfig {
+    /** 仅包含（白名单）：如果设置，只有这些字段会参与 Key 的计算 */
+    include?: string[];
+    /** 排除（黑名单）：用于排除像 `timestamp`、`nonce` 等干扰缓存命中的动态字段 */
+    exclude?: string[];
+}
+/**
+ * 站点级缓存配置
+ */
+interface SiteCacheConfig {
+    /** Query 参数过滤配置 */
+    query?: KeyFilterConfig;
+    /** 请求头过滤配置 */
+    headers?: KeyFilterConfig;
+    /** Cookie 过滤配置 */
+    cookies?: KeyFilterConfig;
+    /** 当后端请求失败且存在旧缓存时，是否强制返回旧缓存（容错机制） */
+    staleIfError?: boolean;
+    /** 是否强制缓存一切响应（无视 no-store 等不缓存指令），用于极端的离线可用容错场景 */
+    forceCache?: boolean;
+}
+/**
+ * 缓存元数据
+ *
+ * 存储在 L1 内存和 L2 磁盘中的非 Body 信息。
+ * 即使 Body 过大未进入内存，此元数据也会驻留在内存中以供快速策略判定。
+ */
+interface CacheMetadata {
+    /** HTTP 状态码 */
+    status: number;
+    /** 响应头对象 */
+    headers: Record<string, string>;
+    /** http-cache-semantics 策略对象，包含 TTL 和缓存指令 */
+    policy: any;
+    /** 原始请求 URL */
+    url: string;
+    /** 原始请求方法 */
+    method: string;
+    /** 缓存写入时的时间戳 */
+    timestamp: number;
+    /** Body 的字节长度，用于精确区分“空响应”与“未入内存的大响应” */
+    size: number;
+}
+/**
+ * 完整的缓存条目
+ */
+interface CacheEntry extends CacheMetadata {
+    /** 响应体数据：小文件为 Buffer，大文件为可读流 */
+    body: Buffer | any;
+}
+/**
+ * 代理拦截器全局配置
+ */
+interface ProxyConfig {
+    /** 默认缓存配置，当请求的域名未在 sites 中匹配时使用 */
+    default: SiteCacheConfig;
+    /** 针对特定域名的精细化缓存配置 */
+    sites: Record<string, SiteCacheConfig>;
+    /** 磁盘缓存（cacache）的物理存储路径，可选，默认为系统临时目录 */
+    storagePath?: string;
+}
+
+/**
+ * SmartCache 选项
+ */
+interface SmartCacheOptions {
+    /** 磁盘缓存的物理路径。如果不提供，将默认使用系统临时目录。 */
+    storagePath?: string;
+    /** 内存缓存阈值（字节）。响应体大小超过此值时，Body 将只存入磁盘，而 Meta 仍保留在内存。默认 1MB。 */
+    maxMemorySize?: number;
+    /** 透传给 L1 (Memory) 的高级配置 */
+    memoryOptions?: Partial<KeyvCacheableMemoryOptions>;
+}
+/**
+ * 智能混合缓存类 (Hybrid Cache)
+ */
+declare class SmartCache {
+    private memory;
+    private storagePath;
+    private maxMemorySize;
+    constructor(options?: SmartCacheOptions);
+    /**
+     * 获取缓存条目
+     * 如果是小文件，返回带 Buffer 的 Entry；如果是大文件，返回带 ReadStream 的 Entry。
+     */
+    get(key: string): Promise<CacheEntry | null>;
+    /**
+     * 写入缓存
+     */
+    set(key: string, body: Buffer, metadata: Omit<CacheMetadata, 'size'>): Promise<void>;
+    /**
+     * 内部方法：处理内存回填
+     */
+    private saveToMemory;
+    getStream(key: string): NodeJS.ReadableStream;
+    setStream(key: string, metadata: Omit<CacheMetadata, 'size'>): NodeJS.WritableStream;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * 根据 Request 和配置生成唯一的缓存键
+ */
+declare const generateCacheKey: (req: Request, config: SiteCacheConfig) => string;
+
+/**
+ * fetchWithCache 选项
+ */
+interface FetchWithCacheOptions {
+    /** 混合缓存实例 */
+    cache: SmartCache;
+    /** 站点级缓存配置 */
+    config: SiteCacheConfig;
+    /** 是否启用后台异步更新 (SWR) */
+    backgroundUpdate?: boolean;
+    /** 后台更新 Promise 触发时的回调 */
+    onBackgroundUpdate?: (promise: Promise<Response>) => void;
+    /** 自定义缓存键生成函数 */
+    generateKey?: typeof generateCacheKey;
+    /**
+     * 并发写入任务追踪器
+     * 传入一个外部维护的 Map，用于在跨请求、跨实例时防止针对同一文件的并发重复下载。
+     * Map 的 Key 是缓存 Key，Value 是一个代表写入完成的 Promise。
+     */
+    activeCacheWrites?: Map<string, Promise<void>>;
+}
+/** 内部流水线上下文，合并了入参和计算出的关键状态 */
+interface FetchWithCacheContext extends FetchWithCacheOptions {
+    request: Request;
+    fetcher: (req: Request) => Promise<Response>;
+    cacheKey: string;
+    activeCacheWrites: Map<string, Promise<void>>;
+}
+/**
+ * 核心协调函数 (Fetcher Orchestrator)
+ *
+ * 实现了基于流的混合缓存代理核心逻辑，主要机制包括：
+ * - **大文件流式处理**：底层完全通过 Streams 实现，代理大文件时自动写入磁盘且防 OOM。
+ * - **SWR (Stale-While-Revalidate)**：后台静默更新机制。
+ * - **并发防击穿 (Request Coalescing)**：利用 `activeCacheWrites` 将并发请求合并。
+ * - **强制离线容灾**：支持 `staleIfError` 和 `forceCache`（无视 Cache-Control 强制入库）。
+ *
+ * 并且会在响应头中自动注入 `x-proxy-cache` 标明缓存命中状态 (`HIT`, `STALE`, `MISS`, `STALE_IF_ERROR`)。
+ */
+declare function fetchWithCache(request: Request, fetcher: (req: Request) => Promise<Response>, options: FetchWithCacheOptions): Promise<Response>;
+
+/**
+ * 单一职责高阶函数：专门用于封装和隔离 activeCacheWrites 并发追踪器。
+ *
+ * 每次调用此函数，都会创建一个完全独立的闭包 Map（或复用传入的 Map），
+ * 并返回一个绑定了该 Map 的 `fetchWithCache` 变体函数。
+ * 从而让使用者无需关心 `activeCacheWrites` 的维护，杜绝了误传或不传导致的并发击穿风险。
+ *
+ * @param activeCacheWrites - 可选参数，用于跨实例共享的并发写入追踪器。
+ *                            如果未提供，将自动创建一个新的 Map。
+ *                            传入同一个 Map 可以让多个 `createFetchWithCache` 实例共享
+ *                            并发追踪状态，从而在整个应用范围内防止缓存击穿。
+ * @returns 一个绑定了并发追踪器的 `fetchWithCache` 变体函数。
+ */
+declare function createFetchWithCache(activeCacheWrites?: Map<string, Promise<void>>): (request: Request, fetcher: (req: Request) => Promise<Response>, options: Omit<FetchWithCacheOptions, "activeCacheWrites">) => Promise<Response>;
+
+/**
+ * 缓存请求工厂函数 (针对终端用户的顶层高阶 API)
+ *
+ * 为用户提供一个只需配置一次（如 Cache 实例、默认 Config），
+ * 即可在整个应用生命周期中随处调用的 `cachedFetch` 方法。
+ *
+ * 底层调用了 `createFetchWithCache` 来保证单一职能隔离，内部自动维护并发追踪。
+ *
+ * @param defaultOptions - 默认缓存配置选项。
+ *                       可以包含 `activeCacheWrites` 字段，用于跨多个 `createCachedFetch`
+ *                       实例共享并发追踪状态，实现应用级别的缓存击穿防护。
+ * @returns 一个预配置的 `cachedFetch` 函数，可直接用于发起带缓存的请求。
+ */
+declare function createCachedFetch(defaultOptions: FetchWithCacheOptions): (request: Request, fetcher: (req: Request) => Promise<Response>, overrideOptions?: Partial<FetchWithCacheOptions>) => Promise<Response>;
+
+/**
+ * 从源对象中根据过滤配置提取数据并标准化。
+ *
+ * 此函数主要用于生成缓存指纹。它会：
+ * 1. 根据 `config` (include/exclude) 过滤键。
+ * 2. 对键进行排序以保证指纹的一致性。
+ * 3. 将所有键转换为小写。
+ * 4. 将值统一包装为数组并进行排序，消除数组项顺序差异。
+ *
+ * @param source 原始数据对象 (如 QueryParams, Headers, Cookies)
+ * @param config 过滤配置 (白名单或黑名单)
+ * @returns 标准化后的数据 Map，键为小写，值为字符串数组
+ */
+declare const extractData: (source: Record<string, any>, config?: KeyFilterConfig) => Record<string, string[]>;
+
+/**
+ * 判断给定的键是否允许参与缓存指纹计算。
+ *
+ * 优先级逻辑：
+ * 1. 如果配置了 `include` (白名单)，则只有存在于 `include` 中的键才会被允许。
+ * 2. 否则，如果配置了 `exclude` (黑名单)，则存在于 `exclude` 中的键将被拒绝。
+ * 3. 如果都没有配置，默认允许所有键。
+ *
+ * @param key 要检查的键名
+ * @param config 过滤配置
+ * @returns 是否允许
+ */
+declare function isAllowed(key: string, config?: KeyFilterConfig): boolean;
+
+export { type CacheEntry, type CacheMetadata, type FetchWithCacheContext, type FetchWithCacheOptions, type KeyFilterConfig, type ProxyConfig, type SiteCacheConfig, SmartCache, type SmartCacheOptions, createCachedFetch, createFetchWithCache, extractData, fetchWithCache, generateCacheKey, isAllowed };