@keq-request/cache 5.0.0-alpha.7 → 5.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { queueAsPromised } from "fastq";
+import { Keq, KeqContext, KeqExecutionContext, KeqMiddleware, KeqNext } from "keq";
+import { Promisable } from "type-fest";
+//#region src/cache-entry/types/cache-entry-options.d.ts
+interface CacheEntryOptions {
+  key: string;
+  response: Response;
+  size: number;
+  expiredAt?: Date;
+}
+//#endregion
+//#region src/cache-entry/types/cache-entry-build-options.d.ts
+interface CacheEntryBuildOptions {
+  key: string;
+  response: Response;
+  size?: number;
+  ttl?: number;
+  expiredAt?: Date;
+}
+//#endregion
+//#region src/cache-entry/cache-entry.d.ts
+declare class CacheEntry {
+  key: string;
+  response: Response;
+  /**
+   * @en bytes
+   * @zh 字节数
+   */
+  size: number;
+  expiredAt: Date;
+  constructor(options: CacheEntryOptions);
+  static build(options: CacheEntryBuildOptions): Promise<CacheEntry>;
+  clone(): CacheEntry;
+  assignResponseHeaders(headers: Headers): void;
+}
+//#endregion
+//#region src/storage/keq-cache-storage.d.ts
+declare abstract class KeqCacheStorage {
+  /**
+   * @en Get the length of the storage
+   * @zh 获取 Storage 缓存的条目数量
+   */
+  abstract get(key: string): Promisable<CacheEntry | undefined>;
+  /**
+   * @en Set a new entry to the storage
+   * @zh 将被缓存的数据添加到Storage中
+   */
+  abstract set(entry: CacheEntry): Promisable<void>;
+  /**
+   * @en Remove an entry by key
+   * @zh 根据key删除Storage中的数据
+   */
+  abstract remove(key: string): Promisable<void>;
+}
+//#endregion
+//#region src/types/keq-cache-key.d.ts
+type KeqCacheKeyFactory = ((context: KeqContext) => string);
+type KeqCacheKey = string | KeqCacheKeyFactory;
+//#endregion
+//#region src/constants/eviction.enum.d.ts
+declare enum Eviction {
+  LRU = "lru",
+  LFU = "lfu",
+  RANDOM = "random",
+  TTL = "ttl"
+}
+//#endregion
+//#region src/constants/size.enum.d.ts
+declare enum Size {
+  B = 1,
+  KB = 1024,
+  MB = 1048576,
+  GB = 1073741824
+}
+//#endregion
+//#region src/constants/strategy.enum.d.ts
+declare const Strategy: {
+  STALE_WHILE_REVALIDATE: KeqCacheStrategy;
+  NETWORK_FIRST: KeqCacheStrategy;
+  NETWORK_ONLY: KeqCacheStrategy;
+  CACHE_FIRST: KeqCacheStrategy;
+};
+//#endregion
+//#region src/storage/internal-storage/types/events.d.ts
+interface OnCacheGetEvent {
+  readonly key: string;
+}
+interface OnCacheSetEvent {
+  readonly key: string;
+}
+interface OnCacheRemoveEvent {
+  readonly key: string;
+}
+interface OnCacheEvictEvent {
+  readonly keys: string[];
+}
+interface OnCacheExpiredEvent {
+  readonly keys: string[];
+}
+//#endregion
+//#region src/storage/internal-storage/types/storage-options.d.ts
+interface InternalStorageOptions {
+  /**
+   * @default false
+   */
+  debug?: boolean;
+  /**
+   * @en bytes
+   * @zh 字节数
+   *
+   * @default Infinity
+   */
+  size?: number;
+  onCacheGet?: (event: OnCacheGetEvent) => void;
+  onCacheSet?: (event: OnCacheSetEvent) => void;
+  onCacheRemove?: (event: OnCacheRemoveEvent) => void;
+  onCacheEvict?: (event: OnCacheEvictEvent) => void;
+  onCacheExpired?: (event: OnCacheExpiredEvent) => void;
+}
+//#endregion
+//#region src/storage/memory-storage/types/memory-storage-options.d.ts
+interface MemoryStorageOptions extends InternalStorageOptions {
+  /**
+   * @default Eviction.LRU
+   */
+  eviction?: Eviction;
+}
+//#endregion
+//#region src/storage/memory-storage/memory-storage.d.ts
+declare class MemoryStorage extends KeqCacheStorage {
+  private storage;
+  constructor(options?: MemoryStorageOptions);
+  set(entry: CacheEntry): Promisable<void>;
+  get(key: string): Promisable<CacheEntry | undefined>;
+  remove(key: string): Promisable<void>;
+  print(): Promise<void>;
+}
+//#endregion
+//#region src/storage/indexed-db-storage/types/indexed-db-storage-options.d.ts
+interface IndexedDbStorageOptions extends InternalStorageOptions {
+  /**
+   * @en The table name for the IndexedDB storage, multiple instances using the same table name will share the cached data.
+   * @zh IndexedDB 存储的表名, 多个实例使用同一个表名会共享缓存数据。
+   */
+  tableName?: string;
+  /**
+   * @default Eviction.LRU
+   */
+  eviction?: Eviction;
+}
+//#endregion
+//#region src/storage/indexed-db-storage/indexed-db-storage.d.ts
+declare class IndexedDBStorage extends KeqCacheStorage {
+  private storage;
+  constructor(options?: IndexedDbStorageOptions);
+  set(entry: CacheEntry): Promisable<void>;
+  get(key: string): Promisable<CacheEntry | undefined>;
+  remove(key: string): Promisable<void>;
+}
+//#endregion
+//#region src/storage/multi-tier-storage/types/multi-tier-storage-options.d.ts
+interface MultiTierStorageOptions {
+  tiers: KeqCacheStorage[];
+}
+//#endregion
+//#region src/storage/multi-tier-storage/multi-tier-storage.d.ts
+/**
+ * @en Multi-tier cache storage that manages multiple KeqCacheStorage instances in tiers
+ * @zh 多层缓存存储，管理多个分层的 KeqCacheStorage 实例
+ */
+declare class MultiTierStorage extends KeqCacheStorage {
+  private readonly storages;
+  /**
+   * @param storages Array of storage instances ordered by performance (fastest first)
+   * @zh 按性价比排序的存储实例数组，排在前面的成本低，排在后面的成本高
+   */
+  constructor(options: MultiTierStorageOptions);
+  /**
+   * @en Get cache entry, searching from lowest to highest tier
+   * @zh 获取缓存条目，从最底层到高层依次搜索
+   */
+  get(key: string): Promise<CacheEntry | undefined>;
+  /**
+   * @en Set cache entry to all tiers concurrently
+   * @zh 并发写入所有层的缓存
+   */
+  set(entry: CacheEntry): Promise<void>;
+  /**
+   * @en Remove cache entry from all tiers
+   * @zh 从所有层删除缓存条目
+   */
+  remove(key: string): Promise<void>;
+  /**
+   * @en Sync cache entry to all lower tiers (tiers with index < currentTierIndex)
+   * @zh 将缓存条目同步到所有低层存储（索引小于当前层的存储）
+   */
+  private syncToLowerTiers;
+}
+//#endregion
+//#region src/storage/tier-storage/types/tier-storage-options.d.ts
+/**
+ * @en Configuration options for TierStorage
+ * @zh TierStorage 的配置选项
+ */
+interface TierStorageOptions {
+  /**
+   * @en Memory storage instance or options for the memory storage (L1 cache)
+   * @zh 内存存储实例或配置选项（一级缓存）
+   */
+  memory?: MemoryStorage | MemoryStorageOptions;
+  /**
+   * @en IndexedDB storage instance or options for the IndexedDB storage (L2 cache)
+   * @zh IndexedDB 存储实例或配置选项（二级缓存）
+   */
+  indexedDB?: IndexedDBStorage | IndexedDbStorageOptions;
+}
+//#endregion
+//#region src/storage/tier-storage/tier-storage.d.ts
+/**
+ * @en Two-tier cache storage that combines MemoryStorage (L1) and IndexedDBStorage (L2)
+ * @zh 二级缓存存储，结合了MemoryStorage（一级）和IndexedDBStorage（二级）
+ *
+ * This is a convenience wrapper around MultiTierStorage that provides:
+ * - Fast in-memory cache (L1)
+ * - Persistent IndexedDB cache (L2)
+ * - Simplified configuration options
+ */
+declare class TierStorage extends MultiTierStorage {
+  constructor(options?: TierStorageOptions);
+}
+//#endregion
+//#region src/request-cache-handler/request-cache-handler.d.ts
+type RequestCacheHandlerOptions = Omit<RequestCacheOptions, 'strategy'>;
+declare class RequestCacheHandler {
+  readonly cacheKey: string;
+  readonly storage: KeqCacheStorage;
+  readonly options: Readonly<RequestCacheHandlerOptions>;
+  constructor(cacheKey: string, storage: KeqCacheStorage, options: Readonly<RequestCacheHandlerOptions>);
+  /**
+   * Resolve cache key for request context
+   */
+  static resolveRequestCacheKey(context: KeqContext, options: RequestCacheHandlerOptions): string;
+  /**
+   * Get cache from storage
+   */
+  getCache(): Promise<[string, CacheEntry | undefined]>;
+  /**
+   * Store response that in context to storage
+   */
+  setCache(context: KeqContext): Promise<[string, CacheEntry | undefined]>;
+}
+//#endregion
+//#region src/types/keq-cache-strategy.d.ts
+interface KeqCacheStrategy {
+  (handler: RequestCacheHandler, context: KeqExecutionContext, next: KeqNext): Promise<void>;
+}
+//#endregion
+//#region src/types/request-cache-options.d.ts
+/**
+ * The options for a cacheable request.
+ */
+interface RequestCacheOptions {
+  /**
+   * Enable debug logs
+   */
+  debug?: boolean;
+  /**
+   * Enable Server-Timing header
+   */
+  serverTiming?: boolean;
+  /**
+   * This configuration item controls whether requests are allowed to be concurrent.
+   * By default, concurrency is disabled
+   *
+   * When multiple requests with the same key occur,
+   * the subsequent ones are blocked until the previous request completes.
+   * This ensures that the cache is utilized effectively and prevents redundant processing for identical keys
+   *
+   * @default false
+   */
+  concurrent?: boolean;
+  /**
+   * Cache Key
+   */
+  key?: KeqCacheKey;
+  /**
+   * @default Strategy.NETWORK_FIRST
+   */
+  strategy: KeqCacheStrategy;
+  /**
+   * @en seconds
+   * @zh 秒
+   *
+   * @default Infinity
+   */
+  ttl?: number;
+  /**
+   * If exclude is true, the request will not be cached.
+   */
+  exclude?: (res: Response) => (Promise<boolean> | boolean);
+}
+//#endregion
+//#region src/types/keq-cache-pattern.d.ts
+type KeqCachePattern = RegExp | ((ctx: KeqContext) => boolean) | true;
+//#endregion
+//#region src/types/keq-cache-rule.d.ts
+interface KeqCacheRule extends RequestCacheOptions {
+  pattern?: KeqCachePattern;
+}
+//#endregion
+//#region src/cache.d.ts
+interface KeqCacheOptions extends Pick<RequestCacheOptions, 'serverTiming'> {
+  storage: KeqCacheStorage;
+  /**
+   * Cache Key Factory
+   */
+  keyFactory?: KeqCacheKeyFactory;
+  rules?: KeqCacheRule[];
+}
+declare module 'keq' {
+  interface KeqMiddlewareOptions<OP> {
+    /**
+     * [keq-cache](https://github.com/keq-request/keq-cache)
+     */
+    cache(option: RequestCacheOptions | false): Keq<OP>;
+  }
+  interface KeqEvents {
+    'cache:hit': {
+      key: string;
+      response: Response;
+      context: KeqContext;
+    };
+    'cache:miss': {
+      key: string;
+      context: KeqContext;
+    };
+    'cache:update': {
+      key: string;
+      oldResponse?: Response;
+      newResponse: Response;
+      context: KeqContext;
+    };
+  }
+  interface KeqGlobalCore {
+    cache?: Record<string, queueAsPromised<{
+      next: KeqNext;
+    }, void>>;
+  }
+}
+declare function cache(options: KeqCacheOptions): KeqMiddleware;
+//#endregion
+export { Eviction, IndexedDBStorage, type IndexedDbStorageOptions, type KeqCacheKey, type KeqCacheKeyFactory, KeqCacheOptions, type KeqCachePattern, type KeqCacheRule, KeqCacheStorage, type KeqCacheStrategy, MemoryStorage, type MemoryStorageOptions, MultiTierStorage, type MultiTierStorageOptions, Size, Strategy, TierStorage, type TierStorageOptions, cache };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cache-entry/types/cache-entry-options.ts","../src/cache-entry/types/cache-entry-build-options.ts","../src/cache-entry/cache-entry.ts","../src/storage/keq-cache-storage.ts","../src/types/keq-cache-key.ts","../src/constants/eviction.enum.ts","../src/constants/size.enum.ts","../src/constants/strategy.enum.ts","../src/storage/internal-storage/types/events.ts","../src/storage/internal-storage/types/storage-options.ts","../src/storage/memory-storage/types/memory-storage-options.ts","../src/storage/memory-storage/memory-storage.ts","../src/storage/indexed-db-storage/types/indexed-db-storage-options.ts","../src/storage/indexed-db-storage/indexed-db-storage.ts","../src/storage/multi-tier-storage/types/multi-tier-storage-options.ts","../src/storage/multi-tier-storage/multi-tier-storage.ts","../src/storage/tier-storage/types/tier-storage-options.ts","../src/storage/tier-storage/tier-storage.ts","../src/request-cache-handler/request-cache-handler.ts","../src/types/keq-cache-strategy.ts","../src/types/request-cache-options.ts","../src/types/keq-cache-pattern.ts","../src/types/keq-cache-rule.ts","../src/cache.ts"],"mappings":"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"}