@isdk/proxy 0.1.1

package/docs/functions/fetchWithCache.md

@@ -0,0 +1,39 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / fetchWithCache
+
+# Function: fetchWithCache()
+
+> **fetchWithCache**(`request`, `fetcher`, `options`): `Promise`\<`Response`\>
+
+Defined in: [core/fetchWithCache.ts:244](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L244)
+
+核心协调函数 (Fetcher Orchestrator)
+
+实现了基于流的混合缓存代理核心逻辑，主要机制包括：
+- **大文件流式处理**：底层完全通过 Streams 实现，代理大文件时自动写入磁盘且防 OOM。
+- **SWR (Stale-While-Revalidate)**：后台静默更新机制。
+- **并发防击穿 (Request Coalescing)**：利用 `activeCacheWrites` 将并发请求合并。
+- **强制离线容灾**：支持 `staleIfError` 和 `forceCache`（无视 Cache-Control 强制入库）。
+
+并且会在响应头中自动注入 `x-proxy-cache` 标明缓存命中状态 (`HIT`, `STALE`, `MISS`, `STALE_IF_ERROR`)。
+
+## Parameters
+
+### request
+
+`Request`
+
+### fetcher
+
+(`req`) => `Promise`\<`Response`\>
+
+### options
+
+[`FetchWithCacheOptions`](../interfaces/FetchWithCacheOptions.md)
+
+## Returns
+
+`Promise`\<`Response`\>

package/docs/functions/generateCacheKey.md

