xxf_react 0.6.6 → 0.6.8

package/dist/http/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * HTTP 网络框架
+ *
+ * 基于 ky + idb-keyval，支持：
+ * - 内存 + 磁盘双层缓存
+ * - 6 种缓存模式
+ * - AsyncGenerator 流式响应
+ * - 类 Retrofit 的 API 定义方式
+ *
+ * @example
+ * ```ts
+ * import { ApiBuilder, CacheMode } from 'xxf_react/http'
+ *
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', {
+ *     path: '/users/{id}',
+ *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
+ *   })
+ *   .build()
+ *
+ * // 方式1: 简单 await
+ * const user = await userApi.getUser({ pathParams: { id: '123' } })
+ *
+ * // 方式2: for await 多次响应
+ * for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
+ *   console.log(data, fromCache)
+ * }
+ *
+ * // 方式3: subscribe 安全消费
+ * await userApi.getUser({ pathParams: { id: '123' } }).subscribe({
+ *   onData: (data, fromCache) => console.log(data),
+ *   onError: (e) => console.error(e),
+ * })
+ * ```
+ */
+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 { HttpClient, ApiStream } from './client';
+export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './api';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/http/index.js

@@ -0,0 +1,45 @@
+/**
+ * HTTP 网络框架
+ *
+ * 基于 ky + idb-keyval，支持：
+ * - 内存 + 磁盘双层缓存
+ * - 6 种缓存模式
+ * - AsyncGenerator 流式响应
+ * - 类 Retrofit 的 API 定义方式
+ *
+ * @example
+ * ```ts
+ * import { ApiBuilder, CacheMode } from 'xxf_react/http'
+ *
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', {
+ *     path: '/users/{id}',
+ *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
+ *   })
+ *   .build()
+ *
+ * // 方式1: 简单 await
+ * const user = await userApi.getUser({ pathParams: { id: '123' } })
+ *
+ * // 方式2: for await 多次响应
+ * for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
+ *   console.log(data, fromCache)
+ * }
+ *
+ * // 方式3: subscribe 安全消费
+ * await userApi.getUser({ pathParams: { id: '123' } }).subscribe({
+ *   onData: (data, fromCache) => console.log(data),
+ *   onError: (e) => console.error(e),
+ * })
+ * ```
+ */
+// Types
+export { CacheMode, } from './types';
+// Cache
+export { DiskLruCache, HttpCache } from './cache';
+// Client
+export { HttpClient, ApiStream } from './client';
+// API
+export { ApiBuilder } from './api';

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

@@ -0,0 +1,54 @@
+/**
+ * API 响应相关类型
+ */
+/**
+ * API 响应结果
+ *
+ * 包含响应数据和来源标识
+ *
+ * @template T 响应数据类型
+ *
+ * @example
+ * ```ts
+ * for await (const result of api.getUser({ pathParams: { id: '1' } })) {
+ *   if (result.fromCache) {
+ *     showSkeleton(result.data)
+ *   } else {
+ *     renderFull(result.data)
+ *   }
+ * }
+ * ```
+ */
+export interface ApiResult<T> {
+    /** 响应数据 */
+    data: T;
+    /** 是否来自缓存 */
+    fromCache: boolean;
+}
+/**
+ * API 回调配置
+ *
+ * 用于 subscribe 安全消费模式，确保回调错误不影响后续响应
+ *
+ * @template T 响应数据类型
+ *
+ * @example
+ * ```ts
+ * await api.getUser({ pathParams: { id: '1' } }).subscribe({
+ *   onData: (data, fromCache) => {
+ *     renderUI(data)  // 即使这里抛错，网络数据仍会返回
+ *   },
+ *   onError: (e) => console.error(e),
+ *   onComplete: () => console.log('done'),
+ * })
+ * ```
+ */
+export interface ApiCallback<T> {
+    /** 数据回调 (可能多次调用) */
+    onData: (data: T, fromCache: boolean) => void;
+    /** 错误回调 */
+    onError?: (error: Error) => void;
+    /** 完成回调 */
+    onComplete?: () => void;
+}
+//# sourceMappingURL=ApiTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ApiTypes.d.ts","sourceRoot":"","sources":["../../../src/http/models/ApiTypes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IACxB,WAAW;IACX,IAAI,EAAE,CAAC,CAAA;IACP,aAAa;IACb,SAAS,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC1B,oBAAoB;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAC7C,WAAW;IACX,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,WAAW;IACX,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAC1B"}

