xxf_react 0.8.5 → 0.8.7

package/dist/cache/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/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/CacheEntry.js

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

package/dist/cache/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/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/cache/DiskCacheConfig.js

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

package/dist/cache/DiskLruCache.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 基于 IndexedDB 的 LRU 磁盘缓存
+ *
+ * 特点：
+ * - 使用 idb-keyval 简化 IndexedDB 操作
+ * - 维护 LRU 元数据实现淘汰策略
+ * - 支持 TTL 过期
+ * - 批量清理优化性能
+ * - 防污染：返回数据的深拷贝
+ * - 使用快速选择算法优化淘汰性能 O(n)
+ */
+import type { CacheEntry } from './CacheEntry';
+import type { DiskLruCacheConfig } from './DiskCacheConfig';
+export declare class DiskLruCache {
+    private store;
+    private config;
+    private metadata;
+    private metadataDirty;
+    private flushTimer;
+    private evicting;
+    constructor(config: DiskLruCacheConfig);
+    /**
+     * 加载或初始化 LRU 元数据（失败返回空元数据）
+     */
+    private loadMetadata;
+    /**
+     * 保存元数据到磁盘 (批量优化，延迟写入)
+     */
+    private scheduleFlushMetadata;
+    /**
+     * 立即刷新元数据到磁盘（失败静默忽略）
+     */
+    flush(): Promise<void>;
+    /**
+     * 获取缓存（失败返回 null，不影响业务）
+     * @returns 缓存条目的深拷贝
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * 设置缓存（失败静默忽略，不影响业务）
+     */
+    set<T>(key: string, data: T, ttl?: number): Promise<void>;
+    /**
+     * 删除缓存（失败静默忽略）
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 检查缓存是否存在（不更新访问时间，失败返回 false）
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 淘汰最旧的缓存条目（失败静默忽略）
+     * 使用快速选择算法，平均时间复杂度 O(n)
+     */
+    private evict;
+    /**
+     * 清空所有缓存（失败静默忽略）
+     */
+    clear(): Promise<void>;
+    /**
+     * 获取缓存数量（失败返回 0）
+     */
+    size(): Promise<number>;
+    /**
+     * 获取所有缓存 key（失败返回空数组）
+     */
+    keys(): Promise<string[]>;
+}
+//# sourceMappingURL=DiskLruCache.d.ts.map

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/cache/DiskLruCache.js