@@ -0,0 +1,27 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / generateCacheKey
+
+# Function: generateCacheKey()
+
+> **generateCacheKey**(`req`, `config`): `string`
+
+Defined in: [core/generateCacheKey.ts:8](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/generateCacheKey.ts#L8)
+
+根据 Request 和配置生成唯一的缓存键
+
+## Parameters
+
+### req
+
+`Request`
+
+### config
+
+[`SiteCacheConfig`](../interfaces/SiteCacheConfig.md)
+
+## Returns
+
+`string`

package/docs/functions/isAllowed.md

@@ -0,0 +1,38 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / isAllowed
+
+# Function: isAllowed()
+
+> **isAllowed**(`key`, `config?`): `boolean`
+
+Defined in: [utils/isAllowed.ts:15](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/utils/isAllowed.ts#L15)
+
+判断给定的键是否允许参与缓存指纹计算。
+
+优先级逻辑：
+1. 如果配置了 `include` (白名单)，则只有存在于 `include` 中的键才会被允许。
+2. 否则，如果配置了 `exclude` (黑名单)，则存在于 `exclude` 中的键将被拒绝。
+3. 如果都没有配置，默认允许所有键。
+
+## Parameters
+
+### key
+
+`string`
+
+要检查的键名
+
+### config?
+
+[`KeyFilterConfig`](../interfaces/KeyFilterConfig.md)
+
+过滤配置
+
+## Returns
+
+`boolean`
+
+是否允许

package/docs/globals.md

@@ -0,0 +1,29 @@
+[**@isdk/proxy**](README.md)
+
+***
+
+# @isdk/proxy
+
+## Classes
+
+- [SmartCache](classes/SmartCache.md)
+
+## Interfaces
+
+- [CacheEntry](interfaces/CacheEntry.md)
+- [CacheMetadata](interfaces/CacheMetadata.md)
+- [FetchWithCacheContext](interfaces/FetchWithCacheContext.md)
+- [FetchWithCacheOptions](interfaces/FetchWithCacheOptions.md)
+- [KeyFilterConfig](interfaces/KeyFilterConfig.md)
+- [ProxyConfig](interfaces/ProxyConfig.md)
+- [SiteCacheConfig](interfaces/SiteCacheConfig.md)
+- [SmartCacheOptions](interfaces/SmartCacheOptions.md)
+
+## Functions
+
+- [createCachedFetch](functions/createCachedFetch.md)
+- [createFetchWithCache](functions/createFetchWithCache.md)
+- [extractData](functions/extractData.md)
+- [fetchWithCache](functions/fetchWithCache.md)
+- [generateCacheKey](functions/generateCacheKey.md)
+- [isAllowed](functions/isAllowed.md)

package/docs/interfaces/CacheEntry.md

@@ -0,0 +1,123 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / CacheEntry
+
+# Interface: CacheEntry
+
+Defined in: [types.ts:55](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L55)
+
+完整的缓存条目
+
+## Extends
+
+- [`CacheMetadata`](CacheMetadata.md)
+
+## Properties
+
+### body
+
+> **body**: `any`
+
+Defined in: [types.ts:57](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L57)
+
+响应体数据：小文件为 Buffer，大文件为可读流
+
+***
+
+### headers
+
+> **headers**: `Record`\<`string`, `string`\>
+
+Defined in: [types.ts:39](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L39)
+
+响应头对象
+
+#### Inherited from
+
+[`CacheMetadata`](CacheMetadata.md).[`headers`](CacheMetadata.md#headers)
+
+***
+
+### method
+
+> **method**: `string`
+
+Defined in: [types.ts:45](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L45)
+
+原始请求方法
+
+#### Inherited from
+
+[`CacheMetadata`](CacheMetadata.md).[`method`](CacheMetadata.md#method)
+
+***
+
+### policy
+
+> **policy**: `any`
+
+Defined in: [types.ts:41](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L41)
+
+http-cache-semantics 策略对象，包含 TTL 和缓存指令
+
+#### Inherited from
+
+[`CacheMetadata`](CacheMetadata.md).[`policy`](CacheMetadata.md#policy)
+
+***
+
+### size
+
+> **size**: `number`
+
+Defined in: [types.ts:49](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L49)
+
+Body 的字节长度，用于精确区分“空响应”与“未入内存的大响应”
+
+#### Inherited from
+
+[`CacheMetadata`](CacheMetadata.md).[`size`](CacheMetadata.md#size)
+
+***
+
+### status
+
+> **status**: `number`
+
+Defined in: [types.ts:37](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L37)
+
+HTTP 状态码
+
+#### Inherited from
+
+[`CacheMetadata`](CacheMetadata.md).[`status`](CacheMetadata.md#status)
+
+***
+
+### timestamp
+
+> **timestamp**: `number`
+
+Defined in: [types.ts:47](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L47)
+
+缓存写入时的时间戳
+
+#### Inherited from
+
+[`CacheMetadata`](CacheMetadata.md).[`timestamp`](CacheMetadata.md#timestamp)
+
+***
+
+### url
+
+> **url**: `string`
+
+Defined in: [types.ts:43](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L43)
+
+原始请求 URL
+
+#### Inherited from
+
+[`CacheMetadata`](CacheMetadata.md).[`url`](CacheMetadata.md#url)

package/docs/interfaces/CacheMetadata.md

@@ -0,0 +1,88 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / CacheMetadata
+
+# Interface: CacheMetadata
+
+Defined in: [types.ts:35](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L35)
+
+缓存元数据
+
+存储在 L1 内存和 L2 磁盘中的非 Body 信息。
+即使 Body 过大未进入内存，此元数据也会驻留在内存中以供快速策略判定。
+
+## Extended by
+
+- [`CacheEntry`](CacheEntry.md)
+
+## Properties
+
+### headers
+
+> **headers**: `Record`\<`string`, `string`\>
+
+Defined in: [types.ts:39](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L39)
+
+响应头对象
+
+***
+
+### method
+
+> **method**: `string`
+
+Defined in: [types.ts:45](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L45)
+
+原始请求方法
+
+***
+
+### policy
+
+> **policy**: `any`
+
+Defined in: [types.ts:41](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L41)
+
+http-cache-semantics 策略对象，包含 TTL 和缓存指令
+
+***
+
+### size
+
+> **size**: `number`
+
+Defined in: [types.ts:49](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L49)
+
+Body 的字节长度，用于精确区分“空响应”与“未入内存的大响应”
+
+***
+
+### status
+
+> **status**: `number`
+
+Defined in: [types.ts:37](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L37)
+
+HTTP 状态码
+
+***
+
+### timestamp
+
+> **timestamp**: `number`
+
+Defined in: [types.ts:47](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L47)
+
+缓存写入时的时间戳
+
+***
+
+### url
+
+> **url**: `string`
+
+Defined in: [types.ts:43](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L43)
+
+原始请求 URL

package/docs/interfaces/FetchWithCacheContext.md

@@ -0,0 +1,161 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / FetchWithCacheContext
+
+# Interface: FetchWithCacheContext
+
+Defined in: [core/fetchWithCache.ts:31](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L31)
+
+内部流水线上下文，合并了入参和计算出的关键状态
+
+## Extends
+
+- [`FetchWithCacheOptions`](FetchWithCacheOptions.md)
+
+## Properties
+
+### activeCacheWrites
+
+> **activeCacheWrites**: `Map`\<`string`, `Promise`\<`void`\>\>
+
+Defined in: [core/fetchWithCache.ts:35](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L35)
+
+并发写入任务追踪器
+传入一个外部维护的 Map，用于在跨请求、跨实例时防止针对同一文件的并发重复下载。
+Map 的 Key 是缓存 Key，Value 是一个代表写入完成的 Promise。
+
+#### Overrides
+
+[`FetchWithCacheOptions`](FetchWithCacheOptions.md).[`activeCacheWrites`](FetchWithCacheOptions.md#activecachewrites)
+
+***
+
+### backgroundUpdate?
+
+> `optional` **backgroundUpdate**: `boolean`
+
+Defined in: [core/fetchWithCache.ts:17](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L17)
+
+是否启用后台异步更新 (SWR)
+
+#### Inherited from
+
+[`FetchWithCacheOptions`](FetchWithCacheOptions.md).[`backgroundUpdate`](FetchWithCacheOptions.md#backgroundupdate)
+
+***
+
+### cache
+
+> **cache**: [`SmartCache`](../classes/SmartCache.md)
+
+Defined in: [core/fetchWithCache.ts:13](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L13)
+
+混合缓存实例
+
+#### Inherited from
+
+[`FetchWithCacheOptions`](FetchWithCacheOptions.md).[`cache`](FetchWithCacheOptions.md#cache)
+
+***
+
+### cacheKey
+
+> **cacheKey**: `string`
+
+Defined in: [core/fetchWithCache.ts:34](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L34)
+
+***
+
+### config
+
+> **config**: [`SiteCacheConfig`](SiteCacheConfig.md)
+
+Defined in: [core/fetchWithCache.ts:15](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L15)
+
+站点级缓存配置
+
+#### Inherited from
+
+[`FetchWithCacheOptions`](FetchWithCacheOptions.md).[`config`](FetchWithCacheOptions.md#config)
+
+***
+
+### fetcher()
+
+> **fetcher**: (`req`) => `Promise`\<`Response`\>
+
+Defined in: [core/fetchWithCache.ts:33](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L33)
+
+#### Parameters
+
+##### req
+
+`Request`
+
+#### Returns
+
+`Promise`\<`Response`\>
+
+***
+
+### generateKey()?
+
+> `optional` **generateKey**: (`req`, `config`) => `string`
+
+Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L21)
+
+自定义缓存键生成函数
+
+根据 Request 和配置生成唯一的缓存键
+
+#### Parameters
+
+##### req
+
+`Request`
+
+##### config
+
+[`SiteCacheConfig`](SiteCacheConfig.md)
+
+#### Returns
+
+`string`
+
+#### Inherited from
+
+[`FetchWithCacheOptions`](FetchWithCacheOptions.md).[`generateKey`](FetchWithCacheOptions.md#generatekey)
+
+***
+
+### onBackgroundUpdate()?
+
+> `optional` **onBackgroundUpdate**: (`promise`) => `void`
+
+Defined in: [core/fetchWithCache.ts:19](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L19)
+
+后台更新 Promise 触发时的回调
+
+#### Parameters
+
+##### promise
+
+`Promise`\<`Response`\>
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FetchWithCacheOptions`](FetchWithCacheOptions.md).[`onBackgroundUpdate`](FetchWithCacheOptions.md#onbackgroundupdate)
+
+***
+
+### request
+
+> **request**: `Request`
+
+Defined in: [core/fetchWithCache.ts:32](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L32)

package/docs/interfaces/FetchWithCacheOptions.md

@@ -0,0 +1,103 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / FetchWithCacheOptions
+
+# Interface: FetchWithCacheOptions
+
+Defined in: [core/fetchWithCache.ts:11](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L11)
+
+fetchWithCache 选项
+
+## Extended by
+
+- [`FetchWithCacheContext`](FetchWithCacheContext.md)
+
+## Properties
+
+### activeCacheWrites?
+
+> `optional` **activeCacheWrites**: `Map`\<`string`, `Promise`\<`void`\>\>
+
+Defined in: [core/fetchWithCache.ts:27](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L27)
+
+并发写入任务追踪器
+传入一个外部维护的 Map，用于在跨请求、跨实例时防止针对同一文件的并发重复下载。
+Map 的 Key 是缓存 Key，Value 是一个代表写入完成的 Promise。
+
+***
+
+### backgroundUpdate?
+
+> `optional` **backgroundUpdate**: `boolean`
+
+Defined in: [core/fetchWithCache.ts:17](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L17)
+
+是否启用后台异步更新 (SWR)
+
+***
+
+### cache
+
+> **cache**: [`SmartCache`](../classes/SmartCache.md)
+
+Defined in: [core/fetchWithCache.ts:13](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L13)
+
+混合缓存实例
+
+***
+
+### config
+
+> **config**: [`SiteCacheConfig`](SiteCacheConfig.md)
+
+Defined in: [core/fetchWithCache.ts:15](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L15)
+
+站点级缓存配置
+
+***
+
+### generateKey()?
+
+> `optional` **generateKey**: (`req`, `config`) => `string`
+
+Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L21)
+
+自定义缓存键生成函数
+
+根据 Request 和配置生成唯一的缓存键
+
+#### Parameters
+
+##### req
+
+`Request`
+
+##### config
+
+[`SiteCacheConfig`](SiteCacheConfig.md)
+
+#### Returns
+
+`string`
+
+***
+
+### onBackgroundUpdate()?
+
+> `optional` **onBackgroundUpdate**: (`promise`) => `void`
+
+Defined in: [core/fetchWithCache.ts:19](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L19)
+
+后台更新 Promise 触发时的回调
+
+#### Parameters
+
+##### promise
+
+`Promise`\<`Response`\>
+
+#### Returns
+
+`void`

package/docs/interfaces/KeyFilterConfig.md

@@ -0,0 +1,33 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / KeyFilterConfig
+
+# Interface: KeyFilterConfig
+
+Defined in: [types.ts:6](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L6)
+
+缓存键过滤配置
+
+用于定义在生成缓存指纹时，哪些字段应该被包含或排除。
+
+## Properties
+
+### exclude?
+
+> `optional` **exclude**: `string`[]
+
+Defined in: [types.ts:10](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L10)
+
+排除（黑名单）：用于排除像 `timestamp`、`nonce` 等干扰缓存命中的动态字段
+
+***
+
+### include?
+
+> `optional` **include**: `string`[]
+
+Defined in: [types.ts:8](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L8)
+
+仅包含（白名单）：如果设置，只有这些字段会参与 Key 的计算

package/docs/interfaces/ProxyConfig.md

@@ -0,0 +1,41 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / ProxyConfig
+
+# Interface: ProxyConfig
+
+Defined in: [types.ts:63](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L63)
+
+代理拦截器全局配置
+
+## Properties
+
+### default
+
+> **default**: [`SiteCacheConfig`](SiteCacheConfig.md)
+
+Defined in: [types.ts:65](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L65)
+
+默认缓存配置，当请求的域名未在 sites 中匹配时使用
+
+***
+
+### sites
+
+> **sites**: `Record`\<`string`, [`SiteCacheConfig`](SiteCacheConfig.md)\>
+
+Defined in: [types.ts:67](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L67)
+
+针对特定域名的精细化缓存配置
+
+***
+
+### storagePath?
+
+> `optional` **storagePath**: `string`
+
+Defined in: [types.ts:69](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L69)
+
+磁盘缓存（cacache）的物理存储路径，可选，默认为系统临时目录