@isdk/proxy 0.1.1 → 0.1.2

package/docs/interfaces/FetchWithCacheOptions.md

@@ -6,7 +6,7 @@
 
 # Interface: FetchWithCacheOptions
 
-Defined in: [core/fetchWithCache.ts:11](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L11)
+Defined in: [core/fetchWithCache.ts:12](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L12)
 
 fetchWithCache 选项
 
@@ -20,7 +20,7 @@ fetchWithCache 选项
 
 > `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)
+Defined in: [core/fetchWithCache.ts:28](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L28)
 
 并发写入任务追踪器
 传入一个外部维护的 Map，用于在跨请求、跨实例时防止针对同一文件的并发重复下载。
@@ -32,7 +32,7 @@ Map 的 Key 是缓存 Key，Value 是一个代表写入完成的 Promise。
 
 > `optional` **backgroundUpdate**: `boolean`
 
-Defined in: [core/fetchWithCache.ts:17](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L17)
+Defined in: [core/fetchWithCache.ts:18](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L18)
 
 是否启用后台异步更新 (SWR)
 
@@ -42,7 +42,7 @@ Defined in: [core/fetchWithCache.ts:17](https://github.com/isdk/proxy.js/blob/be
 
 > **cache**: [`SmartCache`](../classes/SmartCache.md)
 
-Defined in: [core/fetchWithCache.ts:13](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L13)
+Defined in: [core/fetchWithCache.ts:14](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L14)
 
 混合缓存实例
 
@@ -52,7 +52,7 @@ Defined in: [core/fetchWithCache.ts:13](https://github.com/isdk/proxy.js/blob/be
 
 > **config**: [`SiteCacheConfig`](SiteCacheConfig.md)
 
-Defined in: [core/fetchWithCache.ts:15](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L15)
+Defined in: [core/fetchWithCache.ts:16](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L16)
 
 站点级缓存配置
 
@@ -60,13 +60,28 @@ Defined in: [core/fetchWithCache.ts:15](https://github.com/isdk/proxy.js/blob/be
 
 ### generateKey()?
 
-> `optional` **generateKey**: (`req`, `config`) => `string`
+> `optional` **generateKey**: (`req`, `config`) => `Promise`\<`string`\>
 
-Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L21)
+Defined in: [core/fetchWithCache.ts:22](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L22)
 
 自定义缓存键生成函数
 
-根据 Request 和配置生成唯一的缓存键
+根据 Request 对象和站点配置生成唯一的缓存指纹 (异步)
+
+该函数是缓存系统的核心组件，用于将复杂的 HTTP 请求对象转换为唯一的 SHA-256 字符串。
+它实现了高度可定制的提取逻辑，允许通过配置排除掉请求中不稳定的因素（如时间戳、Nonce 等）。
+
+### 生成指纹包含的要素：
+1. **Method**: 请求方法（统一转为大写）。
+2. **Host & Path**: 请求的域名和路径。
+3. **Query Params**: URL 查询参数，受 `config.query` 过滤影响。
+4. **Headers**: 请求头信息，受 `config.headers` 过滤影响。默认排除 `cookie` 头。
+5. **Cookies**: 特别提取的 Cookie 字段，受 `config.cookies` 过滤影响。
+6. **Request Body**:
+   - 对于 `POST`, `PUT`, `PATCH` 请求，会自动尝试读取 Body。
+   - **JSON 类型**: 如果 `Content-Type` 包含 `application/json`，则解析为对象并应用 `config.body` 过滤。
+   - **非 JSON/流类型**: 回退到对原始 Body 字节流进行 SHA-256 哈希计算。
+   - **安全性**: 使用 `req.clone()` 读取 Body，确保不影响后续真实的 Fetch 请求流消费。
 
 #### Parameters
 
@@ -74,13 +89,28 @@ Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/be
 
 `Request`
 
+原始 Web 标准 Request 对象。
+
 ##### config
 
 [`SiteCacheConfig`](SiteCacheConfig.md)
 
+站点级缓存配置，决定了哪些字段参与指纹计算。
+
 #### Returns
 
-`string`
+`Promise`\<`string`\>
+
+返回一个 64 位十六进制的 SHA-256 哈希字符串作为缓存键。
+
+#### Example
+
+```typescript
+const cacheKey = await generateCacheKey(request, {
+  query: { exclude: ['timestamp'] },
+  body: { include: ['id', 'action'] }
+});
+```
 
 ***
 
@@ -88,7 +118,7 @@ Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/be
 
 > `optional` **onBackgroundUpdate**: (`promise`) => `void`
 
-Defined in: [core/fetchWithCache.ts:19](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L19)
+Defined in: [core/fetchWithCache.ts:20](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L20)
 
 后台更新 Promise 触发时的回调
 

package/docs/interfaces/KeyFilterConfig.md

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

package/docs/interfaces/ProxyConfig.md

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

package/docs/interfaces/SiteCacheConfig.md

@@ -6,19 +6,42 @@
 
 # Interface: SiteCacheConfig
 
-Defined in: [types.ts:16](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L16)
+Defined in: [types.ts:81](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L81)
 
 站点级缓存配置
 
 ## Properties
 
+### body?
+
+> `optional` **body**: [`BodyFilterConfig`](BodyFilterConfig.md)
+
+Defined in: [types.ts:104](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L104)
+
+请求体过滤配置 (仅限 JSON 类型)。
+当方法为 POST/PUT/PATCH 且为 JSON 格式时，用于从 Body 中提取特定字段参与指纹计算。
+
+***
+
+### cacheRules?
+
+> `optional` **cacheRules**: [`CacheRule`](CacheRule.md)[]
+
+Defined in: [types.ts:93](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L93)
+
+精细化缓存规则列表。
+如果配置了此项，请求必须匹配其中至少一条规则才会被允许进入缓存流程。
+适用于只希望缓存特定 API 接口的场景。
+
+***
+
 ### cookies?
 
 > `optional` **cookies**: [`KeyFilterConfig`](KeyFilterConfig.md)
 
-Defined in: [types.ts:22](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L22)
+Defined in: [types.ts:99](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L99)
 
-Cookie 过滤配置
+Cookie 过滤配置：决定哪些 Cookie 字段参与缓存指纹计算
 
 ***
 
@@ -26,9 +49,9 @@ Cookie 过滤配置
 
 > `optional` **forceCache**: `boolean`
 
-Defined in: [types.ts:26](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L26)
+Defined in: [types.ts:108](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L108)
 
-是否强制缓存一切响应（无视 no-store 等不缓存指令），用于极端的离线可用容错场景
+强制缓存：是否忽略 `Cache-Control: no-store` 等指令强制入库。
 
 ***
 
@@ -36,9 +59,21 @@ Defined in: [types.ts:26](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > `optional` **headers**: [`KeyFilterConfig`](KeyFilterConfig.md)
 
-Defined in: [types.ts:20](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L20)
+Defined in: [types.ts:97](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L97)
+
+请求头过滤配置：决定哪些 Header 参与缓存指纹计算
+
+***
+
+### methods?
+
+> `optional` **methods**: `string`[]
+
+Defined in: [types.ts:87](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L87)
 
-请求头过滤配置
+允许缓存的 HTTP 方法列表。
+默认值: ['GET', 'HEAD']。
+若要缓存 POST/PUT，必须在此显式添加，并确保后端响应满足缓存条件（或开启 `forceCache`）。
 
 ***
 
@@ -46,9 +81,9 @@ Defined in: [types.ts:20](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > `optional` **query**: [`KeyFilterConfig`](KeyFilterConfig.md)
 
-Defined in: [types.ts:18](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L18)
+Defined in: [types.ts:95](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L95)
 
-Query 参数过滤配置
+Query 参数过滤配置：决定哪些查询参数参与缓存指纹 (Cache Key) 的计算
 
 ***
 
@@ -56,6 +91,6 @@ Query 参数过滤配置
 
 > `optional` **staleIfError**: `boolean`
 
-Defined in: [types.ts:24](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L24)
+Defined in: [types.ts:106](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L106)
 
-当后端请求失败且存在旧缓存时，是否强制返回旧缓存（容错机制）
+容错机制：当后端请求失败（网络错误或 5xx）且存在旧缓存时，是否强制返回旧缓存

package/docs/interfaces/SmartCacheOptions.md

@@ -6,7 +6,7 @@
 
 # Interface: SmartCacheOptions
 
-Defined in: [core/SmartCache.ts:10](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L10)
+Defined in: [core/SmartCache.ts:10](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L10)
 
 SmartCache 选项
 
@@ -16,19 +16,45 @@ SmartCache 选项
 
 > `optional` **maxMemorySize**: `number`
 
-Defined in: [core/SmartCache.ts:14](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L14)
+Defined in: [core/SmartCache.ts:14](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L14)
 
 内存缓存阈值（字节）。响应体大小超过此值时，Body 将只存入磁盘，而 Meta 仍保留在内存。默认 1MB。
 
 ***
 
+### maxTotalMemorySize?
+
+> `optional` **maxTotalMemorySize**: `number`
+
+Defined in: [core/SmartCache.ts:16](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L16)
+
+内存缓存总大小阈值（字节）。默认 100MB。超过此值将清空内存缓存。
+
+***
+
 ### memoryOptions?
 
-> `optional` **memoryOptions**: `Partial`\<`KeyvCacheableMemoryOptions`\>
+> `optional` **memoryOptions**: `object`
+
+Defined in: [core/SmartCache.ts:18](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L18)
+
+透传给 L1 (Memory) 的高级配置 (secondary-cache LRUCache options)
+
+#### Index Signature
+
+\[`key`: `string`\]: `any`
+
+#### capacity?
+
+> `optional` **capacity**: `number`
+
+#### cleanInterval?
+
+> `optional` **cleanInterval**: `number`
 
-Defined in: [core/SmartCache.ts:16](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L16)
+#### expires?
 
-透传给 L1 (Memory) 的高级配置
+> `optional` **expires**: `number`
 
 ***
 
@@ -36,6 +62,6 @@ Defined in: [core/SmartCache.ts:16](https://github.com/isdk/proxy.js/blob/bed37f
 
 > `optional` **storagePath**: `string`
 
-Defined in: [core/SmartCache.ts:12](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L12)
+Defined in: [core/SmartCache.ts:12](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L12)
 
 磁盘缓存的物理路径。如果不提供，将默认使用系统临时目录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isdk/proxy",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A framework-agnostic, high-performance hybrid caching middleware with SWR, request collapsing, and stale-if-error support.",
   "license": "MIT",
   "author": "Riceball LEE <snowyu.lee@gmail.com>",
@@ -19,13 +19,14 @@
     }
   },
   "dependencies": {
-    "@cacheable/memory": "^2.0.8",
     "@isdk/common-error": "^0.2.0",
     "cacache": "^20.0.4",
     "events-ex": "^2.3.1",
     "http-cache-semantics": "^4.2.0",
     "lodash-es": "^4.18.1",
     "nanoid": "^5.1.11",
+    "picomatch": "^4.0.4",
+    "secondary-cache": "^2.1.0",
     "util-ex": "^2.5.2"
   },
   "devDependencies": {
@@ -40,6 +41,7 @@
     "@types/jsdom": "^27.0.0",
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^20.0.0",
+    "@types/picomatch": "^4.0.3",
     "@typescript-eslint/eslint-plugin": "~8.41.0",
     "eslint": "^9.34.0",
     "eslint-config-prettier": "^10.1.8",