@@ -0,0 +1,305 @@
+/**
+ * 基于 IndexedDB 的 LRU 磁盘缓存
+ *
+ * 特点：
+ * - 使用 idb-keyval 简化 IndexedDB 操作
+ * - 维护 LRU 元数据实现淘汰策略
+ * - 支持 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;
+        this.metadataDirty = false;
+        this.flushTimer = null;
+        this.evicting = false; // 防止并发淘汰
+        this.config = {
+            cleanupThreshold: 0.1,
+            ...config,
+        };
+        this.store = createStore(config.dbName, config.storeName);
+    }
+    /**
+     * 加载或初始化 LRU 元数据（失败返回空元数据）
+     */
+    async loadMetadata() {
+        if (this.metadata)
+            return this.metadata;
+        try {
+            const stored = await get(META_KEY, this.store);
+            if (stored) {
+                this.metadata = stored;
+            }
+            else {
+                this.metadata = { entries: {}, count: 0 };
+            }
+        }
+        catch {
+            // 加载失败，使用空元数据
+            this.metadata = { entries: {}, count: 0 };
+        }
+        return this.metadata;
+    }
+    /**
+     * 保存元数据到磁盘 (批量优化，延迟写入)
+     */
+    scheduleFlushMetadata() {
+        if (this.flushTimer)
+            return;
+        this.metadataDirty = true;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            if (this.metadataDirty && this.metadata) {
+                set(META_KEY, this.metadata, this.store)
+                    .then(() => {
+                    this.metadataDirty = false;
+                })
+                    .catch(() => {
+                    // 静默处理写入错误，下次会重试
+                });
+            }
+        }, 1000); // 1 秒后批量写入
+    }
+    /**
+     * 立即刷新元数据到磁盘（失败静默忽略）
+     */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.metadataDirty && this.metadata) {
+            try {
+                await set(META_KEY, this.metadata, this.store);
+                this.metadataDirty = false;
+            }
+            catch {
+                // 刷新失败静默忽略，下次会重试
+            }
+        }
+    }
+    /**
+     * 获取缓存（失败返回 null，不影响业务）
+     * @returns 缓存条目的深拷贝
+     */
+    async get(key) {
+        try {
+            const meta = await this.loadMetadata();
+            // 检查是否存在
+            if (!meta.entries[key]) {
+                return null;
+            }
+            const entry = await get(key, this.store);
+            if (!entry) {
+                // 数据丢失，清理元数据
+                delete meta.entries[key];
+                meta.count = Math.max(0, meta.count - 1);
+                this.scheduleFlushMetadata();
+                return null;
+            }
+            // 检查是否过期
+            if (entry.ttl > 0 && Date.now() - entry.timestamp > entry.ttl) {
+                await this.delete(key);
+                return null;
+            }
+            // 更新访问时间
+            meta.entries[key] = { accessTime: Date.now() };
+            this.scheduleFlushMetadata();
+            return entry;
+        }
+        catch {
+            // IndexedDB 操作失败，返回 null 不影响业务
+            return null;
+        }
+    }
+    /**
+     * 设置缓存（失败静默忽略，不影响业务）
+     */
+    async set(key, data, ttl = 0) {
+        try {
+            const meta = await this.loadMetadata();
+            const entry = {
+                data,
+                timestamp: Date.now(),
+                ttl,
+                key,
+            };
+            // 检查是否需要淘汰
+            if (!meta.entries[key] && meta.count >= this.config.maxSize) {
+                await this.evict();
+            }
+            await set(key, entry, this.store);
+            // 更新元数据
+            if (!meta.entries[key]) {
+                meta.count++;
+            }
+            meta.entries[key] = { accessTime: Date.now() };
+            this.scheduleFlushMetadata();
+        }
+        catch {
+            // IndexedDB 操作失败，静默忽略不影响业务
+        }
+    }
+    /**
+     * 删除缓存（失败静默忽略）
+     */
+    async delete(key) {
+        try {
+            const meta = await this.loadMetadata();
+            if (meta.entries[key]) {
+                await del(key, this.store);
+                delete meta.entries[key];
+                meta.count = Math.max(0, meta.count - 1);
+                this.scheduleFlushMetadata();
+            }
+        }
+        catch {
+            // 删除失败静默忽略
+        }
+    }
+    /**
+     * 检查缓存是否存在（不更新访问时间，失败返回 false）
+     */
+    async has(key) {
+        try {
+            const meta = await this.loadMetadata();
+            return !!meta.entries[key];
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 淘汰最旧的缓存条目（失败静默忽略）
+     * 使用快速选择算法，平均时间复杂度 O(n)
+     */
+    async evict() {
+        // 防止并发淘汰
+        if (this.evicting)
+            return;
+        this.evicting = true;
+        try {
+            const meta = await this.loadMetadata();
+            // 计算需要淘汰的数量
+            const evictCount = Math.ceil(this.config.maxSize * this.config.cleanupThreshold);
+            // 使用快速选择算法找出访问时间最早的 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);
+                }
+                catch {
+                    // 单个删除失败继续处理其他
+                }
+                delete meta.entries[key];
+                meta.count = Math.max(0, meta.count - 1);
+            }
+            this.scheduleFlushMetadata();
+        }
+        catch {
+            // 淘汰失败静默忽略
+        }
+        finally {
+            this.evicting = false;
+        }
+    }
+    /**
+     * 清空所有缓存（失败静默忽略）
+     */
+    async clear() {
+        // 取消待处理的元数据写入
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        try {
+            // 使用 idb-keyval 的 clear 方法一次性清空整个 store
+            await clearStore(this.store);
+        }
+        catch {
+            // 清空失败静默忽略
+        }
+        // 重置内存中的元数据
+        this.metadata = { entries: {}, count: 0 };
+        this.metadataDirty = false;
+    }
+    /**
+     * 获取缓存数量（失败返回 0）
+     */
+    async size() {
+        try {
+            const meta = await this.loadMetadata();
+            return meta.count;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * 获取所有缓存 key（失败返回空数组）
+     */
+    async keys() {
+        try {
+            const meta = await this.loadMetadata();
+            return Object.keys(meta.entries);
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/cache/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/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/LruMetadata.js

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

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';