@isdk/proxy 0.1.1 → 0.1.3

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: [packages/proxy/src/types.ts:81](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L81)
 
 站点级缓存配置
 
 ## Properties
 
+### body?
+
+> `optional` **body**: [`BodyFilterConfig`](BodyFilterConfig.md)
+
+Defined in: [packages/proxy/src/types.ts:104](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L104)
+
+请求体过滤配置 (仅限 JSON 类型)。
+当方法为 POST/PUT/PATCH 且为 JSON 格式时，用于从 Body 中提取特定字段参与指纹计算。
+
+***
+
+### cacheRules?
+
+> `optional` **cacheRules**: [`CacheRule`](CacheRule.md)[]
+
+Defined in: [packages/proxy/src/types.ts:93](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/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: [packages/proxy/src/types.ts:99](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/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: [packages/proxy/src/types.ts:108](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L108)
 
-是否强制缓存一切响应（无视 no-store 等不缓存指令），用于极端的离线可用容错场景
+强制缓存：是否忽略 `Cache-Control: no-store` 等指令强制入库。
 
 ***
 
@@ -36,9 +59,31 @@ 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: [packages/proxy/src/types.ts:97](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L97)
+
+请求头过滤配置：决定哪些 Header 参与缓存指纹计算
+
+***
+
+### methods?
+
+> `optional` **methods**: `string`[]
+
+Defined in: [packages/proxy/src/types.ts:87](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L87)
+
+允许缓存的 HTTP 方法列表。
+默认值: ['GET', 'HEAD']。
+若要缓存 POST/PUT，必须在此显式添加，并确保后端响应满足缓存条件（或开启 `forceCache`）。
+
+***
+
+### offline?
+
+> `optional` **offline**: `boolean`
+
+Defined in: [packages/proxy/src/types.ts:110](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L110)
 
-请求头过滤配置
+严格离线模式：不发起任何网络请求，只读缓存。缓存未命中时抛出 OfflineCacheMissError
 
 ***
 
@@ -46,9 +91,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: [packages/proxy/src/types.ts:95](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L95)
 
-Query 参数过滤配置
+Query 参数过滤配置：决定哪些查询参数参与缓存指纹 (Cache Key) 的计算
 
 ***
 
@@ -56,6 +101,6 @@ Query 参数过滤配置
 
 > `optional` **staleIfError**: `boolean`
 
-Defined in: [types.ts:24](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L24)
+Defined in: [packages/proxy/src/types.ts:106](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/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: [packages/proxy/src/core/SmartCache.ts:10](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/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: [packages/proxy/src/core/SmartCache.ts:14](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L14)
 
 内存缓存阈值（字节）。响应体大小超过此值时，Body 将只存入磁盘，而 Meta 仍保留在内存。默认 1MB。
 
 ***
 
+### maxTotalMemorySize?
+
+> `optional` **maxTotalMemorySize**: `number`
+
+Defined in: [packages/proxy/src/core/SmartCache.ts:16](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L16)
+
+内存缓存总大小阈值（字节）。默认 100MB。超过此值将清空内存缓存。
+
+***
+
 ### memoryOptions?
 
-> `optional` **memoryOptions**: `Partial`\<`KeyvCacheableMemoryOptions`\>
+> `optional` **memoryOptions**: `object`
+
+Defined in: [packages/proxy/src/core/SmartCache.ts:18](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/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: [packages/proxy/src/core/SmartCache.ts:12](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L12)
 
 磁盘缓存的物理路径。如果不提供，将默认使用系统临时目录。

package/docs/variables/OfflineCacheMissErrorCode.md

@@ -0,0 +1,18 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / OfflineCacheMissErrorCode
+
+# Variable: OfflineCacheMissErrorCode
+
+> `const` **OfflineCacheMissErrorCode**: `OfflineCacheMiss` = `ErrorCode.OfflineCacheMiss`
+
+Defined in: [packages/proxy/src/errors.ts:14](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/errors.ts#L14)
+
+Offline 缓存未命中错误代码
+
+当处于 offline 模式且请求的 URL 没有对应缓存时抛出。
+这帮助调用者区分：
+- 网络请求失败（其他错误类型）
+- offline 模式下缓存不存在（本错误）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isdk/proxy",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
+    "@isdk/common-error": "^0.2.2",
     "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",