xxf_react 0.7.4 → 0.7.6

package/README.md

@@ -18,20 +18,21 @@ This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com)
 
 ## 模块文档
 
-| 模块                                       | 说明                      |
-|------------------------------------------|-------------------------|
-| [event-bus](./src/event-bus/README.md)   | 事件总线，支持跨 Tab 通信         |
-| [fetch](./src/fetch/README.md)           | 带超时控制的 fetch 封装         |
-| [http](./src/http/README.md)             | 超强网络框架设计                |
-| [flow](./src/flow/README.md)             | Promise 扩展，全局错误处理       |
-| [foundation](./src/foundation/README.md) | 基础工具，性能监控               |
-| [layout](./src/layout/README.md)         | 布局组件，悬浮交互               |
-| [media](./src/media/README.md)           | 媒体组件，视频播放               |
-| [models](./src/models/README.md)         | 数据模型，API 响应类型           |
-| [refresh](./src/refresh/README.md)       | 刷新加载，分页加载更多             |
-| [responsive](./src/responsive/README.md) | 响应式布局，设备检测              |
-| [sse](./src/sse/README.md)               | Server-Sent Events 连接管理 |
-| [utils](./src/utils/README.md)           | 工具函数，滚动定位、组件刷新          |
+| 模块                                       | 说明                                    |
+|------------------------------------------|---------------------------------------|
+| [cache](./src/cache/README.md)           | 通用 LRU 缓存，IndexedDB 持久化，快速选择算法优化    |
+| [event-bus](./src/event-bus/README.md)   | 事件总线，支持跨 Tab 通信                       |
+| [fetch](./src/fetch/README.md)           | 带超时控制的 fetch 封装                       |
+| [flow](./src/flow/README.md)             | Promise 扩展，全局错误处理                     |
+| [foundation](./src/foundation/README.md) | 基础工具，性能监控                             |
+| [http](./src/http/README.md)             | HTTP 网络框架，双层缓存，6 种缓存模式，类 Retrofit API |
+| [layout](./src/layout/README.md)         | 布局组件，悬浮交互                             |
+| [media](./src/media/README.md)           | 媒体组件，视频播放                             |
+| [models](./src/models/README.md)         | 数据模型，API 响应类型                         |
+| [refresh](./src/refresh/README.md)       | 刷新加载，分页加载更多                           |
+| [responsive](./src/responsive/README.md) | 响应式布局，设备检测                            |
+| [sse](./src/sse/README.md)               | Server-Sent Events 连接管理               |
+| [utils](./src/utils/README.md)           | 工具函数，滚动定位、组件刷新                        |
 
 ## 详细文档
 

package/dist/cache/CacheEntry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheEntry.d.ts","sourceRoot":"","sources":["../../src/cache/CacheEntry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACnC,WAAW;IACX,IAAI,EAAE,CAAC,CAAA;IACP,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa;IACb,GAAG,EAAE,MAAM,CAAA;CACd"}

package/dist/cache/DiskCacheConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiskCacheConfig.d.ts","sourceRoot":"","sources":["../../src/cache/DiskCacheConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC5B,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,gBAAgB;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;CACjB"}

package/dist/{http/cache → cache}/DiskLruCache.d.ts

@@ -7,8 +7,10 @@
  * - 支持 TTL 过期
  * - 批量清理优化性能
  * - 防污染：返回数据的深拷贝
+ * - 使用快速选择算法优化淘汰性能 O(n)
  */