package/dist/http/models/ApiTypes.js

@@ -0,0 +1,4 @@
+/**
+ * API 响应相关类型
+ */
+export {};

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

@@ -0,0 +1,58 @@
+/**
+ * 缓存配置相关类型
+ */
+import { CacheMode } from './CacheMode';
+/**
+ * 缓存 key 计算请求参数
+ *
+ * 用于自定义缓存 key 生成函数
+ *
+ * @example
+ * ```ts
+ * cache: {
+ *   cacheKey: (req: CacheKeyRequest) => `user:${req.pathParams?.id}`,
+ * }
+ * ```
+ */
+export interface CacheKeyRequest {
+    /** 请求方法 */
+    method: string;
+    /** 请求路径 */
+    path: string;
+    /** 查询参数 */
+    query?: Record<string, unknown>;
+    /** 请求体 */
+    body?: unknown;
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 路径参数 */
+    pathParams?: Record<string, string | number>;
+}
+/**
+ * 缓存配置
+ *
+ * 用于配置单个 API 的缓存行为
+ *
+ * @example
+ * ```ts
+ * .get<User>('getUser', {
+ *   path: '/users/{id}',
+ *   cache: {
+ *     mode: CacheMode.FirstCache,
+ *     ttl: 5 * 60 * 1000,  // 5 分钟
+ *     keyHeaders: ['Authorization'],
+ *   },
+ * })
+ * ```
+ */
+export interface CacheConfig {
+    /** 缓存模式 */
+    mode: CacheMode;
+    /** 缓存时间 (ms)，默认 5 分钟 */
+    ttl?: number;
+    /** 参与缓存 key 计算的 header 名称 */
+    keyHeaders?: string[];
+    /** 自定义缓存 key 生成函数 */
+    cacheKey?: (request: CacheKeyRequest) => string;
+}
+//# sourceMappingURL=CacheConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CacheConfig.d.ts","sourceRoot":"","sources":["../../../src/http/models/CacheConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC5B,WAAW;IACX,MAAM,EAAE,MAAM,CAAA;IACd,WAAW;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW;IACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,UAAU;IACV,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,UAAU;IACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,WAAW;IACX,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;CAC/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IACxB,WAAW;IACX,IAAI,EAAE,SAAS,CAAA;IACf,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAA;CAClD"}

package/dist/http/models/CacheConfig.js

@@ -0,0 +1,4 @@
+/**
+ * 缓存配置相关类型
+ */
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * 缓存条目
+ *
+ * 存储在内存缓存和磁盘缓存中的数据结构
+ *
+ * @template T 缓存数据类型
+ *
+ * @example
+ * ```ts
+ * const entry: CacheEntry<User> = {
+ *   data: { id: '1', name: 'John' },
+ *   timestamp: Date.now(),
+ *   ttl: 5 * 60 * 1000,  // 5 分钟
+ *   key: 'GET:/users/1',
+ * }
+ * ```
+ */
+export interface CacheEntry<T = unknown> {
+    /** 缓存数据 */
+    data: T;
+    /** 缓存时间戳 (ms) */
+    timestamp: number;
+    /** 过期时间 (ms)，0 表示永不过期 */
+    ttl: number;
+    /** 缓存 key */
+    key: string;
+}
+//# sourceMappingURL=CacheEntry.d.ts.map

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

