@isdk/proxy 0.1.1 → 0.1.3

package/docs/classes/OfflineCacheMissError.md

@@ -0,0 +1,426 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / OfflineCacheMissError
+
+# Class: OfflineCacheMissError
+
+Defined in: [packages/proxy/src/errors.ts:24](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/errors.ts#L24)
+
+Offline 缓存未命中错误
+
+## Example
+
+```ts
+throw new OfflineCacheMissError('http://example.com/data')
+```
+
+## Extends
+
+- `CommonError`
+
+## Constructors
+
+### Constructor
+
+> **new OfflineCacheMissError**(`url`, `name?`): `OfflineCacheMissError`
+
+Defined in: [packages/proxy/src/errors.ts:26](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/errors.ts#L26)
+
+#### Parameters
+
+##### url
+
+`string` | `number`
+
+##### name?
+
+`string` | `Record`\<`string`, `any`\>
+
+#### Returns
+
+`OfflineCacheMissError`
+
+#### Overrides
+
+`CommonError.constructor`
+
+## Properties
+
+### caller
+
+> **caller**: `string`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:141
+
+#### Inherited from
+
+`CommonError.caller`
+
+***
+
+### cause?
+
+> `optional` **cause**: `unknown`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
+
+#### Inherited from
+
+`CommonError.cause`
+
+***
+
+### code
+
+> **code**: `ErrorCodeType`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:142
+
+the error code
+
+#### Inherited from
+
+`CommonError.code`
+
+***
+
+### data?
+
+> `optional` **data**: `any`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:143
+
+#### Inherited from
+
+`CommonError.data`
+
+***
+
+### message
+
+> **message**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.3/node\_modules/typescript/lib/lib.es5.d.ts:1077
+
+#### Inherited from
+
+`CommonError.message`
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.3/node\_modules/typescript/lib/lib.es5.d.ts:1076
+
+#### Inherited from
+
+`CommonError.name`
+
+***
+
+### stack?
+
+> `optional` **stack**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.3/node\_modules/typescript/lib/lib.es5.d.ts:1078
+
+#### Inherited from
+
+`CommonError.stack`
+
+***
+
+### code
+
+> `static` **code**: `ErrorCode` = `OfflineCacheMissErrorCode`
+
+Defined in: [packages/proxy/src/errors.ts:25](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/errors.ts#L25)
+
+The error code associated with the error.
+
+#### Overrides
+
+`CommonError.code`
+
+***
+
+### stackTraceLimit
+
+> `static` **stackTraceLimit**: `number`
+
+Defined in: node\_modules/.pnpm/@types+node@20.19.26/node\_modules/@types/node/globals.d.ts:68
+
+The `Error.stackTraceLimit` property specifies the number of stack frames
+collected by a stack trace (whether generated by `new Error().stack` or
+`Error.captureStackTrace(obj)`).
+
+The default value is `10` but may be set to any valid JavaScript number. Changes
+will affect any stack trace captured _after_ the value has been changed.
+
+If set to a non-number value, or set to a negative number, stack traces will
+not capture any frames.
+
+#### Inherited from
+
+`CommonError.stackTraceLimit`
+
+## Methods
+
+### fromJSON()
+
+> **fromJSON**(`json`): `BaseError`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:183
+
+#### Parameters
+
+##### json
+
+`any`
+
+#### Returns
+
+`BaseError`
+
+#### Inherited from
+
+`CommonError.fromJSON`
+
+***
+
+### toJSON()
+
+> **toJSON**(): `any`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:165
+
+Returns a JSON representation of the error.
+
+#### Returns
+
+`any`
+
+A JSON representation of the error.
+
+#### Inherited from
+
+`CommonError.toJSON`
+
+***
+
+### captureStackTrace()
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Defined in: node\_modules/.pnpm/@types+node@20.19.26/node\_modules/@types/node/globals.d.ts:52
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+##### targetObject
+
+`object`
+
+##### constructorOpt?
+
+`Function`
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`CommonError.captureStackTrace`
+
+***
+
+### create()
+
+> `static` **create**(`__namedParameters`): `CommonError`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:186
+
+#### Parameters
+
+##### \_\_namedParameters
+
+###### code?
+
+`string` \| `number`
+
+###### data?
+
+`any`
+
+###### error
+
+`string`
+
+###### name?
+
+`string`
+
+#### Returns
+
+`CommonError`
+
+#### Inherited from
+
+`CommonError.create`
+
+***
+
+### createErrorClass()
+
+> `static` **createErrorClass**(`aType`, `aErrorCode?`, `ParentErrorClass?`): *typeof* `BaseError`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:145
+
+Create an Error Class
+
+#### Parameters
+
+##### aType
+
+`string`
+
+the error type(class) name
+
+##### aErrorCode?
+
+`string` | `number` | *typeof* `AbstractError`
+
+##### ParentErrorClass?
+
+*typeof* `BaseError`
+
+the parent error class. defaults to AbstractError
+
+#### Returns
+
+*typeof* `BaseError`
+
+the new Error Class
+
+#### Inherited from
+
+`CommonError.createErrorClass`
+
+***
+
+### fromJSON()
+
+> `static` **fromJSON**(`json`): `BaseError`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.2.2/node\_modules/@isdk/common-error/dist/index.d.ts:182
+
+Creates a new error instance from a JSON representation.
+This method is useful for deserializing an error that was serialized with `toJSON`.
+
+#### Parameters
+
+##### json
+
+`any`
+
+A JSON object representing the error.
+
+#### Returns
+
+`BaseError`
+
+A new instance of the error class (or a subclass).
+
+#### Example
+
+```ts
+const originalError = new NotFoundError('thing');
+const json = originalError.toJSON();
+
+// Deserialize
+const newError = NotFoundError.fromJSON(json);
+console.log(newError instanceof NotFoundError); // true
+console.log(newError.message); // 'Could not find thing.'
+```
+
+#### Inherited from
+
+`CommonError.fromJSON`
+
+***
+
+### prepareStackTrace()
+
+> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
+
+Defined in: node\_modules/.pnpm/@types+node@20.19.26/node\_modules/@types/node/globals.d.ts:56
+
+#### Parameters
+
+##### err
+
+`Error`
+
+##### stackTraces
+
+`CallSite`[]
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+`CommonError.prepareStackTrace`

package/docs/classes/SmartCache.md

@@ -6,9 +6,19 @@
 
 # Class: SmartCache
 
-Defined in: [core/SmartCache.ts:22](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L22)
+Defined in: [packages/proxy/src/core/SmartCache.ts:39](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L39)
 
-智能混合缓存类 (Hybrid Cache)
+智能混合缓存类 (Hybrid Multi-tier Cache)
+
+该类实现了 L1 (内存) 和 L2 (磁盘) 的双层混合存储架构，旨在提供高性能且大容量的缓存能力。
+
+### 核心特性：
+- **双层架构**: L1 使用 LRU 内存缓存（基于 `secondary-cache` 的 LRUCache），L2 使用持久化磁盘缓存（基于 `cacache`）。
+- **大小感知存储**: 自动识别响应体大小。小于阈值的文件同时存于内存和磁盘；超过阈值的文件仅存于磁盘，但其元数据仍保留在内存中。
+- **元数据驻留 (Meta-Residency)**: 无论 Body 多大，Headers、Status、Policy 等信息始终优先从内存读取，确保缓存判定性能。
+- **流式支持**: 支持通过 `setStream` 和 `getStream` 直接操作大数据流，防止 OOM。
+- **一致性保障**: 在并发写入时自动清理内存，确保后续读取不会拿到被污染的旧数据。
+- **内存限制**: 通过 `maxTotalMemorySize` 控制 L1 缓存的总内存占用。
 
 ## Constructors
 
@@ -16,7 +26,7 @@ Defined in: [core/SmartCache.ts:22](https://github.com/isdk/proxy.js/blob/bed37f
 
 > **new SmartCache**(`options`): `SmartCache`
 
-Defined in: [core/SmartCache.ts:27](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L27)
+Defined in: [packages/proxy/src/core/SmartCache.ts:44](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L44)
 
 #### Parameters
 
@@ -32,9 +42,19 @@ Defined in: [core/SmartCache.ts:27](https://github.com/isdk/proxy.js/blob/bed37f
 
 ### clear()
 
-> **clear**(): `Promise`\<`void`\>
+> **clear**(`clearPersistent?`): `Promise`\<`void`\>
+
+Defined in: [packages/proxy/src/core/SmartCache.ts:202](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L202)
+
+Clears the cache. By default, both the in-memory cache and the persistent disk cache are cleared.
+
+#### Parameters
+
+##### clearPersistent?
+
+`boolean` = `true`
 
-Defined in: [core/SmartCache.ts:122](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L122)
+Whether to clear the persistent (disk) cache. Defaults to `true` for backward compatibility.
 
 #### Returns
 
@@ -44,9 +64,11 @@ Defined in: [core/SmartCache.ts:122](https://github.com/isdk/proxy.js/blob/bed37
 
 ### delete()
 
-> **delete**(`key`): `Promise`\<`void`\>
+> **delete**(`key`, `clearPersistent?`): `Promise`\<`void`\>
 
-Defined in: [core/SmartCache.ts:117](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L117)
+Defined in: [packages/proxy/src/core/SmartCache.ts:193](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L193)
+
+Deletes the cache entry for the specified key.
 
 #### Parameters
 
@@ -54,6 +76,14 @@ Defined in: [core/SmartCache.ts:117](https://github.com/isdk/proxy.js/blob/bed37
 
 `string`
 
+The cache key to delete
+
+##### clearPersistent?
+
+`boolean` = `true`
+
+Whether to also delete the entry from persistent (disk) storage. Defaults to `true`.
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -64,10 +94,15 @@ Defined in: [core/SmartCache.ts:117](https://github.com/isdk/proxy.js/blob/bed37
 
 > **get**(`key`): `Promise`\<[`CacheEntry`](../interfaces/CacheEntry.md) \| `null`\>
 
-Defined in: [core/SmartCache.ts:41](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L41)
+Defined in: [packages/proxy/src/core/SmartCache.ts:79](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L79)
 
 获取缓存条目
-如果是小文件，返回带 Buffer 的 Entry；如果是大文件，返回带 ReadStream 的 Entry。
+
+逻辑：
+1. 首先尝试从 L1 内存获取。
+2. 如果内存中有 Body，直接返回（Buffer 类型）。
+3. 如果内存中只有 Meta（大文件），则从 L2 磁盘创建并返回 ReadStream。
+4. 如果内存完全未命中，从磁盘 L2 检索，并根据大小决定是否回填 L1。
 
 #### Parameters
 
@@ -75,17 +110,25 @@ Defined in: [core/SmartCache.ts:41](https://github.com/isdk/proxy.js/blob/bed37f
 
 `string`
 
+缓存指纹键
+
 #### Returns
 
 `Promise`\<[`CacheEntry`](../interfaces/CacheEntry.md) \| `null`\>
 
+完整的缓存条目（带 Buffer 或 Stream 的 Body），未命中返回 null
+
 ***
 
 ### getStream()
 
 > **getStream**(`key`): `ReadableStream`
 
-Defined in: [core/SmartCache.ts:107](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L107)
+Defined in: [packages/proxy/src/core/SmartCache.ts:159](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L159)
+
+获取磁盘读取流
+
+允许直接从 L2 磁盘层以流的形式读取数据，适用于大文件代理。
 
 #### Parameters
 
@@ -93,19 +136,25 @@ Defined in: [core/SmartCache.ts:107](https://github.com/isdk/proxy.js/blob/bed37
 
 `string`
 
+缓存指纹键
+
 #### Returns
 
 `ReadableStream`
 
+Node.js 可读流
+
 ***
 
 ### set()
 
 > **set**(`key`, `body`, `metadata`): `Promise`\<`void`\>
 
-Defined in: [core/SmartCache.ts:85](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L85)
+Defined in: [packages/proxy/src/core/SmartCache.ts:129](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L129)
+
+写入缓存条目 (原子写入)
 
-写入缓存
+适用于已知长度的小型数据块。该操作会同时写入磁盘并回填内存（如果大小未超标）。
 
 #### Parameters
 
@@ -113,14 +162,20 @@ Defined in: [core/SmartCache.ts:85](https://github.com/isdk/proxy.js/blob/bed37f
 
 `string`
 
+缓存指纹键
+
 ##### body
 
 `Buffer`
 
+响应体数据 Buffer
+
 ##### metadata
 
 `Omit`\<[`CacheMetadata`](../interfaces/CacheMetadata.md), `"size"`\>
 
+响应元数据（不含 size，由本方法自动计算）
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -131,7 +186,14 @@ Defined in: [core/SmartCache.ts:85](https://github.com/isdk/proxy.js/blob/bed37f
 
 > **setStream**(`key`, `metadata`): `WritableStream`
 
-Defined in: [core/SmartCache.ts:111](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L111)
+Defined in: [packages/proxy/src/core/SmartCache.ts:175](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/SmartCache.ts#L175)
+
+获取磁盘写入流 (流式缓存)
+
+该方法用于支持真正的流式代理。它会执行以下一致性操作：
+1. 立即清除 L1 内存中的对应键，防止读到旧数据。
+2. 返回一个可写流，数据将直接流入磁盘。
+3. **一致性修复**: 在流写入完成（finish）时再次清理内存，防止写入期间的并发读取将旧数据再次回填进内存。
 
 #### Parameters
 
@@ -139,10 +201,16 @@ Defined in: [core/SmartCache.ts:111](https://github.com/isdk/proxy.js/blob/bed37
 
 `string`
 
+缓存指纹键
+
 ##### metadata
 
 `Omit`\<[`CacheMetadata`](../interfaces/CacheMetadata.md), `"size"`\>
 
+响应元数据
+
 #### Returns
 
 `WritableStream`
+
+Node.js 可写流

package/docs/functions/createCachedFetch.md

@@ -8,7 +8,7 @@
 
 > **createCachedFetch**(`defaultOptions`): (`request`, `fetcher`, `overrideOptions?`) => `Promise`\<`Response`\>
 
-Defined in: [core/createCachedFetch.ts:17](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/createCachedFetch.ts#L17)
+Defined in: [packages/proxy/src/core/createCachedFetch.ts:17](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/createCachedFetch.ts#L17)
 
 缓存请求工厂函数 (针对终端用户的顶层高阶 API)
 

package/docs/functions/createFetchWithCache.md

@@ -8,7 +8,7 @@
 
 > **createFetchWithCache**(`activeCacheWrites?`): (`request`, `fetcher`, `options`) => `Promise`\<`Response`\>
 
-Defined in: [core/createFetchWithCache.ts:16](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/createFetchWithCache.ts#L16)
+Defined in: [packages/proxy/src/core/createFetchWithCache.ts:16](https://github.com/isdk/proxy.js/blob/a1563efa4c3081261eb3af8a6404f1b704b33bf1/src/core/createFetchWithCache.ts#L16)
 
 单一职责高阶函数：专门用于封装和隔离 activeCacheWrites 并发追踪器。