@isdk/proxy 0.1.2 → 0.1.3

package/docs/interfaces/PrefetchOptions.md

@@ -0,0 +1,107 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / PrefetchOptions
+
+# Interface: PrefetchOptions
+
+Defined in: [packages/proxy/src/core/prefetch.ts:17](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L17)
+
+## Properties
+
+### cache
+
+> **cache**: [`SmartCache`](../classes/SmartCache.md)
+
+Defined in: [packages/proxy/src/core/prefetch.ts:23](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L23)
+
+SmartCache 实例
+
+***
+
+### concurrency?
+
+> `optional` **concurrency**: `number`
+
+Defined in: [packages/proxy/src/core/prefetch.ts:27](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L27)
+
+并发数，默认 3
+
+***
+
+### config
+
+> **config**: [`ProxyConfig`](ProxyConfig.md)
+
+Defined in: [packages/proxy/src/core/prefetch.ts:21](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L21)
+
+完整的代理配置
+
+***
+
+### fetcher()?
+
+> `optional` **fetcher**: (`req`) => `Promise`\<`Response`\>
+
+Defined in: [packages/proxy/src/core/prefetch.ts:25](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L25)
+
+自定义 fetcher，默认使用 globalThis.fetch
+
+#### Parameters
+
+##### req
+
+`Request`
+
+#### Returns
+
+`Promise`\<`Response`\>
+
+***
+
+### onProgress()?
+
+> `optional` **onProgress**: (`completed`, `total`, `url`) => `void`
+
+Defined in: [packages/proxy/src/core/prefetch.ts:29](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L29)
+
+进度回调 (completed, total, url)
+
+#### Parameters
+
+##### completed
+
+`number`
+
+##### total
+
+`number`
+
+##### url
+
+`string`
+
+#### Returns
+
+`void`
+
+***
+
+### signal?
+
+> `optional` **signal**: `AbortSignal`
+
+Defined in: [packages/proxy/src/core/prefetch.ts:31](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L31)
+
+取消信号
+
+***
+
+### urls
+
+> **urls**: [`PrefetchRequest`](PrefetchRequest.md)[]
+
+Defined in: [packages/proxy/src/core/prefetch.ts:19](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L19)
+
+要预缓存的 URL 列表及其请求选项

package/docs/interfaces/PrefetchRequest.md

@@ -0,0 +1,31 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / PrefetchRequest
+
+# Interface: PrefetchRequest
+
+Defined in: [packages/proxy/src/core/prefetch.ts:10](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L10)
+
+预缓存请求选项
+
+## Properties
+
+### request?
+
+> `optional` **request**: `RequestInit`
+
+Defined in: [packages/proxy/src/core/prefetch.ts:14](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L14)
+
+可选的请求配置（method, headers, body 等）
+
+***
+
+### url
+
+> **url**: `string`
+
+Defined in: [packages/proxy/src/core/prefetch.ts:12](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L12)
+
+请求 URL

package/docs/interfaces/PrefetchResult.md