@@ -0,0 +1 @@
+{"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/CacheEntry.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,112 @@
+/**
+ * 缓存拦截器相关类型
+ *
+ * 用于根据响应内容动态决定是否缓存
+ */
+import type { CacheKeyRequest } from './CacheConfig';
+/**
+ * 缓存拦截器上下文
+ *
+ * 包含响应的完整信息，供拦截器判断是否应该缓存
+ *
+ * @template T 响应数据类型
+ *
+ * @example
+ * ```ts
+ * cacheInterceptor: (ctx) => {
+ *   // 可以访问响应数据、HTTP 状态码、响应头等
+ *   console.log(ctx.data)      // 响应数据
+ *   console.log(ctx.status)    // HTTP 状态码
+ *   console.log(ctx.headers)   // 响应头
+ *   console.log(ctx.request)   // 请求信息
+ *   console.log(ctx.cacheKey)  // 缓存 key
+ * }
+ * ```
+ */
+export interface CacheInterceptorContext<T = unknown> {
+    /** 响应数据（已解析的 JSON） */
+    data: T;
+    /** HTTP 状态码 */
+    status: number;
+    /** 响应头 */
+    headers: Headers;
+    /** 请求信息（用于调试或高级判断） */
+    request: CacheKeyRequest;
+    /** 缓存 key（用于调试或高级判断） */
+    cacheKey: string;
+}
+/**
+ * 缓存拦截器返回结果
+ *
+ * 当需要更精细控制时使用对象形式返回
+ *
+ * @example
+ * ```ts
+ * // 简单返回 boolean
+ * cacheInterceptor: (ctx) => ctx.status === 200
+ *
+ * // 返回对象，可以覆盖 TTL
+ * cacheInterceptor: (ctx) => ({
+ *   shouldCache: true,
+ *   ttl: 10 * 60 * 1000,  // 覆盖为 10 分钟
+ * })
+ * ```
+ */
+export interface CacheInterceptorResult {
+    /** 是否允许缓存 */
+    shouldCache: boolean;
+    /**
+     * 可选：覆盖缓存 TTL (ms)
+     * 如果不指定，使用请求配置中的 ttl
+     */
+    ttl?: number;
+}
+/**
+ * 缓存拦截器
+ *
+ * 在响应返回后、写入缓存前调用，用于根据响应内容决定是否缓存。
+ *
+ * ## 常见场景
+ * - 只缓存 HTTP 200 响应
+ * - 只缓存业务 code 为成功的响应
+ * - 根据响应头决定是否缓存
+ * - 根据响应内容动态调整缓存时间
+ *
+ * ## 返回值
+ * - `true`：允许缓存
+ * - `false`：不缓存
+ * - `CacheInterceptorResult`：精细控制（是否缓存 + 可选覆盖 TTL）
+ * - `Promise<...>`：支持异步判断
+ *
+ * @template T 响应数据类型
+ * @param context 拦截器上下文，包含响应的完整信息
+ *
+ * @example
+ * ```ts
+ * // 示例 1：只缓存 HTTP 200
+ * cacheInterceptor: (ctx) => ctx.status === 200
+ *
+ * // 示例 2：检查业务 code
+ * cacheInterceptor: (ctx) => {
+ *   const res = ctx.data as { code?: number }
+ *   return res.code === 200
+ * }
+ *
+ * // 示例 3：检查响应头
+ * cacheInterceptor: (ctx) => {
+ *   return ctx.headers.get('X-Cacheable') !== 'false'
+ * }
+ *
+ * // 示例 4：动态 TTL
+ * cacheInterceptor: (ctx) => {
+ *   const res = ctx.data as { code?: number; cacheTtl?: number }
+ *   if (res.code !== 200) return false
+ *   return {
+ *     shouldCache: true,
+ *     ttl: res.cacheTtl ?? 5 * 60 * 1000,
+ *   }
+ * }
+ * ```
+ */
+export type CacheInterceptor<T = unknown> = (context: CacheInterceptorContext<T>) => boolean | CacheInterceptorResult | Promise<boolean | CacheInterceptorResult>;
+//# sourceMappingURL=CacheInterceptor.d.ts.map

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

@@ -0,0 +1 @@
+{"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/CacheInterceptor.js

@@ -0,0 +1,6 @@
+/**
+ * 缓存拦截器相关类型
+ *
+ * 用于根据响应内容动态决定是否缓存
+ */
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * 缓存模式枚举
+ *
+ * 定义了 6 种缓存策略，覆盖各种业务场景
+ */
+export declare enum CacheMode {
+    /**
+     * 先从本地缓存拿，然后从服务器拿
+     * - 可能 yield 两次（先缓存后网络）
+     * - 适用于：需要快速展示旧数据，同时更新最新数据
+     */
+    FirstCache = "firstCache",
+    /**
+     * 先从服务器获取，没网络则读缓存
+     * - yield 1 次
+     * - 适用于：优先保证数据最新，网络异常时降级
+     */
+    FirstRemote = "firstRemote",
+    /**
+     * 只从服务器拿（默认模式）
+     * - yield 1 次
+     * - 适用于：实时性要求高的数据
+     */
+    OnlyRemote = "onlyRemote",
+    /**
+     * 只从缓存拿
+     * - yield 0-1 次（无缓存时不 yield）
+     * - 适用于：离线场景、纯本地数据
+     */
+    OnlyCache = "onlyCache",
+    /**
+     * 有缓存返回缓存，否则请求网络
+     * - yield 1 次
+     * - 适用于：缓存优先，减少网络请求
+     */
+    IfCache = "ifCache",
+    /**
+     * 读上次缓存，后台静默更新
+     * - yield 1 次（返回缓存或网络）
+     * - 有缓存时后台同步网络但不 yield
+     * - 适用于：SWR（stale-while-revalidate）策略
+     */
+    LastCache = "lastCache"
+}
+//# sourceMappingURL=CacheMode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CacheMode.d.ts","sourceRoot":"","sources":["../../../src/http/models/CacheMode.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,SAAS;IACjB;;;;OAIG;IACH,UAAU,eAAe;IAEzB;;;;OAIG;IACH,WAAW,gBAAgB;IAE3B;;;;OAIG;IACH,UAAU,eAAe;IAEzB;;;;OAIG;IACH,SAAS,cAAc;IAEvB;;;;OAIG;IACH,OAAO,YAAY;IAEnB;;;;;OAKG;IACH,SAAS,cAAc;CAC1B"}

package/dist/http/models/CacheMode.js

@@ -0,0 +1,45 @@
+/**
+ * 缓存模式枚举
+ *
+ * 定义了 6 种缓存策略，覆盖各种业务场景
+ */
+export var CacheMode;
+(function (CacheMode) {
+    /**
+     * 先从本地缓存拿，然后从服务器拿
+     * - 可能 yield 两次（先缓存后网络）
+     * - 适用于：需要快速展示旧数据，同时更新最新数据
+     */
+    CacheMode["FirstCache"] = "firstCache";
+    /**
+     * 先从服务器获取，没网络则读缓存
+     * - yield 1 次
+     * - 适用于：优先保证数据最新，网络异常时降级
+     */
+    CacheMode["FirstRemote"] = "firstRemote";
+    /**
+     * 只从服务器拿（默认模式）
+     * - yield 1 次
+     * - 适用于：实时性要求高的数据
+     */
+    CacheMode["OnlyRemote"] = "onlyRemote";
+    /**
+     * 只从缓存拿
+     * - yield 0-1 次（无缓存时不 yield）
+     * - 适用于：离线场景、纯本地数据
+     */
+    CacheMode["OnlyCache"] = "onlyCache";
+    /**
+     * 有缓存返回缓存，否则请求网络
+     * - yield 1 次
+     * - 适用于：缓存优先，减少网络请求
+     */
+    CacheMode["IfCache"] = "ifCache";
+    /**
+     * 读上次缓存，后台静默更新
+     * - yield 1 次（返回缓存或网络）
+     * - 有缓存时后台同步网络但不 yield
+     * - 适用于：SWR（stale-while-revalidate）策略
+     */
+    CacheMode["LastCache"] = "lastCache";
+})(CacheMode || (CacheMode = {}));

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

@@ -0,0 +1,56 @@
+/**
+ * 缓存存储配置
+ */
+/**
+ * DiskLruCache 配置
+ *
+ * 用于配置基于 IndexedDB 的磁盘 LRU 缓存
+ *
+ * @example
+ * ```ts
+ * const diskCache = new DiskLruCache({
+ *   dbName: 'my-app-cache',
+ *   storeName: 'http-cache',
+ *   maxSize: 500,
+ *   cleanupThreshold: 0.1,
+ * })
+ * ```
+ */
+export interface DiskLruCacheConfig {
+    /** IndexedDB 数据库名 */
+    dbName: string;
+    /** 存储名（ObjectStore 名称） */
+    storeName: string;
+    /** 最大条目数 */
+    maxSize: number;
+    /**
+     * 清理阈值
+     *
+     * 超过 maxSize * (1 + cleanupThreshold) 后触发清理
+     * 默认 0.1，即超过 110% 时清理到 100%
+     */
+    cleanupThreshold?: number;
+}
+/**
+ * HttpCache 配置
+ *
+ * 用于配置 HTTP 缓存（内存 + 磁盘双层）
+ *
+ * @example
+ * ```ts
+ * const cache = new HttpCache({
+ *   memoryMaxSize: 100,
+ *   diskMaxSize: 500,
+ *   dbName: 'my-app-cache',
+ * })
+ * ```
+ */
+export interface HttpCacheConfig {
+    /** 内存缓存最大条目数 */
+    memoryMaxSize: number;
+    /** 磁盘缓存最大条目数 */
+    diskMaxSize: number;
+    /** IndexedDB 数据库名 */
+    dbName: string;
+}
+//# sourceMappingURL=DiskCacheConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"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/DiskCacheConfig.js

@@ -0,0 +1,4 @@
+/**
+ * 缓存存储配置
+ */
+export {};

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

@@ -0,0 +1,77 @@
+/**
+ * HTTP 客户端配置
+ */
+import type { CacheConfig } from './CacheConfig';
+import type { CacheInterceptor } from './CacheInterceptor';
+/**
+ * HTTP 客户端配置
+ *
+ * 用于创建 HttpClient 或 ApiBuilder 时的全局配置
+ *
+ * @example
+ * ```ts
+ * const api = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ *   timeout: 10000,
+ *   headers: { 'X-App-Version': '1.0.0' },
+ *   defaultCache: {
+ *     mode: CacheMode.FirstRemote,
+ *     ttl: 5 * 60 * 1000,
+ *   },
+ *   cacheInterceptor: (ctx) => ctx.status === 200,
+ * })
+ * ```
+ */
+export interface HttpClientConfig {
+    /** 基础 URL */
+    baseUrl: string;
+    /** 默认请求头 */
+    headers?: Record<string, string>;
+    /** 默认超时时间 (ms)，默认 30000 */
+    timeout?: number;
+    /** 默认重试次数，默认 2 */
+    retry?: number;
+    /** 内存缓存最大条目数，默认 100 */
+    memoryCacheMaxSize?: number;
+    /** 磁盘缓存最大条目数，默认 500 */
+    diskCacheMaxSize?: number;
+    /** IndexedDB 数据库名，默认 'xxf-http-cache' */
+    dbName?: string;
+    /** 默认参与缓存 key 的 header，默认 ['Authorization'] */
+    defaultKeyHeaders?: string[];
+    /**
+     * 全局默认缓存配置
+     *
+     * 如果不设置，默认为 OnlyRemote（不缓存）
+     * 单个接口的 cache 配置会覆盖此全局配置
+     *
+     * @example
+     * ```ts
+     * defaultCache: {
+     *   mode: CacheMode.FirstRemote,
+     *   ttl: 5 * 60 * 1000,
+     * }
+     * ```
+     */
+    defaultCache?: Partial<CacheConfig>;
+    /**
+     * 全局缓存拦截器
+     *
+     * 在响应返回后、写入缓存前调用，用于根据响应内容决定是否缓存。
+     * 只有当缓存模式需要写入缓存时才会调用此拦截器。
+     *
+     * @example
+     * ```ts
+     * // 只缓存 HTTP 200 且业务 code 为 200 的响应
+     * cacheInterceptor: (ctx) => {
+     *   if (ctx.status !== 200) return false
+     *   const res = ctx.data as { code?: number }
+     *   return res.code === 200
+     * }
+     * ```
+     *
+     * @see CacheInterceptor 查看更多示例
+     */
+    cacheInterceptor?: CacheInterceptor;
+}
+//# sourceMappingURL=HttpClientConfig.d.ts.map

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

@@ -0,0 +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"}

package/dist/http/models/HttpClientConfig.js

@@ -0,0 +1,4 @@
+/**
+ * HTTP 客户端配置
+ */
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * LRU 缓存元数据
+ *
+ * 用于 DiskLruCache 内部管理缓存条目的访问顺序
+ */
+/**
+ * LRU 元数据条目
+ *
+ * 单个缓存条目的元数据信息
+ */
+export interface LruMetadataEntry {
+    /** 最后访问时间 (ms) */
+    accessTime: number;
+    /** 数据大小估算 (可选，用于未来扩展) */
+    size?: number;
+}
+/**
+ * LRU 元数据
+ *
+ * 存储在 IndexedDB 中的元数据，用于 LRU 淘汰算法
+ */
+export interface LruMetadata {
+    /** 所有缓存 key 及其元数据 */
+    entries: Record<string, LruMetadataEntry>;
+    /** 总条目数 */
+    count: number;
+}
+//# sourceMappingURL=LruMetadata.d.ts.map

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

@@ -0,0 +1 @@
+{"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"}

package/dist/http/models/LruMetadata.js

@@ -0,0 +1,6 @@
+/**
+ * LRU 缓存元数据
+ *
+ * 用于 DiskLruCache 内部管理缓存条目的访问顺序
+ */
+export {};