-import type { CacheEntry, DiskLruCacheConfig } from '../types';
+import type { CacheEntry } from './CacheEntry';
+import type { DiskLruCacheConfig } from './DiskCacheConfig';
 export declare class DiskLruCache {
     private store;
     private config;
@@ -48,6 +50,7 @@ export declare class DiskLruCache {
     has(key: string): Promise<boolean>;
     /**
      * 淘汰最旧的缓存条目（失败静默忽略）
+     * 使用快速选择算法，平均时间复杂度 O(n)
      */
     private evict;
     /**

package/dist/cache/DiskLruCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiskLruCache.d.ts","sourceRoot":"","sources":["../../src/cache/DiskLruCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AA6D3D,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,MAAM,EAAE,kBAAkB;IAQtC;;OAEG;YACW,YAAY;IAiB1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmCxD;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAexC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxC;;;OAGG;YACW,KAAK;IAwCnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAS7B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAQlC"}

package/dist/{http/cache → cache}/DiskLruCache.js

@@ -7,9 +7,59 @@
  * - 支持 TTL 过期
  * - 批量清理优化性能
  * - 防污染：返回数据的深拷贝
+ * - 使用快速选择算法优化淘汰性能 O(n)
  */
 import { get, set, del, clear as clearStore, createStore } from 'idb-keyval';
 const META_KEY = '__lru_metadata__';
+/**
+ * 快速选择算法：找出数组中最小的 k 个元素
+ * 平均时间复杂度 O(n)，比完整排序 O(n log n) 更高效
+ */
+function quickSelectSmallestK(items, k, getValue) {
+    if (k <= 0 || items.length === 0)
+        return [];
+    if (k >= items.length)
+        return items;
+    // 复制数组避免修改原数组
+    const arr = [...items];
+    const n = arr.length;
+    // 分区函数
+    const partition = (left, right, pivotIndex) => {
+        const pivotValue = getValue(arr[pivotIndex]);
+        [arr[pivotIndex], arr[right]] = [arr[right], arr[pivotIndex]];
+        let storeIndex = left;
+        for (let i = left; i < right; i++) {
+            if (getValue(arr[i]) < pivotValue) {
+                ;
+                [arr[storeIndex], arr[i]] = [arr[i], arr[storeIndex]];
+                storeIndex++;
+            }
+        }
+        // 将 pivot 移回正确位置
+        ;
+        [arr[storeIndex], arr[right]] = [arr[right], arr[storeIndex]];
+        return storeIndex;
+    };
+    // 快速选择主逻辑
+    let left = 0;
+    let right = n - 1;
+    while (left < right) {
+        // 使用中间元素作为 pivot（比随机选择更稳定）
+        const pivotIndex = left + Math.floor((right - left) / 2);
+        const newPivotIndex = partition(left, right, pivotIndex);
+        if (newPivotIndex === k) {
+            break;
+        }
+        else if (newPivotIndex < k) {
+            left = newPivotIndex + 1;
+        }
+        else {
+            right = newPivotIndex - 1;
+        }
+    }
+    // 返回前 k 个元素
+    return arr.slice(0, k);
+}
 export class DiskLruCache {
     constructor(config) {
         this.metadata = null;
@@ -174,6 +224,7 @@ export class DiskLruCache {
     }
     /**
      * 淘汰最旧的缓存条目（失败静默忽略）
+     * 使用快速选择算法，平均时间复杂度 O(n)
      */
     async evict() {
         // 防止并发淘汰
@@ -184,10 +235,10 @@ export class DiskLruCache {
             const meta = await this.loadMetadata();
             // 计算需要淘汰的数量
             const evictCount = Math.ceil(this.config.maxSize * this.config.cleanupThreshold);
-            // 按访问时间排序
-            const sorted = Object.entries(meta.entries).sort((a, b) => a[1].accessTime - b[1].accessTime);
-            // 淘汰最旧的
-            const toEvict = sorted.slice(0, evictCount);
+            // 使用快速选择算法找出访问时间最早的 k 个条目 O(n)
+            const entries = Object.entries(meta.entries);
+            const toEvict = quickSelectSmallestK(entries, evictCount, ([, entry]) => entry.accessTime);
+            // 淘汰选中的条目
             for (const [key] of toEvict) {
                 try {
                     await del(key, this.store);

package/dist/cache/LruMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LruMetadata.d.ts","sourceRoot":"","sources":["../../src/cache/LruMetadata.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IACzC,WAAW;IACX,KAAK,EAAE,MAAM,CAAA;CAChB"}

package/dist/cache/index.d.ts

@@ -0,0 +1,5 @@
+export type { CacheEntry } from './CacheEntry';
+export type { DiskLruCacheConfig, HttpCacheConfig } from './DiskCacheConfig';
+export type { LruMetadataEntry, LruMetadata } from './LruMetadata';
+export { DiskLruCache } from './DiskLruCache';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAG5E,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAGlE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/cache/index.js

@@ -0,0 +1,2 @@
+// 磁盘缓存实现
+export { DiskLruCache } from './DiskLruCache';

package/dist/http/api/ApiBuilder.d.ts

@@ -38,6 +38,13 @@ import type { RequestConfig, ApiOptions, CacheConfig, HttpClientConfig } from '.
  * 基础 API 调用选项（不含 body）
  */
 type BaseApiOptions = Omit<ApiOptions, 'body'>;
+/**
+ * 强制 TypeScript 展开交叉类型为单一对象类型
+ * 用于用户自定义接口类型时使用
+ */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 /**
  * 带 body 的 API 调用选项（body 必需）
  */
@@ -133,8 +140,10 @@ type EmptyApi = {};
  * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
  *
  * 建议：
- * - 保持单个 builder 的端点数量在 4 个以内
+ * - 保持单个 builder 的端点数量在 4 个以内以获得最佳类型推断
  * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ * - 可以使用导出的 `ApiEndpointWithBody`、`ApiEndpointWithoutBody` 等类型
+ *   来定义自己的接口类型，获得更精确的类型检查
  *
  * @example
  * ```ts

package/dist/http/api/ApiBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}

package/dist/http/api/ApiBuilder.js

@@ -43,8 +43,10 @@ import { HttpClient } from '../client/HttpClient';
  * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
  *
  * 建议：
- * - 保持单个 builder 的端点数量在 4 个以内
+ * - 保持单个 builder 的端点数量在 4 个以内以获得最佳类型推断
  * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ * - 可以使用导出的 `ApiEndpointWithBody`、`ApiEndpointWithoutBody` 等类型
+ *   来定义自己的接口类型，获得更精确的类型检查
  *
  * @example
  * ```ts

package/dist/http/api/index.d.ts

@@ -1,2 +1,2 @@
-export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './ApiBuilder';
+export { ApiBuilder, type ApiEndpoint, type ApiDefinition, type ApiEndpointWithBody, type ApiEndpointWithoutBody, type ApiEndpointWithBodyRequired, type ApiEndpointWithBodyOptional, type Simplify, } from './ApiBuilder';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,QAAQ,GAChB,MAAM,cAAc,CAAA"}

package/dist/http/api/index.js

@@ -1 +1 @@
-export { ApiBuilder } from './ApiBuilder';
+export { ApiBuilder, } from './ApiBuilder';

package/dist/http/cache/HttpCache.d.ts

@@ -7,7 +7,7 @@
  * - 容错：缓存操作失败不影响正常业务
  * - 防污染：返回数据的深拷贝，防止上层修改影响缓存
  */
-import { DiskLruCache } from './DiskLruCache';
+import { DiskLruCache } from '../../cache';
 import type { CacheEntry, HttpCacheConfig } from '../types';
 export declare class HttpCache {
     private memoryCache;

package/dist/http/cache/HttpCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpCache.d.ts","sourceRoot":"","sources":["../../../src/http/cache/HttpCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG3D,qBAAa,SAAS;IAClB,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,SAAS,CAAc;gBAEnB,MAAM,EAAE,eAAe;IAcnC;;;;OAIG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAwCxD;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;OAGG;IACH,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAgBnD;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,IAAI;IAc3D;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBxC;;OAEG;IACH,YAAY,IAAI,YAAY;IAI5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO/B"}
+{"version":3,"file":"HttpCache.d.ts","sourceRoot":"","sources":["../../../src/http/cache/HttpCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG3D,qBAAa,SAAS;IAClB,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,SAAS,CAAc;gBAEnB,MAAM,EAAE,eAAe;IAcnC;;;;OAIG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAwCxD;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;OAGG;IACH,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAgBnD;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,IAAI;IAc3D;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBxC;;OAEG;IACH,YAAY,IAAI,YAAY;IAI5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO/B"}

package/dist/http/cache/HttpCache.js

@@ -8,7 +8,7 @@
  * - 防污染：返回数据的深拷贝，防止上层修改影响缓存
  */
 import { lru } from 'tiny-lru';
-import { DiskLruCache } from './DiskLruCache';
+import { DiskLruCache } from '../../cache';
 import { copy } from '../../foundation';
 export class HttpCache {
     constructor(config) {

package/dist/http/cache/index.d.ts

@@ -1,3 +1,3 @@
-export { DiskLruCache } from './DiskLruCache';
+export { DiskLruCache } from '../../cache/DiskLruCache';
 export { HttpCache } from './HttpCache';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/dist/http/cache/index.js

@@ -1,2 +1,2 @@
-export { DiskLruCache } from './DiskLruCache';
+export { DiskLruCache } from '../../cache/DiskLruCache';
 export { HttpCache } from './HttpCache';

package/dist/http/client/HttpClient.js

@@ -85,7 +85,7 @@ export class HttpClient {
             memoryCacheMaxSize: 100,
             diskCacheMaxSize: 500,
             dbName: 'xxf-http-cache',
-            defaultKeyHeaders: ['Authorization'],
+            defaultKeyHeaders: [], // 默认不包含任何 header，避免 token 变化导致缓存失效
             defaultCache: undefined, // 默认不缓存 (OnlyRemote)
             cacheInterceptor: undefined, // 默认无拦截器
             ...config,

package/dist/http/demo/api-builder.demo.d.ts

@@ -1,10 +1,12 @@
 /**
  * ApiBuilder 使用示例
  *
- * 此文件演示 ApiBuilder 的类型安全特性：
+ * 此文件演示 ApiBuilder 的核心特性：
  * 1. 泛型累积 - 链式调用自动累积端点类型
  * 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
  * 3. 端点名称字面量 - 调用不存在的端点会编译报错
+ * 4. 缓存策略 - CacheMode 控制缓存行为
+ * 5. 多次响应 - 支持缓存优先场景下的两次数据返回
  */
 /** 用户实体 */
 interface User {
@@ -31,23 +33,70 @@ interface PaginatedResponse<T> {
     pageSize: number;
 }
 export declare const userApi: object & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<User[]>;
+    [x: string]: ApiEndpointWithoutBody<User[]>;
 } & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<User>;
+    [x: string]: ApiEndpointWithoutBody<User>;
 } & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<PaginatedResponse<User>>;
+    [x: string]: ApiEndpointWithoutBody<PaginatedResponse<User>>;
 } & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, CreateUserDTO>;
+    [x: string]: import("..").ApiEndpointWithBodyRequired<User, CreateUserDTO>;
 } & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyOptional<void>;
+    [x: string]: import("..").ApiEndpointWithBodyOptional<void>;
 } & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, UpdateUserDTO>;
+    [x: string]: import("..").ApiEndpointWithBodyRequired<User, UpdateUserDTO>;
 } & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, Partial<UpdateUserDTO>>;
+    [x: string]: import("..").ApiEndpointWithBodyRequired<User, Partial<UpdateUserDTO>>;
 } & {
-    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<void>;
+    [x: string]: ApiEndpointWithoutBody<void>;
 };
 declare function demo(): Promise<void>;
+/**
+ * CacheMode 枚举值说明：
+ *
+ * - OnlyRemote:   只请求网络，不使用缓存（适用于实时性要求高的数据）
+ * - OnlyCache:    只读取缓存，不请求网络（适用于离线场景）
+ * - FirstCache:   先返回缓存，再请求网络更新（可能返回两次数据）
+ * - FirstRemote:  先请求网络，失败时回退到缓存（网络优先）
+ * - IfCache:      有缓存则用缓存，无缓存则请求网络（只返回一次）
+ */
+/**
+ * 缓存模式使用示例
+ */
+declare function cacheModeDemo(): Promise<void>;
+/**
+ * FirstCache 模式会返回两次数据：
+ * 1. 第一次：从缓存返回（如果有缓存），fromCache = true
+ * 2. 第二次：从网络返回最新数据，fromCache = false
+ *
+ * 这种模式非常适合：
+ * - 列表页快速展示 + 后台刷新
+ * - 详情页先显示旧数据，再更新为最新数据
+ * - 提升用户体验，减少白屏时间
+ */
+/**
+ * 方式一：使用 for await 处理多次响应
+ * 推荐用于需要处理每次响应的场景
+ */
+declare function multiResponseWithForAwait(): Promise<void>;
+/**
+ * 方式二：使用 subscribe 处理多次响应
+ * 推荐用于 React/Vue 等框架中的响应式更新
+ */
+declare function multiResponseWithSubscribe(): Promise<void>;
+/**
+ * 方式三：只需要最终结果时使用 await
+ * 注意：await 只返回最后一次响应（网络数据）
+ */
+declare function singleResponseWithAwait(): Promise<void>;
+/**
+ * React 组件中的典型用法示例（伪代码）
+ */
+declare function reactUsageExample(): void;
 declare function typeErrors(): void;
-export { demo, typeErrors };
+import type { ApiEndpointWithoutBody } from '../api/ApiBuilder';
+/**
+ * 类型兼容性验证示例
+ */
+declare function verifyTypeCompatibility(): void;
+export { demo, typeErrors, verifyTypeCompatibility, cacheModeDemo, multiResponseWithForAwait, multiResponseWithSubscribe, singleResponseWithAwait, reactUsageExample, };
 //# sourceMappingURL=api-builder.demo.d.ts.map

package/dist/http/demo/api-builder.demo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-builder.demo.d.ts","sourceRoot":"","sources":["../../../src/http/demo/api-builder.demo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,WAAW;AACX,UAAU,IAAI;IACV,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CACpB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,WAAW;AACX,UAAU,iBAAiB,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACnB;AAMD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;CA8DR,CAAA;AAMZ,iBAAe,IAAI,kBAuElB;AAoBD,iBAAS,UAAU,SAYlB;AAMD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"api-builder.demo.d.ts","sourceRoot":"","sources":["../../../src/http/demo/api-builder.demo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,WAAW;AACX,UAAU,IAAI;IACV,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CACpB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,WAAW;AACX,UAAU,iBAAiB,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACnB;AAMD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;CA8DR,CAAA;AAMZ,iBAAe,IAAI,kBAqDlB;AAMD;;;;;;;;GAQG;AAEH;;GAEG;AACH,iBAAe,aAAa,kBAmC3B;AAMD;;;;;;;;;GASG;AAEH;;;GAGG;AACH,iBAAe,yBAAyB,kBAiBvC;AAED;;;GAGG;AACH,iBAAe,0BAA0B,kBA0BxC;AAED;;;GAGG;AACH,iBAAe,uBAAuB,kBAUrC;AAED;;GAEG;AACH,iBAAS,iBAAiB,SA4CzB;AAoBD,iBAAS,UAAU,SAYlB;AAMD,OAAO,KAAK,EAAuB,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAcpF;;GAEG;AACH,iBAAS,uBAAuB,SAkB/B;AAMD,OAAO,EACH,IAAI,EACJ,UAAU,EACV,uBAAuB,EACvB,aAAa,EACb,yBAAyB,EACzB,0BAA0B,EAC1B,uBAAuB,EACvB,iBAAiB,GACpB,CAAA"}

package/dist/http/demo/api-builder.demo.js

@@ -1,10 +1,12 @@
 /**
  * ApiBuilder 使用示例
  *
- * 此文件演示 ApiBuilder 的类型安全特性：
+ * 此文件演示 ApiBuilder 的核心特性：
  * 1. 泛型累积 - 链式调用自动累积端点类型
  * 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
  * 3. 端点名称字面量 - 调用不存在的端点会编译报错
+ * 4. 缓存策略 - CacheMode 控制缓存行为
+ * 5. 多次响应 - 支持缓存优先场景下的两次数据返回
  */
 import { ApiBuilder } from '../api/ApiBuilder';
 import { CacheMode } from '../models/CacheMode';
@@ -113,23 +115,182 @@ async function demo() {
         cache: { mode: CacheMode.OnlyRemote },
     });
     console.log('Fresh:', freshUser);
-    // ✅ 多次响应（for await）
-    for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
-        console.log('Data:', data, 'FromCache:', fromCache);
+}
+// ============================================================================
+// CacheMode 缓存模式详解
+// ============================================================================
+/**
+ * CacheMode 枚举值说明：
+ *
+ * - OnlyRemote:   只请求网络，不使用缓存（适用于实时性要求高的数据）
+ * - OnlyCache:    只读取缓存，不请求网络（适用于离线场景）
+ * - FirstCache:   先返回缓存，再请求网络更新（可能返回两次数据）
+ * - FirstRemote:  先请求网络，失败时回退到缓存（网络优先）
+ * - IfCache:      有缓存则用缓存，无缓存则请求网络（只返回一次）
+ */
+/**
+ * 缓存模式使用示例
+ */
+async function cacheModeDemo() {
+    // 1. OnlyRemote - 始终请求网络，忽略缓存
+    // 适用场景：提交表单、实时数据
+    const realTimeData = await userApi.getUser({
+        pathParams: { id: '123' },
+        cache: { mode: CacheMode.OnlyRemote },
+    });
+    console.log('实时数据:', realTimeData);
+    // 2. OnlyCache - 只读缓存，不请求网络
+    // 适用场景：离线模式、快速展示历史数据
+    try {
+        const cachedData = await userApi.getUser({
+            pathParams: { id: '123' },
+            cache: { mode: CacheMode.OnlyCache },
+        });
+        console.log('缓存数据:', cachedData);
+    }
+    catch (error) {
+        console.log('无缓存数据');
+    }
+    // 3. IfCache - 有缓存用缓存，无缓存请求网络（只返回一次）
+    // 适用场景：静态资源、不常变化的配置
+    const configData = await userApi.getUsers({
+        cache: { mode: CacheMode.IfCache, ttl: 60 * 60 * 1000 }, // 1小时
+    });
+    console.log('配置数据:', configData);
+    // 4. FirstRemote - 优先网络，失败回退缓存（只返回一次）
+    // 适用场景：希望获取最新数据，但网络不稳定时有兜底
+    const freshData = await userApi.getUser({
+        pathParams: { id: '123' },
+        cache: { mode: CacheMode.FirstRemote },
+    });
+    console.log('最新数据:', freshData);
+}
+// ============================================================================
+// 多次响应处理 - FirstCache 模式的核心特性
+// ============================================================================
+/**
+ * FirstCache 模式会返回两次数据：
+ * 1. 第一次：从缓存返回（如果有缓存），fromCache = true
+ * 2. 第二次：从网络返回最新数据，fromCache = false
+ *
+ * 这种模式非常适合：
+ * - 列表页快速展示 + 后台刷新
+ * - 详情页先显示旧数据，再更新为最新数据
+ * - 提升用户体验，减少白屏时间
+ */
+/**
+ * 方式一：使用 for await 处理多次响应
+ * 推荐用于需要处理每次响应的场景
+ */
+async function multiResponseWithForAwait() {
+    console.log('=== for await 方式 ===');
+    for await (const { data, fromCache } of userApi.getUser({
+        pathParams: { id: '123' },
+        cache: { mode: CacheMode.FirstCache },
+    })) {
+        if (fromCache) {
+            console.log('📦 缓存数据（快速展示）:', data);
+            // 可以先用缓存数据渲染 UI
+        }
+        else {
+            console.log('🌐 网络数据（最新）:', data);
+            // 用最新数据更新 UI
+        }
     }
-    // ✅ subscribe 方式
-    await userApi.getUser({ pathParams: { id: '123' } }).subscribe({
+    console.log('✅ 请求完成');
+}
+/**
+ * 方式二：使用 subscribe 处理多次响应
+ * 推荐用于 React/Vue 等框架中的响应式更新
+ */
+async function multiResponseWithSubscribe() {
+    console.log('=== subscribe 方式 ===');
+    await userApi
+        .getUser({
+        pathParams: { id: '123' },
+        cache: { mode: CacheMode.FirstCache },
+    })
+        .subscribe({
         onData: (data, fromCache) => {
-            console.log('Subscribe data:', data, fromCache);
+            if (fromCache) {
+                console.log('📦 缓存数据:', data);
+                // setState({ user: data, loading: false })
+            }
+            else {
+                console.log('🌐 网络数据:', data);
+                // setState({ user: data, loading: false, isStale: false })
+            }
         },
         onError: (error) => {
-            console.error('Error:', error);
+            console.error('❌ 请求失败:', error);
+            // setState({ error, loading: false })
         },
         onComplete: () => {
-            console.log('Complete');
+            console.log('✅ 请求完成');
         },
     });
 }
+/**
+ * 方式三：只需要最终结果时使用 await
+ * 注意：await 只返回最后一次响应（网络数据）
+ */
+async function singleResponseWithAwait() {
+    console.log('=== await 方式（只获取最终结果）===');
+    // 直接 await 只会返回最终的网络数据
+    const user = await userApi.getUser({
+        pathParams: { id: '123' },
+        cache: { mode: CacheMode.FirstCache },
+    });
+    console.log('最终数据:', user);
+}
+/**
+ * React 组件中的典型用法示例（伪代码）
+ */
+function reactUsageExample() {
+    /*
+    // React 组件示例
+    function UserProfile({ userId }: { userId: string }) {
+        const [user, setUser] = useState<User | null>(null)
+        const [isStale, setIsStale] = useState(false)
+        const [loading, setLoading] = useState(true)
+
+        useEffect(() => {
+            let cancelled = false
+
+            // 使用 subscribe 处理多次响应
+            userApi.getUser({
+                pathParams: { id: userId },
+                cache: { mode: CacheMode.FirstCache }
+            }).subscribe({
+                onData: (data, fromCache) => {
+                    if (cancelled) return
+                    setUser(data)
+                    setIsStale(fromCache)  // 标记是否为陈旧数据
+                    setLoading(false)
+                },
+                onError: (error) => {
+                    if (cancelled) return
+                    console.error(error)
+                    setLoading(false)
+                }
+            })
+
+            return () => { cancelled = true }
+        }, [userId])
+
+        if (loading) return <div>加载中...</div>
+        if (!user) return <div>用户不存在</div>
+
+        return (
+            <div>
+                {isStale && <span className="badge">数据更新中...</span>}
+                <h1>{user.name}</h1>
+                <p>{user.email}</p>
+            </div>
+        )
+    }
+    */
+}
 // ============================================================================
 // 类型错误示例
 // ============================================================================
@@ -157,7 +318,26 @@ function typeErrors() {
     // @ts-expect-error body not allowed for GET
     simpleApi.getUser({ pathParams: { id: '1' }, body: {} });
 }
+/**
+ * 类型兼容性验证示例
+ */
+function verifyTypeCompatibility() {
+    const api = ApiBuilder.create({ baseUrl: 'http://test' })
+        .get('getUser', { path: '/users/{id}' })
+        .get('getUsers', { path: '/users' })
+        .post('createUser', { path: '/users' })
+        .put('updateUser', { path: '/users/{id}' })
+        .delete('deleteUser', { path: '/users/{id}' })
+        .build();
+    // ✅ 使用类型断言确保 API 符合定义
+    // 注意：由于 TypeScript 深层交叉类型限制，需要通过 unknown 进行断言
+    const typedApi = api;
+    // 现在可以获得精确的类型检查
+    typedApi.createUser({ body: { name: 'John', email: 'john@test.com' } });
+    typedApi.getUser({ pathParams: { id: '1' } });
+    console.log('Typed API:', typedApi);
+}
 // ============================================================================
 // 导出
 // ============================================================================
-export { demo, typeErrors };
+export { demo, typeErrors, verifyTypeCompatibility, cacheModeDemo, multiResponseWithForAwait, multiResponseWithSubscribe, singleResponseWithAwait, reactUsageExample, };

package/dist/http/index.d.ts

@@ -35,8 +35,18 @@
  * })
  * ```
  */
-export { CacheMode, type CacheEntry, type ApiResult, type ApiCallback, type CacheConfig, type CacheKeyRequest, type HttpClientConfig, type RequestConfig, type ApiOptions, type DiskLruCacheConfig, type HttpCacheConfig, type CacheInterceptor, type CacheInterceptorContext, type CacheInterceptorResult, } from './types';
-export { DiskLruCache, HttpCache } from './cache';
+export { CacheMode } from './types';
+export type { ApiResult, ApiCallback } from './types';
+export type { CacheConfig, CacheKeyRequest, CacheEntry, DiskLruCacheConfig, HttpCacheConfig, LruMetadataEntry, LruMetadata, } from './types';
+export type { CacheInterceptor, CacheInterceptorContext, CacheInterceptorResult, } from './types';
+/** 默认缓存拦截器：检查 HTTP 200 + JSON + ApiResponse.code */
+export { defaultCacheInterceptor, createCacheInterceptor } from './interceptor';
+export type { HttpClientConfig, RequestConfig, ApiOptions } from './types';
+export type { ApiEndpoint, ApiDefinition, ApiEndpointWithBody, ApiEndpointWithoutBody, ApiEndpointWithBodyRequired, ApiEndpointWithBodyOptional, Simplify, } from './api';
+/** 磁盘 LRU 缓存（从 cache 模块重导出） */
+export { DiskLruCache } from '../cache';
+/** HTTP 缓存（内存 + 磁盘双层） */
+export { HttpCache } from './cache';
 export { HttpClient, ApiStream } from './client';
-export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './api';
+export { ApiBuilder } from './api';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EACH,SAAS,EACT,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC9B,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAGjD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGhD,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAKnC,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAKrD,YAAY,EAER,WAAW,EACX,eAAe,EAEf,UAAU,EAEV,kBAAkB,EAClB,eAAe,EAEf,gBAAgB,EAChB,WAAW,GACd,MAAM,SAAS,CAAA;AAKhB,YAAY,EACR,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACzB,MAAM,SAAS,CAAA;AAKhB,oDAAoD;AACpD,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAK/E,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAK1E,YAAY,EACR,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,QAAQ,GACX,MAAM,OAAO,CAAA;AAKd,+BAA+B;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,yBAAyB;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAKnC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAKhD,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA"}

package/dist/http/index.js

@@ -35,11 +35,27 @@
  * })
  * ```
  */
-// Types
-export { CacheMode, } from './types';
-// Cache
-export { DiskLruCache, HttpCache } from './cache';
-// Client
+// ============================================================================
+// 枚举
+// ============================================================================
+export { CacheMode } from './types';
+// ============================================================================
+// 缓存拦截器实现
+// ============================================================================
+/** 默认缓存拦截器：检查 HTTP 200 + JSON + ApiResponse.code */
+export { defaultCacheInterceptor, createCacheInterceptor } from './interceptor';
+// ============================================================================
+// 缓存实现
+// ============================================================================
+/** 磁盘 LRU 缓存（从 cache 模块重导出） */
+export { DiskLruCache } from '../cache';
+/** HTTP 缓存（内存 + 磁盘双层） */
+export { HttpCache } from './cache';
+// ============================================================================
+// 客户端
+// ============================================================================
 export { HttpClient, ApiStream } from './client';
-// API
+// ============================================================================
+// API Builder
+// ============================================================================
 export { ApiBuilder } from './api';

package/dist/http/{models → interceptor}/CacheInterceptor.d.ts

@@ -3,7 +3,7 @@
  *
  * 用于根据响应内容动态决定是否缓存
  */
-import type { CacheKeyRequest } from './CacheConfig';
+import type { CacheKeyRequest } from '../models/CacheConfig';
 /**
  * 缓存拦截器上下文
  *

package/dist/http/interceptor/CacheInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheInterceptor.d.ts","sourceRoot":"","sources":["../../../src/http/interceptor/CacheInterceptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAChD,sBAAsB;IACtB,IAAI,EAAE,CAAC,CAAA;IACP,eAAe;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,sBAAsB;IACtB,OAAO,EAAE,eAAe,CAAA;IACxB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB;IACnC,aAAa;IACb,WAAW,EAAE,OAAO,CAAA;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CACxC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAClC,OAAO,GAAG,sBAAsB,GAAG,OAAO,CAAC,OAAO,GAAG,sBAAsB,CAAC,CAAA"}

package/dist/http/interceptor/DefaultCacheInterceptor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 全局缓存拦截器
+ * 用于 xxf_react/http 的 ApiBuilder
+ */
+import { CacheInterceptor } from "./CacheInterceptor";
+/**
+ * 默认缓存拦截器
+ * 只有满足以下条件才缓存：
+ * - HTTP 状态码 = 200
+ * - Content-Type 包含 application/json
+ * - data 是有效对象
+ * - ApiResponse.code = 0 或 200
+ *
+ * @example
+ * ```ts
+ * ApiBuilder.create({
+ *     baseUrl: '...',
+ *     cacheInterceptor: defaultCacheInterceptor,
+ * })
+ * ```
+ */
+export declare const defaultCacheInterceptor: CacheInterceptor;
+/**
+ * 创建自定义缓存拦截器
+ * 在默认检查基础上添加自定义逻辑
+ *
+ * @param customCheck 自定义检查函数，在默认检查通过后执行
+ *
+ * @example
+ * ```ts
+ * const myInterceptor = createCacheInterceptor((ctx) => {
+ *     // 额外检查：只缓存有 data 字段的响应
+ *     const res = ctx.data as { data?: unknown }
+ *     return res.data !== undefined
+ * })
+ * ```
+ */
+export declare function createCacheInterceptor(customCheck?: (ctx: Parameters<CacheInterceptor>[0]) => boolean): CacheInterceptor;
+//# sourceMappingURL=DefaultCacheInterceptor.d.ts.map

package/dist/http/interceptor/DefaultCacheInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultCacheInterceptor.d.ts","sourceRoot":"","sources":["../../../src/http/interceptor/DefaultCacheInterceptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAkBrC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAClC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,GAChE,gBAAgB,CASlB"}

package/dist/http/interceptor/DefaultCacheInterceptor.js

@@ -0,0 +1,63 @@
+/**
+ * 全局缓存拦截器
+ * 用于 xxf_react/http 的 ApiBuilder
+ */
+/**
+ * 默认缓存拦截器
+ * 只有满足以下条件才缓存：
+ * - HTTP 状态码 = 200
+ * - Content-Type 包含 application/json
+ * - data 是有效对象
+ * - ApiResponse.code = 0 或 200
+ *
+ * @example
+ * ```ts
+ * ApiBuilder.create({
+ *     baseUrl: '...',
+ *     cacheInterceptor: defaultCacheInterceptor,
+ * })
+ * ```
+ */
+export const defaultCacheInterceptor = (ctx) => {
+    // 检查 HTTP 状态码
+    if (ctx.status !== 200) {
+        return false;
+    }
+    // 检查 Content-Type 是否为 JSON
+    const contentType = ctx.headers.get('Content-Type') || '';
+    if (!contentType.includes('application/json')) {
+        return false;
+    }
+    // 检查 data 是否为有效对象
+    if (!ctx.data || typeof ctx.data !== 'object') {
+        return false;
+    }
+    // 检查业务码：code 必须是 0 或 200
+    const res = ctx.data;
+    return !(res.code !== 0 && res.code !== 200);
+};
+/**
+ * 创建自定义缓存拦截器
+ * 在默认检查基础上添加自定义逻辑
+ *
+ * @param customCheck 自定义检查函数，在默认检查通过后执行
+ *
+ * @example
+ * ```ts
+ * const myInterceptor = createCacheInterceptor((ctx) => {
+ *     // 额外检查：只缓存有 data 字段的响应
+ *     const res = ctx.data as { data?: unknown }
+ *     return res.data !== undefined
+ * })
+ * ```
+ */
+export function createCacheInterceptor(customCheck) {
+    return (ctx) => {
+        // 先执行默认检查
+        if (!defaultCacheInterceptor(ctx)) {
+            return false;
+        }
+        // 执行自定义检查
+        return !(customCheck && !customCheck(ctx));
+    };
+}

package/dist/http/interceptor/index.d.ts

@@ -0,0 +1,3 @@
+export type { CacheInterceptor, CacheInterceptorContext, CacheInterceptorResult, } from './CacheInterceptor';
+export { defaultCacheInterceptor, createCacheInterceptor } from './DefaultCacheInterceptor';
+//# sourceMappingURL=index.d.ts.map

package/dist/http/interceptor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/interceptor/index.ts"],"names":[],"mappings":"AACA,YAAY,EACR,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACzB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/http/interceptor/index.js

@@ -0,0 +1,2 @@
+// 默认缓存拦截器
+export { defaultCacheInterceptor, createCacheInterceptor } from './DefaultCacheInterceptor';

package/dist/http/models/HttpClientConfig.d.ts

@@ -2,7 +2,7 @@
  * HTTP 客户端配置
  */
 import type { CacheConfig } from './CacheConfig';
-import type { CacheInterceptor } from './CacheInterceptor';
+import type { CacheInterceptor } from '../interceptor/CacheInterceptor';
 /**
  * HTTP 客户端配置
  *
@@ -37,7 +37,20 @@ export interface HttpClientConfig {
     diskCacheMaxSize?: number;
     /** IndexedDB 数据库名，默认 'xxf-http-cache' */
     dbName?: string;
-    /** 默认参与缓存 key 的 header，默认 ['Authorization'] */
+    /**
+     * 默认参与缓存 key 计算的 header 列表
+     *
+     * 默认为空数组 `[]`，不包含任何 header。
+     *
+     * **为什么默认不包含 Authorization？**
+     * - Authorization header 通常包含会变化的 token（如 JWT 刷新、时间戳签名）
+     * - 如果 token 变化，缓存 key 也会变化，导致缓存失效
+     * - 同一用户在同一浏览器中不会共享缓存，无需通过 header 区分用户
+     *
+     * 如需根据 header 区分缓存，可以：
+     * 1. 设置 `defaultKeyHeaders: ['Accept-Language']` 等稳定的 header
+     * 2. 使用 `cacheKey` 函数提取 token 中不变的部分（如 userId）
+     */
     defaultKeyHeaders?: string[];
     /**
      * 全局默认缓存配置

package/dist/http/models/HttpClientConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpClientConfig.d.ts","sourceRoot":"","sources":["../../../src/http/models/HttpClientConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAC7B,aAAa;IACb,OAAO,EAAE,MAAM,CAAA;IAEf,YAAY;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEhC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,uBAAuB;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B,uBAAuB;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE5B;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAEnC;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;CACtC"}
+{"version":3,"file":"HttpClientConfig.d.ts","sourceRoot":"","sources":["../../../src/http/models/HttpClientConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAEvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAC7B,aAAa;IACb,OAAO,EAAE,MAAM,CAAA;IAEf,YAAY;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEhC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,uBAAuB;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B,uBAAuB;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE5B;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAEnC;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;CACtC"}

package/dist/http/models/index.d.ts

@@ -13,12 +13,12 @@
  * - LruMetadata: LRU 元数据
  */
 export { CacheMode } from './CacheMode';
-export type { CacheEntry } from './CacheEntry';
+export type { CacheEntry } from '../../cache/CacheEntry';
 export type { ApiResult, ApiCallback } from './ApiTypes';
 export type { CacheConfig, CacheKeyRequest } from './CacheConfig';
-export type { CacheInterceptor, CacheInterceptorContext, CacheInterceptorResult, } from './CacheInterceptor';
+export type { CacheInterceptor, CacheInterceptorContext, CacheInterceptorResult, } from '../interceptor/CacheInterceptor';
 export type { HttpClientConfig } from './HttpClientConfig';
 export type { RequestConfig, ApiOptions } from './RequestConfig';
-export type { DiskLruCacheConfig, HttpCacheConfig } from './DiskCacheConfig';
-export type { LruMetadataEntry, LruMetadata } from './LruMetadata';
+export type { DiskLruCacheConfig, HttpCacheConfig } from '../../cache/DiskCacheConfig';
+export type { LruMetadataEntry, LruMetadata } from '../../cache/LruMetadata';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/models/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/models/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGvC,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxD,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGjE,YAAY,EACR,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACzB,MAAM,oBAAoB,CAAA;AAG3B,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAG1D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAGhE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAG5E,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/models/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGvC,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGxD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxD,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGjE,YAAY,EACR,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACzB,MAAM,iCAAiC,CAAA;AAGxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAG1D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAGhE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAGtF,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from './responsive';
 export * from './foundation';
 export * from './layout';
 export * from './event-bus';
+export * from './cache';
 export * from './http';
 export declare function initXXF(): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AAGvB,wBAAgB,OAAO,SAGtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AAGvB,wBAAgB,OAAO,SAGtB"}

package/dist/index.js

@@ -11,6 +11,7 @@ export * from './responsive';
 export * from './foundation';
 export * from './layout';
 export * from './event-bus';
+export * from './cache';
 export * from './http';
 ///框架初始化函数，调用后会初始化一些全局功能
 export function initXXF() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -57,6 +57,10 @@
     "./http": {
       "types": "./dist/http/index.d.ts",
       "import": "./dist/http/index.js"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.ts",
+      "import": "./dist/cache/index.js"
     }
   },
   "files": [

package/dist/http/cache/DiskLruCache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DiskLruCache.d.ts","sourceRoot":"","sources":["../../../src/http/cache/DiskLruCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAe,MAAM,UAAU,CAAA;AAK3E,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,MAAM,EAAE,kBAAkB;IAQtC;;OAEG;YACW,YAAY;IAiB1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmCxD;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAexC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxC;;OAEG;YACW,KAAK;IAsCnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAS7B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAQlC"}

package/dist/http/models/CacheEntry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CacheEntry.d.ts","sourceRoot":"","sources":["../../../src/http/models/CacheEntry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACnC,WAAW;IACX,IAAI,EAAE,CAAC,CAAA;IACP,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa;IACb,GAAG,EAAE,MAAM,CAAA;CACd"}

package/dist/http/models/CacheInterceptor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CacheInterceptor.d.ts","sourceRoot":"","sources":["../../../src/http/models/CacheInterceptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAChD,sBAAsB;IACtB,IAAI,EAAE,CAAC,CAAA;IACP,eAAe;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,sBAAsB;IACtB,OAAO,EAAE,eAAe,CAAA;IACxB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB;IACnC,aAAa;IACb,WAAW,EAAE,OAAO,CAAA;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CACxC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAClC,OAAO,GAAG,sBAAsB,GAAG,OAAO,CAAC,OAAO,GAAG,sBAAsB,CAAC,CAAA"}

package/dist/http/models/DiskCacheConfig.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DiskCacheConfig.d.ts","sourceRoot":"","sources":["../../../src/http/models/DiskCacheConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC5B,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,gBAAgB;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;CACjB"}

package/dist/http/models/LruMetadata.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"LruMetadata.d.ts","sourceRoot":"","sources":["../../../src/http/models/LruMetadata.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IACzC,WAAW;IACX,KAAK,EAAE,MAAM,CAAA;CAChB"}