@@ -0,0 +1,47 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / PrefetchResult
+
+# Interface: PrefetchResult
+
+Defined in: [packages/proxy/src/core/prefetch.ts:34](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L34)
+
+## Properties
+
+### errors?
+
+> `optional` **errors**: `object`[]
+
+Defined in: [packages/proxy/src/core/prefetch.ts:40](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L40)
+
+失败详情
+
+#### error
+
+> **error**: `Error`
+
+#### url
+
+> **url**: `string`
+
+***
+
+### failed
+
+> **failed**: `number`
+
+Defined in: [packages/proxy/src/core/prefetch.ts:38](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L38)
+
+失败数量
+
+***
+
+### succeeded
+
+> **succeeded**: `number`
+
+Defined in: [packages/proxy/src/core/prefetch.ts:36](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/prefetch.ts#L36)
+
+成功数量

package/docs/interfaces/ProxyConfig.md

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

package/docs/interfaces/SiteCacheConfig.md

@@ -6,7 +6,7 @@
 
 # Interface: SiteCacheConfig
 
-Defined in: [types.ts:81](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L81)
+Defined in: [packages/proxy/src/types.ts:81](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L81)
 
 站点级缓存配置
 
@@ -16,7 +16,7 @@ Defined in: [types.ts:81](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5b
 
 > `optional` **body**: [`BodyFilterConfig`](BodyFilterConfig.md)
 
-Defined in: [types.ts:104](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L104)
+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 中提取特定字段参与指纹计算。
@@ -27,7 +27,7 @@ Defined in: [types.ts:104](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5
 
 > `optional` **cacheRules**: [`CacheRule`](CacheRule.md)[]
 
-Defined in: [types.ts:93](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L93)
+Defined in: [packages/proxy/src/types.ts:93](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L93)
 
 精细化缓存规则列表。
 如果配置了此项，请求必须匹配其中至少一条规则才会被允许进入缓存流程。
@@ -39,7 +39,7 @@ Defined in: [types.ts:93](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5b
 
 > `optional` **cookies**: [`KeyFilterConfig`](KeyFilterConfig.md)
 
-Defined in: [types.ts:99](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L99)
+Defined in: [packages/proxy/src/types.ts:99](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L99)
 
 Cookie 过滤配置：决定哪些 Cookie 字段参与缓存指纹计算
 
@@ -49,7 +49,7 @@ Cookie 过滤配置：决定哪些 Cookie 字段参与缓存指纹计算
 
 > `optional` **forceCache**: `boolean`
 
-Defined in: [types.ts:108](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L108)
+Defined in: [packages/proxy/src/types.ts:108](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L108)
 
 强制缓存：是否忽略 `Cache-Control: no-store` 等指令强制入库。
 
@@ -59,7 +59,7 @@ Defined in: [types.ts:108](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5
 
 > `optional` **headers**: [`KeyFilterConfig`](KeyFilterConfig.md)
 
-Defined in: [types.ts:97](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L97)
+Defined in: [packages/proxy/src/types.ts:97](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L97)
 
 请求头过滤配置：决定哪些 Header 参与缓存指纹计算
 
@@ -69,7 +69,7 @@ Defined in: [types.ts:97](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5b
 
 > `optional` **methods**: `string`[]
 
-Defined in: [types.ts:87](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L87)
+Defined in: [packages/proxy/src/types.ts:87](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L87)
 
 允许缓存的 HTTP 方法列表。
 默认值: ['GET', 'HEAD']。
@@ -77,11 +77,21 @@ Defined in: [types.ts:87](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5b
 
 ***
 
+### 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
+
+***
+
 ### query?
 
 > `optional` **query**: [`KeyFilterConfig`](KeyFilterConfig.md)
 
-Defined in: [types.ts:95](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L95)
+Defined in: [packages/proxy/src/types.ts:95](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/types.ts#L95)
 
 Query 参数过滤配置：决定哪些查询参数参与缓存指纹 (Cache Key) 的计算
 
@@ -91,6 +101,6 @@ Query 参数过滤配置：决定哪些查询参数参与缓存指纹 (Cache Key
 
 > `optional` **staleIfError**: `boolean`
 
-Defined in: [types.ts:106](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L106)
+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/76fee3a101f98e5bf29599fe7ea02ab06479cf70/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,7 +16,7 @@ SmartCache 选项
 
 > `optional` **maxMemorySize**: `number`
 
-Defined in: [core/SmartCache.ts:14](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/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。
 
@@ -26,7 +26,7 @@ Defined in: [core/SmartCache.ts:14](https://github.com/isdk/proxy.js/blob/76fee3
 
 > `optional` **maxTotalMemorySize**: `number`
 
-Defined in: [core/SmartCache.ts:16](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L16)
+Defined in: [packages/proxy/src/core/SmartCache.ts:16](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L16)
 
 内存缓存总大小阈值（字节）。默认 100MB。超过此值将清空内存缓存。
 
@@ -36,7 +36,7 @@ Defined in: [core/SmartCache.ts:16](https://github.com/isdk/proxy.js/blob/76fee3
 
 > `optional` **memoryOptions**: `object`
 
-Defined in: [core/SmartCache.ts:18](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L18)
+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)
 
@@ -62,6 +62,6 @@ Defined in: [core/SmartCache.ts:18](https://github.com/isdk/proxy.js/blob/76fee3
 
 > `optional` **storagePath**: `string`
 
-Defined in: [core/SmartCache.ts:12](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/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.2",
+  "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,7 +19,7 @@
     }
   },
   "dependencies": {
-    "@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",